MCP agent mail rust

MCPAI代理

提供方 Dicklesworthstone

AI代理 未标注 Token 社区 / 第三方 Claude

为AI编码代理提供的邮件式协调层,支持Git存档、SQLite索引、37种工具和25种资源,包含交互式TUI和Web UI。

一句话选型结论

按资料字段整理

MCP agent mail rust 属于AI代理类 MCP 服务器,传输方式未标注,Token,可直接接入 Claude,没有现成安装命令,需按官方文档接入。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类AI代理 传输方式未标注 鉴权Token 部署方式未标注
GitHub 星标 79 仓库热度,无公开仓库时显示未标注
工具数 37 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

AI代理
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量37暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

AI编码Rust本地部署多代理协调文件管理消息传递Git集成多代理协作

安装与配置

未标注 Token
上游未给出传输方式
  1. 1
    准备运行环境

    按官方文档确认运行环境(常见为 Node.js 或 Python),装好后再执行安装命令。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 37 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
给代理接外部能力

让代理在任务中途调用搜索、数据库等真实工具。

多步任务编排

把一串操作拆成步骤,由代理按顺序执行。

自动化重复流程

把固定流程交给代理跑,减少手工操作。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 37 个工具,覆盖面较广,能满足多种调用。
  • 已适配 Claude,换客户端不用重新研究配置。

先想清楚的地方

  • 没有现成安装命令,需要按官方文档自己填启动命令和参数。
  • 使用前要准备好Token对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在AI代理场景里让模型直接调用外部能力的人。
  • 已经在用 Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
MCP agent mail rust当前 37 未标注 未标注 无 2026-05-17
Filesystem 560c4363 13 未标注 本地部署 无 2026-05-17
Server Everything (everything) 11 stdio · 本地进程 本地部署 有 2026-05-17
Time 7365cb6d 2 SSE · 服务端推送 远程部署 有 2026-05-18
Everything Claude Code 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Openmemory 557e1585 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

AI代理
字段来自项目仓库与公开索引,中文说明由本站标注
提供方Dicklesworthstone上游标注的维护方 Dicklesworthstone
分类AI代理本站按上游分类展示
连接方式未标注上游未给出传输方式
鉴权方式Token远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型未标注上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

97.4 KB
来自项目仓库与上游目录的原文,未做删改

MCP代理邮件(Rust)

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

一个用于AI编码代理的类似邮件的协调层,作为一个MCP服务器公开,包含37个工具和25个资源、Git支持的存档、SQLite索引、一个交互式16屏幕TUI、一个服务器渲染的web UI和一个代理优先的机器人CLI。Rust重写 原始Python项目 (1700多颗星)。

支持的代理: 克劳德代码, Codex CLI, Gemini CLI, GitHub Copilot 命令行工具,以及任何兼容MCP的客户端。

看 23分钟演练 看到七个AI编码代理在两天内实施开发计划时相互发送1000多条消息。

Quick Install```bash

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


Works on Linux and macOS (x86_64 and aarch64). Auto-detects your platform, downloads the right binary, and auto-configures detected Codex CLI installs for HTTP MCP.

______________________________________________________________________

## 目录

- 太长,读不下去了
- 为什么存在
- 人们在说什么
- 设计理念
- Rust与Python:压力测试结果
- 安装
- 快速开始
- 代理配置
- 服务器模式
- 操作员CLI界面
- 37 MCP工具
- TUI操作控制台
- 机器人模式(`am robot`)
- 文件预订
- 多代理协调工作流
- Web 用户界面
- 部署验证
- 配置
- 建筑
- ATC学习实施图
- 核心数据模型
- 系统的工作原理
- 搜索架构
- 协调算法与安全不变量
- 一致性和恢复模型
- 比较与替代方案
- 发展
- 绩效和基准测试
- 邮箱诊断(`am doctor`)
- 故障排除
- 局限性
- 常见问题
- 附录:方案记录
- 附录:途易vs.网络vs.机器人
- 文档
- 关于捐款
- 许可证

______________________________________________________________________

## 太长,读不下去了

**问题**:现代项目通常同时运行多个编码代理(后端、前端、脚本、基础设施)。如果没有共享的协调结构,代理会覆盖彼此的编辑,错过并行工作流中的关键上下文,并要求人类在工具和团队之间传递消息。

**解决方案**:Agent Mail为每个编码代理提供持久身份(例如。, `GreenCastle`)、收件箱/发件箱、可搜索的线程对话和咨询文件预订(租赁),以表明编辑意图。Git为人类可审计的工件提供支持,SQLite为快速索引和搜索提供支持。

### 为什么使用代理邮件?

|功能|它做什么|
|---------|--------------|
| **咨询文件预订** |代理在编辑之前在文件glob上声明独占或共享租约,以防止与预提交保护发生冲突|
| **异步消息传递** |主题、抄送/密送、致谢和重要性级别的线程收件箱/发件箱|
| **代币高效** |消息存储在每个项目的存档中,而不是代理上下文窗口中|
| **25 MCP资源** |只读收件箱、线程、预订、工具、身份和注意力视图,以实现廉价查找|
| **37 MCP工具** |基础设施、身份、消息传递、联系人、预订、搜索、宏、产品总线和构建槽|
| **16屏幕TUI** |实时操作员驾驶舱,用于消息、线程、代理、搜索、预订、指标、健康状况、分析、附件、档案浏览和ATC|
| **Web 用户界面** |服务器渲染 `/mail/` 人工监督、统一收件箱审查、搜索、附件和监督消息传递的路线|
| **机器人模式** |18个经过代理优化的CLI子命令 `toon`/`json`/`md` 非交互式工作流的输出|
| **Git支持的存档** |每个消息、预订和代理配置文件都作为文件存储在每个项目的Git存储库中|
| **混合搜索** |通过frankensearch搜索V3。默认情况下,词汇层会发货;语义路由和混合路由由混合特征标志控制(`feature = "hybrid"`). |
| **预承诺警卫** |阻止提交其他代理保留的接触文件的Git钩子|
| **双模式接口** |MCP服务器(`mcp-agent-mail`)和操作员CLI(`am`)共享工具,但强制执行严格的曲面分离|

### 快速示例```bash
# Install and start (auto-detects all installed coding agents)
am

