proton-mail-mcp

Proton Suite Agent

本文档的目的

• 目标： 指引项目的当前状态、快速入门，以及如何跳转到规范文档。
• 结构： 概览 → 当前状态 → 阅读指南 → 安装、工具、Agent、质量。
• 根据上下文整合的内容： TypeScript/MCP 技术栈、Bridge 边界、默认 dry-run、门面 Makefile。

在以下情况下打开：了解概况、当前状态和文档跳转。 批准日期：2026 年 8 月 15 日 受众：Agent、管理层、用户 权威级别：参考 类别：必需 复审间隔（天）：14 位于仓库中：是 状态：有效 顺序：1 目的：入口文档：当前状态、快速入门以及后续阅读建议。 修订类型：操作性 负责人：Alexendros 复审日期：2026 年 8 月 29 日 角色：入口 路径：./README.md

📌

目的

阅读入口。介绍项目当前状态、如何启动，以及接下来该打开哪份文档。不可妥协的要求见 CONSTITUTION.md。

---

一览当前状态

当前状态： 2026 年 9 月 24 日 · v1.4.0

当前阶段： 阶段 1（Pass / Agent / DX）检查清单已完成 · 下一步：阶段 2（Calendar，已阻塞）。参见 ROADMAP.md。

指标： 默认 47 个工具（启用实验性 Calendar 时为 50 个）· 965 项测试 · 覆盖率约 98%（门槛 95%）。

层	状态
Mail（Bridge IMAP/SMTP）	运行中
Pass（pass / gopass）	运行中
Drive（proton-drive CLI）	运行中（ADR-006）
Calendar	在 Bridge 支持 CalDAV 前保持为 Stub（ADR-005）
规范文档	子阶段 0 已完成

面向 Proton Suite 多产品的 MCP 服务：Mail、Pass、Drive 和 Calendar（Stub）。Agent 可操作邮箱、管理密码并同步文件——在本地运行，不会外泄 E2E 内容。

模式	描述
stdio（默认）	不开放网络。适用于本地 AI Agent。
streamable HTTP	Bearer 身份验证 + 来源允许列表。适用于 Docker / 反向代理。

---

接下来阅读什么

如果你需要	打开	暂时不要
不可妥协的要求	CONSTITUTION.md	整份 ROADMAP
工作顺序和阶段	ROADMAP.md	代码
以 Agent 身份实现	AGENTS.md	完整的 ARCHITECTURE
各层和流程	ARCHITECTURE.md	代码
威胁模型	SECURITY.md	—
贡献 / PR	CONTRIBUTING.md	—
MCP 工具契约	docs/api/mcp-tools.md	—
决策（原因）	docs/adr/	—
指南索引	docs/README.md	—
操作手册 + 提示词	playbooks/README.md	—

首次使用： 本 README → AGENTS.md §§ TL;DR + 概览 → ROADMAP.md 中的当前阶段 → 引用的 ADR/锚点。

---

快速入门

前置条件： Node ≥ 22、pnpm、本地运行的 Proton Mail Bridge、用于管理密码的 pass 或 gopass + gpg。

1. 安装和构建

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

2. 配置环境变量

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

3. 连接你的 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",
      },
    },
  },
}

安全性： 使用 PROTON_PASS_BRIDGE_PATH=proton/bridge/password 或 connectors/stdio-wrapper.sh.example 中的 JIT 包装器，避免将 bridge password 留在磁盘上。

4. 整理邮箱（dry-run）

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

Agent 会分析收件箱并展示计划，但不会应用任何更改。只有在审核之后，才停用 AGENT_DRY_RUN。

---

MCP 工具

工具清单取决于已启用的产品：已关闭的产品不会注册或公布其工具。

配置	工具
默认（Mail + Drive）	39
+ Pass 和 Calendar（PROTON_PASS_ENABLED=true、PROTON_CALENDAR_ENABLED=true）	47
+ 实验性 Calendar（PROTON_CALENDAR_EXPERIMENTAL=true）	50
所有产品均关闭	5（仅 proton_suite_status 和 proton_ecosystem_*）

