已被mcp_agent_mail_rust取代。 该 Python 版本已不再维护;新安装时请使用 Rust 版本。

“这就像你的编码代理的Gmail！”

一个类似邮件的编码代理协调层，作为仅支持 HTTP 的 FastMCP 服务器。它为代理提供了令人难忘的身份、收件箱/发件箱、可搜索的消息历史，以及自愿的文件保留“租赁”，以避免相互干扰。

可以把它看作是异步邮件+目录+变更意图信号，配合Git（用于人工审计的工件）和SQLite（用于索引和查询）。

状态：正在积极开发中。设计详细记录在docs/planning/project_idea_and_guide.md中（从该文件顶部的原始提示开始）。

为什么会有这样的存在

现代项目通常同时运行多个编码代理（后端、前端、脚本、基础设施）。没有共享的协调结构，代理：

• 互相覆盖对方的编辑或因意外差异而慌乱
• 忽略并行工作流的关键上下文
• 要求人工在工具和团队间“联络”消息

该项目提供了一个轻量级、互操作性的层，使代理能够：

MCP Agent Mail

Superseded by mcp_agent_mail_rust. This Python version is no longer maintained; use the Rust version for new installs.

“It’s like gmail for your coding agents!”

A mail-like coordination layer for coding agents, exposed as an HTTP-only FastMCP server. It gives agents memorable identities, an inbox/outbox, searchable message history, and voluntary file reservation “leases” to avoid stepping on each other.

Think of it as asynchronous email + directory + change-intent signaling for your agents, backed by Git (for human-auditable artifacts) and SQLite (for indexing and queries).

Status: Maintenance mode. This Python implementation is superseded by the Rust rewrite and is no longer actively developed; new installs should use mcp_agent_mail_rust. The original design is captured in detail in docs/planning/project_idea_and_guide.md (start with the original prompt at the top of that file).

Why this exists

Modern projects often run multiple coding agents at once (backend, frontend, scripts, infra). Without a shared coordination fabric, agents:

• Overwrite each other’s edits or panic on unexpected diffs
• Miss critical context from parallel workstreams
• Require humans to “liaison” messages across tools and teams

This project provides a lightweight, interoperable layer so agents can:

• Register a temporary-but-persistent identity (e.g., GreenCastle)
• Send/receive GitHub-Flavored Markdown messages with images
• Search, summarize, and thread conversations
• Declare advisory file reservations (leases) on files/globs to signal intent
• Inspect a directory of active agents, programs/models, and activity

It’s designed for: FastMCP clients and CLI tools (Claude Code, Codex, Gemini CLI, Factory Droid, etc.) coordinating across one or more codebases.

From Idea Spark to Shipping Swarm

If a blank repo feels daunting, follow the field-tested workflow we documented in docs/planning/project_idea_and_guide.md (“Appendix: From Blank Repo to Coordinated Swarm”):

• Ideate fast: Write a scrappy email-style blurb about the problem, desired UX, and any must-have stack picks (≈15 minutes).
• Promote it to a plan: Feed that blurb to GPT-5 Pro (and optionally Grok4 Heavy / Opus 4.1) until you get a granular Markdown plan, then iterate on the plan file while it’s still cheap to change. The Markdown Web Browser sample plan shows the level of detail to aim for.
• Codify the rules: Clone a tuned AGENTS.md, add any tech-specific best-practice guides, and let Codex scaffold the repo plus Beads tasks straight from the plan.
• Spin up the swarm: Launch multiple Codex panes (or any agent mix), register each identity with Agent Mail, and have them acknowledge AGENTS.md, the plan document, and the Beads backlog before touching code.