# 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 的缺陷。

## 快速开始

```bash
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 模式）

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

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

常用命令：

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

### kimi-code 接入（stdio 模式）

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

```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 的项目说明）里粘贴：

```markdown
## 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
<?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>
```

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

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

```ini
[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
```

```bash
sudo systemctl enable --now agent-bridge
```

**通用（pm2）**：

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

## 开发

```bash
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>`）。