读取方式：response_format: "markdown" | "json"。

产品	工具	摘要
Mail	14	列出、搜索、读取、发送、回复、转发、标记、移动、删除、附件
Pass	4+	列出、获取（不含值）、生成、健康状态；由 Agent 执行审计
Drive	8+	状态、列出、下载、上传、共享、审计、整理
Calendar	stub	通过 Bridge 实现 CalDAV 前为 {available: false}（ADR-005）
Suite / Bridge / Ecosystem / Agent	其余	统一状态、Bridge、二进制文件、Agent 计划

生成的契约：docs/api/mcp-tools.md。指南：docs/agent-quickstart.md。

写入需要你的批准

读取无需批准。写入、删除或操作凭据不会直接执行：服务端会创建申请并向你展示。

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

批准后，请重复完全相同的调用。如果更改收件人或正文中的一个字母，原批准便会失效，需要重新批准。

只能在你的终端中批准：无法通过 MCP 批准，也不能要求模型代为批准。详情见 ADR-0009。

---

Agent

目标	工作流
setup	检查 Bridge（IMAP + SMTP）
organize	分类收件箱、文件夹/标签和威胁
monitor / alert	只读 — 告警
pass-audit	强度、重复项和轮换计划。只读：绝不会写入 store。
suite-status	跨产品报告
discover / check-imap	连通性
Drive 目标	drive-audit、drive-organize，…

Drive 命令行

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

需要 DRIVE_ENABLED=true（默认值）。参见 docs/drive-audit.md。

---

部署

docker compose up -d

参见 docs/deployment-http-docker.md。安装程序：scripts/install.sh。

本地界面

apps/web 中的静态 SPA（ADR-0007）：落地页和状态面板。它不属于 MCP 进程的一部分。pnpm run build 会在 apps/web/dist 中生成该应用。无需 Bridge 即可打开；面板使用本地“示例数据”适配器，不会要求提供凭据。Calendar 仍为 stub。

---

文档

文档	面向对象	涵盖内容
CONSTITUTION.md	所有人	不可妥协事项
ROADMAP.md	指导者 / Agent	阶段和退出标准
AGENTS.md	AI Agent	操作规范
docs/human-quickstart.md	用户	分步安装
docs/agent-quickstart.md	AI Agent	工具和示例
docs/bridge-core.md	运维人员	无头 Bridge
docs/deployment-http-docker.md	DevOps	Docker、身份验证、compose 中的 Pass
docs/local-stdio-secrets.md	运维人员	JIT 封装器
docs/alerting.md	运维人员	Webhook、ntfy、日志
docs/drive-audit.md	运维人员	Drive CLI
ARCHITECTURE.md	开发者	层和流程
SECURITY.md	审计人员	威胁模型
CONTRIBUTING.md	贡献者	PR、pnpm、测试
SUPPORT.md	用户	求助渠道
CODE_OF_CONDUCT.md	社区	行为准则
docs/	所有人	架构 / 指南 / 运行手册
playbooks/	运维人员	工作流 + 提示词

---

质量

规范入口（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

安全（摘要）

• Bearer 使用时序安全比较、来源允许列表、速率限制为每个令牌每分钟 120 次。
• HTTP 按会话隔离；空闲 30 分钟后清除。
• Pass 从不公开值——仅返回 {found: true}。
• Agent 默认采用 Dry-run（参见 CONSTITUTION.md §4）。

覆盖率进展

日期	语句	分支	测试	备注
2026 年 8 月	~98%	~95%	953	子阶段 0 + 阶段 1
2026 年 7 月	98.07%	93.63%	864	分支覆盖排查
2026 年 6 月	61.7%	—	258	基线

规范统计方式：pnpm test 2>&1 | grep -E 'Test Files|Tests'。

许可证

AGPL-3.0 — Copyright 2026 Alejandro Domingo Agustí（Alexendros）。与 Proton AG 无关联。

依赖项请参见 NOTICE.md。