# That's it. Server starts on 127.0.0.1:8765 with the interactive TUI.

# Agents coordinate through MCP tools:
#   ensure_project(human_key="/abs/path")
#   register_agent(project_key="/abs/path", program="claude-code", model="opus-4.6")
#   file_reservation_paths(project_key="/abs/path", agent_name="BlueLake", paths=["src/**"], ttl_seconds=3600, exclusive=true)
#   send_message(project_key="/abs/path", sender_name="BlueLake", to=["GreenCastle"], subject="Starting refactor", body_md="Taking src/**", thread_id="FEAT-123")
#   fetch_inbox(project_key="/abs/path", agent_name="BlueLake")

# Or use the robot CLI for non-interactive agent workflows:
am robot status --project /abs/path --agent BlueLake
am robot inbox --project /abs/path --agent BlueLake --urgent --format json
am robot reservations --project /abs/path --agent BlueLake --conflicts

Agent对话是什么样子的

协调重构的两个代理之间的示例交换:```
┌──────────────────────────────────────────────────────────────────────────────┐
│ Thread: FEAT-123 - Auth module refactor │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ GreenCastle -> BlueLake 2026-02-16 10:03 │ │
│ │ Subject: Starting auth refactor │ │
│ ├──────────────────────────────────────────────────────────────────────────┤ │
│ │ I'm reserving src/auth/ for the next hour. Can you focus on the API │ │
│ │ tests in tests/api/
instead? │ │
│ │ [ack_required: true] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ BlueLake -> GreenCastle 2026-02-16 10:04 │ │
│ │ Subject: Re: Starting auth refactor │ │
│ ├──────────────────────────────────────────────────────────────────────────┤ │
│ │ Confirmed. Releasing my reservation on src/auth/ and taking │ │
│ │ tests/api/
exclusively. Will sync when I hit the auth middleware │ │
│ │ boundary. │ │
│ │ [ack: OK] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ BlueLake -> GreenCastle 2026-02-16 10:31 │ │
│ │ Subject: Re: Starting auth refactor │ │
│ ├──────────────────────────────────────────────────────────────────────────┤ │
│ │ Found a broken assertion in tests/api/auth_test.rs:142 -- the expected │ │
│ │ token format changed. Heads up if you're touching the JWT issuer. │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ GreenCastle -> BlueLake 2026-02-16 10:33 │ │
│ │ Subject: Re: Starting auth refactor │ │
│ ├──────────────────────────────────────────────────────────────────────────┤ │
│ │ Good catch. I just changed the claims struct. Updated the test fixture │ │
│ │ in my commit. Releasing src/auth/** now -- all yours if you need it. │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘


不需要人工接力。代理通过存储在Git中的结构化、线程化消息协商文件所有权、实时突破标记的更改并移交工作。

______________________________________________________________________

## 为什么存在

现代项目经常同时运行多个编码代理(后端、前端、脚本、基础设施)。如果没有共享的协调结构,代理会覆盖彼此的编辑,错过并行工作流中的关键上下文,并要求人类在工具和团队之间传递消息。

Agent Mail自2025年10月以来一直可用,它是围绕Claude Code、Codex CLI和Gemini CLI等提供商的真实多代理编码工作负载而设计的。相邻 珠子 和 bv 工具使其作为一个完整的协调堆栈更有用:Beads跟踪工作,bv帮助选择正确的下一个工作,Agent Mail承载协调流量。

### Footguns特工邮件避免

**没有“向所有人广播”模式。** 如果有这种选择,许多代理将过度使用广播式消息传递。这相当于电子邮件中的默认回复:大量无关的噪音和浪费的上下文。

**精心提炼的API人体工程学。** 糟糕的MCP文件和糟糕的代理人体工程学悄悄地破坏了可靠性。Agent Mail的37个工具定义经过了重复的现实世界迭代,因此它们可以预测地工作,而不会浪费令牌。

**没有git工作树。** 当代理发生分歧时,工作树可能会减缓开发速度并产生和解债务。Agent Mail采取了相反的方法:将代理保持在一个共享空间中,快速解决冲突,并为他们提供工具来协调。

**咨询文件保留而不是硬锁。** 对于这个问题,咨询预订比硬锁更合适。代理可以在工作时临时声明文件,保留会自动过期,过时的声明可以回收。这使得系统对崩溃或重置代理具有鲁棒性;硬锁不会。

**半持久身份。** 一种身份,可以在离散任务的持续时间内持续(出于协调的目的),但也可以消失得无影无踪,不会破坏事物。你不希望头目特工的死亡摧毁整个系统。代理邮件身份是令人难忘的(例如。, `GreenCastle`),但设计上是短暂的。

**图形感知任务选择。** 如果你有200-500个任务,你不希望代理随机选择它们或浪费上下文来交流要做什么。每个代理应该处理什么通常都有一个“正确答案”,而这个正确答案来自任务的依赖结构。这就是 bv 使用图形理论进行计算,就像一个指南针,告诉每个代理哪个方向将解锁最多的工作。

### 代理邮件给你什么

- **防止冲突:** 文件/Glob的显式文件保留(租约)可防止代理相互覆盖
- **减少人工接力工作:** 代理通过线程对话、确认和优先级直接相互发送消息
- **使通信远离代币预算:** 消息存储在每个项目的Git存档中,不使用代理上下文窗口
- **提供快速阅读:** `resource://inbox/{Agent}?project=`, `resource://thread/{id}?project=`,以及31个其他MCP资源
- **提供完整的审计跟踪:** 每个指令、租约、消息和附件都在Git中供人审查
- **跨仓库扩展:** 不同仓库中的前端和后端代理通过产品总线和联系系统进行协调

