MCP Agent Mail

MCP开发工具

提供方 Dicklesworthstone

开发工具 stdio · 本地进程 API Key 社区 / 第三方 ClaudeCursorWindsurfCline
查看接入方式

MCP Agent Mail 是一个为编码代理提供类似邮件的协调层的服务,通过HTTP-only FastMCP服务器暴露,提供可记忆的身份、收件箱/发件箱、可搜索的消息历史记录和文件预留租赁功能。

一句话选型结论

按资料字段整理

MCP Agent Mail 属于开发工具类 MCP 服务器,stdio · 本地进程,API Key,可直接接入 Claude、Cursor、Windsurf 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类开发工具 传输方式stdio · 本地进程 鉴权API Key 部署方式本地部署
GitHub 星标 1,942 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

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

能力标签

支持客户端

适用场景

代理协调Python本地部署消息队列文件管理多代理协作开发工具

安装与配置

stdio · 本地进程 API Key
客户端在本机拉起子进程,数据不出本机
uv run python -m mcp_agent_mail.cli config set-port 9000

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Python,再按安装命令拉取依赖。

  2. 2
    安装服务

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

  3. 3
    写入客户端配置

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

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
代码与仓库操作

在对话里直接查代码、提 issue、走 PR,省掉来回切工具。

本地命令与脚本

把构建、测试、格式化这类重复命令交给模型执行。

接口联调与测试

让模型调你的接口、跑一遍用例,快速定位问题。

选择建议

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

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude、Cursor、Windsurf,换客户端不用重新研究配置。
  • 仓库有一定关注度(星标 1,942),遇到问题更容易搜到资料。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好API Key对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

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

不太适合

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

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
MCP Agent Mail当前 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Git 838e2ec1 12 stdio · 本地进程 本地部署 有 2026-05-17
Markitdown MCP 2c653a5f 1 stdio · 本地进程 本地部署 有 2026-05-17
JavaGuide 未标注 stdio · 本地进程 本地部署 有 2026-04-11
awesome-claude-skills 未标注 stdio · 本地进程 本地部署 有 2026-04-26
Context7 831acf40 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

开发工具
字段来自项目仓库与公开索引,中文说明由本站标注
提供方Dicklesworthstone上游标注的维护方 Dicklesworthstone
分类开发工具本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式API Key远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Python本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

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

MCP代理邮件

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

用于编码代理的类似邮件的协调层,作为仅支持HTTP的FastMCP服务器公开。它为代理提供了令人难忘的身份、收件箱/发件箱、可搜索的消息历史记录和自愿的文件保留“租约”,以避免相互踩踏。

将其视为代理的异步电子邮件+目录+更改意图信号,由Git(用于人类可审计的工件)和SQLite(用于索引和查询)支持。

状态:正在积极开发中。该设计详见 docs/planning/project_idea_and_guide.md (从该文件顶部的原始提示开始)。

为什么存在

现代项目经常同时运行多个编码代理(后端、前端、脚本、基础设施)。如果没有共享的协调结构,代理:

  • 覆盖对方的编辑或对意外差异感到恐慌
  • 忽略平行工作流中的关键上下文
  • 要求人类跨工具和团队“联络”信息

该项目提供了一个轻量级、可互操作的层,因此代理可以:

  • 注册一个临时但持久的身份(例如GreenCastle)
  • 发送/接收带有图片的GitHub风格Markdown消息
  • 搜索、总结和讨论对话
  • 在文件/球体上声明咨询文件保留(租赁),以表明意图
  • 检查活动代理、程序/模型和活动的目录

它专为:FastMCP客户端和CLI工具(Claude Code、Codex、Gemini CLI、Factory Droid等)跨一个或多个代码库进行协调而设计。

从创意火花到航运集群

如果空白仓库令人望而生畏,请遵循我们在中记录的经过现场测试的工作流程 docs/planning/project_idea_and_guide.md (“附录:从空白回购到协调群”):

  • 快速思考: 写一篇关于问题、所需用户体验和任何必备堆栈选择的零碎电子邮件风格的简介(≈15分钟)。
  • 将其推广到计划中: 将该简介提供给GPT-5 Pro(以及可选的Grok4 Heavy/Opus 4.1),直到你得到一个细粒度的Markdown计划,然后在更改仍然便宜的时候迭代计划文件。Markdown Web浏览器示例计划显示了要达到的详细程度。
  • 对规则进行编码: 克隆已调谐 AGENTS.md,添加任何特定于技术的最佳实践指南,并让Codex直接从计划中构建repo和Beads任务。
  • 启动蜂群: 启动多个Codex窗格(或任何代理组合),在agent Mail中注册每个身份,并让他们确认 AGENTS.md在接触代码之前,先查看计划文档和Beads待办事项列表。
  • 让每个人都吃饱: 重用推特线程中预设的指令节奏,或者更好的是,让商业Companion应用程序的消息堆栈自动广播这些提示,这样你就再也不用手动输入窗格了。

