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 協議