### 典型使用案例

- 多个代理在保持同步的同时跨服务拆分大型重构
- 前端和后端代理团队跨存储库逐线程协调
- 通过专用文件保留和预提交保护来保护关键迁移
- 随着线索的发展,搜索和总结冗长的技术讨论
- 跑步代理人蜂拥而至 珠子 依赖感知工作选择的任务跟踪

### 生产率数学

平行代理工作改变了监督的经济性。一个人工操作员可以花一个小时指导多个代理,而这些代理并行完成数小时的实现工作。确切的乘数取决于任务和工作流的纪律性,但重点很简单:协调开销很重要,而Agent Mail的构建是为了保持较低的开销。

______________________________________________________________________

## 人们在说什么

> “Agent Mail和Beads感觉像是第一个‘原生代理’工具。”
> — @杰夫汤克斯

> “第一次代理邮件是一次真正的大脑融化体验。感谢您构建它。”
> — @夸斯托拉

> “在Claude Code、Codex CLI和Gemini、Beads和Agent Mail之间,基本上已经实现了80%的自治公司。这让我大吃一惊,现在一切都正常了!”
> — @好奇_vii

> “将其与代理邮件==圣杯一起使用。”
> — @隐喻

> “唯一正确的答案是mcp代理邮件。”
> — @技能创造

> GPT 5.2建议使用珠子+代理邮件进行代理协调(当然,我已经在使用它们了)
> — @jjpcodes

______________________________________________________________________

## 设计理念

**邮件隐喻,而不是聊天。** 代理发送带有主题、收件人和线程ID的离散消息。工作协调是有明确意图的结构化沟通,而不是消防水带。想象一下,如果你工作时的电子邮件系统默认每次都回复;这就是基于聊天的协调所做的,它会快速燃烧上下文。

**Git是真理的源泉。** 每个消息、代理配置文件和保留工件都作为一个文件存在于每个项目的Git存储库中。整个通信历史是人类可审计、可区分和可恢复的。SQLite是快速索引,而不是权威。

**咨询,非强制性。** 文件保留是咨询租赁,而不是硬锁。预提交保护在提交时强制执行它们,但如果需要,代理始终可以覆盖。当意外冲突仍然被抓住时,僵局就变得不可能了。预订在TTL到期,因此崩溃的代理不会永远扣押文件。

**对特工死亡有抵抗力。** 代理一直在死亡:上下文窗口溢出、会话崩溃、内存被擦除。任何代理都可以在不破坏系统的情况下消失。没有主谋,没有单点失误。半持久身份用于协调,但不会产生硬依赖关系。

**双重坚持。** Git中人类可读的Markdown,可审计;SQLite用于索引,Search V3用于快速词汇/语义检索。两者在写入管道中保持同步。

**结构化并发,没有Tokio。** 整个异步堆栈使用 作物 随着 `Cx`-线程结构化并发。没有孤立任务,取消正确的通道,并使用虚拟时间进行确定性测试。

______________________________________________________________________

## Rust与Python:压力测试结果

在真实的多代理工作负载下,Python实现有三种反复出现的故障模式:并发写入的Git锁文件争用、持续负载下的SQLite池耗尽,以及许多代理同时撞击服务器时的级联故障。Rust重写是专门为消除这些问题而设计的,一个专门的压力测试套件证明了这一点。

### 10测试手套

|测试|结果|关键指标|
|------|--------|-------------|
|30个代理消息管道|PASS|150/150成功,p99=6.8秒,0个错误|
|10个项目并发操作|通过| 150/150成功,0个错误|
|提交聚结器批处理|PASS|9.1倍批处理比(100次写入→ 11 承诺)|
|过期git锁恢复|PASS|检测到锁,已清理,写入已恢复|
|混合预订+消息|通过| 80+80次操作,0个错误|
|WBQ饱和|通过| 2000/2000排队,0个错误,0个回退|
|池耗尽(60个线程,池=15)|PASS | 600/600成功,0超时,24次操作/秒|
|持续30秒的混合工作负载|PASS | 1494次操作,~49个RPS,p99=2.6秒,0个错误|
|雷霆群发(50个线程,1个代理)|通过|所有50个线程都获得了相同的ID,0个错误|
|邮件风暴期间收件箱读取|通过| 150次发送+300次读取,0次错误|

### Python问题→ 防锈修复

|Python失败模式| Rust测试练习|结果|
|---------------------|------------------------------|--------|
| **Git锁文件争用** |提交合并器批处理(100次并发写入→ 11 提交、9.1x缩减)、过时锁恢复、多项目隔离|0个锁错误|
| **SQLite池耗尽** |15个线程池中有60个线程,持续50个RPS 30秒,雷鸣般的群体(50个线程→ 1 代理)|0超时,0数据库错误|
| **代理过多** |30个代理×5条消息,10个项目×5个代理,2000个WBQ操作,混合保留+消息工作负载|0个错误|