观看完整的23分钟演练(https://youtu.be/68VVcqMEDrs?si=pCm6AiJAndtZ6u7q)查看循环的运行情况。

生产力数学与自动化循环

GPT-5 Codex的一个有纪律的小时——当它不等待人类提示时——通常会产生10-20个“人工小时”的工作,因为代理以机器速度进行推理和打字。Agent Mail将这一优势分为两层:

  1. 基础OSS服务器: Git支持的邮箱、咨询文件保留、Typer CLI帮助程序和可搜索的存档使独立代理保持一致,而无需保姆。每个指令、租约和附件都是可审计的。
  2. 配套堆栈(商业): iOS应用程序+主机自动化可以使用可定制的消息堆栈、人工监督广播、珠子感知和计划编辑工具,从您的手机配置、配对和引导异构舰队(Claude Code、Codex、Gemini CLI、Factory Droid等),无需手动tmux编排。自动化通过安排提示、遵守限制模式和强制执行双臂确认破坏性工作来完成循环。

结果:你投入了1-2个小时的人工监督,但数十个代理小时的时间与清晰的审计跟踪和冲突避免并行执行。

TLDR快速入门

单线安装器```bash

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


这有什么作用:

- 如果缺少uv,则安装uv并更新此会话的PATH
- 如果缺少jq,则安装jq(安全配置合并所需;自动检测您的包管理器)
- 创建Python 3.14虚拟环境并使用uv安装依赖项
- 运行自动检测集成以连接支持的代理工具
- 启动端口8765上的MCP HTTP服务器,并打印一个掩码承载令牌
- 在下创建辅助脚本 `scripts/` (包括 `run_server_with_token.sh`)
- 添加一个 `am` shell别名到您的 `.zshrc` 或 `.bashrc` 为了快速启动服务器(只需键入 `am` 在一个新的终端!)
- 安装 **珠子生锈(`br`)**,Beads任务跟踪器的Rust重新实现,并创建 `bd` 指向的shell别名 `br` 为了向后兼容性。这将替换任何现有的 `bd` (Go)安装。通过 `--skip-beads` 选择退出。看 珠锈 有关CLI差异的详细信息。
- 安装/更新珠子查看器 `bv` TUI用于交互式任务浏览和AI友好的机器人命令(pass `--skip-bv` 选择退出)
- 打印每个设置步骤的简短退出摘要,以便您立即知道发生了什么变化

更喜欢特定的位置或选项?添加标志,如 `--dir `, `--project-dir `, `--no-start`, `--start-only`, `--port `,或 `--token `.

已经安装了珠子或珠子查看器?追加 `--skip-beads` 和 `--skip-bv` 绕过自动安装。

### 重要提示:珠子生锈(br)代替珠子脱落(bd)

安装程序会自动替换 `bd` (最初的基于Go的Beads CLI) `br` (珠子生锈):

1. **`br` 是主动维护的版本。** Beads Rust是一个完整的重新实现,正在进行开发,而原始的Go版本不再被积极维护。

1. **现有的 `bd` 用户会得到自动别名。** 安装程序创建一个shell别名,以便 `bd` 命令通过重定向到继续工作 `br`。保留您现有的工作流程和肌肉记忆。

1. **为代理安装了迁移技能。** AI编码代理接收 `bd-br-migration` 帮助他们适应两种实现之间的任何CLI差异的技能。

1. **相同的数据格式,兼容的工作流程。** 两种实现都使用相同的 `.beads/issues.jsonl` 格式,因此您现有的Beads数据保持完全兼容。

要选择退出此替换,请通过 `--skip-beads` 安装程序。看 beads_rust存储库 有关CLI差异的详细文档。

### 将来启动服务器

安装后,您可以从以下位置启动MCP代理邮件服务器 **任何地方** 只需输入:```bash
am

就是这样!这 am 别名(添加到您的 .zshrc 或 .bashrc 在安装过程中)自动:

  1. 更改MCP代理邮件目录
  2. 运行服务器启动脚本(使用 uv run 处理虚拟环境)
  3. 从以下位置加载您保存的承载令牌 .env 并启动HTTP服务器

注: 如果您刚刚运行了安装程序,请打开一个新的终端或运行 source ~/.zshrc (或 source ~/.bashrc)加载别名。

港口冲突? 使用 --port 要指定其他端口(默认值:8765):

使用自定义端口安装:```bash
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh?$(date +%s)" | bash -s -- --port 9000 --yes


或者在安装后使用CLI命令:
uv运行python-m mcpcagent_mail.cli配置设置端口9000````

### If you want to do it yourself

Clone the repo, set up and install with uv in a python 3.14 venv (install uv if you don't have it already), and then run `scripts/automatically_detect_all_installed_coding_agents_and_install_mcp_agent_mail_in_all.sh`. This will automatically set things up for your various installed coding agent tools and start the MCP server on port 8765. If you want to run the MCP server again in the future, simply run `scripts/run_server_with_token.sh`:

Install uv (if you don't have it already):

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

# Clone the repo
git clone https://github.com/Dicklesworthstone/mcp_agent_mail
cd mcp_agent_mail

# Create a Python 3.14 virtual environment and install dependencies
# Note: If you have an older uv version, run `uv self update` first
uv python install 3.14
uv venv -p 3.14
source .venv/bin/activate
uv sync

# Detect installed coding agents, integrate, and start the MCP server on port 8765
scripts/automatically_detect_all_installed_coding_agents_and_install_mcp_agent_mail_in_all.sh

# Later, to run the MCP server again with the same token
scripts/run_server_with_token.sh

# Now, simply launch Codex-CLI or Claude Code or other agent tools in other consoles; they should have the mail tool available. See below for a ready-made chunk of text you can add to the end of your existing AGENTS.md or CLAUDE.md files to help your agents better utilize the new tools.

# Change port after installation
uv run python -m mcp_agent_mail.cli config set-port 9000````

## 可添加到AGENTS.md或CLAUDE.md文件的现成Blurb:

MCP Agent Mail: coordination for multi-agent workflows

What it is
- A mail-like layer that lets coding agents coordinate asynchronously via MCP tools and resources.
- Provides identities, inbox/outbox, searchable threads, and advisory file reservations, with human-auditable artifacts in Git.

Why it's useful
- Prevents agents from stepping on each other with explicit file reservations (leases) for files/globs.
- Keeps communication out of your token budget by storing messages in a per-project archive.
- Offers quick reads (resource://inbox/..., resource://thread/...) and macros that bundle common flows.

How to use effectively
1) Same repository
- Register an identity: call ensure_project, then register_agent using this repo's absolute path as project_key.
- Reserve files before you edit: file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true) to signal intent and avoid conflict.
- Communicate with threads: use send_message(..., thread_id="FEAT-123"); check inbox with fetch_inbox and acknowledge with acknowledge_message.
- Read fast: resource://inbox/{Agent}?project=&limit=20&agent_token= or resource://thread/{id}?project=&agent=&agent_token=&include_bodies=true unless the current MCP session already authenticated as that agent.
- Tip: set AGENT_NAME in your environment so the pre-commit guard can block commits that conflict with others' active exclusive file reservations.

2) Across different repos in one project (e.g., Next.js frontend + FastAPI backend)
- Option A (single project bus): register both sides under the same project_key (shared key/path). Keep reservation patterns specific (e.g., frontend/** vs backend/**).
- Option B (separate projects): each repo has its own project_key; use macro_contact_handshake or request_contact/respond_contact to link agents, then message directly. Keep a shared thread_id (e.g., ticket key) across repos for clean summaries/audits.

Macros vs granular tools
- Prefer macros when you want speed or are on a smaller model: macro_start_session, macro_prepare_thread, macro_file_reservation_cycle, macro_contact_handshake.
- Use granular tools when you need control: register_agent, file_reservation_paths, send_message, fetch_inbox, acknowledge_message.

Common pitfalls
- "from_agent not registered": always register_agent in the correct project_key first.
- "FILE_RESERVATION_CONFLICT": adjust patterns, wait for expiry, or use a non-exclusive reservation when appropriate.
- Auth errors: if JWT+JWKS is enabled, include a bearer token with a kid that matches server JWKS; static bearer is used only when JWT is disabled.```

与Beads集成(依赖感知任务规划)

Beads是一个轻量级的任务规划器,它通过将状态和依赖关系保存在一个地方来补充Agent Mail,而Mail则处理消息传递、文件保留和审计跟踪。

实施说明: MCP代理邮件安装程序安装 珠子生锈(br),一个Rust重新实现,并创建一个 bd 别名用于向后兼容性。最初的Go实现位于 史蒂夫耶格/珠子。两者共享相同的数据格式(.beads/issues.jsonl)但存在一些CLI差异。使用 --skip-beads 在安装过程中,如果您更喜欢自己管理。

亮点:

  • Beads拥有任务优先级;Agent Mail携带对话和工件。
  • 共享标识符(例如。, bd-123)保持Beads问题、邮件线程和提交的一致性。
  • 这 br CLI(别名为 bd)提供了与原版类似的功能,并进行了一些增强。

复制/粘贴面向代理的文档的简介(保持原样以供重用):


## Integrating with Beads (dependency-aware task planning)

Beads provides a lightweight, dependency-aware issue database and a CLI (`bd`) for selecting "ready work," setting priorities, and tracking status. It complements MCP Agent Mail's messaging, audit trail, and file-reservation signals. Project: steveyegge/beads

Recommended conventions
- **Single source of truth**: Use **Beads** for task status/priority/dependencies; use **Agent Mail** for conversation, decisions, and attachments (audit).
- **Shared identifiers**: Use the Beads issue id (e.g., `bd-123`) as the Mail `thread_id` and prefix message subjects with `[bd-123]`.
- **Reservations**: When starting a `bd-###` task, call `file_reservation_paths(...)` for the affected paths; include the issue id in the `reason` and release on completion.

Typical flow (agents)
1) **Pick ready work** (Beads)
- `bd ready --json` → choose one item (highest priority, no blockers)
2) **Reserve edit surface** (Mail)
- `file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true, reason="bd-123")`
3) **Announce start** (Mail)
- `send_message(..., thread_id="bd-123", subject="[bd-123] Start: ", ack_required=true)`
4) **Work and update**
- Reply in-thread with progress and attach artifacts/images; keep the discussion in one thread per issue id
5) **Complete and release**
- `bd close bd-123 --reason "Completed"` (Beads is status authority)
- `release_file_reservations(project_key, agent_name, paths=["src/**"])`
- Final Mail reply: `[bd-123] Completed` with summary and links

