Mailbird MCP

你可访问一个本地的 Mailbird MCP 服务器，该服务器暴露了用户真实的邮箱账户、文件夹、会话（邮件往来线程）、草稿及附件。该服务仅在用户本机的 Mailbird 桌面应用中运行，绑定地址为 127.0.0.1 —— 不存在远程部署版本。

最重要的一条规则：凡涉及电子邮件、收件箱、消息、草稿、联系人、附件、文件夹或发送操作的任务——即使用户表述得非常随意（例如：“查看我的收件箱”“X 有回复了吗？”“为那张发票起草一封回信”“找到 Mira 发来的那个邮件线程”）——请**优先使用这些工具**。切勿通过 grep 扫描本地文件系统，切勿直接读取源码，切勿凭猜测作答。该服务器是唯一可信的数据源。

配置方式

用户需在 Mailbird 中手动启用 MCP 服务器，路径为： 设置 → Wingman AI → 启用 MCP 服务器。

该设置页同时提供以下信息：

• Bearer Token（含“复制”按钮）。
• 终端地址（http://127.0.0.1:/mcp，端口号显示在状态栏旁）。
• “允许写入操作”开关——所有写入类工具均需此开关开启后方可生效。

若连接失败，请提示用户确认该开关已开启，并确认已复制当前有效的 Token。每次禁用并重新启用 MCP 服务器时，Token 均会刷新生成。

配置（环境变量）

两项均为可选；单用户本地安装场景下，默认值即可正常工作。

安全模型

该能力赋予 Agent 对用户完整邮箱的访问权限：包括邮件正文、附件、联系人，以及在“允许写入操作”开启后的发信能力。请严格保护 URL 与 Token：

• Mailbird MCP 服务器仅绑定环回地址（127.0.0.1）。禁止代理、端口转发或隧道方式将其暴露至公网地址；禁止将 URL 或 Token 粘贴至任何非本机运行的远程/云端 Agent（即不在同一台运行 Mailbird 的机器上）。
• Token 等效于邮箱登录凭证。禁止在聊天记录中回显、禁止提交至代码仓库、禁止出现在截图中、禁止包含在 Bug 报告内。一旦 Token 泄露，请立即禁用并重启服务器以触发刷新。
• 写入操作（归档、移入废纸篓、发送等）需用户在 Wingman AI 设置页中开启“允许写入操作”。此外，发送操作还需每次调用时显式传入 confirm: true 参数。该能力在执行发送前，必须始终向用户展示草稿内容并获得明确确认。
• Mailbird 提供可选的MCP 请求审计日志功能，会将每一次请求（方法名 + 参数，不含响应体）记录至本地文件，供用户自行检查。建议用户启用该功能以提升操作可见性。

会话启动检查清单

首次在本次会话中调用服务器前（执行任何实质性操作之前），请务必完成以下步骤：

1. 通过 resources/read 读取 mailbird://help。这是权威用户指南，涵盖 ID 模型、写入工具门控机制、发送流程、搜索索引延迟、归档→还原逻辑、附件处理、内嵌图片（cid:）等关键主题。快速通读一次，熟记常用操作模式。
2. 调用 list_accounts，获取已配置账户的 ID 列表。
3. 如需按文件夹范围操作，请先调用 list_folders(accountId)，并依据 identity 字段选取目标文件夹（如 Inbox、Sent、Drafts、Trash、Spam、Archived、AllMail、Generic（用户自建））。注意：文件夹 ID 在不同账户间不具稳定性。list_accounts 不返回收件箱文件夹 ID，请始终通过 list_folders 发现。

读取类工具（始终可用）

• list_accounts — 返回账户列表，含 ID、发件人名称、邮箱地址、未读数。
• list_folders(accountId) — 返回指定账户下的全部文件夹。
• list_conversations(folderId, limit?, unreadOnly?, starredOnly?, importantOnly?) — 获取某文件夹中最近的会话列表。
• get_conversation(conversationId, folderId) — 返回单个会话（邮件线程）的消息列表及其元数据。
• get_message(messageId) — 返回完整邮件正文；其中 cid: 内嵌图片 URI 已重写为 mailbird://messages/{messageId}/attachments/{attachmentId} 格式的资源地址。
• get_unread_counts(accountId? | folderId?) — 快速获取未读统计信息。
• search_conversations(query, accountId?, folderId?) — 使用 Mailbird 搜索语法（如 from:foo subject:bar）。结果中包含 actualFolders[] 字段，请使用其中的文件夹 ID 对命中项执行后续操作，切勿使用虚拟 ID（如 folderId: -2）。
• list_attachments(messageId) / get_attachment_status(...) / get_attachment_content(...)。
• get_send_status(messageId) — 返回发送状态：sent / draft_pending_send / scheduled / trashed。

