proton-mail-mcp

Proton Suite Agent

Propósito de este documento

• Objetivos: Orientar el pulso del repo, el quickstart y el enrutado a los documentos canónicos.
• Estructura: Ficha → pulso → mapa de lectura → instalación, tools, agente, calidad.
• Contenido a integrar según contexto: Stack TypeScript/MCP, frontera Bridge, dry-run por defecto, Makefile fachada.

Abrir cuando: Orientación, pulso y enrutado. Aprobado: 15 de agosto de 2026 Audiencia: Agente, Dirección, Usuarios Autoridad: Lectura Clase: Obligatorio Días para revisión: 14 En repo: Sí Estado: Vigente Orden: 1 Propósito: Punto de entrada: pulso, quickstart y qué leer después. Reforma: Operativa Responsable: Alexendros Revisión: 29 de agosto de 2026 Rol: Entrada Ruta: ./README.md

📌

Propósito

Punto de entrada de lectura. Te dice el pulso, cómo arrancar y qué documento abrir después. Lo no negociable vive en CONSTITUTION.md.

---

Estado en una mirada

Pulso: 24 de septiembre de 2026 · v1.4.0

Fase activa: Fase 1 (Pass / agente / DX) checklist cerrada · siguiente: Fase 2 (Calendar, bloqueada). Ver ROADMAP.md.

Métricas: 47 tools por defecto (50 con Calendar experimental) · 965 tests · cobertura ~98% (gate 95%).

Capa	Estado
Mail (Bridge IMAP/SMTP)	Operativo
Pass (pass / gopass)	Operativo
Drive (proton-drive CLI)	Operativo (ADR-006)
Calendar	Stub hasta CalDAV en Bridge (ADR-005)
Documentación canónica	Subfase 0 completada

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.

Modo	Descripción
stdio (default)	Sin exponer red. Ideal para agentes IA locales.
streamable HTTP	Bearer auth + origin allowlist. Docker / reverse proxy.

---

Qué leer a continuación

Si necesitas	Abre	Aún no
Lo no negociable	CONSTITUTION.md	ROADMAP entero
Orden de trabajo y fases	ROADMAP.md	Código
Implementar como agente	AGENTS.md	ARCHITECTURE completo
Capas y flujos	ARCHITECTURE.md	Código
Threat model	SECURITY.md	—
Contribuir / PR	CONTRIBUTING.md	—
Contrato de tools MCP	docs/api/mcp-tools.md	—
Decisiones (por qué)	docs/adr/	—
Índice de guías	docs/README.md	—
Playbooks + prompts	playbooks/README.md	—

Primera sesión: este README → AGENTS.md §§ TL;DR + ficha → fase activa en ROADMAP.md → ADR/ancla citada.

---

Quickstart

Prerrequisitos: Node ≥ 22, pnpm, Proton Mail Bridge en local, pass o gopass + gpg para contraseñas.

1. Instalar y compilar

git clone https://github.com/Soluciones-Alexendros/protonsuite-tools.git
cd protonsuite-tools
pnpm install && pnpm build && pnpm run smoke

2. Configurar variables de entorno

export [email protected]
export PROTON_BRIDGE_PASS=your-bridge-password
export [email protected]

3. Conectar tu cliente MCP

{
  "mcpServers": {
    "protonsuite": {
      "command": "npx",
      "args": ["-y", "@alexendros/protonsuite-agent", "protonsuite-mcp"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "PROTON_BRIDGE_USER": "[email protected]",
        "PROTON_BRIDGE_PASS": "your-bridge-password",
        "PROTON_MAIL_FROM": "[email protected]",
        "PROTON_BRIDGE_TLS_INSECURE": "true",
        "PROTON_PASS_ENABLED": "true",
      },
    },
  },
}

Seguridad: usa PROTON_PASS_BRIDGE_PATH=proton/bridge/password o el wrapper JIT en connectors/stdio-wrapper.sh.example para no dejar el bridge password en disco.

4. Organizar el buzón (dry-run)

AGENT_DRY_RUN=true pnpm exec protonsuite-agent organize
# o: npx -y @alexendros/protonsuite-agent organize

El agente analiza el inbox y presenta un plan sin aplicar cambios. Desactiva AGENT_DRY_RUN solo tras revisión.

---

Tools MCP

El inventario depende de qué productos estén habilitados: un producto apagado no registra ni anuncia sus herramientas.

Configuración	Tools
Por defecto (Mail + Drive)	39
+ Pass y Calendar (PROTON_PASS_ENABLED=true, PROTON_CALENDAR_ENABLED=true)	47
+ Calendar experimental (PROTON_CALENDAR_EXPERIMENTAL=true)	50
Todos los productos apagados	5 (solo proton_suite_status y proton_ecosystem_*)

Lectura: response_format: "markdown" | "json".