Mapping cheat-sheet
- **Mail `thread_id`** ↔ `bd-###`
- **Mail subject**: `[bd-###] …`
- **File reservation `reason`**: `bd-###`
- **Commit messages (optional)**: include `bd-###` for traceability

Event mirroring (optional automation)
- On `bd update --status blocked`, send a high-importance Mail message in thread `bd-###` describing the blocker.
- On Mail "ACK overdue" for a critical decision, add a Beads label (e.g., `needs-ack`) or bump priority to surface it in `bd ready`.

Pitfalls to avoid
- Don't create or manage tasks in Mail; treat Beads as the single task queue.
- Always include `bd-###` in message `thread_id` to avoid ID drift across tools.```

更喜欢自动化?跑 `uv run python -m mcp_agent_mail.cli docs insert-blurbs` 扫描代码目录以查找 `AGENTS.md`/`CLAUDE.md` 文件,并将最新的Agent Mail+Beads片段附加到每个项目的确认中。安装程序还提供在安装后立即启动此帮助程序,以便您可以立即处理入职文档。

## Beads Viewer(bv)——人工智能友好的任务分析

珠子查看器(`bv`)是Beads项目的快速终端UI,还提供 **机器人标志** 专为AI代理集成而设计。项目: [Dicklesworthstone/珠子_观众](https://github.com/Dicklesworthstone/beads_viewer)

### 为什么选择bv代理?

虽然 `bd` (Beads CLI)处理任务CRUD操作, `bv` 提供 **预计算图分析** 帮助代理做出智能优先级决策:

- **PageRank得分**:确定能够解锁最下游工作的高影响力任务
- **关键路径分析**:找到完成的最长依赖链
- **循环检测**:在循环依赖关系导致死锁之前发现它们
- **平行轨道规划**:确定哪些任务可以并发运行

而不是代理解析 `.beads/issues.jsonl` 直接或试图计算图度量(冒着产生幻觉的风险),他们可以调用bv的确定性机器人标志,并获得他们可以信任的JSON输出。遗产 `.beads/beads.jsonl` 在此仓库中已弃用。

### 用于AI集成的机器人标志

|标志|输出|代理用例|
|------|--------|----------------|
| `bv --robot-help` |所有面向AI的命令|发现/能力检查|
| `bv --robot-insights` |PageRank、介数、HITS、关键路径、周期|快速分类:“什么最有影响?”|
| `bv --robot-plan` |并行轨道、每条轨道的项目、解锁列表|执行计划:“什么可以并行运行?”|
| `bv --robot-priority` |推理+自信的优先建议|任务选择:“我接下来应该做什么?”|
| `bv --robot-recipes` |可用的过滤器预设(可操作、已阻止等)|工作流设置:“显示准备好的工作”|
| `bv --robot-diff --diff-since ` |自提交/日期以来的更改、新的/已关闭的项目、周期|进度跟踪:“更改了什么?”|

### 示例:代理任务选择工作流

```bash
# 1. Get priority recommendations with reasoning
bv --robot-priority
# Returns JSON with ranked tasks, impact scores, and confidence levels

# 2. Check what completing a task would unblock
bv --robot-plan
# Returns parallel tracks showing dependency chains

# 3. After completing work, check what changed
bv --robot-diff --diff-since "1 hour ago"
# Returns new items, closed items, cycle changes```

### 什么时候使用bv vs bd

|工具|最适合|
|------|----------|
| `bd` |创建、更新、关闭任务; `bd ready` 简单的“下一步是什么”|
| `bv` |图形分析、影响评估、并行规划、变更跟踪|

**经验法则**:使用 `bd` 对于任务操作,请使用 `bv` 任务智能。

### 与代理邮件集成

将bv见解与代理邮件协调相结合:

