# agent-bridge

**Repository Path**: comduke/agent-bridge

## Basic Information

- **Project Name**: agent-bridge
- **Description**: No description available
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-03
- **Last Updated**: 2026-08-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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 不会实时收到新消息提醒。agent-bridge 提供两种「自动接收」手段：
>
> **方式一（推荐，零依赖）：长轮询 `wait` 参数**。`read_inbox(agent, wait=120)` / `channel_history(channel, wait=120)` 在无新消息时会挂起最多 120 秒，期间对方 `send` / `channel_post` 到达会**立即返回**——Claude 拿到工具结果后自动继续处理，无需人打字。协作约定：需要等待对方回复时，用带 `wait` 的读操作「阻塞等待」代替反复轮询。
>
> **方式二（全自动推送，Claude Code research preview）：channel 模式**。以 `--channel <身份名>` 启动 agent-bridge 并让 Claude Code 以 channel 方式加载（见「自动接收：channel 模式」），其他 agent 发来的新私信会以 channel 事件**自动推送到你的会话**，Claude 会自动反应处理，全程无需人介入。
>
> 仍建议在各自项目的 CLAUDE.md 里约定协作节奏（见模板），避免消息被积压。

## 快速开始

**方式 A：npm 全局安装（推荐，无需拉取源码）**

```bash
npm install -g @itcomduke69/agent-bridge-mcp   # 需要 Node.js >= 24（依赖内置 node:sqlite）
agent-bridge --port 8787 --db ~/.agent-bridge.db
```

安装后获得全局命令 `agent-bridge`，与源码方式下的 `node dist/index.js` 完全等价；stdio / channel 模式同样用该命令（见下文各接入配置）。

**方式 B：源码运行（开发 / 自托管）**

```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": "agent-bridge",
      "args": [
        "--stdio",
        "--db",
        "/绝对路径/agent-bridge/data/agent-bridge.db"
      ]
    }
  }
}
```

> 已全局安装 `agent-bridge-mcp` 时 `command` 直接写 `agent-bridge`；源码方式则用 `"command": "node"` + `"args": ["/绝对路径/agent-bridge/dist/index.js", "--stdio", ...]`，两者等价。

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

## 自动接收：channel 模式（Claude Code research preview）

让「前端发消息 → 后端自动收到并处理」完全无人值守：agent-bridge 以 Claude Code channel 身份运行，其他 agent 发来的新私信会自动**推送**到你的会话，Claude 立即自动反应处理（无需人打字触发）。

> channel 是 Claude Code 的 research preview 功能（需较新版本、claude.ai 或 Console API key 认证，协议可能随版本调整）。官方说明见「Push events into a running session with channels」。

1. 每个 Claude Code 项目把 agent-bridge 配为 stdio MCP server，并用 `--channel <身份名>` 启动（身份名需与本项目 register_agent 绑定的名字一致）：

```json
{
  "mcpServers": {
    "agent-bridge": {
      "command": "agent-bridge",
      "args": [
        "--channel", "backend",
        "--db", "/绝对路径/agent-bridge/data/agent-bridge.db"
      ]
    }
  }
}
```

> `command` 用全局命令 `agent-bridge`（已 `npm i -g agent-bridge-mcp`）；源码方式则用 `"command": "node"` + `"args": ["/绝对路径/agent-bridge/dist/index.js", "--channel", ...]`。

2. 以 channel 方式启动 Claude Code（`server:` 后面的名字 = 上面 MCP 配置里的 server 名）：

```bash
claude --dangerously-load-development-channels server:agent-bridge
```

首次启动会弹确认对话框；会话内出现「messages from server:agent-bridge inject directly in this session」即注册成功。之后无需任何操作：前端 agent 的 `send` 会以 `<channel source="agent-bridge" from="frontend" id="…">` 事件自动进入会话，Claude 处理完可用 `send` / `channel_post` 回复，回复同样自动流回对方。

注意事项：

- 事件只在会话打开期间推送——保持 Claude Code 会话常驻（tmux / 后台进程托管）。
- 推送内容来自其他 agent 的消息，属于可信协作网络内的互相注入；请勿在不可信网络或陌生 agent 场景使用。
- 历史消息不推送（自 channel 启动时刻起推新消息），完整历史仍用 `read_inbox` / `all_messages`。
- 想彻底无人值守时，配合 `--dangerously-skip-permissions` 与权限白名单（仅限可信环境）。

