MCP Agent Mail

🚀 MCP Agent Mail

MCP Agent Mail 是一個專為編碼代理設計的類郵件協調層，以僅支持 HTTP 的 FastMCP 服務器形式呈現。它為代理提供了易於記憶的身份、收件箱/發件箱、可搜索的消息歷史記錄，以及自願的文件保留“租約”，以避免相互干擾。

🚀 快速開始

一鍵安裝

curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --yes

上述命令會執行以下操作：

• 若缺少 uv 則進行安裝，並在當前會話中更新 PATH。
• 創建 Python 3.14 虛擬環境，並使用 uv 安裝依賴項。
• 運行自動檢測集成，以連接支持的代理工具。
• 在端口 8765 上啟動 MCP HTTP 服務器，並打印一個掩碼令牌。
• 在 scripts/ 目錄下創建輔助腳本（包括 run_server_with_token.sh）。

若你想指定特定位置或選項，可添加如 --dir <path>、--project-dir <path>、--no-start、--start-only、--port <number> 或 --token <hex> 等標誌。

若遇到端口衝突：可使用 --port 指定不同的端口（默認端口為 8765）：

# 自定義端口安裝
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --port 9000 --yes

# 或在安裝後使用 CLI 命令
uv run python -m mcp_agent_mail.cli config set-port 9000

手動安裝

克隆倉庫，在 Python 3.14 虛擬環境中使用 uv 進行設置和安裝（若沒有 uv，需先進行安裝），然後運行 scripts/automatically_detect_all_installed_coding_agents_and_install_mcp_agent_mail_in_all.sh。這將自動為你安裝的各種編碼代理工具進行設置，並在端口 8765 上啟動 MCP 服務器。若你日後想再次運行 MCP 服務器，只需運行 scripts/run_server_with_token.sh：

# 安裝 uv（若尚未安裝）
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

# 克隆倉庫
git clone https://github.com/Dicklesworthstone/mcp_agent_mail
cd mcp_agent_mail

# 創建 Python 3.14 虛擬環境並安裝依賴項
uv python install 3.14
uv venv -p 3.14
source .venv/bin/activate
uv sync

# 檢測已安裝的編碼代理，進行集成，並在端口 8765 上啟動 MCP 服務器
scripts/automatically_detect_all_installed_coding_agents_and_install_mcp_agent_mail_in_all.sh

# 之後，使用相同的令牌再次運行 MCP 服務器
scripts/run_server_with_token.sh

# 現在，只需在其他控制檯中啟動 Codex - CLI、Claude Code 或其他代理工具；它們應該可以使用郵件工具。以下是一段現成的文本，你可以添加到現有的 AGENTS.md 或 CLAUDE.md 文件末尾，以幫助你的代理更好地利用新工具。

# 安裝後更改端口
uv run python -m mcp_agent_mail.cli config set-port 9000

✨ 主要特性

• 身份管理：為編碼代理提供臨時但持久的身份，便於識別和跟蹤。
• 消息傳遞：支持發送和接收包含圖像的 GitHub 風格 Markdown 消息，方便信息交流。
• 搜索與彙總：可對對話進行搜索、彙總和線程化管理，提高信息檢索效率。
• 文件保留：允許代理聲明對文件或文件通配符的保留租約，避免衝突。
• 目錄查看：可查看活動代理、程序/模型和活動的目錄，瞭解整體情況。

💻 使用示例

基礎用法

# 一鍵安裝
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --yes

高級用法

# 自定義端口安裝
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --port 9000 --yes

📚 詳細文檔

集成 Beads（依賴感知任務規劃）

Beads 是一個輕量級任務規劃器（bd CLI），它與 Agent Mail 互補，將狀態和依賴關係集中管理，而 Agent Mail 負責消息傳遞、文件保留和審計跟蹤。項目地址：steveyegge/beads

網頁界面（面向人類的郵件查看器）

服務器提供了一個輕量級、服務器渲染的網頁界面，供人類使用。你可以瀏覽項目、代理、收件箱、單個消息、附件、文件保留信息，並在支持 FTS5 時進行全文搜索（自動回退到 LIKE 查詢）。

靜態郵箱導出（共享和分發存檔）

share 命令組可將項目的郵箱導出為一個便攜式、只讀的捆綁包，任何人都可以在瀏覽器中查看。這適用於審計人員、利益相關者或團隊成員，他們可以在不啟動完整 MCP Agent Mail 堆棧的情況下瀏覽線程、搜索歷史記錄或證明交付時間線。

🔧 技術細節

核心架構

• HTTP 服務器：僅支持 HTTP 的 FastMCP 服務器，採用可流式 HTTP 協議，不使用 SSE 和 STDIO。
• 持久化模型：採用雙持久化模型，將人類可讀的 Markdown 文件存儲在每個項目的 Git 倉庫中，同時使用 SQLite 進行快速搜索、目錄查詢和文件保留/租約管理。
• 查詢方式：採用“目錄/LDAP”風格的查詢方式，為代理提供易於記憶的形容詞 + 名詞名稱。
• 文件保留：提供諮詢性的文件保留功能，可選擇使用預提交鉤子來強制執行。
• 資源層：提供方便的讀取資源層，如 resource://inbox/{agent}。

數據模型（SQLite）

• projects(id, human_key, slug, created_at)
• agents(id, project_id, name, program, model, task_description, inception_ts, last_active_ts, attachments_policy, contact_policy)
• messages(id, project_id, sender_id, thread_id, subject, body_md, created_ts, importance, ack_required, attachments)
• message_recipients(message_id, agent_id, kind, read_ts, ack_ts)
• file_reservations(id, project_id, agent_id, path_pattern, exclusive, reason, created_ts, expires_ts, released_ts)
• agent_links(id, a_project_id, a_agent_id, b_project_id, b_agent_id, status, reason, created_ts, updated_ts, expires_ts)
• project_sibling_suggestions(id, project_a_id, project_b_id, score, status, rationale, created_ts, evaluated_ts, confirmed_ts, dismissed_ts)
• fts_messages(message_id UNINDEXED, subject, body) + 觸發器用於增量更新

📄 許可證

文檔中未提及相關信息。

📋 配置參考