1. **代理人A** 跑 `bv --robot-priority` → 识别 `bd-42` 影响最大
1. **代理人A** 保留文件: `file_reservation_paths(..., reason="bd-42")`
1. **代理人A** 宣布: `send_message(..., thread_id="bd-42", subject="[bd-42] Starting high-impact refactor")`
1. **其他代理商** 查看预订和邮件公告,选择不同的任务
1. **代理人A** 完成,运行 `bv --robot-diff` 报告下游畅通情况

这创建了一个反馈循环,其中图形智能驱动协调。

## 核心思想(一目了然)

- 仅支持HTTP的FastMCP服务器(流式HTTP)。没有SSE,没有STDIO。
- 双重持久性模型:
- 每个项目Git仓库中每个规范消息和每个收件人收件箱/发件箱副本的人类可读标记
- 带FTS5的SQLite,用于快速搜索、目录查询和文件保留/租赁
- 代理的“目录/LDAP”风格查询;令人难忘的形容词+名词名称
- 编辑曲面的咨询文件保留;可选的预提交保护
- 用于方便读取的资源层(例如。, `resource://inbox/{agent}`)

## 典型使用案例

- 多个代理在保持同步的同时跨服务拆分大型重构
- 代理的前端和后端团队逐线程协调
- 通过专用文件保留和预提交保护来保护关键迁移
- 随着线索的发展,搜索和总结冗长的技术讨论
- 通过人工智能建议发现和链接相关项目(例如前端/后端)

## 工作流常见问题

**我还需要tmux广播脚本来“馈送”每个Codex窗格吗?**

不需要。如果你自己运行OSS堆栈,那么推特线程的历史zsh循环仍然很方便,但AgentMail Companion系统现在可以通过消息堆栈自动执行这种节奏。安装配套主机服务后,您可以从iOS应用程序或CLI对预设(构建器循环、审阅器扫描、测试焦点等)进行排队,自动化会将这些指令扇出给每个注册的代理,而无需接触tmux。

## 建筑

```mermaid
graph LR
A[Agents]
S[Server]
G[Git repo]
Q[SQLite FTS5]

A --> · HTTP tools/resources · S
S --> · writes/reads · G
S --> · indexes/queries · Q

subgraph GitTree["Git tree"]
GI1[agents/profile.json]
GI2[agents/mailboxes/...]
GI3[messages/YYYY/\nMM/\nid.md]
GI4[file_reservations/\nsha1.json]
GA[attachments/xx/\nsha1.webp]
end

G --- GI1
G --- GI2
G --- GI3
G --- GI4
G --- GA```

## Web UI(面向人的邮件查看器)

该服务器为人类提供了一个轻量级的、服务器渲染的Web UI。它允许您浏览项目、代理、收件箱、单个消息、附件、文件保留,并在FTS5可用时使用FTS5执行全文搜索(具有自动LIKE回退功能)。

- 它所在的位置:内置于HTTP服务器中 `mcp_agent_mail.http` 在...之下 `/mail` 路径。
- 为谁服务:人类审查活动;代理应继续使用MCP工具/资源API。

### 启动Web UI

推荐(简单):

```bash
scripts/run_server_with_token.sh
# then open http://127.0.0.1:8765/mail```

高级(手动命令):

```bash
uv run python -m mcp_agent_mail.http --host 127.0.0.1 --port 8765
# or:
uv run uvicorn mcp_agent_mail.http:build_http_app --factory --host 127.0.0.1 --port 8765```

授权说明:

- UI中的GET页面不受RBAC中间件的控制(它仅对已发布的MCP调用进行分类),但如果您设置了承载令牌,则默认情况下,单独的BearerAuth中间件会保护所有路由。
- 对于本地开发,设置 `HTTP_ALLOW_LOCALHOST_UNAUTHENTICATED=true` (以及可选 `HTTP_BEARER_TOKEN`),因此localhost可以加载没有标头的UI。
- 健康端点始终在以下位置打开 `/health/*`.

### 路线和你能做什么

- `/mail` (统一收件箱+项目+相关项目发现)

- 显示一个统一的、按时间倒序排列的收件箱,其中包含所有项目的最新消息,包括摘录、相对时间戳、发件人/收件人和项目徽章。
- 收件箱下方列出了所有带有兄弟建议的项目(slug、人名、创建时间)。
- 建议 **可能的兄弟项目** 当两个slug似乎是同一产品的一部分时(例如,后端与前端)。建议按照启发式方法进行排名,当 `LLM_ENABLED=true`,LLM传递关键文档(`README.md`, `AGENTS.md`等等)。
- 人类可以 **确认链接** 或 **解雇** 仪表板上的建议。确认的兄弟姐妹成为突出显示的徽章,但 *不要* 自动授权跨项目消息传递;代理商仍必须建立 `AgentLink` 批准通过 `request_contact`/`respond_contact`.

- `/mail/projects` (项目索引)

- 专用项目列表视图;单击一个项目以深入了解。

- `/mail/{project}` (项目概述+搜索+代理)

- 带有过滤器的丰富搜索表单:
- 范围:主题/正文/两者,顺序:相关性或时间,可选“增强主题”。
- 查询令牌:支持 `subject:foo`, `body:"multi word"`引用的短语和简单的术语。
- 在可用时使用FTS5 bm25评分;否则,在您选择的范围内,在subject/body上回退到SQL LIKE。
- 使用FTS时,结果显示主题、发件人、创建时间、线程id和突出显示的代码段。
- 代理面板显示项目的注册代理,并带有每个收件箱的链接。
- 指向项目标题的“文件保留和附件”的快速链接。

- `/mail/{project}/inbox/{agent}` (一个代理的收件箱)

- 按时间倒序列出主题、发件人、创建时间、重要性徽章、线程id。
- 分页(`?page=N&limit=M`).

- `/mail/{project}/message/{id}` (消息详细信息)

- 显示主题、发件人、创建时间、重要性、收件人(收件人/抄送/密送)、主题邮件。
- 车身渲染:
- 如果服务器将markdown预转换为HTML,则使用Bleachs(有限的标签/属性,通过CSSSanitizer安全的CSS)对其进行消毒,然后显示。
- 否则,markdown将在客户端使用Marked+Prism进行渲染,以突出显示代码。
- 附件从消息前端引用(WebP文件或内联数据URI)。

- `/mail/{project}/search?q=...` (专用搜索页面)

- 与项目概述搜索相同的查询语法,带有用于组装/删除过滤器的标记“pill”UI。

