hypermail-mcp

# hypermail-mcp 一个 **Model Context Protocol** 服务器，允许代理通过单一、统一的工具界面操作用户的任意邮箱。 > **v0.7.20** — 强化了长时间运行的 IMAP 和新邮件轮询路径： > IMAP 连接现在使用显式连接/问候/套接字/操作超时，重置卡住的连接，并报告 TLS 身份验证后失败，带有账户特定的修复指导。`get_new_emails` 现在在候选收集和水合期间应用每个账户的超时，因此一个挂起的账户不会阻止所有账户的轮询；部分超时失败与成功账户的邮件一起返回。 > > **v0.7.19** — 强化了微软图搜索返回的 Outlook ID 处理，当 `/me/messages/{id}` 拒绝作为格式错误的 ID 时：`search_emails` 现在返回一个可翻译的只读不可变 ID（如果可用），并且 `read_email` 通过 `translateExchangeIds` 重试格式错误的 ID，然后再失败。`list_emails` 也会从本地化的文件夹显示名称（例如 `Éléments envoyés`）回退到匹配的图文件夹 ID。 > > **v0.7.18** — `search_emails` 现在可以省略 `account` 以并行搜索所有注册的账户，返回带有账户注释的结果以及每个账户的错误，而不丢弃成功的匹配。所有账户的 `get_new_emails` 轮询也收集并水合每个账户的批次并行，同时保留全局最旧优先的限制。 > > **v0.7.17** — 强化了 `list_emails` 和 `search_emails` 返回的 Outlook 消息 ID：Outlook 读取现在请求微软图的不可变 ID，`search_emails` 探测结果并标记过时/未找到的消息为 `stale: true`，并且 `read_email` / `read_attachment` 为旧 ID 保留一个遗留的可变 ID 回退。图错误现在包括可用的结构化诊断详细信息。 > > **v0.7.16** — 成功创建草稿后强化了 `draft_email`：如果保存后读取失败，该工具现在返回创建的草稿 ID，带有 `warning` 和 `draftReadbackError`，而不是在错误后面丢失草稿。撰写操作还发出消毒的 `HYPERMAIL_DEBUG` 阶段日志，IMAP 草稿现在使用服务器宣传的 `\\Drafts` 邮箱（如果存在），并且 CLI 支持 `--version`。 > > **v0.7.15** — 强化了 IMAP 草稿创建：草稿现在直接追加到草稿邮箱，如果 IMAP 服务器拒绝标记为旗帜的 APPEND，则重试不带 `\\Draft` 标志的操作，并像 `send_email` 一样在草稿中保留 IMAP 回复/转发上下文。单个账户的 IMAP 操作序列化以避免共享连接竞争，并且 IMAP 写失败现在包括安全的服务器响应详细信息，而不仅仅是“命令失败”。账户设置响应不再暴露存储的提供程序令牌/密码。同时拒绝多行纯文本作为 `format: "html"` 传递，并添加 Hermes `get_new_emails` 轮询器示例。 > > **v0.7.14** — 增加了可选的 `HYPERMAIL_DEBUG` 结构化 stderr 日志，带有服务器启动、账户存储锁定/检查点写入和 `get_new_emails` 候选/声明流的删除。强化了 Outlook `edit_draft` 正文更新，通过请求图的更新表示、重新读取并重试、并在请求的正文更改不可观察时返回错误；Outlook 正文编辑在最终读取过时时还会进行一次安全的重放。 > > **v0.7.13** — 强化了 `get_new_emails` 以防止多个 MCP 进程共享相同的加密账户存储时重复投递。存储写入现在在跨进程锁下重新加载和合并，检查点是单调的，新邮件批次在返回前原子性地声明。`trash_email` 还使用 Gmail 和 IMAP 垃圾邮件别名的提供程序原生垃圾邮件操作。 > > **v0.7.12** — 强化了 Outlook 回复/转发草稿格式，当微软图标记生成的线程历史记录为 HTML 但返回纯/非结构化文本时。这样的历史记录现在进行防御性规范化，带有转义的内容和换行符，以便引用的消息保持可读。 > > **v0.7.11** — 通过转义和修补草稿为 HTML，解决了 Outlook 回复/转发草稿的引用的正文为纯文本的问题，新编写的 HTML 回复不再渲染为原始文本。 > > **v0.7.10** — 修复了一个账户存储竞争，其中 Gmail/Outlook 令牌刷新可能会覆盖 `get_new_emails` 检查点。检查点更新现在保留令牌数据，并在同一时间戳合并传递的 ID。`edit_draft` 正文编辑现在需要精确的选定部分替换（`old_text` + `new_text`），以便保留回复/转发历史记录而不是覆盖它。 > > **v0.7.9** — 用基于拉取的 `get_new_emails` 工具替换了服务器端邮件监视/网络钩子/脚本投递。代理计划自己的重复调用并获取有界的新收件箱邮件批次。 > > **v0.7.8** — 默认 Gmail 环回重定向 URI 从随机端口 `/oauth2callback` 更改为固定 `http://127.0.0.1:33333/callback`（仍然可以通过 `HYPERMAIL_GMAIL_REDIRECT_URI` 覆盖）。`.data/` 加密密钥目录添加到 `.gitignore`。 > > **v0.7.7** — 仅限环境的配置。运行时配置现在来自扁平的 `HYPERMAIL_*` 环境变量和选定的 CLI 覆盖。配置文件的配置和遗留提供程序环境名称不再读取。托管 Gmail OAuth 回调通过 `HYPERMAIL_GMAIL_REDIRECT_URI` 支持；本地环回和手动完成仍然有效。 > > **v0.7.6** — Gmail 设置使用 OAuth 授权 URL 而不是 Google 的废弃设备代码流用于 Gmail API 范围。`complete_add_account` 接受最终的重定向 URL 或原始 `code`/`state`，并且提供程序凭据使用专用的 `HYPERMAIL_GMAIL_*` / `HYPERMAIL_OUTLOOK_*` 环境变量。 > > **v0.7.5** — 通过 `send_email`/`draft_email`（`attachments` 参数）上的文件路径附加文件。`edit_draft` 获得 `new_attachments` 和 `remove_attachments` — `add_attachment_to_draft` 被删除（23 个工具现在）。草稿编辑使用多策略线程边界检测，以实现更可靠的引用线程保留。发布的 CLI 安装 MCP SDK 依赖项，以便全局/npx 运行不会因缺少的 SDK 模块而失败。 > > **v0.7.4** — `inReplyTo` 现在是 `send_email` 和 `draft_email` 上的必填参数（以前是可选的）。将其设置为 `false` 以创建新邮件，或传递消息 ID 以线程回复。这强制代理做出明确的选择，而不是静默地将回复视为新对话。 > > **v0.7.3** — `edit_draft` 现在在编辑 Outlook 回复/转发草稿时保留引用的线程历史记录。以前，编辑草稿正文会覆盖整个内容 — 包括引用的线程。现在，只有答案部分（在分隔符上方）被替换。 > > **v0.7.1** — 现在每个配置字段都可以通过专用的 `HYPERMAIL_*` 环境变量设置。遗留提供程序环境变量不再被接受。有关完整参考，请参见[环境变量](#环境变量)。 > > **v0.6.3** — 将stdio和HTTP模式统一为一个功能集。删除了电子邮件监视（收件箱轮询、SSE推送、通知缓冲区）、代理多租户（`agents.yaml`、`x-api-key`身份验证、每个代理的允许列表）和`check_notifications`工具。删除了`js-yaml`依赖项。Dockerfile简化为单个`install → build → prune`步骤。 > > **v0.6.2** — 版本真实性修复：`version.ts`现在直接从`package.json`导入，而不是硬编码版本号，防止两个文件之间的版本漂移。 > > **v0.6.1** — Docker部署（独立的Dockerfile，带有健康检查）、电子邮件通知错误修复（基于ID的去重、分页上限、动态重新扫描）、Node 22基础镜像、废弃docker-compose。 > > **v0.5.0** — 在`send_email`、`draft_email`和`edit_draft`上用必需的`format`参数（`"html"` | `"markdown"`）替换了可选的`isHtml`布尔值。 Markdown 正文通过`marked`转换为HTML，以便收件人始终看到干净的HTML。 > > **v0.4.3** — 升级到Zod v4.4.3。通过将所有工具模式包装在`z.object()`中，并替换导致`validateToolOutput`崩溃的区分联合输出模式，修复了MCP SDK v1.29.0兼容性。 代理不关心地址是工作 Outlook 账户、个人 Microsoft 账户、个人 IMAP 邮箱还是 Gmail — 它只是调用 `list_emails`、`search_emails`、`read_email`、`send_email` 并将电子邮件地址作为 `account` 参数传递。服务器会路由到正确的后端。 **v1 状态：** Outlook / Microsoft 365（个人 + 工作）通过 Microsoft Graph 完全支持。IMAP（任何 IMAP 服务器）通过 `imapflow` + `nodemailer` 支持。Gmail 通过 Google OAuth 授权码流与本地环回或托管回调以及远程安全手动完成支持。 ## 为什么 - 现有的 Outlook/M365 MCP 服务器（例如 `@softeria/ms-365-mcp-server`）公开约 200 个原始 Graph 端点，并且与单个已登录用户绑定。 - 该项目包装相同的经过验证的堆栈（`@azure/msal-node` 用于身份验证，`@microsoft/microsoft-graph-client` 用于 HTTP），但公开一个小型、提供者无关的电子邮件 API，并支持 **多个帐户**，按电子邮件地址键控。 ## 安装 / 运行 ```bash npm install -g hypermail-mcp # 或 pnpm / npx hypermail-mcp --help ``` 作为 stdio MCP 服务器运行（默认）- 将其连接到您的 MCP 主机： ### Claude Desktop / Claude Code ```jsonc { "mcpServers": { "hyper-email": { "command": "npx", "args": ["-y", "hypermail-mcp"] } } } ``` 或通过 CLI： ```bash claude mcp add hypermail -- npx -y hypermail-mcp ``` ### 作为托管的 HTTP 服务器 ```bash hypermail-mcp --http --port 3000 --host 0.0.0.0 # 端点：http://<host>:3000/mcp （可流式传输的 HTTP 传输，带有会话感知） ``` 当托管时，设置 `HYPERMAIL_KEY` 以便账户文件在重启和重新部署之间可重复解密。 ### Docker ```bash # 构建 docker build -t hypermail-mcp . # 运行 # 从您的 shell 或部署环境传递秘密值；不要提交它们。 docker run -d \ --name hypermail-mcp \ -p 3000:3000 \ -e HYPERMAIL_KEY \ -e HYPERMAIL_OUTLOOK_CLIENT_ID \ -e HYPERMAIL_OUTLOOK_TENANT_ID \ -v hypermail-data:/var/lib/mcp \ hypermail-mcp ``` 镜像在端口 3000 上以 HTTP 模式运行，并带有 30 秒的健康检查 `/mcp`。数据通过 Docker 卷在 `/var/lib/mcp` 处持久化。 ### 开发 要在本地测试 HTTP 服务器： ```bash # 终端 1：自动重新构建 TypeScript 以保存 pnpm dev # 终端 2：使用环境变量/CLI 配置启动 HTTP 服务器 pnpm dev:http ``` 服务器监听 `http://127.0.0.1:3000/mcp`。 ## 运行时和提供者配置 Hypermail 使用扁平的 `HYPERMAIL_*` 环境变量作为真实来源。没有运行时配置文件。CLI 标志仅覆盖单个调用的传输、主机、端口和数据目录。 CLI 标志：`--http`、`--port`、`--host`、`--data-dir`、`--version`、`--help`。 子命令：`hypermail-mcp generate-key` — 为 `HYPERMAIL_KEY` 生成基于 64 位的 32 字节密钥。 ### 本地 CLI / 环境示例 ```bash export HYPERMAIL_KEY="$(hypermail-mcp generate-key)" export HYPERMAIL_DATA_DIR="$HOME/.local/share/hypermail-mcp" export HYPERMAIL_OUTLOOK_CLIENT_ID="<your-client-id>" hypermail-mcp ``` ### 通用 MCP 客户端 JSON 示例 ```jsonc { "mcpServers": { "hypermail": { "command": "npx", "args": ["-y", "hypermail-mcp"], "env": { "HYPERMAIL_KEY": "${HYPERMAIL_KEY}", "HYPERMAIL_DATA_DIR": "${HYPERMAIL_DATA_DIR}", "HYPERMAIL_OUTLOOK_CLIENT_ID": "${HYPERMAIL_OUTLOOK_CLIENT_ID}" } } } } ``` ### 环境变量 | 环境变量 | 目的 | 默认值 / 行为 | | --- | --- | --- | | `HYPERMAIL_DATA_DIR` | 账户/令牌存储位置 | `${XDG_DATA_HOME:-~/.local/share}/hypermail-mcp` | | `HYPERMAIL_KEY` | 32 字节 AES-256-GCM 密钥作为十六进制/ base64，或通过 SHA-256 派生的任何口令 | 如果未设置，则生成并持久化本地密钥并打印启动警告 | | `HYPERMAIL_TRANSPORT` | 运行时传输：`stdio` 或 `http` | `stdio`；`--http` 覆盖为 `http` | | `HYPERMAIL_HTTP_PORT` | HTTP 绑定端口 | `3000`；无效的 HTTP 模式值会警告并回退 | | `HYPERMAIL_HTTP_HOST` | HTTP 绑定主机 | `127.0.0.1`；无效的 HTTP 模式值会警告并回退 | | `HYPERMAIL_OUTLOOK_CLIENT_ID` | 自定义 Azure/Entra 公共客户端 ID（可选） | 内置公共客户端 | | `HYPERMAIL_OUTLOOK_TENANT_ID` | Outlook 租户/权限选择器（可选） | `common` | | `HYPERMAIL_GMAIL_CLIENT_ID` | Google OAuth 客户端 ID | 添加 Gmail 账户时需要 | | `HYPERMAIL_GMAIL_CLIENT_SECRET` | Google OAuth 客户端秘密，当由客户端类型颁发时 | 未设置 | | `HYPERMAIL_GMAIL_REDIRECT_URI` | 托管 Gmail OAuth 回调 URI | 未设置时使用本地环回回调 | | `HYPERMAIL_TOOLS_ENABLED` | 以逗号分隔的工具允许列表 | 空/未设置表示无过滤 | | `HYPERMAIL_TOOLS_DISABLED` | 以逗号分隔的工具阻止列表 | 空/未设置表示无过滤 | | `HYPERMAIL_DEBUG` | 启用结构化调试日志到 stderr（`1`、`true`、`yes`、`on` 或 `debug`） | 默认情况下禁用 | **优先级顺序：** 选择的 CLI 标志 > `HYPERMAIL_*` 环境变量 > 硬编码默认值。 每个工具的过滤（`HYPERMAIL_TOOLS_ENABLED` / `HYPERMAIL_TOOLS_DISABLED`）允许操作员提供最小的面向代理的界面。如果两个非空列表都被设置，或者任一列表包含未知工具名称，则启动失败。 ## 工具 所有"电子邮件"工具都需要一个`account`参数——要操作的邮箱地址。服务器从加密的账户存储中解析出正确的提供商。 | 工具 | 输入 | 备注 | | --- | --- | --- | | `list_accounts` | — | 返回已注册的电子邮件 + 提供商，无密钥。 | | `add_account` | `provider`, `email?`, `config?` | 启动提供商添加流程。Outlook 返回设备代码；Gmail 返回 OAuth URL。准备好的账户响应仅包含公共元数据，从不返回存储的令牌/密码。返回 `{handle, verification:{type, userCode, verificationUri, expiresAt, message}}` 以备待处理流程。 | | `complete_add_account` | `provider`, `handle`, `authorizationResponse?`, `code?`, `state?` | 返回 `pending` / `ready` / `expired` / `error`。准备好的账户响应仅包含公共元数据，从不返回存储的令牌/密码。Gmail 接受粘贴的最终重定向 URL 或原始代码/状态以进行远程安全完成。 | | `get_account_settings` | `account` | 获取账户的签名（HTML）和样式偏好。 | | `set_account_settings` | `account`, `signature?`, `signaturePath?`, `style?` | 设置签名 HTML（内联或通过文件路径）和字体偏好。 | | `remove_account` | `email` | 删除账户的令牌。 | | `list_emails` | `account`, `folder?`, `limit?`, `unreadOnly?`, `skip?` | 默认：folder=`inbox`, limit=25。通过 `skip` 支持分页——响应包含 `hasMore`。Outlook 接受已知的文件夹名称、文件夹 ID，并从本地化显示名称回退到匹配的文件夹 ID。 | | `get_new_emails` | `account?`, `limit?` | 拉取新的收件箱电子邮件，这些邮件以前未被此工具返回。`limit` 默认值为 10，当省略 `account` 时为全局。返回完整的 Markdown 正文和附件元数据；正文可能会被截断。 | | `search_emails` | `account?`, `query`, `limit?` | 搜索一个账户（提供 `account` 时）或省略它以并行搜索所有已注册的账户。返回账户注释的摘要和每个账户的部分错误。在 Outlook 上使用 KQL，并尽可能将格式错误的 Outlook 搜索结果 ID 归一化为可读的不可变 ID。 | | `read_email` | `account`, `id`, `format?` | 返回完整的正文 + 收件人 + 附件元数据。`format`：`markdown`（默认），`html` 或 `text`。Outlook 在失败之前通过 Graph ID 转换重试格式错误/过时的 ID。 | | `read_attachment` | `account`, `messageId`, `attachmentId` | 下载附件到临时文件并返回其路径。 | | `archive_email` | `account`, `id` | 将消息移动到存档文件夹。 | | `trash_email` | `account`, `id` | 将消息移动到已删除项（回收站）。 | | `move_email` | `account`, `id`, `destination` | 通过已知名称（`inbox`, `drafts` 等）或自定义文件夹 ID 移动到任何文件夹。 | | `send_email` | `account`, `to[]`, `cc?`, `bcc?`, `subject`, `body`, `format`, `include_signature`, `inReplyTo`, `replyAll?`, `forwardMessageId?`, `attachments?` | 发送电子邮件。`format`（`"html"` 或 `"markdown"`）控制正文格式——Markdown 通过 `marked` 转换为 HTML；多行纯文本且 `format: "html"` 被拒绝，因此对于段落或添加标签（如 `<p>`/`<br>`）使用 `"markdown"`。当 `include_signature` 为真时，追加签名。`inReplyTo` 发送为线程回复；`forwardMessageId` 发送为转发。`inReplyTo` 是必需的——对于新电子邮件，设置为 `false`。`attachments` 是 `{filePath, name?}` 的可选数组——文件从磁盘读取并自动编码。 | | `draft_email` | `account`, `to[]`, `cc?`, `bcc?`, `subject`, `body`, `format`, `include_signature`, `inReplyTo`, `replyAll?`, `forwardMessageId?`, `attachments?` | 保存为草稿而不是发送。参数与 `send_email` 相同，包括 `attachments`。返回草稿消息 ID 和（当成功读取时）HTML 正文（`draftHtml`）。如果草稿已创建但读取失败，返回草稿 ID 和 `warning` 和 `draftReadbackError`，以便调用者可以重试 `read_email` 或继续使用 `send_draft`。`inReplyTo` 是必需的——对于新电子邮件，设置为 `false`。 | | `edit_draft` | `account`, `id`, `to?`, `cc?`, `bcc?`, `subject?`, `old_text?`, `new_text?`, `body?`, `format?`, `include_signature?`, `new_attachments?`, `remove_attachments?` | 通过 ID 编辑现有草稿。主体编辑需要精确的选定部分替换：从当前草稿 HTML（`draftHtml` 或 `read_email` 且 `format: "html"`）复制 `old_text` 并提供 `new_text`；匹配必须恰好发生一次，并且保留未选定的内容，例如回复/转发历史。已弃用的 `body` 仅在提供 `old_text` 时是 `new_text` 的别名；仅限正文的完整替换被拒绝。多行纯文本替换且 `format: "html"` 被拒绝；对于段落或添加标签（如 `<p>`/`<br>`）使用 `"markdown"`。保存后重新读取正文编辑；如果更新后的正文在重试后不可观察，工具返回错误而不是报告成功。`new_attachments` 添加文件（`{filePath, name?}[]`）；`remove_attachments` 通过附件 ID（`string[]`）删除。返回更新的草稿 ID、HTML 正文（`draftHtml`）和附件元数据。 | | `send_draft` | `account`, `id` | 通过 ID 发送现有的草稿电子邮件。与 `draft_email` 或 `edit_draft` 返回的草稿 ID 一起使用。 | | `list_folders` | `account`, `parentFolderId?` | 列出可用的邮件文件夹。默认返回顶级文件夹，或 `parentFolderId` 的子文件夹。 | | `create_folder` | `account`, `displayName`, `parentFolderId?` | 在根目录（默认）或给定父目录下创建新的邮件文件夹。 | | `delete_folder` | `account`, `folderId` | 通过 ID 删除邮件文件夹。 | | `rename_folder` | `account`, `folderId`, `newName` | 重命名现有的邮件文件夹。 | | `mark_read` | `account`, `id` | 将消息标记为已读。 | | `mark_unread` | `account`, `id` | 将消息标记为未读。 | ## 拉取新邮件 `get_new_emails` 是服务器端监视/推送交付的替代方案。服务器不运行后台 cron 作业；代理或其工具包按自己的计划调用此工具，例如每 30-60 秒。 **行为：** - 仅轮询 **收件箱**。 - `account` 是可选的。当省略时，工具检查所有已注册的账户。 - `limit` 默认值为 `10`。在所有账户模式下，限制是账户之间的全局总数，首先按 `receivedAt` 最旧的排序。 - 所有账户轮询并行执行每个账户的候选收集和水合，然后按旧到新的顺序返回组合批次。 - 首次使用账户时，会初始化其检查点到最新的收件箱邮件，并为该账户返回没有邮件。 - 后续调用返回以前未被此工具返回的邮件，按时间顺序排列。 - 返回的正文是 Markdown，可能在 20k 个字符周围被截断；当需要时调用 `read_email` 获取完整正文。 - 附件仅作为元数据返回；调用 `read_attachment` 获取内容。 - 工具不会将邮件标记为已读。 - `limit: 0` 可以初始化/检查状态而无需获取消息正文。 所有账户调用返回部分失败作为 `errors: [{ account, message }]`，并且仍然返回成功的账户邮件。轮询者应该继续处理返回的邮件，即使 `errors` 为非空，并使用这些条目通知或记录哪些账户正在失败。 有关 Hermes 调度器集成的示例，请参阅 [`examples/hermes/`](examples/hermes/)，它轮询此工具并将新邮件有效负载交给 Hermes 代理。 ## 添加账户流程 ### Outlook 1. 代理调用 `add_account({ provider: "outlook" })`。 2. 服务器返回： ```json { "status": "pending", "handle": "…uuid…", "verification": { "type": "device_code", "userCode": "ABCD-EFGH", "verificationUri": "https://microsoft.com/devicelogin", "expiresAt": "2025-…", "message": "To sign in, use a web browser to open …" } } ``` 3. 用户打开 URL 并输入代码。 4. 代理轮询 `complete_add_account({ provider: "outlook", handle })` 直到 它返回 `{ "status": "ready", "account": {...} }`。 5. 从那时起，可以使用 `account: "<that-email>"` 调用任何工具。 ### IMAP IMAP 账户通过主机/用户/密码设置同步添加。如果服务器接受 TCP/TLS 但在登录期间关闭，Hypermail 报告 IMAP 身份验证失败。检查邮箱密码或应用密码，确认提供商启用 IMAP 访问，然后重新添加或更新账户。 ### Gmail Gmail 使用 Google OAuth 2.0，与官方 Gmail MCP 模型匹配。Google 的设备代码端点拒绝 Gmail API 范围，因此 Hypermail 使用带有真实回调的授权 URL。服务账户仅适用于 Google Workspace 域范围的委托；它们不授予服务器到服务器访问消费者 `@gmail.com` 收件箱。 对于本地 stdio/Desktop OAuth 客户端，Hypermail 自动启动一个临时的 `127.0.0.1` 回路回调服务器。对于托管的 HTTP 部署，设置 `HYPERMAIL_GMAIL_REDIRECT_URI` 并在 Google Auth 平台上注册确切的 URI，例如： ```bash HYPERMAIL_TRANSPORT=http HYPERMAIL_GMAIL_REDIRECT_URI=https://mail.example.com/oauth/gmail/callback ``` 1. 配置 `HYPERMAIL_GMAIL_CLIENT_ID` 和（当由您的 Google 客户端类型颁发时）`HYPERMAIL_GMAIL_CLIENT_SECRET`。为本地回路使用桌面客户端，或为托管的 HTTP 回调使用 Web 客户端。 2. 代理调用 `add_account({ provider: "gmail" })`。 3. 服务器返回一个 OAuth URL： ```json { "status": "pending", "handle": "…uuid…", "verification": { "type": "oauth_url", "userCode": "", "verificationUri": "https://accounts.google.com/o/oauth2/v2/auth?...", "expiresAt": "2025-…", "message": "Open this URL in a browser to authorize Gmail access..." } } ``` 4. 用户打开 `verificationUri` 并授予访问权限。如果可达的回调已配置，浏览器显示一个小成功页面，代理可以轮询 `complete_add_account({ provider: "gmail", handle })` 直到准备就绪。 5. 如果浏览器无法访问回调，仍然可以使用手动回退：复制浏览器的最终重定向 URL 并调用： ```json { "provider": "gmail", "handle": "…uuid…", "authorizationResponse": "http://127.0.0.1:54321/oauth2callback?code=...&state=..." } ``` 6. `complete_add_account` 验证状态，交换代码获取令牌，存储账户，并返回 `{ "status": "ready", "account": {...} }`。 ## 路线图 - 线程/对话。 - 日历集成。 ## 项目布局 ``` src/ cli.ts # 参数解析 + 入口 server.ts # MCP 服务器，stdio + HTTP 传输，会话管理 version.ts # 版本常量 config.ts # 仅限环境配置类型 + 解析 store/ account-store.ts # 加密的多账户存储（AES-256-GCM） crypto.ts # AES-256-GCM 加密/解密，密钥解析，原子写入 providers/ types.ts # 电子邮件提供商接口 + 共享 DTO registry.ts # 路由账户电子邮件 → 提供商 outlook/ auth.ts # msal-node 设备代码流程 client.ts # @microsoft/microsoft-graph-client 工厂 index.ts # Outlook 提供商实现 imap/index.ts # IMAP 提供商（imapflow + nodemailer） gmail/ auth.ts # Google OAuth 授权码流程 client.ts # Gmail API（googleapis） index.ts # Gmail 提供商实现 shared/ # 提供商间的共享实用程序 tools/ index.ts # MCP 工具注册 accounts.ts # list/add/remove/complete-add 账户工具 browse.ts # list/search/read 电子邮件工具 new-emails.ts # get_new_emails 拉取/检查点工具 compose.ts # send/draft/edit/send-draft 工具 folders.ts # list/create/delete/rename 文件夹工具 organize.ts # archive/trash/move/mark-read/mark-unread 工具 shared.ts # 共享工具帮助程序 ``` ## 许可证 MIT