Agent Handoff MCP

Agent Handoff MCP

一个以本地优先为原则的 Model Context Protocol 服务，用于 AI Agent 之间边界明确、可审计的任务交接。

Agent Handoff MCP 为 Claude、Codex、本地 Agent 和其他 MCP 客户端提供共享收件箱，同时不让一个模型控制另一个模型。Agent 可以发送结构化任务、确认接收、报告阻碍、完成任务，或取消自己最初排入队列的任务。每次状态变更都会记录责任方，并保存在 SQLite 中。

为什么要开发它

多 Agent 系统通常通过聊天记录、临时文件或供应商专属的编排方式传递任务。这会丢失任务归属、生命周期状态、授权边界和持久审计记录。此服务将任务交接转换为一个小型协议对象：

sender -> queued -> accepted -> completed
                   |             ^
                   v             |
                 blocked --------+

sender may cancel only while queued

此服务负责协调任务；它不会执行 Agent、获取参考资料、读取任意文件，也不会创建自主 Agent 循环。

MCP 工具

工具	用途
handoff_whoami	显示经过身份验证的身份、边界和策略修订版本。
handoff_send	向获授权的接收方发送结构化任务交接。
handoff_inbox	列出发给当前身份的任务交接。
handoff_get	读取任务交接及其仅追加的事件历史记录。
handoff_acknowledge	接受已排队或受阻的任务。
handoff_update_status	将任务标记为受阻或已完成，或在任务仍处于排队状态时取消它。

设计特性

• 使用 WAL 模式和参数化查询的 SQLite 共享状态
• Streamable HTTP 和 stdio 传输
• 不透明的 UUID 任务交接、事件和线程标识符
• 显式设置 send_to 和 receive_from 授权，且不提供宽松的默认值
• 每个 Agent 的信息披露上限：public-safe、internal 或 restricted
• 严格的注册表验证：拒绝未知键、重复项和不受支持的版本
• 不可变策略快照：每次操作都会根据当前注册表进行检查，因此禁用身份、轮换令牌或收紧关系后，无需重启即可对现有会话生效
• 用于 HTTP 的哈希化、可过期持有者令牌绑定
• 幂等键，支持安全重试
• 回复链深度上限，限制自动往返
• 严格限制消息、数组、引用和请求大小
• 仅允许发送方和接收方读取，并根据当前策略重新授权
• 仅追加的生命周期事件；没有 MCP 删除工具
• 引用按惰性字符串存储，绝不会解引用

命令行

此软件包会安装一个分发器二进制文件 agent-handoff-mcp，其名称与软件包一致，因此一旦软件包发布到 npm，npx @sarutobi-sasuke/agent-handoff-mcp <command> 即可直接解析。（目前尚未发布；在此之前请使用源代码检出版本。）

命令	用途
http	启动共享的 Streamable HTTP 服务。
stdio	启动绑定到 HANDOFF_AGENT_ID 的 stdio 服务。
init --registry <path>	创建包含已禁用合成身份的初始注册表。
validate --registry <path>	验证注册表，不读取令牌或数据库。
issue --registry <path> --agent <id> --expires <iso8601>	签发一个会过期的令牌，并仅输出一次到 stdout。
rotate ...	替换现有令牌；旧令牌会立即失效。
disable / enable	在所有传输方式中启用或禁用某个身份。
revoke	移除某个身份的令牌绑定。
token	生成令牌和摘要，不触及注册表。

agent-handoff-http、agent-handoff-stdio、agent-handoff-token 和 agent-handoff-validate 也会作为直接调用的别名安装。

快速开始

要求：Node.js 22.13 或更高版本。

对于源代码检出：

git clone https://github.com/SarutobiSasuke8/agent-handoff-mcp.git
cd agent-handoff-mcp
npm ci
npm run build
cp .env.example .env
node dist/src/cli.js init --registry ./config/agents.yaml
node dist/src/cli.js issue --registry ./config/agents.yaml --agent example-alpha --expires 2027-01-01T00:00:00Z
node dist/src/cli.js issue --registry ./config/agents.yaml --agent example-beta --expires 2027-01-01T00:00:00Z
node dist/src/cli.js enable --registry ./config/agents.yaml --agent example-alpha
node dist/src/cli.js enable --registry ./config/agents.yaml --agent example-beta
node dist/src/cli.js validate --registry ./config/agents.yaml
npm run check
npm start

每条 issue 命令都会准确输出一次该身份的原始令牌；请通过安全通道将其交给相应客户端。系统只存储 SHA-256 摘要。完整的 PowerShell 和 POSIX 净室流程，请参阅 docs/QUICKSTART.md。

默认端点为：

GET  http://127.0.0.1:3220/healthz   liveness and policy state
GET  http://127.0.0.1:3220/readyz    readiness; 503 while the policy is degraded
POST http://127.0.0.1:3220/mcp
Authorization: Bearer handoff_<agent-specific-token>

服务器默认绑定到 localhost。在进行任何远程部署之前，请在服务器前设置经过身份验证的专用网络或 TLS 边界。

Stdio 模式

每个 stdio 客户端通过各自的进程环境提供身份，同时共用同一个 SQLite 数据库和注册表：