### 有什么不同

- **Git锁争用已消除。** 提交合并器批处理快速写入的git提交要少得多(观察到减少了9.1倍)。免锁git管道提交避免 `index.lock` 在大多数情况下完全如此。
- **游泳池的疲惫得到了妥善处理。** 即使线程数是池连接的4倍(60对15),所有600个操作都成功了,没有超时。WAL模式+60s `busy_timeout` 让作者排队而不是失败。
- **死锁恢复工作。** 崩溃的进程锁文件通过PID检查检测并自动清理,因此死代理永远不会劫持存档。
- **写后队列背压是干净的。** 来自20个线程的2000个快速射击队列——全部接受,没有回退或错误。
- **读/写并发性是可靠的。** 并发收件箱读取和邮件写入会产生0个错误。WAL模式允许无限的读者和作者一起阅读。

压力测试现场直播 `crates/mcp-agent-mail-storage/tests/stress_pipeline.rs` (针对DB+Git管道的Rust单元测试)和 `tests/e2e/test_stress_load.sh` (HTTP E2E测试通过整个网络攻击实时服务器→服务器→DB→git管道)。

______________________________________________________________________

## 安装

### One Liner(推荐)```bash
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail_rust/main/install.sh?$(date +%s)" | bash

下载适合您平台的二进制文件,安装到 ~/.local/bin,可选择更新您的 PATH,并为HTTP MCP URL模式自动配置检测到的Codex CLI配置。支持 --verify 用于校验和+Sigstore联合签名验证。

选项: --version vX.Y.Z, --dest DIR, --system (安装到 /usr/local/bin), --from-source, --verify, --easy-mode (自动更新PATH), --force, --uninstall, --yes, --purge.

Windows One Liner(PowerShell)```powershell

iwr -useb "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail_rust/main/install.ps1?$(Get-Random)" | iex


PowerShell选项: `-Version vX.Y.Z`, `-Dest PATH`, `-Force`.

### 来源```bash
git clone https://github.com/Dicklesworthstone/mcp_agent_mail_rust
cd mcp_agent_mail_rust
./install-local.sh          # builds release, installs to ~/.local/bin
# DEST=/usr/local/bin ./install-local.sh   # custom destination

该脚本通过以下方式解析正确的Cargo目标目录 cargo metadata,所以
安装的二进制文件始终与新构建的工件匹配,无论
CARGO_TARGET_DIR 覆盖或工作区设置。做 不 手动复制自
target/release/am --如果 CARGO_TARGET_DIR 如果已设置,则该路径可能已过时。

每晚需要Rust(参见 rust-toolchain.toml).源代码构建还需要在父目录中为以下对象进行本地修补的兄弟签出 七 回购协议 ../asupersync, ../fastmcp_rust, ../beads_rust, ../sqlmodel_rust, ../frankensqlite, ../frankentui,以及 ../frankensearch.

平台

平台 架构 二进制
Linux x86_64 mcp-agent-mail-x86_64-unknown-linux-gnu
Linux aarch64 mcp-agent-mail-aarch64-unknown-linux-gnu
macOS x86_64 mcp-agent-mail-x86_64-apple-darwin
macOS 苹果硅 mcp-agent-mail-aarch64-apple-darwin
Windows x86_64 mcp-agent-mail-x86_64-pc-windows-msvc.zip

快速开始

1.启动服务器```bash

am


自动检测所有已安装的编码代理(Claude Code、Codex CLI、Gemini CLI等),根据需要刷新其MCP连接,并在上启动HTTP服务器 `127.0.0.1:8765` 通过交互式TUI。

### 2.代理人登记和协调

服务器运行后,代理使用MCP工具进行协调:

术语注释: `ensure_project` 需要a `human_key`,它必须是绝对回购路径。大多数后续工具需要 `project_key`,可以是相同的绝对路径或项目的计算段塞。```
# Register identity
ensure_project(human_key="/abs/path/to/repo")
register_agent(project_key="/abs/path/to/repo", program="claude-code", model="opus-4.6")

# Reserve files before editing
file_reservation_paths(project_key="/abs/path/to/repo", agent_name="GreenCastle", paths=["src/**"], ttl_seconds=3600, exclusive=true)

# Send a message
send_message(project_key="/abs/path/to/repo", sender_name="GreenCastle", to=["BlueLake"],
subject="Starting auth refactor", body_md="Taking src/auth/**",
thread_id="FEAT-123", ack_required=true)

# Check inbox
fetch_inbox(project_key="/abs/path/to/repo", agent_name="BlueLake")
acknowledge_message(project_key="/abs/path/to/repo", agent_name="BlueLake", message_id=123)

3.对通用流使用宏```

Boot a full session (ensure project + register agent + reserve files + fetch inbox)

macro_start_session(human_key="/abs/path/to/repo", program="claude-code", model="opus-4.6")

Prepare for a thread (fetch context + recent messages)

macro_prepare_thread(project_key="/abs/path/to/repo", thread_id="FEAT-123",
program="claude-code", model="opus-4.6")

Reserve, work, release cycle

macro_file_reservation_cycle(project_key="/abs/path/to/repo", agent_name="GreenCastle",
paths=["src/auth/**"], ttl_seconds=3600, auto_release=true)

Contact handshake between agents in different projects

macro_contact_handshake(project_key="/abs/path/to/repo", requester="GreenCastle",
target="BlueLake", to_project="/abs/path/to/other/repo",
auto_accept=true, welcome_subject="Coordination channel",
welcome_body="Use thread FEAT-123 for the cutover")


______________________________________________________________________

## 代理配置

安装人员和 `am` 命令自动检测已安装的代理。如果使用curl安装程序,则检测到的Codex CLI配置将以HTTP URL模式自动写入;下面的示例是手动回退。

### 克劳德代码

添加到您的项目 `.mcp.json` 或 `~/.claude/settings.json`:```json
{
"mcpServers": {
"agent-mail": {
"command": "mcp-agent-mail",
"args": []
}
}
}

