agent-bridge — 个人 Agent 消息桥（MCP 中心服务器）

让多个独立运行的 AI agent（Claude Code、Claude、kimi-code……）通过 MCP 协议自动互传消息、共享频道与工作上下文，省去「把 A 的输出复制给 B」的手动环节。

解决什么问题

你同时开着多个项目、每个项目里有一个 agent，它们各自独立工作但产出需要互相传递：

• 后端项目 → Claude Code
• 前端项目 → Claude（或 kimi-code）
• 多个后端项目并存 → Claude1（项目 A）、Claude2（项目 B）

以前只能手动复制粘贴。agent-bridge 让任意数量的 agent 直接通过 MCP 工具互相「发消息 / 收消息 / 回消息」，人只需在任一入口查看全量消息流并回复。

架构

后端项目A (Claude Code) ─┐
后端项目B (Claude Code) ─┼─▶ agent-bridge (Streamable HTTP MCP 中心服务器, SQLite 持久化)
前端项目 (Claude/kimi) ──┘           ▲
                                     │ 人在任一入口用 all_messages 统一查看 / send 回复

• 信箱（私信）：send(from, to, content) 一对一投递，对方 read_inbox 拉取
• 共享频道：channel_post(channel, content) 广播，channel_history 拉取
• 人视角统一入口：all_messages 按时间序返回全部私信+频道消息，人用 send(from='human', ...) 回复
• 互相引用：reply_to 字段可引用原消息 id，register_agent 让每个 agent 有稳定身份名
• 连接绑定身份：每个 MCP 连接（一个 Claude 终端 = 一个连接）首次 register_agent 即绑定该身份，之后该连接只能以自己身份发消息，防止冒名
• 持久化：消息存 SQLite，重启不丢

关于"自动"的说明（重要）：MCP 协议没有服务端主动推送机制——对方 agent 不会实时收到新消息提醒，需要定期调用 read_inbox（或 channel_history）拉取。建议在各自项目的 CLAUDE.md 里约定：「每完成一个阶段性任务后，先 read_inbox 检查是否有新消息，再决定下一步」，避免消息被积压。这是 MCP 架构的固有约束，不是 agent-bridge 的缺陷。

快速开始

cd agent-bridge
npm install
npm run build
npm run start -- --port 8787 --db ./data/agent-bridge.db

启动后是一个 Streamable HTTP MCP 服务器（默认 http://127.0.0.1:8787/mcp），另支持 --stdio 模式供仅支持 stdio 的客户端使用。

Claude Code 接入（HTTP 模式）

每个项目的终端里执行一次：

claude mcp add agent-bridge --transport http http://127.0.0.1:8787/mcp

常用命令：

claude mcp list                 # 查看已配置的 MCP
claude mcp remove agent-bridge  # 移除

kimi-code 接入（stdio 模式）

在 kimi-code 的 MCP 配置（如 ~/.kimi/mcp.json 或项目 .mcp.json）中加入：

{
  "mcpServers": {
    "agent-bridge": {
      "command": "node",
      "args": [
        "/绝对路径/agent-bridge/dist/index.js",
        "--stdio",
        "--db",
        "/绝对路径/agent-bridge/data/agent-bridge.db"
      ]
    }
  }
}

无论多少 agent 接入，都必须连同一个服务器：HTTP 模式天然共享；stdio 模式各实例要指向同一个 --db 文件路径。

多项目 / 多实例并行（>2 个 agent）

想让任意数量的项目 agent 互通，只需让每个实例连同一服务器、注册一个唯一名字：

项目	agent 实例	身份名
后端项目 A	Claude1（Claude Code）	backend-a
后端项目 B	Claude2（Claude Code）	backend-b
前端项目	Claude / kimi-code	frontend
你自己	任意入口	human

backend-a 与 backend-b 之间、与 frontend 之间都能直接 send / read_inbox 互传，信箱按名字隔离、互不干扰；人用 all_messages() 一个入口看全局进展。

每个项目的 CLAUDE.md / 约定模板

在每个项目的 CLAUDE.md（或 kimi-code 的项目说明）里粘贴：

## agent-bridge 协作约定
- 本 agent 身份：backend-a（先调用 register_agent(name="backend-a", role="backend", description="后端项目A") 声明）
- 开始协作前：list_agents 确认参与方，all_messages 查看是否有待处理消息
- 需要对方信息时：read_inbox("backend-a") 拉取新消息，处理完用 send 回复（带 reply_to 引用原消息）
- 公开讨论/契约：channel_post 到 api-contract / general 等频道
- 每完成一个可交付的阶段性成果，主动向相关 agent 发消息同步

工具清单