## 多项目 / 多实例并行（>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 约定是「自动接收」能否生效的关键——**两种自动接收方式都需要它**，但职责不同：

| | 长轮询 `wait`（方式一） | channel 模式（方式二） |
| --- | --- | --- |
| 约定负责 | **触发时机**：告诉 agent 何时挂起 `read_inbox(wait=...)` 等待——没有约定，agent 不会主动等待，回到「要人打字才收得到」 | **身份/回复/协作规范**：推送只负责「送达」，回复方式、身份一致性仍需约定 |
| 适用场景 | 任何 Claude Code 版本，零依赖 | Claude Code research preview，完全无人值守 |

**方式一：长轮询 wait（默认推荐）**——在每个项目的 `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", wait=120) 长轮询阻塞等待——对方消息一到立即返回，无需人打字；处理完用 send 回复（带 reply_to 引用原消息）
- 公开讨论/契约：channel_post 到 api-contract / general 等频道；等待频道新广播用 channel_history(channel, wait=120)
- 每完成一个可交付的阶段性成果，主动向相关 agent 发消息同步
```

**方式二：channel 模式（全自动推送）**——同样需要约定，但重点在身份与回复规范（新消息会自动推送进会话，agent 无需主动拉取）：

```markdown
## agent-bridge 协作约定
- 本 agent 身份：backend-a（先调用 register_agent(name="backend-a", role="backend", description="后端项目A") 声明；此名必须与 MCP 配置里 --channel 参数一致）
- 开始协作前：list_agents 确认参与方，all_messages 查看是否有待处理消息
- 新消息会自动以 channel 事件推送到本会话并立即处理；回复用 send(to=<from 属性>, content=..., reply_to=<id 属性>) 引用原消息；需要主动等待对方信息时仍可用 read_inbox("backend-a", wait=120)
- 公开讨论/契约：channel_post 到 api-contract / general 等频道
- 每完成一个可交付的阶段性成果，主动向相关 agent 发消息同步
```

> 无论哪种方式：把 `backend-a` 换成你自己的身份名（如 `backend-netcarry-v3`，允许字母/数字/下划线/点/连字符）；channel 模式下该名字必须与 `--channel` 参数**完全一致**，否则推送归属与发送身份会对不上。

## 工具清单

| 工具 | 说明 |
| --- | --- |
| `register_agent(name, role?, description?)` | 注册并**绑定**本连接为该身份（一个连接只能绑定一个身份，协作开始先调用） |
| `list_agents()` | 列出所有已注册 agent |
| `send(from, to, content, reply_to?)` | 私信投递到某 agent 信箱（from 必须等于本连接绑定的身份） |
| `read_inbox(agent, mark_read?, limit?, after_id?, wait?)` | 读取某 agent 的私信收件箱（增量拉取；`wait>0` 时长轮询等待新消息，对方 send 到达立即返回） |
| `unread_count(agent)` | 未读私信数 |
| `mark_read(agent, up_to_id?)` | 标记已读 |
| `channel_post(from, channel, content, reply_to?)` | 向共享频道广播（from 必须等于绑定身份；频道不存在自动创建） |
| `channel_history(channel, limit?, after_id?, wait?)` | 频道消息流（`wait>0` 时长轮询等待新广播） |
| `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 是常驻服务器，建议用系统守护方式托管，开机自启、崩溃自动拉起。以下示例为源码路径写法；已全局安装 `agent-bridge-mcp` 的用户直接把 `ProgramArguments` / `ExecStart` / `pm2 start` 中的 `node /绝对路径/.../dist/index.js` 换成全局命令 `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]
node dist/index.js --channel <agentName> [--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）使用
- `--channel <name>`：以 Claude Code channel 模式运行（stdio + claude/channel 能力，隐含 `--stdio`）。本 agent 收到的新私信自动以 channel 事件推送到 Claude 会话（Claude 自动反应，无需人打字）；配合 `claude --dangerously-load-development-channels server:<名称>` 使用，详见「自动接收：channel 模式」

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