或者对于HTTP传输(当服务器已在运行时):```json
{
"mcpServers": {
"agent-mail": {
"type": "url",
"url": "http://127.0.0.1:8765/mcp/"
}
}
}


### Codex CLI

curl安装程序会自动为检测到的Codex CLI安装写入此内容。对于源安装、手动设置或自定义端点覆盖,请将此添加到 `~/.codex/config.toml`:```toml
[mcp_servers.mcp_agent_mail]
url = "http://127.0.0.1:8765/mcp/"
# Add this when HTTP bearer auth is enabled:
http_headers = { Authorization = "Bearer " }

Gemini CLI

添加 ~/.gemini/settings.json:```json
{
"mcpServers": {
"agent-mail": {
"command": "mcp-agent-mail",
"args": []
}
}
}


对于项目本地Gemini设置和代理邮件身份注册:```bash
scripts/register_gemini.sh /abs/path/to/repo
AGENT_NAME=BlueLake AGENT_MODEL=gemini-2.5-pro scripts/register_gemini.sh /abs/path/to/repo

任何MCP兼容客户端

Agent Mail支持stdio和HTTP传输:

  • 标准:运行 mcp-agent-mail 作为子流程(大多数MCP客户端的默认设置)
  • 超文本传输协议:连接到 http://127.0.0.1:8765/mcp/ 当服务器通过运行时 am 或 mcp-agent-mail serve
  • 例子:无令牌客户端模板位于 docs/examples/mcp/

服务器模式

MCP服务器(默认)```bash

mcp-agent-mail # stdio transport (for MCP client integration)
mcp-agent-mail serve # HTTP server with TUI (default 127.0.0.1:8765)
mcp-agent-mail serve --no-tui # Headless server (CI/daemon mode)
mcp-agent-mail serve --reuse-running # Reuse existing server on same port


### CLI操作工具```bash
am                                      # Auto-detect agents, refresh MCP config, start server + TUI
am serve-http --port 9000               # Different port
am serve-http --host 0.0.0.0            # Bind to all interfaces
am serve-http --no-auth                 # Skip authentication (local dev)
am serve-http --path api                # Use /api/ transport instead of /mcp/
am --help                               # Full operator CLI

双模式接口

此项目将MCP服务器和CLI命令界面分开:

用例 入口点 注释
MCP服务器(默认) mcp-agent-mail 默认值:MCP stdio传输。HTTP: serve.
CLI(操作员+代理优先) am 推荐的CLI入口点。
通过单个二进制命令行界面 AM_INTERFACE_MODE=cli mcp-agent-mail 相同的CLI界面,一个二进制文件。

通过MCP二进制文件运行仅CLI命令会在stderr上产生具有退出代码的确定性拒绝 2反之亦然,防止自动化工作流中的意外模式混淆。


操作员CLI界面

am 它不仅仅是一个发射器。它是运行时控制、诊断、迁移、导出、基准测试和面向代理的非交互式工作流的操作员界面。在非交互式环境中,裸 am 自动回退到机器人输出,而不是试图启动一个阻塞的TUI。

命令族

Surface · 子命令/表单 · 它的用途
运行时间 · serve-http, serve-stdio, service install · status · logs · restart, check-inbox · 启动服务器、运行stdio MCP、管理后台服务或从钩子/编辑器轮询收件箱状态
质量门 · ci, verify, lint, typecheck, bench · 运行本机质量管道,构建受插槽保护的验证通道和CLI/perf基线
E2E与决定论 · e2e list · run · show, golden capture · verify · list, flake-triage scan · reproduce · detect · 测试传输和工作流,保护CLI输出契约,并对不稳定的故障进行分类
共享和部署 · share export · update · preview · verify · decrypt · wizard · static-export, share deploy validate · tooling · verify · verify-live · 构建便携式邮箱捆绑包,预览它们,并验证实时静态部署
存档和恢复 · archive save · list · restore, doctor check · archive-scan · archive-normalize · repair · backups · restore · reconstruct · fix · 快照邮箱状态、扫描/存档卫生、规范安全存档债务或从Git存档修复/重建SQLite
协调数据 · agents ..., mail ..., contacts ..., macros ..., file_reservations ..., acks ..., list-acks · 直接操作MCP工具公开的相同概念
项目和产品路线 · projects ..., products ..., list-projects, beads ... · 管理项目标识、跨项目产品分组和任务跟踪器视图
平台和设置 · setup run · status, config set-port · show-port, amctl env, tooling ..., docs insert-blurbs · Bootstrap连接器、检查运行时配置、内省工具模式/度量/锁和标记文档
迁移和生命周期 · legacy detect · import · status, upgrade, migrate, self-update, am-run, guard ... · 迁移Python安装、执行DB格式升级、运行插槽感知构建命令和管理保护挂钩
打碎玻璃管理员 · clear-and-reset-everything · 在可选存档后完全重置本地状态。谨慎使用。

设置漂移报告