{
  "command": "node",
  "args": ["/absolute/path/agent-handoff-mcp/dist/src/cli.js", "stdio"],
  "env": {
    "HANDOFF_AGENT_ID": "example-beta",
    "HANDOFF_MCP_DB": "/absolute/shared/path/handoffs.sqlite",
    "HANDOFF_MCP_REGISTRY": "/absolute/path/agents.yaml"
  }
}

如果多个客户端要连接到同一个长期运行的服务，请使用 HTTP。如果本地客户端可以通过自身配置安全地接收固定身份，请使用 stdio。两种传输方式都会在每次操作时重新检查注册表，因此撤销也适用于正在运行的 stdio 会话。

本地 HTTP 一致性检查

在源代码检出目录中运行 npm run conformance（此前需运行 npm ci）。该命令会使用现有的固定版本 Registry 架构验证 server.json，启动隔离的环回服务器和一次性 SQLite 注册表测试夹具，使用 curl 检查缺少和无效的 bearer 请求，并运行官方框架，以及 Inspector tools/list 和只读的 handoff_whoami 调用。它需要 curl 和网络访问权限，以使用版本完全固定的 npx 工具。不会使用运维人员的注册表、现有数据库、已存储的登录信息或正在运行的服务。

断言的规范修订版本为 2026-07-28，使用 @modelcontextprotocol/[email protected] --requirements 2026-07-28。 当前 HTTP 传输方式针对 2025-11-25；仅采用无状态请求处理并不能证明支持更新的生命周期。Inspector @modelcontextprotocol/[email protected] 在应用冒烟测试中明确使用其旧版协议时代。上游框架没有 bearer 标头标志，因此仅供测试使用的 fetch 适配器会向该环回端点添加临时测试夹具标头。生产环境身份验证保持原样进行测试。

由于修订版本差异，该检查目前会以 1 退出。检查结果和已脱敏的日志会写入被忽略的 release-evidence/conformance/（可通过 HANDOFF_CONFORMANCE_OUTPUT 覆盖）。即使某项检查失败，也会运行所有检查。运行器绝不会静默地将失败设为基线或修复失败。提议将此命令用作发布门禁前，请参阅 首次运行检查结果。此命令不会发布内容或修改 CI。

运行指标

设置 HANDOFF_MCP_METRICS=1 可记录进程内计数器，包括创建、接受（认领）和过期的交接，以及存储错误；还会记录每种工具调用时长的直方图。只有从排队状态首次转为接受状态时，才计为认领。默认关闭。启用后，HTTP 和 stdio 服务器都会在启动时、每隔 60 秒以及正常关闭时，将一份 JSON 快照写入本地 stderr。例如，运行 HANDOFF_MCP_METRICS=1 agent-handoff-mcp stdio 2>metrics.jsonl 可捕获运行中进程的快照，而不会将其与 MCP stdout 混在一起。src/metrics.ts 中的快照采用 OpenTelemetry OTLP JSON 风格的 resourceMetrics/scopeMetrics 结构。它只包含固定的指标名称、计数、耗时和范围有限的工具名称标签；交接内容、标题、Agent 文本或令牌都不会进入记录器。未安装网络导出器或公共指标端点。由于当前交接生命周期没有过期转换，过期计数器始终为 0。

文档

MCP Registry 清单草案会使用 stdio 参数启动 npm 二进制文件，并要求操作人员提供 HANDOFF_AGENT_ID、HANDOFF_MCP_REGISTRY 和 HANDOFF_MCP_DB。它不会创建任何身份或凭据。 命名空间使用与 GitHub 完全一致的所有者拼写：io.github.SarutobiSasuke8。 prepublishOnly 包含 check:registry；发布和登录注册表仍是 操作人员需要分别执行的操作。构建不会包含源映射及其 JavaScript 链接。

• 无污染环境快速入门
• 协议与生命周期
• 架构
• 安全模型
• 注册表 JSON Schema
• 路线图
• 发布验证，2026-10-01
• 更新日志

范围边界

本项目是一个协调原语，而非通用任务平台。共享任务看板、决策、广播、状态、租约、通知、上下文提升和远程调度将由未来的可选模块提供。由六个工具组成的交接界面仍是稳定核心。

许可证

Apache-2.0。请参阅 LICENSE。

恢复与本地发布证据

使用 agent-handoff-mcp backup <out-file> 创建包含已验证注册表的实时 WAL 快照，并在停止服务后将其 restore <file> 到新文件中。现有目标文件需要使用 --force；实时服务、损坏的备份和不完整的恢复均会被阻止。有关命令、策略协调以及本地进程防护的限制，请参阅恢复。

本地 SQLite 存储会在启动时于 schema_migrations 表中应用有序且有记录的迁移。它可以识别现有的无版本存储， 并在应用待处理的更改前记录其检测到的架构。较新架构版本的存储将拒绝打开，并显示明确的错误；请使用兼容的二进制文件，而不要降级数据库。

npm run release:dry-run 会在受 git 忽略规则管理的 release-evidence/ 下生成本地检查、e2e 恢复证明、允许列表验证、SPDX SBOM、tarball 和 SHA-256 证据。软件包发布仍由所有者执行。