- `/mail/{project}/file_reservations` (文件保留列表)

- 显示活动和历史文件保留(独占/共享、路径模式、时间戳、发布/过期状态)。

- `/mail/{project}/attachments` (带附件的邮件)

- 列出包含任何附件的邮件,包括主题和创建时间。

- `/mail/unified-inbox` (跨项目活动)

- 显示所有项目的最新消息,包括线程数和发件人/收件人。

### 人类监督者:向特工发送信息

有时,人工操作员需要直接指导或重定向代理,无论是处理紧急问题、提供澄清还是调整优先级。这 **人力监督者** 该功能提供了一个基于网络的消息编辑器,允许人类向项目中的任何代理组合发送高优先级消息。

**访问权限:** 点击突出的 **“发送消息”** 任何项目视图标题中的按钮(带有监督员徽章)(`/mail/{project}`),或直接导航到 `/mail/{project}/overseer/compose`.

#### 是什么让监督员信息特别

1. **自动前导**:每条消息都包含一个格式化的前导码,明确标识它来自人类操作员,并指示代理:

- **暂停当前工作** 暂时
- **优先考虑人类的请求** 超过现有任务
- **恢复原计划** 之后(除非按照说明进行修改)

1. **高优先级**:所有监督信息都会自动标记为 **高度重要性**,确保他们在代理收件箱中脱颖而出。

1. **策略绕过**:监督消息绕过了正常的联系策略,因此无论联系人设置如何,人们都可以随时联系到任何代理。

1. **特殊发件人身份**:消息来自一位名为的特工 **“人类监督者”** (按项目自动创建),具有:

- 程序: `WebUI`
- 型号: `Human`
- 联系方式: `open`

#### 信息前言

每条监督消息都以以下前导码开头(自动添加):


🚨 MESSAGE FROM HUMAN OVERSEER 🚨

This message is from a human operator overseeing this project. Please prioritize
the instructions below over your current tasks.

You should:
1. Temporarily pause your current work
2. Complete the request described below
3. Resume your original plans afterward (unless modified by these instructions)

The human's guidance supersedes all other priorities.


[Your message body follows here]```

使用Composer

作曲家界面提供:

  • 收件人选择:所有注册代理的复选框网格(带有“全选”/“清除”快捷键)
  • 主题行:必填,显示在代理收件箱中
  • 消息正文:GitHub风格的Markdown编辑器,带预览
  • 线程ID (可选):继续现有对话或开始新对话
  • 前言预览:看看你的消息在客服面前会是什么样子

示例用例

紧急问题:

Subject: Urgent: Stop migration and revert changes

The database migration in PR #453 is causing data corruption in staging.

Please:
1. Immediately stop any migration-related work
2. Revert commits from the last 2 hours
3. Wait for my review before resuming

I'm investigating the root cause now.```

**优先级调整:**

Subject: New Priority: Security Vulnerability

A critical security vulnerability was just disclosed in our auth library.

Drop your current tasks and:
1. Update auth-lib to version 2.4.1 immediately
2. Review all usages in src/auth/
3. Run the full security test suite
4. Report status in thread #892

This takes precedence over the refactoring work.```

澄清:

Subject: Clarification on API design approach

I see you're debating REST vs. GraphQL in thread #234.

Go with REST for now because:
- Our frontend team has more REST experience
- GraphQL adds complexity we don't need yet
- We can always add GraphQL later if needed

Resume the API implementation with REST.```

#### 代理如何查看监督员消息

当代理检查收件箱时(通过 `fetch_inbox` 或 `resource://inbox/{name}`),监督者消息与其他消息一样显示,但有:

- **发送者**: `HumanOverseer`
- **重要性**: `high` (突出显示)
- **身体**:以监督员序言开头,然后是人的信息
- **视觉提示**:在Web UI中,这些消息可能有特殊的突出显示(未来的增强)

代理可以像回复任何其他消息一样回复监督消息,继续对话线程。

#### 技术细节

- **存储**:监督消息与代理到代理消息(Git+SQLite)的存储方式相同
- **Git 历史**:完全可审计;消息出现在 `messages/YYYY/MM/{id}.md` 有提交历史
- **线程连续性**:可以是现有线程的一部分,也可以启动新线程
- **无身份验证绕过**:监督员撰写表单仍然需要正确的HTTP服务器身份验证(如果启用)

#### 设计理念

人工监督功能旨在:

- **明确的**:代理人清楚地知道指导何时来自人类,何时来自另一个代理人
- **恭敬的**:说明承认代理人有现有的工作,不应该永远“放弃一切”
- **临时**:特工们被告知,一旦人类的请求完成,就要恢复原来的计划
- **灵活的**:人类可以直接在其消息体中覆盖此指导