am setup status 是只读的。它盘点了支持MCP的客户,报告了
当前已编辑的服务器条目位于预期条目旁边,标签漂移如下
作为 missing_file, legacy_stdio, stale_http_path, wrong_bearer_header,
wrong_startup_timeout, duplicate_server_entries,以及 unsupported_config.

分两步使用报告的补救措施:```bash
am setup status --format json
am setup run --dry-run --project-dir "$PWD" --format toon
am setup run --yes --project-dir "$PWD" --format toon


对于承载头检查,请通过 `--token` 到 `am setup status` 或暴露
预期令牌通过 `HTTP_BEARER_TOKEN` / `config.env`;状态输出编辑
令牌值。

### 家庭详细信息

|家族|当前子命令/模式|
|--------|------------------------------|
| `share` | `export`, `update`, `preview`, `verify`, `decrypt`, `wizard`, `static-export`, `deploy validate`, `deploy tooling`, `deploy verify`, `deploy verify-live` |
| `archive` | `save`, `list`, `restore` |
| `guard` | `install`, `uninstall`, `status`, `check` |
| `file_reservations` | `list`, `active`, `soon`, `reserve`, `renew`, `release`, `conflicts` |
| `acks` | `pending`, `remind`, `overdue` |
| `projects` | `mark-identity`, `discovery-init`, `adopt` |
| `mail` | `status`, `send`, `reply`, `inbox`, `read`, `ack`, `search`, `summarize-thread` |
| `products` | `ensure`, `link`, `status`, `search`, `inbox`, `summarize-thread` |
| `doctor` | `check`, `archive-scan`, `archive-normalize`, `repair`, `backups`, `restore`, `reconstruct`, `fix` |
| `agents` | `register`, `create`, `list`, `show`, `detect` |
| `tooling` | `directory`, `schemas`, `metrics`, `metrics-core`, `diagnostics`, `locks`, `decommission-fts` |
| `macros` | `start-session`, `prepare-thread`, `file-reservation-cycle`, `contact-handshake` |
| `contacts` | `request`, `respond`, `list`, `policy` |
| `beads` | `ready`, `list`, `show`, `status` |
| `setup` | `run`, `status` |
| `golden` | `capture`, `verify`, `list` |
| `flake-triage` | `scan`, `reproduce`, `detect` |
| `robot` | `status`, `inbox`, `timeline`, `overview`, `thread`, `search`, `message`, `navigate`, `reservations`, `metrics`, `health`, `analytics`, `agents`, `contacts`, `projects`, `attachments`, `atc` |
| `verify` | `cargo-fmt`, `cargo-check`, `cargo-clippy`, `cargo-test`, `e2e-list`, `e2e-stdio`, `bench-quick` |
| `legacy` | `detect`, `import`, `status` |
| `service` | `install`, `uninstall`, `status`, `logs`, `restart` |

______________________________________________________________________

## 37 MCP工具

### 9个集群

|集群|计数|工具|
|---------|-------|-------|
|基础设施|4| `health_check`, `ensure_project`, `install_precommit_guard`, `uninstall_precommit_guard` |
|身份|6| `register_agent`, `create_agent_identity`, `whois`, `resolve_pane_identity`, `cleanup_pane_identities`, `list_agents` |
|消息|5| `send_message`, `reply_message`, `fetch_inbox`, `acknowledge_message`, `mark_message_read` |
|联系人|4| `request_contact`, `respond_contact`, `list_contacts`, `set_contact_policy` |
|文件保留|4| `file_reservation_paths`, `renew_file_reservations`, `release_file_reservations`, `force_release_file_reservation` |
|搜索|2| `search_messages`, `summarize_thread` |
|宏|4| `macro_start_session`, `macro_prepare_thread`, `macro_contact_handshake`, `macro_file_reservation_cycle` |
|产品总线|5| `ensure_product`, `products_link`, `search_messages_product`, `fetch_inbox_product`, `summarize_thread_product` |
|构建插槽|3| `acquire_build_slot`, `renew_build_slot`, `release_build_slot` |

### 25 MCP资源

只读资源涵盖环境/配置检查、项目和代理发现、收件箱和线程视图、保留视图和工具诊断。他们在那里,这样特工就可以在不改变任何东西的情况下廉价地获取国家。```
resource://inbox/{Agent}?project=&limit=20
resource://thread/{id}?project=&include_bodies=true
resource://mailbox/{Agent}?project=
resource://views/ack-overdue/{Agent}?project=
resource://agents/
resource://file_reservations/?active_only=true
resource://tooling/metrics
resource://config/environment

resource://agents/... 和 resource://file_reservations/... 将项目放在路径段中。收件箱、邮箱、线程和邮件资源将代理或线程放在路径中,将项目放在查询字符串中。

宏与粒度工具

  • 当你想要速度时,更喜欢宏 或者使用较小的型号: macro_start_session, macro_prepare_thread, macro_file_reservation_cycle, macro_contact_handshake
  • 需要控制时使用粒度工具: register_agent, file_reservation_paths, send_message, fetch_inbox, acknowledge_message

TUI操作控制台

交互式TUI有16个屏幕。直接跳 1-9, 0 (屏幕10)和移位数字 !, @, #, $, %, ^ (屏幕11-16)。使用 Tab/Shift+Tab 按顺序循环。

