Jmap MCP

🚀 JMAP MCP 服务器

JMAP MCP 服务器是一个模型上下文协议（MCP）服务器，它提供了与 JMAP（JSON 元应用协议）电子邮件服务器进行交互的工具。该服务器使用 Deno 构建，并采用了 @htunnicliff/jmap-jam 客户端库。

🚀 快速开始

在使用 JMAP MCP 服务器之前，你需要完成以下准备工作：

前提条件

• Deno v1.40 或更高版本
• 一个支持 JMAP 的电子邮件服务器（例如，Cyrus IMAP、Stalwart Mail Server、FastMail）
• 有效的 JMAP 认证凭证

安装设置

将以下内容添加到你选择的代理中：

{
  "mcpServers": {
    "fastmail": {
      "type": "stdio",
      "command": "deno",
      "args": [
        "run",
        "--allow-net=api.fastmail.com",
        "--allow-env=JMAP_SESSION_URL,JMAP_BEARER_TOKEN,JMAP_ACCOUNT_ID",
        "jsr:@wyattjoh/jmap-mcp@0.1.1"
      ],
      "env": {
        "JMAP_SESSION_URL": "https://api.fastmail.com/jmap/session",
        "JMAP_BEARER_TOKEN": "API_TOKEN"
      }
    }
  }
}

✨ 主要特性

电子邮件管理工具

• 搜索邮件：可以使用文本查询、发件人/收件人过滤、日期范围和关键词来搜索邮件。
• 获取邮件：通过邮件 ID 检索特定邮件的完整详细信息。
• 获取邮件线程：检索邮件线程（对话链）。
• 标记邮件：将邮件标记为已读/未读、已标记/未标记。
• 移动邮件：在不同邮箱之间移动邮件。
• 删除邮件：永久删除邮件。

邮箱管理

• 获取邮箱列表：列出所有邮箱/文件夹，并支持层级显示。

邮件撰写

• 发送邮件：支持撰写并发送纯文本和 HTML 格式的新邮件。
• 回复邮件：支持回复现有邮件，包括全部回复。

关键能力

• 通过 jmap-jam 完全符合 JMAP RFC 8620/8621 标准。
• 使用 Zod 模式进行全面的输入验证。
• 所有列表操作都支持分页。
• 提供丰富的错误处理和连接管理功能。
• 全程采用函数式编程模式。
• 支持 TypeScript 并具有强类型。

📦 安装指南

前提条件

• Deno v1.40 或更高版本
• 一个支持 JMAP 的电子邮件服务器（例如，Cyrus IMAP、Stalwart Mail Server、FastMail）
• 有效的 JMAP 认证凭证

安装步骤

将以下配置添加到你选择的代理中：

{
  "mcpServers": {
    "fastmail": {
      "type": "stdio",
      "command": "deno",
      "args": [
        "run",
        "--allow-net=api.fastmail.com",
        "--allow-env=JMAP_SESSION_URL,JMAP_BEARER_TOKEN,JMAP_ACCOUNT_ID",
        "jsr:@wyattjoh/jmap-mcp@0.1.1"
      ],
      "env": {
        "JMAP_SESSION_URL": "https://api.fastmail.com/jmap/session",
        "JMAP_BEARER_TOKEN": "API_TOKEN"
      }
    }
  }
}

💻 使用示例

环境变量

可用工具

search_emails

使用各种过滤器搜索邮件。 参数：

• query（可选）：文本搜索查询
• from（可选）：按发件人电子邮件地址过滤
• to（可选）：按收件人电子邮件地址过滤
• subject（可选）：按主题文本过滤
• inMailbox（可选）：在特定邮箱中搜索
• hasKeyword（可选）：按关键词过滤（例如，'$seen'、'$flagged'）
• notKeyword（可选）：排除特定关键词
• before（可选）：仅搜索指定日期之前的邮件（ISO 日期时间格式）
• after（可选）：仅搜索指定日期之后的邮件（ISO 日期时间格式）
• limit（可选）：最大结果数（1 - 100，默认值：50）
• position（可选）：分页起始位置（默认值：0）

get_emails

通过邮件 ID 检索特定邮件。 参数：

• ids：邮件 ID 数组（1 - 50 个 ID）
• properties（可选）：要返回的特定属性

get_mailboxes

获取邮箱/文件夹列表。 参数：

• parentId（可选）：按父邮箱过滤
• limit（可选）：最大结果数（1 - 200，默认值：100）
• position（可选）：分页起始位置

get_threads

通过线程 ID 获取邮件线程。 参数：

• ids：线程 ID 数组（1 - 20 个 ID）

mark_emails

使用关键词标记邮件（已读/未读、已标记/未标记）。 参数：

• ids：邮件 ID 数组（1 - 100 个 ID）
• seen（可选）：标记为已读（true）或未读（false）
• flagged（可选）：标记为已标记（true）或未标记（false）