这创建了一个清晰的层次结构(人类→ 同时保持代理通信系统的协作、尊重的语气。

### 相关项目发现

项目索引(`/mail`)特点a **人工智能驱动的发现系统** 这可以智能地建议哪些项目应该链接在一起,例如前端+后端或相关的微服务。

#### Discovery的工作原理

**1.智能分析**
该系统使用多个信号来识别关系:

- **模式匹配**:比较项目名称和路径(例如,“我的应用程序前端”↔ “我的应用后端”)
- **AI理解** (当 `LLM_ENABLED=true`):阅读 `README.md`, `AGENTS.md`,以及其他文档,以了解每个项目的目的并检测自然关系
- **信心评分**:对建议进行0-100%的排名,并给出明确的理由

**2.漂亮的建议**
相关项目在您的仪表板上显示为精美的卡片,上面有:

- 🎯 显示比赛实力的视觉信心指标
- 💬 人工智能生成的解释这种关系的理由
- ✅ **确认链接** -接受建议
- ✖️ **解雇** -隐藏不相关的匹配项

**3.快速导航**
一旦确认,这两个项目都会显示交互式徽章,以便在相关代码库之间进行即时导航。

#### 为什么是建议,而不是自动链接?

> **太长,读不下去了**:我们控制着你。发现帮助你找到关系;明确的批准控制着谁可以实际沟通。

**Agent Mail使用以代理为中心的消息传递**:每条消息都遵循明确的权限链:

Send Message → Find Recipient → Check AgentLink Approval → Deliver```

该设计确保:

  • 安全:没有意外的跨项目消息传递
  • 透明度你总是知道谁能和谁说话
  • 审核跟踪:所有通信路径都经过明确批准

为什么不与AI自动链接?
如果我们让LLM自动授权项目之间的消息传递,我们会:

  • ❌ 在没有人为监督的情况下绕过联系政策
  • ❌ 将邮件错误传递给非预期收件人的风险
  • ❌ 创建难以审计的不可见路由路径
  • ❌ 可能错误地链接了名称模糊的项目

相反,我们给你 发现+控制:

  • ✅ 人工智能建议可能的关系(安全、只读分析)
  • ✅ 您确认什么是有意义的(点击一下)
  • ✅ 代理商仍在使用 request_contact / respond_contact 用于实际消息传递权限
  • ✅ 明确区分:发现≠授权

完整的工作流程

1. System suggests: "These projects look related" (AI analysis)
↓
2. You confirm: "Yes, link them" (updates UI badges)
↓
3. Agents request: request_contact(from_agent, to_agent, to_project)
↓
4. You approve: respond_contact(accept=true)
↓
5. Messages flow: Agents can now communicate across projects```

**把它想象成LinkedIn**:系统建议连接,但仅限于 *你* 决定谁可以发送消息。

### 搜索语法(UI)

UI与API共享相同的解析 `_parse_fts_query`:

- 字段筛选器: `subject:login`, `body:"api key"`
- 短语搜索: `"build plan"`
- 合并术语: `login AND security` (FTS)
- 回退LIKE:范围决定是否搜索主题、正文或两者

### 查看数据的先决条件

UI读取与MCP工具相同的SQLite+Git工件。要填充内容,请执行以下操作:

1. 确保项目存在(通过工具调用或CLI):
- 确保/创建项目: `ensure_project(human_key)`
1. 注册一个或多个代理: `register_agent(project_key, program, model, name?)`
1. 发送消息: `send_message(...)` (支持附件和内联图像;图像可以转换为WebP)。

一旦消息存在,请访问 `/mail`,单击您的项目,然后打开代理收件箱或搜索。

### 实施和依赖关系

- 模板位于 `src/mcp_agent_mail/templates/` 并且由Jinja2渲染。
- Markdown转换为 `markdown2` 在可能的情况下在服务器上;HTML用漂白剂消毒(可用时用CSS消毒剂消毒)。
- Tailwind CSS、Lucide图标、Alpine.js、Marked和Prism通过CDN加载到 `base.html` 无需前端构建步骤即可获得现代外观。
- 所有渲染都是服务器端的;没有SPA路由器。没有JavaScript,页面会干净地降级。

### 安全注意事项

- HTML净化:只允许使用一组保守的标签/属性;CSS被过滤掉了。链接仅限于http/https/mailto/data。
- Auth:在本地主机之外公开时,使用承载令牌或JWT。对于本地开发,如上所述启用localhost旁路。
- 速率限制(可选):可以启用令牌桶限制器;UI GET请求很轻,不受POST限制的影响。

### UI故障排除

- 本地主机上的空白页或401:未设置 `HTTP_BEARER_TOKEN` 或设置 `HTTP_ALLOW_LOCALHOST_UNAUTHENTICATED=true`.
- 未列出项目:创建一个 `ensure_project`.
- 空收件箱:验证收件人姓名是否完全匹配,以及邮件是否已发送到该代理。
- 搜索不返回任何内容:尝试更简单的术语或LIKE回退(切换范围/正文)。

## 静态邮箱导出(共享和分发存档)

这 `share` 命令组将项目的邮箱导出到可移植的只读包中,任何人都可以在浏览器中查看。它专为需要浏览线程、搜索历史记录或证明交付时间表而无需启动完整MCP代理邮件堆栈的审计员、利益相关者或团队成员而设计。

### 为什么导出到静态捆绑包?

**合规和审计跟踪**向审计员或合规官提供项目沟通的不可变快照。静态捆绑包包括用于防篡改分发的加密签名。

**利益相关者审查**:与不需要写权限的产品经理、高管或外部顾问共享对话历史。他们可以在浏览器中浏览邮件、搜索线程和查看附件,而无需身份验证。

**离线访问**:为气隙环境、灾难恢复备份或互联网连接不可靠的情况创建便携式档案。

**长期档案**:以几十年后仍然可读的格式保存项目沟通。静态HTML不需要数据库服务器,不需要运行时依赖性,并且比专有格式更能经受住软件过时的考验。

**安全分发**:对机密项目的捆绑包进行加密。只有拥有私钥的收件人才能解密和查看内容。

### 出口包括什么

每个捆绑包包含:

- **自足**:所有内容都放在一个目录中(HTML、CSS/JS、SQLite快照、附件)。将其放到静态主机上或在本地打开。
- **丰富的阅读器用户界面**:Gmail风格的收件箱,带有项目过滤器、搜索和全线程渲染——每条消息都会显示其元数据和Markdown正文,就像在实时web UI中一样。
- **快速搜索和筛选**:FTS支持的搜索和预先计算的每条消息摘要即使在大型存档中也能保持滚动和过滤响应。
- **可验证的完整性**:每个资产的SHA-256哈希加上可选的Ed25519签名使真实性和篡改检查变得简单。
- **Chunk友好档案**:大型数据库可以分块用于httpvfs流式传输;伴侣 `chunks.sha256` 文件列出了每个块的摘要,这样客户端就可以信任流式blob,而无需重新计算哈希值。
- **一键托管**:交互式向导可以直接发布到GitHub Pages或Cloudflare Pages,或者您可以使用CLI预览命令在本地提供捆绑包。

## 灾难恢复档案(`archive` 命令)

使用 `archive` 子命令,当你需要 *可恢复的* 快照(而不仅仅是只读共享包)。每个ZIP下 `./archived_mailbox_states/` 包括:

- 由与相同的清理管道处理的SQLite快照 `share`,但使用 `archive` 擦除预设,使ack/read状态、收件人、附件和邮件正文保持不变。
- Git仓库的逐字节副本(`STORAGE_ROOT`),保留markdown工件、附件和钩子脚本。

### 快速参考

```bash
# Save current state (defaults to the lossless preset)
uv run python -m mcp_agent_mail.cli archive save --label nightly

# List available restore points (JSON is handy for scripts)
uv run python -m mcp_agent_mail.cli archive list --json

# Restore after a disaster (backs up any existing DB/storage before overwriting)
uv run python -m mcp_agent_mail.cli archive restore archived_mailbox_states/.zip --force```

在恢复CLI期间:

1. 将ZIP解压缩到临时目录中。
1. 移动任何现有 `storage.sqlite3`WAL/SHM兄弟姐妹,以及 `STORAGE_ROOT` 进入时间戳 `.backup-` 文件夹,这样就不会丢失任何东西。
1. 将快照复制回配置的数据库路径,并根据存档内容重建存储仓库。

每个存档都会写入一个 `metadata.json` 描述所捕获项目的清单、擦洗预设和友好的提醒 `archive restore …` 命令稍后运行。

### 重置安全网

`clear-and-reset-everything` 现在提供在删除任何内容之前创建其中一个存档。默认情况下,它以交互方式提示;通过 `--archive/--no-archive` 强制选择,并与 `--force --no-archive` 用于非交互式自动化。成功创建存档后,CLI会打印路径和还原命令,以便您以后可以撤消重置。

## 邮箱运行状况: `am doctor`

这 `doctor` 命令组提供全面的诊断和修复功能,以维护邮箱健康。它强调 **数据安全**--在任何破坏性操作之前创建备份,并使用半自动修复来防止意外数据丢失。

### 为什么 `am doctor`?

随着时间的推移,邮箱状态可能会漂移:

- **陈旧的锁**:进程崩溃留下 `.archive.lock` 或 `.commit.lock` 阻止操作的文件
- **孤立记录**:代理将被删除,但其邮件收件人仍保留在数据库中
- **FTS索引不同步**:全文搜索索引与实际邮件不同步
- **已过期的文件保留**:预订过期但未清理
- **WAL文件**:SQLite WAL/SHM文件累积(运行期间正常,但值得监控)

医生命令检测这些问题并提供安全、自动的修复。

### 诊断检查

对邮箱运行全面的诊断:

```bash
# Check all projects
uv run python -m mcp_agent_mail.cli doctor check

# Check with verbose output
uv run python -m mcp_agent_mail.cli doctor check --verbose

# JSON output for automation
uv run python -m mcp_agent_mail.cli doctor check --json```

**它检查什么:**

|检查|状态|描述|
|-------|--------|-------------|
|锁定|确定/警告|检测崩溃进程中的过时存档和提交锁定|
|数据库|正常/错误|运行 `PRAGMA integrity_check` SQLite损坏|
|孤立记录|确定/警告|查找没有相应代理的邮件收件人|
|FTS索引|确定/警告|比较消息计数与FTS索引条目|
|文件保留|确定/INFO |统计等待清理的过期保留|
|WAL文件|确定/信息|报告SQLite WAL/SHM文件的存在|

**输出示例:**

MCP Agent Mail Doctor - Diagnostic Report

Check Status Details
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Locks OK No stale locks found
Database OK Database integrity check passed
Orphaned OK No orphaned records found
FTS Index OK FTS index synchronized (1,234 messages)
File Res. INFO 4 expired reservation(s) pending cleanup
WAL Files OK No orphan WAL/SHM files

All checks passed!```

半自动维修

修复命令使用 半自动方法:

  • 安全维修 (锁、过期预订)自动应用
  • 影响维修的数据 (孤儿清理)需要确认
  • A. 在进行任何更改之前创建备份
# Preview what would be repaired (dry-run)
uv run python -m mcp_agent_mail.cli doctor repair --dry-run

# Run repairs with prompts for data changes
uv run python -m mcp_agent_mail.cli doctor repair

# Auto-confirm all repairs (for automation)
uv run python -m mcp_agent_mail.cli doctor repair --yes

# Specify custom backup location
uv run python -m mcp_agent_mail.cli doctor repair --backup-dir /path/to/backups```

**维修工作流程:**

1. **创建备份** --在任何更改之前创建Git捆绑包+SQLite副本
1. **安全维修** (自动应用):
- 修复陈旧的锁(删除孤立的锁 `.archive.lock`, `.commit.lock` 文件)
- 释放过期的文件保留(标记 `released_ts` 在数据库中)
1. **数据修复** (需要确认):
- 删除孤立邮件收件人
- 重建FTS索引(如果需要)

### 备份管理

医生在维修前创建带时间戳的备份。您还可以直接管理备份:

```bash
# List all available backups
uv run python -m mcp_agent_mail.cli doctor backups

# JSON output for scripting
uv run python -m mcp_agent_mail.cli doctor backups --json```

**备份内容:**

每个备份包括:

- `database.sqlite3` --完整的SQLite数据库副本
- `database.sqlite3-wal`, `database.sqlite3-shm` --WAL文件(如果存在)
- `archive.bundle` 或 `{project}.bundle` --归档存储库的Git捆绑包
- `manifest.json` --元数据:创建时、原因、包含的内容、还原说明

**目录结构:**

{storage_root}/backups/
2026-01-06T12-30-45_doctor-repair/
manifest.json
database.sqlite3
archive.bundle```

从备份恢复

如果出现问题,请从任何备份还原:

# Preview what would be restored
uv run python -m mcp_agent_mail.cli doctor restore /path/to/backup --dry-run

# Restore (prompts for confirmation)
uv run python -m mcp_agent_mail.cli doctor restore /path/to/backup

# Skip confirmation prompt
uv run python -m mcp_agent_mail.cli doctor restore /path/to/backup --yes```

**还原过程:**

1. 验证备份清单是否存在并且可读
1. 显示备份元数据(创建时间、原因、内容)
1. **创建还原前备份** 当前状态(安全网)
1. 从备份还原SQLite数据库
1. 从捆绑包中恢复Git存档
1. 报告遇到的任何错误

**安全特性:**

- 当前数据库另存为 `*.sqlite3.pre-restore` 覆盖之前
- 当前存档另存为 `*.pre-restore` 覆盖前的目录
- 还原过程中的错误会被捕获并报告

### 最佳实践

1. **定期运行诊断程序**: `am doctor check` 快速且无损
1. **维修前检查**:使用 `--dry-run` 首先看看会发生什么变化
1. **保留备份**:在验证系统是否正常之前,不要删除旧备份
1. **自动检查**:包括 `am doctor check --json` 在您的CI/预警监控中

### 快速入门:交互式部署向导

导出和部署最简单的方法是交互式向导,它支持GitHub Pages和Cloudflare Pages:

```bash
# Via CLI (recommended)
uv run python -m mcp_agent_mail.cli share wizard

# Or run the script directly
./scripts/share_to_github_pages.py```

#### 巫师在做什么

该向导提供完全自动化的端到端部署体验:

1. **会话恢复**:检测中断的会话,并提供从您中断的位置继续,避免重新导出
1. **配置管理**:记住您上次的设置并提供重复使用它们,从而节省重复导出的时间
1. **部署目标选择**:在GitHub页面、Cloudflare页面或本地导出之间进行选择
1. **自动CLI安装**:检测并安装缺失的工具(`gh` 对于GitHub, `wrangler` Cloudflare)
1. **引导式身份验证**:GitHub和Cloudflare的逐步浏览器登录流程
1. **智能项目选择**:
- 在格式化表中显示所有可用项目
- 支持多种选择模式: `all`,单个号码(`1`),列表(`1,3,5`),或范围(`1-3`, `2-5,8`)
- 记住您之前的选择,以便快速重新导出
1. **重动作配置**:从中选择 `standard` (清除API密钥/令牌等机密,保留代理名称)或 `strict` (编辑所有邮件正文)
1. **加密签名**:可选Ed25519签名,可自动生成密钥或重用现有密钥。生成的密钥被写入 `~/.mcp-agent-mail/signing-keys/` (模式0700,从不连接到cwd),因此它们不会意外 `git add -f`'d进入存储库
1. **飞行前验证**:在开始导出之前,检查GitHub仓库名称是否可用
1. **部署摘要**:显示将部署的内容(项目计数、捆绑包大小、目标、签名状态)并要求确认
1. **导出和预览**:导出捆绑包并启动具有自动端口检测功能的交互式预览服务器(尝试9000-9100)
1. **交互式预览控件**:
- 按 **r** 强制浏览器刷新(手动缓存中断)
- 按 **d** 跳过预览并立即部署
- 按 **q** 退出预览服务器
1. **自动刷新查看器资源**:始终确保使用源代码树中的最新HTML/JS/CSS,即使在重用捆绑包时也是如此
1. **实时部署**:实时流式传输git和部署输出,以便您跟踪进度
1. **自动部署**:创建仓库、启用页面、推送代码并为您提供实时URL

#### 会话恢复(最新版本中的新功能)

如果您中断向导(关闭终端、预览时按Ctrl+C等),它会将您的进度保存到 `~/.mcp-agent-mail/wizard-session/`。再次运行向导时:

Incomplete session detected
Projects: 3 selected
Stage: preview
Workspace: ~/.mcp-agent-mail/wizard-session/bundle

Resume where you left off? (Y/n):```

保存的内容:

  • 选定项目和擦洗预设
  • 部署配置(目标、仓库名称等)
  • 签署关键偏好和路径
  • 导出的捆绑包(会话工作区中)
  • 当前阶段(预览、部署)

恢复场景:

  • 预览期间关闭终端:简历→ 跳过再出口→ 立即启动预览
  • 出口后改变主意了:简历→ “重复使用捆绑包?”→ 预览或重新导出
  • 想稍后部署:简历→ 在预览中按“d”→ 无需重新导出即可部署
  • 对查看器代码进行了更改:简历→ 从源树自动刷新资产

成功部署后,会话状态将自动清除。如果会话无效(工作区被删除、项目被删除等),会话也会被清除。

配置持久性

向导将您的配置保存到 ~/.mcp-agent-mail/wizard-config.json 每次成功部署后。在后续运行中,它将显示:

Previous Configuration Found
Projects: 3 selected
Redaction: standard
Target: github-new

Use these settings again? (Y/n):```

这允许使用相同的设置快速重新部署。保存的配置包括:

- 选定的项目索引(根据当前项目列表进行验证)
- 红色动作预设
- 部署目标和参数(仓库名称、隐私、项目名称)
- 签名首选项(是否签名,是否生成新密钥)
- 上次使用的签名密钥路径(在不生成新密钥时作为默认路径提供)

配置与项目无关:如果添加或删除项目,向导将验证已保存的索引,并在需要时提示重新选择。

**session和config的区别:**

- **会话状态** (`wizard-session/`):临时,用于恢复中断的运行,包括导出的捆绑包
- **配置文件** (`wizard-config.json`):持久,用于在新运行中“使用上次设置”,无捆绑包

#### 多项目选择

项目选择器支持灵活的选择语法:

Available Projects:

Slug Path

1 backend-abc123 /abs/path/backend
2 frontend-xyz789 /abs/path/frontend
3 infra-def456 /abs/path/infra
4 scripts-ghi789 /abs/path/scripts

Select projects to export (e.g., 'all', '1,3,5', or '1-3'):```

选择模式:

  • all:导出所有项目(默认)
  • 1:仅出口项目#1
  • 1,3,5:出口项目#1、#3和#5
  • 1-3:出口项目#1、#2和#3(包括范围)
  • 2-4,7:导出项目#2、#3、#4和#7(组合范围和列表)

无效的选择(超出范围、格式错误)将被拒绝,并显示有用的错误消息,向导将再次提示。

动态端口分配

如果端口9000正在使用中,预览服务器会自动检测9000-9100范围内的可用端口,而不会失败。显示实际端口:

Launching preview server...
Using port 9001 (Ctrl+C to stop server)
Waiting for server to start...
✓ Server ready, opening browser at http://127.0.0.1:9001```

这可以防止在运行多个预览或其他服务使用端口9000时发生端口冲突。

#### 部署摘要面板

在开始导出之前,向导会显示一个全面的摘要:

═══ Deployment Summary ═══

Projects: 3 selected
Bundle size: ~32 MB
Redaction: standard
Target: GitHub Pages
Repository: mailbox-viewer-2024
Visibility: Private
Signing: Enabled (Ed25519)

Proceed with export and deployment? (Y/n):```

这为您提供了最后一次机会来查看所有设置,并在需要时取消。捆绑包大小估计基于每个项目约10 MB加上静态资产约2 MB。

实时部署流媒体

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

常见问题

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

在客户端按下面的安装命令接入:uv run python -m mcp_agent_mail.cli config set-port 9000。装完在客户端配置里引用同一个包或端点。

MCP Agent Mail 怎么在 Claude、Cursor、Windsurf 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

MCP Agent Mail 收费吗?

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

MCP Agent Mail 需要 API Key 吗?

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

MCP Agent Mail 支持哪些客户端?

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

MCP Agent Mail 能提供哪些能力?

资料显示能力标签包括 多代理协作、Python、Claude、开发工具。具体工具清单以官方文档为准。

MCP Agent Mail 需要什么运行环境?

运行时为 Python;属于本地进程,需要在本机装好运行环境。

MCP Agent Mail 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

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

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