# 屏幕 显示
1 仪表板 实时操作概述,包括事件流和异常轨道
2 消息 带有详细信息窗格、预设和撰写/回复流的消息浏览器
3 线程 线程资源管理器和对话深入分析
4 代理人 代理人名单,包括活动、状态和快速行动
5 搜索 具有方面和预览的统一多范围搜索
6 保留 文件保留状态、冲突和创建/发布操作
7 工具度量 每个工具调用计数、延迟分布和失败
8 系统健康 探头/电路/磁盘/内存诊断以及ATC健康小部件
9 时间线 事件/提交/与检查器组合的时间线视图
10 项目 项目库存和路线助手
11 联系人 联系人链接、政策视图和图表/美人鱼模式
12 资源管理器 具有方向和后退过滤器的统一收件箱/发件箱资源管理器
13 分析 异常洞察提供信心和深度链接
14 附件 带有预览和出处的附件清单
15 存档浏览器 两窗格Git存档浏览器,带树+文件预览
16 ATC 快照驱动的ATC控制界面,带有决策钻取和保留报告

全局密钥: ? 帮助, Ctrl+P/: 命令调色板, / 全局搜索焦点, . 上下文动作菜单, Ctrl+N 合成叠加, Ctrl+Y 吐司聚焦模式, Ctrl+T/Shift+T 循环主题, m 切换MCP/neneneba API传输, q 退出。
ATC钥匙: d 决策细节, r 保留报告, i 切换细节窗格, Tab 切换代理/决策。

屏幕特定亮点: 消息使用 g 用于本地/全球收件箱;线程使用 e/c 用于在对话视图中展开/折叠所有内容;时间线使用 V 活动/承诺/联合和 v 用于视觉选择;搜索用途 f +用于范围/排序/现场控制的分面轨道导航;联系人使用 n 用于表格/图形模式;可批处理的屏幕共享 Space/v/A/C;预设启用的屏幕使用 Ctrl+S/Ctrl+L.

命令面板: 按 Ctrl+P (或 : 外部文本输入)打开一个可搜索的动作启动器,其中包括屏幕导航、传输/布局控件和动态实体(代理/项目/线程/工具/预订)。

主题: 赛博朋克极光、Darcula、流明、北欧霜、高对比度。辅助功能支持包括高对比度模式和减少运动。
存档浏览器注意事项:使用 Enter 为了展开/预览, Tab 切换树与预览窗格, / 过滤文件名,以及 Ctrl+D/U 用于预览分页。


机器人模式(am robot)

非交互式、代理优先的CLI界面,用于TUI等效的态势感知。当您需要快速生成结构化快照时,特别是在自动循环和令牌重要时,请使用它。

18个子命令

命令 目的 关键标志
am robot status 仪表板综合 --format, --project, --agent
am robot inbox 可操作的收件箱,带有紧急/确认综合功能 --urgent, --ack-overdue, --unread, --all, --limit, --include-bodies
am robot timeline 自上次检查以来的事件流 --since, --kind, --source
am robot overview 跨项目总结 --format, --project, --agent
am robot thread 全线程渲染 --limit, --since, --format
am robot search 具有方面/相关性的全文搜索 --kind, --importance, --since, --format
am robot message 单消息深度视图 --format, --project, --agent
am robot navigate 将资源解析为机器人格式的输出 --format, --project, --agent
am robot reservations 具有冲突/到期意识的预订视图 --all, --conflicts, --expiring, --agent
am robot metrics 工具调用率、失败率、延迟百分比 --format, --project, --agent
am robot health 运行时/系统诊断 --format, --project, --agent
am robot analytics 异常和补救总结 --format, --project, --agent
am robot agents 代理人名册和活动概述 --active, --sort
am robot contacts 联系图和政策界面 --format, --project, --agent
am robot projects 每个项目的汇总统计数据 --format, --project, --agent
am robot attachments 附件清单和来源 --format, --project, --agent
am robot atc 服务器不可用时,使用本地数据库回退的实时ATC快照 --since, --stratum, --summary-only, --limit
am robot handoff 只读过时的珠子所有权和交接仪表板 --stale-minutes, --active-minutes, --fresh-comment-minutes, --include-fresh, --dry-run

输出格式

  • toon (默认为TTY):令牌高效、紧凑、针对代理解析进行了优化
  • json (管道时默认):机器可读信封,带 _meta, _alerts, _actions
  • md (以主题/信息为中心):人类可读的深层语境叙事

am robot atc 读取实时ATC快照 /mail/ws-state 当本地服务器正在运行时,当快照不可用时,回退到本地SQLite汇总/活性视图。使用 --since 减少最近的决定/执行, --stratum 关注开放地层数量,以及 --summary-only 对于紧凑的健康视图。

am robot handoff 将正在进行的珠子与代理邮件活动、活动文件保留、线程邮件和最近的评论相关联。它始终是只读的:重新打开/接管行包含建议 br update ... --status open --json 命令,但代理在运行之前必须检查保留、对等脏工作和相关线程。

代理工作流配方```bash

Startup triage

am robot status --project /abs/path --agent AgentName

Immediate urgency pass

am robot inbox --project /abs/path --agent AgentName --urgent --format json

Incremental monitoring loop

am robot timeline --project /abs/path --agent AgentName --since 2026-02-16T10:00:00Z

Deep thread drill-down

am robot thread br-123 --project /abs/path --agent AgentName --format md

Reservation safety check before edits

am robot reservations --project /abs/path --agent AgentName --conflicts --expiring 30

Heavy verification recommendation with build-slot admission and rch

am robot status --project /abs/path --agent AgentName --format json \
| jq '.recommendations[] | select(.category == "verification_lane")'


______________________________________________________________________

## 多代理编辑的文件保留

在编辑之前,代理会保留文件路径以避免冲突:```
file_reservation_paths(project_key, agent_name, paths=["src/**"], ttl_seconds=3600, exclusive=true)

