{
  "markdown": "# Proton Suite Agent\n\nAbrir cuando: Orientación, pulso y enrutado.\nAprobado: 15 de agosto de 2026\nAudiencia: Agente, Dirección, Usuarios\nAutoridad: Lectura\nClase: Obligatorio\nDías para revisión: 14\nEn repo: Sí\nEstado: Vigente\nOrden: 1\nPropósito: Punto de entrada: pulso, quickstart y qué leer después.\nReforma: Operativa\nResponsable: Alexendros\nRevisión: 29 de agosto de 2026\nRol: Entrada\nRuta: ./README.md\n\n[![CI](https://github.com/Iniciativas-Alexendros/agent-protonsuite/actions/workflows/ci.yml/badge.svg)](https://github.com/Iniciativas-Alexendros/agent-protonsuite/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/Iniciativas-Alexendros/agent-protonsuite/actions/workflows/codeql.yml/badge.svg)](https://github.com/Iniciativas-Alexendros/agent-protonsuite/actions/workflows/codeql.yml)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Iniciativas-Alexendros/agent-protonsuite/badge)](https://scorecard.dev/viewer/?uri=github.com/Iniciativas-Alexendros/agent-protonsuite)\n[![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen)](./docs/coverage-report.md)\n[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](./LICENSE)\n[![Node](https://img.shields.io/badge/node-%E2%89%A522-brightgreen.svg)](./package.json)\n[![npm](https://img.shields.io/npm/v/@alexendros/protonsuite-agent)](https://www.npmjs.com/package/@alexendros/protonsuite-agent)\n\n<aside>\n📌\n\n**Propósito**\n\nPunto de entrada de lectura. Te dice el pulso, cómo arrancar y qué documento abrir después. Lo no negociable vive en [CONSTITUTION.md](./CONSTITUTION.md).\n\n</aside>\n\n---\n\n# Estado en una mirada\n\n**Pulso:** 15 de agosto de 2026 · `v1.2.1`\n\n**Fase activa:** Fase 1 (Pass / agente / DX) checklist cerrada · siguiente: Fase 2 (Calendar, bloqueada). Ver [ROADMAP.md](./ROADMAP.md).\n\n**Métricas:** 47 tools por defecto (50 con Calendar experimental) · 958 tests · cobertura ~98% (gate 95%).\n\n| Capa | Estado |\n| --- | --- |\n| Mail (Bridge IMAP/SMTP) | Operativo |\n| Pass (`pass` / `gopass`) | Operativo |\n| Drive (`proton-drive` CLI) | Operativo (ADR-006) |\n| Calendar | Stub hasta CalDAV en Bridge (ADR-005) |\n| Documentación canónica | Subfase 0 |\n\n**MCP server** multi-producto para **Proton Suite**: Mail, Pass, Drive y Calendar (stub). Un agente opera el buzón, gestiona contraseñas y sincroniza archivos — local, sin exfiltrar contenido E2E.\n\n| Modo | Descripción |\n| --- | --- |\n| **stdio** (default) | Sin exponer red. Ideal para agentes IA locales. |\n| **streamable HTTP** | Bearer auth + origin allowlist. Docker / reverse proxy. |\n\n---\n\n# Qué leer a continuación\n\n| Si necesitas | Abre | Aún no |\n| --- | --- | --- |\n| Lo no negociable | [CONSTITUTION.md](./CONSTITUTION.md) | ROADMAP entero |\n| Orden de trabajo y fases | [ROADMAP.md](./ROADMAP.md) | Código |\n| Implementar como agente | [AGENTS.md](./AGENTS.md) | ARCHITECTURE completo |\n| Capas y flujos | [ARCHITECTURE.md](./ARCHITECTURE.md) | Código |\n| Threat model | [SECURITY.md](./SECURITY.md) | — |\n| Contribuir / PR | [CONTRIBUTING.md](./CONTRIBUTING.md) | — |\n| Contrato de tools MCP | [docs/api/mcp-tools.md](./docs/api/mcp-tools.md) | — |\n| Decisiones (por qué) | [docs/adr/](./docs/adr/) | — |\n| Índice de guías | [docs/README.md](./docs/README.md) | — |\n| Playbooks + prompts | [playbooks/README.md](./playbooks/README.md) | — |\n\n**Primera sesión:** este README → [AGENTS.md](./AGENTS.md) §§ TL;DR + ficha → fase activa en [ROADMAP.md](./ROADMAP.md) → ADR/ancla citada.\n\n---\n\n## Quickstart\n\n**Prerrequisitos:** Node ≥ 22, pnpm, Proton Mail Bridge en local, `pass` o `gopass` + `gpg` para contraseñas.\n\n### 1. Instalar y compilar\n\n```bash\ngit clone https://github.com/Iniciativas-Alexendros/agent-protonsuite.git\ncd agent-protonsuite\npnpm install && pnpm build && pnpm run smoke\n```\n\n### 2. Configurar variables de entorno\n\n```bash\nexport PROTON_BRIDGE_USER=you@proton.me\nexport PROTON_BRIDGE_PASS=your-bridge-password\nexport PROTON_MAIL_FROM=you@proton.me\n```\n\n### 3. Conectar tu cliente MCP\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"protonsuite\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@alexendros/protonsuite-agent\", \"protonsuite-mcp\"],\n      \"env\": {\n        \"MCP_TRANSPORT\": \"stdio\",\n        \"PROTON_BRIDGE_USER\": \"you@proton.me\",\n        \"PROTON_BRIDGE_PASS\": \"your-bridge-password\",\n        \"PROTON_MAIL_FROM\": \"you@proton.me\",\n        \"PROTON_BRIDGE_TLS_INSECURE\": \"true\",\n        \"PROTON_PASS_ENABLED\": \"true\",\n      },\n    },\n  },\n}\n```\n\n> **Seguridad:** usa `PROTON_PASS_BRIDGE_PATH=proton/bridge/password` o el wrapper JIT en [`connectors/stdio-wrapper.sh.example`](./connectors/stdio-wrapper.sh.example) para no dejar el bridge password en disco.\n\n### 4. Organizar el buzón (dry-run)\n\n```bash\nAGENT_DRY_RUN=true pnpm exec protonsuite-agent organize\n# o: npx -y @alexendros/protonsuite-agent organize\n```\n\nEl agente analiza el inbox y presenta un plan **sin aplicar cambios**. Desactiva `AGENT_DRY_RUN` solo tras revisión.\n\n---\n\n## Tools MCP\n\n47 tools por defecto (50 con Calendar experimental). Lectura: `response_format: \"markdown\" | \"json\"`.\n\n| Producto | Tools | Resumen |\n| --- | --- | --- |\n| **Mail** | 14 | List, search, read, send, reply, forward, flag, move, delete, attachments |\n| **Pass** | 4+ | List, get (sin valores), generate, health; audit vía agente |\n| **Drive** | 8+ | Status, list, download, upload, share, audit, organize |\n| **Calendar** | stub | `{available: false}` hasta CalDAV vía Bridge (ADR-005) |\n| **Suite / Bridge / Ecosystem / Agent** | resto | Estado unificado, Bridge, binarios, plan de agente |\n\nContrato generado: [`docs/api/mcp-tools.md`](./docs/api/mcp-tools.md). Guía: [`docs/agent-quickstart.md`](./docs/agent-quickstart.md).\n\n---\n\n## Agente\n\n| Goal | Pipeline |\n| --- | --- |\n| `setup` | Verifica Bridge (IMAP + SMTP) |\n| `organize` | Clasifica inbox, carpetas/etiquetas, amenazas |\n| `monitor` / `alert` | Solo lectura — alertas |\n| `pass-audit` | Fortaleza, duplicados, plan de rotación (dry-run) |\n| `suite-status` | Reporte cross-producto |\n| `discover` / `check-imap` | Conectividad |\n| Drive goals | `drive-audit`, `drive-organize`, … |\n\n### Drive CLI\n\n```bash\nsudo wget -q 'https://proton.me/download/drive/cli/linux/proton-drive' \\\n  -O /usr/local/bin/proton-drive && sudo chmod +x /usr/local/bin/proton-drive\nproton-drive auth login\n```\n\nRequiere `DRIVE_ENABLED=true` (default). Ver [`docs/drive-audit.md`](./docs/drive-audit.md).\n\n---\n\n## Despliegue\n\n```bash\ndocker compose up -d\n```\n\nVer [`docs/deployment-http-docker.md`](./docs/deployment-http-docker.md). Instalador: [`scripts/install.sh`](./scripts/install.sh).\n\n---\n\n## Documentación\n\n| Documento | Para quién | Qué cubre |\n| --- | --- | --- |\n| [`CONSTITUTION.md`](./CONSTITUTION.md) | Todos | No negociables |\n| [`ROADMAP.md`](./ROADMAP.md) | Dirección / agente | Fases y criterios de salida |\n| [`AGENTS.md`](./AGENTS.md) | Agentes IA | Contrato operativo |\n| [`docs/human-quickstart.md`](./docs/human-quickstart.md) | Usuarios | Instalación paso a paso |\n| [`docs/agent-quickstart.md`](./docs/agent-quickstart.md) | Agentes IA | Tools y ejemplos |\n| [`docs/bridge-core.md`](./docs/bridge-core.md) | Operadores | Bridge headless |\n| [`docs/deployment-http-docker.md`](./docs/deployment-http-docker.md) | DevOps | Docker, auth, Pass en compose |\n| [`docs/local-stdio-secrets.md`](./docs/local-stdio-secrets.md) | Operadores | Wrapper JIT |\n| [`docs/alerting.md`](./docs/alerting.md) | Operadores | Webhook, ntfy, logs |\n| [`docs/drive-audit.md`](./docs/drive-audit.md) | Operadores | Drive CLI |\n| [`ARCHITECTURE.md`](./ARCHITECTURE.md) | Desarrolladores | Capas y flujos |\n| [`SECURITY.md`](./SECURITY.md) | Auditores | Threat model |\n| [`CONTRIBUTING.md`](./CONTRIBUTING.md) | Contribuidores | PRs, pnpm, tests |\n| [`playbooks/`](./playbooks/) | Operadores | Workflows + prompts |\n\n---\n\n## Calidad\n\n```bash\npnpm run typecheck   # TypeScript strict\npnpm test            # Vitest (953+)\npnpm run coverage    # Coverage v8 — gate 95%, objetivo ≥98%\npnpm run build       # tsc → dist/\npnpm run smoke       # stdio initialize + tools/list\npnpm run knip        # Unused deps/exports\npnpm docs:check      # mcp-tools.md en sync\n```\n\n### Seguridad (resumen)\n\n- Bearer timing-safe, origin allowlist, rate-limit 120/min/token.\n- HTTP per-session; idle eviction 30 min.\n- Pass nunca expone valores — solo `{found: true}`.\n- Dry-run por defecto en el agente ([CONSTITUTION.md](./CONSTITUTION.md) §4).\n\n### Progreso de cobertura\n\n| Fecha | Statements | Branches | Tests | Notas |\n|-------|-----------|----------|-------|-------|\n| Ago 2026 | **~98%** | **~95%** | **953** | Subfase 0 + Fase 1 |\n| Jul 2026 | 98.07% | 93.63% | 864 | Branch hunt |\n| Jun 2026 | 61.7% | — | 258 | Base |\n\n*Conteo canónico: `pnpm test 2>&1 | grep -E 'Test Files|Tests'`.*\n\n## Licencia\n\n[AGPL-3.0](./LICENSE) — Copyright 2026 Alejandro Domingo Agustí (Alexendros). Sin afiliación a Proton AG.\n\nVer [`NOTICE.md`](./NOTICE.md) para dependencias.\n",
  "bytes": 8946,
  "sha": "09adb23e912a851b66428af6616bb6beb4d388dbb26d3ef5831692cbe294f6af",
  "repo_slug": "alexendros/proton-mail-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_alexendros_proton_mail_mcp_54f8746b/readme"
}