Producto	Tools	Resumen
Mail	14	List, search, read, send, reply, forward, flag, move, delete, attachments
Pass	4+	List, get (sin valores), generate, health; audit vía agente
Drive	8+	Status, list, download, upload, share, audit, organize
Calendar	stub	{available: false} hasta CalDAV vía Bridge (ADR-005)
Suite / Bridge / Ecosystem / Agent	resto	Estado unificado, Bridge, binarios, plan de agente

Contrato generado: docs/api/mcp-tools.md. Guía: docs/agent-quickstart.md.

Escribir requiere tu aprobación

Leer no pide nada. Escribir, borrar o tocar credenciales no se ejecuta: el servidor deja una solicitud y te la enseña.

protonsuite-agent pending          # qué espera aprobación, con los campos sensibles tachados
protonsuite-agent approve <id>     # lo autorizas
protonsuite-agent reject <id>      # lo deniegas

Después de aprobar, repite exactamente la misma llamada. Si cambias un destinatario o una letra del cuerpo, la aprobación ya no vale y habrá que aprobar otra vez.

Aprobar solo se puede desde tu terminal: no hay forma de hacerlo por MCP ni pidiéndoselo al modelo. Detalles en ADR-0009.

---

Agente

Goal	Pipeline
setup	Verifica Bridge (IMAP + SMTP)
organize	Clasifica inbox, carpetas/etiquetas, amenazas
monitor / alert	Solo lectura — alertas
pass-audit	Fortaleza, duplicados y plan de rotación. Solo lectura: nunca escribe en el store.
suite-status	Reporte cross-producto
discover / check-imap	Conectividad
Drive goals	drive-audit, drive-organize, …

Drive CLI

sudo wget -q 'https://proton.me/download/drive/cli/linux/proton-drive' \
  -O /usr/local/bin/proton-drive && sudo chmod +x /usr/local/bin/proton-drive
proton-drive auth login

Requiere DRIVE_ENABLED=true (default). Ver docs/drive-audit.md.

---

Despliegue

docker compose up -d

Ver docs/deployment-http-docker.md. Instalador: scripts/install.sh.

Interfaz local

SPA estática en apps/web (ADR-0007): landing y panel de estado. No forma parte del proceso MCP. pnpm run build la genera en apps/web/dist. Se abre sin Bridge; el panel usa el adaptador local «datos de ejemplo» y no pide credenciales. Calendar sigue en stub.

---

Documentación

Documento	Para quién	Qué cubre
CONSTITUTION.md	Todos	No negociables
ROADMAP.md	Dirección / agente	Fases y criterios de salida
AGENTS.md	Agentes IA	Contrato operativo
docs/human-quickstart.md	Usuarios	Instalación paso a paso
docs/agent-quickstart.md	Agentes IA	Tools y ejemplos
docs/bridge-core.md	Operadores	Bridge headless
docs/deployment-http-docker.md	DevOps	Docker, auth, Pass en compose
docs/local-stdio-secrets.md	Operadores	Wrapper JIT
docs/alerting.md	Operadores	Webhook, ntfy, logs
docs/drive-audit.md	Operadores	Drive CLI
ARCHITECTURE.md	Desarrolladores	Capas y flujos
SECURITY.md	Auditores	Threat model
CONTRIBUTING.md	Contribuidores	PRs, pnpm, tests
SUPPORT.md	Usuarios	Canales de ayuda
CODE_OF_CONDUCT.md	Comunidad	Conducta
docs/	Todos	architecture / guides / runbooks
playbooks/	Operadores	Workflows + prompts

---

Calidad

Fachada canónica (Makefile): make lint, make test, make smoke, make validate.

make validate        # lint + typecheck + test + build + smoke
pnpm run typecheck   # TypeScript strict
pnpm test            # Vitest (953+)
pnpm run coverage    # Coverage v8 — gate 95%, objetivo ≥98%
pnpm run build       # tsc → dist/ y SPA apps/web (tokens, contraste, vite)
pnpm run smoke       # stdio initialize + tools/list
pnpm run knip        # Unused deps/exports
pnpm docs:check      # mcp-tools.md en sync

Seguridad (resumen)

• Bearer timing-safe, origin allowlist, rate-limit 120/min/token.
• HTTP per-session; idle eviction 30 min.
• Pass nunca expone valores — solo {found: true}.
• Dry-run por defecto en el agente (CONSTITUTION.md §4).

Progreso de cobertura

Fecha	Statements	Branches	Tests	Notas
Ago 2026	~98%	~95%	953	Subfase 0 + Fase 1
Jul 2026	98.07%	93.63%	864	Branch hunt
Jun 2026	61.7%	—	258	Base

Conteo canónico: pnpm test 2>&1 | grep -E 'Test Files|Tests'.

Licencia

AGPL-3.0 — Copyright 2026 Alejandro Domingo Agustí (Alexendros). Sin afiliación a Proton AG.

Ver NOTICE.md para dependencias.