预承诺警卫(mcp-agent-mail-guard)以Git钩子的形式安装,并阻止接触其他代理保留的文件的提交。预订是咨询性的、基于TTL的,并支持glob模式。

区域 保护区球体
核心类型/配置 crates/mcp-agent-mail-core/src/**
SQLite层 crates/mcp-agent-mail-db/src/**
Git存档 crates/mcp-agent-mail-storage/src/**
工具实施 crates/mcp-agent-mail-tools/src/**
推 crates/mcp-agent-mail-server/src/tui_*.rs
CLI/启动器 crates/mcp-agent-mail-cli/src/**

多代理协调工作流

代理如何交互(协议流)```mermaid

sequenceDiagram
participant A as Agent A (GreenCastle)
participant S as Agent Mail Server
participant B as Agent B (BlueLake)

A->>S: ensure_project(human_key="/abs/path")
A->>S: register_agent(project_key="/abs/path", program="claude-code")
S-->>A: identity: GreenCastle

B->>S: register_agent(project_key="/abs/path", program="codex-cli")
S-->>B: identity: BlueLake

A->>S: file_reservation_paths(project_key="/abs/path", agent_name="GreenCastle", paths=["src/auth/**"], exclusive=true)
S-->>A: reserved ✓

B->>S: file_reservation_paths(project_key="/abs/path", agent_name="BlueLake", paths=["src/auth/**"], exclusive=true)
S-->>B: CONFLICT — reserved by GreenCastle

B->>S: file_reservation_paths(project_key="/abs/path", agent_name="BlueLake", paths=["tests/api/**"], exclusive=true)
S-->>B: reserved ✓

A->>S: send_message(project_key="/abs/path", sender_name="GreenCastle", to=["BlueLake"], thread_id="FEAT-123", ack_required=true)
S-->>B: new message in inbox

B->>S: fetch_inbox(project_key="/abs/path", agent_name="BlueLake")
S-->>B: [message from GreenCastle]

B->>S: acknowledge_message(project_key="/abs/path", agent_name="BlueLake", message_id=1482)
S-->>A: ack received ✓

A->>S: release_file_reservations(project_key="/abs/path", agent_name="GreenCastle", paths=["src/auth/**"])
S-->>A: released ✓


### 同一存储库

1. **注册身份:** `ensure_project(human_key=)` + `register_agent(project_key=, ...)`
1. **编辑前保留文件:** `file_reservation_paths(project_key, agent_name, paths=["src/**"], ttl_seconds=3600, exclusive=true)`
1. **与线程通信:** `send_message(..., thread_id="FEAT-123")`,请查看 `fetch_inbox`,承认 `acknowledge_message`
1. **快速阅读:** `resource://inbox/{Agent}?project=&limit=20`

### 跨越不同的仓库

- **选项A(单项目总线):** 在同一目录下注册两个存储库 `project_key`.保持预订模式的特定性(`frontend/**` vs `backend/**`).
- **选项B(单独项目):** 每个回购都有自己的 `project_key`.使用 `macro_contact_handshake` 链接代理,然后直接发送消息。保持共享 `thread_id` 跨repos。

### 外部Git协调(选择加入)

`mcp-agent-mail` 通过以下方式序列化其自己的进程内git shell输出
每次回购 `flock` 上 `/.git/am.git-serialize.lock`外部工具
(包装脚本、编辑器集成、CI)可以尊重相同的哨兵
通过调用git `scripts/git-with-amlock.sh`:```bash
# one-time: put the wrapper on PATH
install -m755 scripts/git-with-amlock.sh ~/.local/bin/git-with-amlock

# per-shell: resolve an "am-aware" git for automation
export GIT_BIN="$(command -v git-with-amlock || command -v git)"
alias gitam='"$GIT_BIN"'

# your automation invokes gitam instead of git:
gitam status
gitam commit -m 'synced'

缓解范围:

  • mcp代理邮件自己的进程内调用→ 始终保持协调
    (自动)。
  • 选择进入包装器的外部工具→ 协调。
  • 您的IDE正在运行 git commit 直接,无需包装→
    仍在比赛。对于这种情况,唯一的完全缓解措施是
    集 AM_GIT_BINARY 升级/降级到安全的git二进制文件
    系统git。看
    已知的错误git版本 部分。

包装荣誉 AM_GIT_BINARY 用于二元选择和
AM_GIT_FLOCK_TIMEOUT_SECS (默认60秒)为有界等待上限。
退出代码75(EX_TEMPFAIL)发出羊群超时的信号。

使用Beads任务跟踪

代理邮件与 珠子 (br)对于依赖关系感知任务选择:

  1. 准备就绪的工作: br ready --json (选择最高优先级,无阻塞)
  2. 保留编辑表面: file_reservation_paths(..., reason="br-123")

…(正文过长,页面只展示前面部分,完整内容见仓库)

常见问题

6 问
答案由本站依据条目字段整理,不引用上游原文
MCP agent mail rust 怎么安装?

资料没有给出安装命令,请到官方仓库或文档按说明接入;这类条目多数是生态应用,或尚未发布可安装包。

MCP agent mail rust 怎么在 Claude 里配置?

它的传输方式未标注,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

MCP agent mail rust 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

MCP agent mail rust 需要 API Key 吗?

资料标注需要Token认证,使用前准备好对应凭据,并按最小权限配置。

MCP agent mail rust 支持哪些客户端?

资料标注支持 Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

MCP agent mail rust 能提供哪些能力?

资料显示约 37 个工具;能力标签包括 Rust、Claude、多代理协作。具体工具清单以官方文档为准。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。