move_emails

将邮件移动到不同的邮箱。 参数：

• ids：邮件 ID 数组（1 - 100 个 ID）
• mailboxId：目标邮箱 ID

delete_emails

永久删除邮件。 参数：

• ids：邮件 ID 数组（1 - 100 个 ID）

send_email

发送新邮件。 参数：

• to：收件人数组，包含 name 和 email。
• cc（可选）：抄送收件人数组。
• bcc（可选）：密送收件人数组。
• subject：邮件主题。
• textBody（可选）：纯文本邮件正文。
• htmlBody（可选）：HTML 格式邮件正文。
• identityId（可选）：发件身份。

reply_to_email

回复现有邮件。 参数：

• emailId：要回复的邮件 ID。
• replyAll（可选）：是否全部回复（默认值：false）。
• subject（可选）：自定义回复主题。
• textBody（可选）：纯文本回复正文。
• htmlBody（可选）：HTML 格式回复正文。
• identityId（可选）：发件身份。

📚 详细文档

JMAP 服务器兼容性

该服务器应能与任何支持 JMAP 的电子邮件服务器兼容，包括：

• Cyrus IMAP 3.0 及以上版本
• Stalwart Mail Server
• FastMail（商业版）
• Apache James（支持 JMAP）

开发

开发环境运行

deno run --allow-env --allow-net --watch src/mod.ts

测试

# 测试连接
deno run --allow-env --allow-net src/mod.ts

架构

该服务器使用以下技术构建：

• Deno：现代 JavaScript/TypeScript 运行时。
• @modelcontextprotocol/sdk：MCP 服务器框架。
• jmap-jam：轻量级、类型化的 JMAP 客户端。
• Zod：运行时类型验证。

安全

• 所有输入都使用 Zod 模式进行验证。
• 使用环境变量进行敏感配置。
• 不会在日志或响应中记录或暴露任何机密信息。
• 遵循 JMAP 安全最佳实践。

贡献

1. 分叉仓库。
2. 创建功能分支。
3. 按照函数式编程风格进行更改。
4. 彻底测试你的更改。
5. 提交拉取请求。

🔧 技术细节

该服务器的架构基于多个关键组件构建，以确保其高效性、安全性和兼容性。

运行时环境

使用 Deno 作为运行时，Deno 是一个现代的 JavaScript 和 TypeScript 运行时，具有安全、高效等特点。它提供了强大的网络和文件系统访问能力，同时支持 TypeScript 的强类型特性，有助于提高代码的可维护性和可靠性。

核心框架

采用 @modelcontextprotocol/sdk 作为 MCP 服务器框架，该框架为服务器提供了基础的结构和功能，使得服务器能够遵循模型上下文协议进行开发和扩展。

JMAP 客户端

使用 jmap-jam 作为轻量级、类型化的 JMAP 客户端。它帮助服务器与 JMAP 电子邮件服务器进行交互，确保服务器能够准确地处理 JMAP 请求和响应，并且完全符合 JMAP RFC 8620/8621 标准。

输入验证

借助 Zod 进行运行时类型验证。Zod 提供了强大的模式定义和验证功能，能够对服务器接收到的所有输入进行全面的验证，确保输入数据的合法性和完整性，从而提高服务器的安全性和稳定性。

安全措施

• 输入验证：通过 Zod 模式对所有输入进行严格验证，防止恶意输入和数据错误。
• 环境变量：使用环境变量来存储敏感配置信息，如认证令牌和会话 URL，避免在代码中硬编码这些信息，从而提高安全性。
• 日志管理：确保不会在日志或响应中记录或暴露任何机密信息，防止信息泄露。
• 标准遵循：遵循 JMAP 安全最佳实践，确保服务器在与 JMAP 电子邮件服务器交互时的安全性。

功能实现

• 电子邮件管理：实现了搜索、获取、标记、移动和删除邮件等功能，通过与 JMAP 服务器的交互，对邮件进行高效管理。
• 邮箱管理：支持获取邮箱列表，方便用户查看和管理邮箱。
• 邮件撰写：提供发送和回复邮件的功能，支持纯文本和 HTML 格式，满足不同的邮件撰写需求。

性能优化

• 分页支持：所有列表操作都支持分页，通过设置 limit 和 position 参数，能够有效地控制数据的返回量，减少不必要的数据传输，提高系统性能。
• 输入验证：全面的输入验证不仅提高了安全性，还减少了无效数据的处理，提高了服务器的处理效率。

兼容性

该服务器能够与多种 JMAP 电子邮件服务器兼容，包括 Cyrus IMAP、Stalwart Mail Server、FastMail 等，确保了广泛的适用性。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

相关项目

• jmap-jam - JMAP 客户端库
• Model Context Protocol - MCP 规范
• JMAP RFC 8620 - JMAP 核心协议
• JMAP RFC 8621 - 邮件 JMAP 协议