jmap-mcp 是一个模型上下文协议（MCP）服务器，用于与 JMAP（JSON Meta Application Protocol）邮件服务器交互。它使用 Deno 构建，底层使用 jmap-jam 客户端库。
用途 该仓库是一个 Deno workspace，包含一个可用的 JMAP 邮件客户端，以及构建在该客户端之上的 MCP 服务器。客户端包通过 jmap-jam 访问 JMAP 协议；MCP 包将那些带类型的操作适配为可调用的工具，供支持 MCP 的智能体使用。
主要能力 邮件管理工具：
- 搜索邮件：支持文本查询、发件人/收件人过滤、日期范围与关键词；所有过滤条件以 AND 组合。
- 获取邮件：按 ID 获取指定邮件，并可配置返回的属性集合。
- 获取邮件会话：获取邮件线程（对话链）。
- 标记邮件：标记为已读/未读、已加旗标/未加旗标。
- 移动邮件：将邮件移动到一个邮箱。
- 调整邮件邮箱归属：添加或移除所选邮箱成员关系，同时保留未指定的成员关系。
- 删除邮件：永久删除邮件。
邮箱管理：
- 获取邮箱：列出所有邮箱/文件夹并支持层级结构，可用于查找其他工具所需的邮箱 ID。
增量同步：
- 获取邮件变更：根据上一次状态，获取自那时起被创建、更新或销毁的邮件 ID（基于状态的增量跟踪）。
- 获取搜索更新：获取上一次搜索查询在其 queryState 之后新增或移除的邮件。
邮件撰写：
- 发送邮件：撰写并发送新邮件，支持纯文本与 HTML。
- 回复邮件：回复已有邮件，自动处理头部并支持 reply-all。
关键特性还包括：通过 jmap-jam 完整遵循 JMAP RFC 8620/8621；使用 Zod 模式进行全面输入校验；所有列表操作支持分页；基于状态的增量同步以实现高效轮询；完善的错误处理与连接管理；基于能力的工具注册（只读、提交）；强类型的 TypeScript 支持。
使用方式 环境要求：Deno v2 或更高版本；一个符合 JMAP 的邮件服务器（例如 Cyrus IMAP、Stalwart Mail Server、FastMail）；有效的 JMAP 认证凭据。
推荐通过插件市场安装 Claude Code 插件，然后在 MCP 服务器设置中配置所需的环境变量。也可以将配置添加到你所选择的智能体中；若非使用 FastMail，请将 --allow-net 中的 api.fastmail.com 替换为你的 JMAP 服务器主机名。
客户端可复用：独立应用可以直接导入 @wyattjoh/jmap，而无需创建 MCP 服务器或传输层；参见 packages/jmap/README.md。
工具概览（节选说明）
- get_mailboxes：列出邮箱/文件夹及其 ID、名称与元数据。应先调用以获取 search_emails（inMailbox）和 move_emails（mailboxId）所需的邮箱 ID。常用名称：Inbox、Drafts、Sent、Trash、Archive、Spam/Junk。可选参数 parentId（按父邮箱 ID 过滤）、limit（1-200，默认 100）、position（分页起始位置）。
- search_emails：带过滤条件搜索邮件，所有条件以 AND 组合，只返回邮件 ID——需用 get_emails 获取内容。结果包含 queryState，可用于通过 get_search_updates 做增量同步。可选参数包括 query、body、from、to、subject、inMailbox、hasKeyword、notKeyword、allInThreadHaveKeyword、someInThreadHaveKeyword、before、after、limit（1-100，默认 50）、position（默认 0）。
- get_emails：按 ID 获取指定邮件，建议用 properties 只请求所需字段，避免拉取全部属性导致载荷过大。ids 为邮件 ID 数组（1-50）。推荐属性集合：摘要 ["id", "subject", "from", "to", "receivedAt", "preview"]；完整读取 ["id", "subject", "from", "to", "cc", "receivedAt", "bodyValues", "textBody", "htmlBody"]。注意获取正文需同时包含 bodyValues 与 textBody/htmlBody。
- get_threads：按 ID 获取邮件会话。会话 ID 来自 get_emails 响应中的 threadId 属性。返回每个会话中的邮件 ID，再对这些 ID 调用 get_emails 获取内容。ids 为会话 ID 数组（1-20）。
- get_email_changes：获取自上次状态以来被创建、更新或销毁的邮件 ID，使用来自 get_emails 响应的 state 字符串。参数：sinceState；可选 maxChanges（1-500）、fetchEmails（默认 false，自动获取变更 ID 的完整邮件详情）、properties（当 fetchEmails 为 true 时获取的属性）。
- get_search_updates：获取上一次搜索查询在 queryState 之后的变化，必须使用与最初 search_emails 调用相同的过滤参数。参数：sinceQueryState，以及 search_emails 的全部过滤参数（须与原始查询一致）。
- mark_emails：将邮件标记为已读/未读或已加旗标/未加旗标。参数：ids（1-100）、seen（true 已读 / false 未读）、flagged（true 已加旗标 / false 未加旗标）。
- move_emails：将邮件移动到另一个邮箱，可用 get_mailboxes 查找目标邮箱 ID。参数：mailboxId。
- patch_email_mailboxes：添加或移除所选邮箱成员关系而不替换未指定的成员关系，支持类似标签的工作流与复合分类。参数：addMailboxIds、removeMailboxIds；至少需添加或移除一个邮箱，且同一邮箱不能同时出现在两个数组中。
- delete_emails：永久删除邮件（不可撤销）。如需可恢复删除，建议先用 move_emails 移到 Trash。
- send_email：发送新邮件，必须提供 textBody 或 htmlBody（或两者）。参数：to（收件人数组，name 可选、email 必填）、cc、bcc、subject、textBody、htmlBody、identityId（可选，用于指定发送身份，省略则使用服务器默认）。
- reply_email：回复已有邮件，自动设置 To/CC、Re: 主题前缀以及线程头部（In-Reply-To、References）。参数：emailId、replyAll（默认 false）、subject（可选，默认 Re: <原始主题>）。
JMAP 服务器兼容性 可与任何符合 JMAP 的邮件服务器配合使用，包括：Cyrus IMAP 3.0+、Stalwart Mail Server、FastMail（商业）、Apache James（支持 JMAP 时）。
开发与结构 仓库是 Deno workspace，包含两个可独立发布的包：
- packages/jmap / @wyattjoh/jmap：功能性的连接、检索、增量同步、变更与提交操作。
- packages/jmap-mcp / @wyattjoh/jmap-mcp：MCP 模式、工具适配器、能力注册与 stdio 入口点。 MCP 适配器直接调用客户端包。JMAP 行为属于客户端包；传输层校验与面向用户的工具契约属于 MCP 包。
安全方面：所有输入使用 Zod 模式校验；敏感配置通过环境变量传入；不在日志或响应中记录或暴露密钥；遵循 JMAP 安全最佳实践。
贡献方式：Fork 仓库，创建功能分支，按函数式编程风格进行修改，充分测试后提交拉取请求。
许可证：MIT，详见 LICENSE 文件。
相关项目：jmap-jam（JMAP 客户端库）、Model Context Protocol（MCP 规范）、JMAP RFC 8620（JMAP 核心协议）、JMAP RFC 8621（JMAP for Mail）。