工具	说明
register_agent(name, role?, description?)	注册并绑定本连接为该身份（一个连接只能绑定一个身份，协作开始先调用）
list_agents()	列出所有已注册 agent
send(from, to, content, reply_to?)	私信投递到某 agent 信箱（from 必须等于本连接绑定的身份）
read_inbox(agent, mark_read?, limit?, after_id?)	读取某 agent 的私信收件箱（支持增量拉取）
unread_count(agent)	未读私信数
mark_read(agent, up_to_id?)	标记已读
channel_post(from, channel, content, reply_to?)	向共享频道广播（from 必须等于绑定身份；频道不存在自动创建）
channel_history(channel, limit?, after_id?)	频道消息流
list_channels()	列出所有频道
all_messages(limit?, after_id?)	人的统一入口：全量消息流（私信+频道）

身份与连接绑定（重要）

每个 MCP 连接代表一个 agent：第一个 register_agent 调用的名字就是本连接的绑定身份，之后：

• send / channel_post 的 from 必须等于绑定身份，冒名会被拒绝；
• 一个连接不能再注册第二个身份（想再开一个 agent 就再开一个 Claude/终端）；
• 读类工具（read_inbox / all_messages 等）不限制，任何连接可看（人的视角）；mark_read 只能操作自己的信箱；
• 人介入：开一个连接注册 human，用 send(from='human', ...) 回复；
• 安全边界：身份认领无密码——任何新连接都能注册/认领一个已存在的名字（会返回认领警告）。个人可信网络内可用；若网络环境不可信，务必启用 --token，并留意 register_agent 返回的「已存在/认领」提示。

典型协作流程

1. 后端 agent：register_agent('backend', 'claude-code')，完成后 send('backend', 'frontend', 'GET /api/users 返回 {id,name}，契约见频道 #api-contract')
2. 前端 agent：read_inbox('frontend') 收到契约 → 开始实现
3. 前端遇到问题：channel_post('frontend', 'general', '/api/users 缺分页参数，请确认')
4. 人在任意一端：all_messages() 看到全局进展，用 send('human', 'backend', '分页用 page/size 即可') 介入
5. 后端改完：send('backend', 'frontend', '已加 page/size', reply_to=<原消息id>)，前端按引用追溯上下文

常驻运行（守护进程）

agent-bridge 是常驻服务器，建议用系统守护方式托管，开机自启、崩溃自动拉起：

macOS（launchd）——保存到 ~/Library/LaunchAgents/com.agent-bridge.plist：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.agent-bridge</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/node</string>
    <string>/绝对路径/agent-bridge/dist/index.js</string>
    <string>--port</string><string>8787</string>
    <string>--db</string><string>/绝对路径/agent-bridge/data/agent-bridge.db</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>/tmp/agent-bridge.log</string>
  <key>StandardErrorPath</key><string>/tmp/agent-bridge.log</string>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.agent-bridge.plist   # 加载并启动
launchctl unload ~/Library/LaunchAgents/com.agent-bridge.plist # 停止

Linux（systemd）——/etc/systemd/system/agent-bridge.service：

[Unit]
Description=agent-bridge MCP message server
After=network.target

[Service]
ExecStart=/usr/bin/node /opt/agent-bridge/dist/index.js --port 8787 --db /opt/agent-bridge/data/agent-bridge.db
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now agent-bridge

通用（pm2）：

npm i -g pm2
pm2 start dist/index.js --name agent-bridge -- --port 8787 --db data/agent-bridge.db
pm2 save && pm2 startup   # 开机自启

开发

npm run build   # 编译到 dist/
npm test        # 构建 + 冒烟测试（启动服务器、多 agent 收发、双客户端并发、重启持久化）
npm run start   # 启动服务器（默认 127.0.0.1:8787）

CLI 参数

node dist/index.js [--port 8787] [--host 127.0.0.1] [--db data/agent-bridge.db] [--token <t>] [--cors-origin <o> ...]
node dist/index.js --stdio [--db data/agent-bridge.db]

• --host 0.0.0.0：允许局域网内其他机器/agent 连接（此时必须 --token，否则拒绝启动；局域网客户端访问时用 --allowed-host <局域网IP> 放行，可重复传）
• --token <t>：启用 Bearer 认证（所有 MCP 请求需带 Authorization: Bearer <t>）；也可用环境变量 AGENT_BRIDGE_TOKEN（推荐，避免 token 出现在进程列表）
• --allowed-host <h>：DNS rebinding 白名单额外放行的 Host（自动补端口；也可直接传 host:port 形式），如 --allowed-host 192.168.1.5
• --cors-origin <o>：允许浏览器跨域访问的 Origin 白名单（可重复传）。默认拒绝所有浏览器跨域（防止恶意网页读写本服务）；仅在使用 MCP Inspector 等浏览器工具时按需添加，如 --cors-origin http://localhost:5173
• --stdio：以 stdio 模式运行，供仅支持 stdio 的 MCP 客户端（如 kimi-code）使用

健康检查：GET http://127.0.0.1:8787/health 返回 {"ok":true,"service":"agent-bridge","sessions":N,"pending":M}，供守护进程/监控探活（启用 --token 时需带 Authorization: Bearer <t>）。