写入类工具（受“允许写入操作”开关管控）

• archive_conversation、trash_conversation、move_conversation、move_conversation_to_inbox。
• mark_conversation_as_read / unread、flag_conversation_important、star_conversation / unstar_conversation、mark_conversation_as_spam / unmark_conversation_as_spam、snooze_conversation(wakeAtUtc)。
• create_draft(accountId, to, cc?, bcc?, subject, body, attachments?) — 创建草稿并返回 messageId。该操作不会发送邮件。
• update_draft(messageId, ...) — 更新已有草稿的任意字段。
• reply_to_conversation、reply_all_to_conversation、forward_conversation — 创建带标准引用结构的草稿，并返回 messageId。该操作不会发送邮件；正文内容需由你最终完善。
• send_message_now(messageId | accountId+to+...; confirm: true) — 实际执行发送。**务必先向用户展示草稿并获得明确批准。** 返回 status: "queued" 及 deliveryState 字段（反映 IMAP/SMTP 连接健康状态）。
• unsubscribe_from_newsletter(messageId) — 利用 List-Unsubscribe 邮件头执行退订。在不适用或已退订等情形下，返回结构化结果：not_applicable / already_unsubscribed。
• delete_conversation_permanently — 仅适用于当前位于“废纸篓”或“垃圾邮件”文件夹中的会话。若会话位于其他位置，请先移入废纸篓，再重新发现其新 ID，然后对该废纸篓副本调用本接口。

若某写入类工具返回错误，提示问题出在“允许写入操作”开关，请将原始错误信息原样呈现给用户——**不得重试**。

常见陷阱（易使疏忽的 Agent 出错）

1. 会话 ID 是按文件夹作用域唯一的。调用 trash_conversation、archive_conversation 或 move_conversation 后，该会话在目标文件夹中将拥有全新的 ID。如需链式调用后续操作，请先通过 list_conversations(folderId=) 重新发现 ID。而消息 ID（messageId）则跨文件夹保持稳定。
2. 搜索索引存在延迟（约 10–30 秒）。你刚刚发送或接收的邮件可能尚未进入 search_conversations 的结果中。对极新邮件，请优先使用 list_conversations(folderId=) 而非搜索。
3. 发送流程异步化。 send_message_now 会立即返回 status: "queued"。该邮件会在“草稿”文件夹短暂可见后才移入“已发送”，属正常现象。请使用 get_send_status 确认最终状态。
4. 归档目标文件夹依服务商而异。 Gmail 和支持标签（Labels）的 IMAP 账户归档至 AllMail；其余账户统一使用 Archived。每个账户中二者必居其一。完整的还原流程（list_folders → list_conversations → move_conversation_to_inbox）详见 mailbird://help。
5. get_message 中的内嵌（cid:）图片 已被重写为 mailbird://messages/.../attachments/... 格式 URI，需通过 resources/read 解析。响应中还附带 inlineAttachments 映射表。

回复操作模式

Agent 撰写回复的标准操作链如下：

1. reply_to_conversation(conversationId, folderId)        → messageId
2. update_draft(messageId, body: "<你的正文>")           # 保留引用结构
3. <向用户展示草稿，获取批准>
4. send_message_now(messageId, confirm: true)              → status: queued
5. （可选，约 5 秒后）get_send_status(messageId)        → status: sent

对于全新邮件（无历史线程），请直接使用 create_draft 并传入 to/subject/body/attachments，随后执行步骤 3–5。

应交由用户决策的情形

• “允许写入操作”尚未开启时，任何写入操作均需用户确认。
• 任何发送操作——必须展示草稿并获得用户明确批准。
• 从“废纸篓”或“垃圾邮件”以外的任意位置执行永久删除。
• 搜索未返回用户预期存在的内容（可能因索引延迟所致，建议提示用户稍候重试）。

当对服务商特定行为或边界情况存疑时，请再次查阅 mailbird://help —— 它是唯一权威参考来源。