MCP Agent Mail

“这就像是为你编程 Agent 准备的 Gmail！”

这是一个为编程 Agent 提供的类似邮件的协作层，通过基于 HTTP 的 FastMCP 服务器暴露。它为 Agent 提供了可识别的身份、收件箱/发件箱、可搜索的消息历史记录，以及自愿性的文件保留“租约”（leases），以避免 Agent 之间发生冲突。

你可以将其视为一种面向 Agent 的异步电子邮件 + 目录 + 变更意图信号系统，底层由 Git（用于人类可审计的工件）和 SQLite（用于索引和查询）提供支持。

状态：处于活跃开发阶段。设计细节已在 docs/planning/project_idea_and_guide.md 中详细记录（请从该文件顶部的原始提示词开始阅读）。

为什么需要这个项目

现代项目通常同时运行多个编程 Agent（后端、前端、脚本、基础设施）。在没有共享协作基础架构的情况下，Agent 会出现以下问题：

• 相互覆盖编辑内容或因意料之外的 diff 而崩溃
• 错过并行工作流中的关键上下文
• 需要人工在不同工具和团队之间“联络”消息

本项目提供了一个轻量级、可互操作的层，以便 Agent 可以：

• 注册临时但持久的身份（例如：GreenCastle）
• 发送/接收包含图片的 GitHub-Flavored Markdown 消息
• 搜索、总结和跟踪对话
• 声明对文件/Glob 模式的建议性文件保留（租约），以表明意图
• 检查活跃 Agent、程序/模型和活动的目录

它专为 FastMCP 客户端和 CLI 工具（Claude Code、Codex、Gemini CLI、Factory Droid 等）在单个或多个代码库中进行协作而设计。

从灵感迸发到交付集群

如果面对一个空白仓库感到无从下手，请遵循我们在 docs/planning/project_idea_and_guide.md 中记录的经过实战检验的工作流程（“附录：从空白仓库到协同集群”）：

• 快速构思： 撰写一段类似电子邮件的草稿，描述问题、期望的 UX 以及必须使用的技术栈（约 15 分钟）。
• 将其提升为计划： 将草稿喂给 GPT-5 Pro（可选 Grok4 Heavy / Opus 4.1），直到获得一份详细的 Markdown 计划，然后在成本尚低时对计划文件进行迭代。Markdown Web Browser 的示例计划展示了应达到的详细程度。
• 编码规则： 克隆一份经过调整的 AGENTS.md，添加任何特定于技术的最佳实践指南，并让 Codex 直接根据计划搭建仓库和 Beads 任务。
• 启动集群： 启动多个 Codex 面板（或任意 Agent 组合），将每个身份注册到 Agent Mail，并让他们在触碰代码之前确认 AGENTS.md、计划文档和 Beads 待办事项。
• 保持供给： 重复使用推文线索中的罐装指令节奏，或者更好的是，让商业版 Companion App 的 Message Stacks 自动广播这些提示词，这样你就再也不用手动喂送面板了。

观看完整的 23 分钟演示视频 (https://youtu.be/68VVcqMEDrs?si=pCm6AiJAndtZ6u7q) 以查看该循环的实际运作。

生产力数学与自动化循环

当 GPT-5 Codex 不必等待人工提示时，一个专注的小时通常能产生 10–20 个“人类小时”的工作量，因为 Agent 以机器速度推理和打字。Agent Mail 通过两层方式放大了这种优势：

1. 基础 OSS 服务器： 基于 Git 的邮箱、建议性文件租约、Typer CLI 助手和可搜索的存档，使独立的 Agent 保持同步，无需人工看管。每一条指令、租约和附件都是可审计的。
2. Companion 堆栈（商业版）： iOS App + 主机自动化工具，可以使用可定制的 Message Stacks、人类监督广播、Beads 感知和计划编辑工具，从你的手机上供应、配对和引导异构集群（Claude Code、Codex、Gemini CLI、Factory Droid 等）——无需手动进行 tmux 编排。自动化系统通过调度提示词、遵循有限模式（Limited Mode）并在执行破坏性工作时强制执行双重确认，从而闭合循环。

结果：你投入 1–2 小时的人工监督，却能让数十个 Agent 小时并行执行，并具有清晰的审计追踪和内置的冲突规避机制。

TLDR 快速入门

一行安装命令

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh?$(date +%s)" | bash -s -- --yes

此操作的作用：

• 如果缺少 uv 则安装，并为当前会话更新 PATH
• 如果缺少 jq 则安装（用于安全的配置合并；自动检测你的包管理器）
• 创建 Python 3.14 虚拟环境并使用 uv 安装依赖
• 运行自动检测集成以连接受支持的 Agent 工具
• 在 8765 端口启动 MCP HTTP 服务器并打印一个屏蔽后的 Bearer Token
• 在 scripts/ 下创建辅助脚本（包括 run_server_with_token.sh）
• 将 am shell 别名添加到你的 .zshrc 或 .bashrc 以便快速启动服务器（在新终端中只需输入 am！）
• 安装 Beads Rust (br)，这是 Beads 任务追踪器的 Rust 重写版本，并创建一个指向 br 的 bd shell 别名以保持向后兼容。