╔═══════════════════════════════════════════════════════════╗
║ ║
║ ░█▀▀░█░░░█▀█░█░█░█▀▄░█▀▀░░░█▀▄░█▀▀░█░░░█▀█░█░█ ║
║ ░█░░░█░░░█▀█░█░█░█░█░█▀▀░░░█▀▄░█▀▀░█░░░█▀█░░█░ ║
║ ░▀▀▀░▀▀▀░▀░▀░▀▀▀░▀▀░░▀▀▀░░░▀░▀░▀▀▀░▀▀▀░▀░▀░░▀░ ║
║ ║
║ Session A ──task──▶ [RELAY] ──SSE──▶ Session B ║
║ Session B ──reply─▶ [RELAY] ──notify─▶ Session A ║
║ │ ║
║ [SQLite] ║
║ ║
╚═══════════════════════════════════════════════════════════╝
克劳德中继MCP服务器
用于会话间通信的MCP服务器 克劳德代码 实例。通过持久存储、访问控制和@notice路由，在机器上路由任务、群聊和协调多个AI代理。
运作原理
Session A (host) Relay Server Session B (client)
| | |
|-- relay_send_task ------>| |
| |-- SSE push task ------>|
| | (processes task)
| |<-- relay_reply --------|
|<-- channel notification -| (task completed) |
中继器作为MCP服务器在stdio上运行。在 主机模式，它还启动了一个HTTP服务器，该服务器接受任务并通过SSE进行广播。在 客户端模式 （端口已占用），它订阅主机的SSE流并将消息中继到本地Claude Code会话。
特性
- SQLite持久性 （WAL模式）--任务、聊天和计算机注册表在重启后仍然有效
- 乐观锁定 --基于版本的并发控制可防止竞争条件
- Idempotency键 --无重复的安全任务重试
- 带ACL的房间 --每个代理每个房间的读/写/历史权限
- @提及路线 --
@researcher 仅交付给该代理 - 断路器 --降级的机器在连续3次故障后停止接收任务
- 指数退避 --带有抖动的SSE重新连接可防止闪电群
- 自我清理 --代理永远不会收到自己的广播消息
- 审核日志 --为调试记录的每个状态转换
- 观察者流 --SSE消防水带
/observe 用于仪表板
快速开始
npm install
npm run build
主机会话（运行HTTP服务器）
claude --dangerously-load-development-channels server:claude-relay
客户端会话（通过SSE连接到主机）
RELAY_URL=http://host-ip:8788 RELAY_SESSION_NAME=worker \
claude --dangerously-load-development-channels server:claude-relay
交叉机器（通过Tailscale或直接IP）
# On remote machine
RELAY_URL=http://100.86.56.43:8788 \
RELAY_TOKEN=your-shared-secret \
RELAY_SESSION_NAME=mac-mini \
claude --dangerously-load-development-channels server:claude-relay
配置
| 变量 | 默认值 | 描述 |
|---|
RELAY_PORT | 8788 | HTTP服务器端口 |
RELAY_BIND | 0.0.0.0 | 绑定地址 |
RELAY_URL | http://127.0.0.1:8788 | 中继URL（客户端模式） |
RELAY_TOKEN | _（空）_ | 身份验证的承载令牌（空=打开） |
RELAY_SESSION_NAME | _（自动）_ | 会话标识符 |
RELAY_TASK_TTL_HOURS | 8 | 任务到期时间 |
RELAY_DB_PATH | relay.db | SQLite数据库文件路径 |
MCP工具
| 工具 | 说明 |
|---|
relay_send_task | 将任务发送到另一个会话。返回轮询的任务ID。 |
relay_check_task | 检查任务状态并检索结果。 |
relay_reply | 向请求者报告任务结果。 |
relay_list_machines | 列出处于联机/脱机状态的已连接机器。 |
relay_chat | 向房间发送群聊消息。 |
relay_chat_history | 获取房间的最近聊天记录。 |
relay_respond_permission | 批准/拒绝远程会话的工具权限请求。 |
HTTP API
任务
| 方法 | 端点 | 身份验证 | 描述 |
|---|
| 职位 | /task | 是 | 创建任务（支持 idempotency_key) |
| 得到 | /task/:id | 是 | 检查任务状态和结果 |
| PUT | /task/:id | 是 | 提交任务结果 |
| 得到 | /tasks | 是 | 列出所有任务 |
聊天
| 方法 | 端点 | 身份验证 | 描述 |
|---|
| 职位 | /chat | 是 | 发送聊天消息（支持 @mentions) |
| 得到 | /chat | 是 | 按房间获取聊天记录 |
房间和门禁
| 方法 | 端点 | 身份验证 | 描述 |
|---|
| 得到 | /rooms | 是 | 列出所有具有ACL的房间 |
| 职位 | /rooms | 是 | 创建具有权限的房间 |
| PUT | /rooms/:id/acl | 是 | 设置每个代理的权限 |
每个代理的房间权限： read, write, history （每个真/假）。默认设置为打开（全部允许）。
机器
| 方法 | 端点 | 身份验证 | 描述 |
|---|
| 得到 | /machines | 是 | 列出处于联机/降级/脱机状态的机器 |
| 职位 | /machines/heartbeat | 是 | 客户端心跳 |
权限
| 方法 | 端点 | 身份验证 | 描述 |
|---|
| 职位 | /permission | 是 | 许可裁决（允许/拒绝） |
| 得到 | /permissions | 是 | 列出待处理的权限请求 |
流和可观测性
| 方法 | 端点 | 身份验证 | 描述 |
|---|
| 得到 | / | 否 | 健康检查 |
| 得到 | /subscribe | 是 | 客户端会话的SSE流 |
| 得到 | /observe | 是 | 所有事件的SSE消防水带（用于仪表板） |
| 得到 | /history | 是 | 初始加载的完整事件历史记录 |
建筑
src/
├── index.ts # Entry point — wires modules, HTTP routes, MCP tools
├── relay/
│ ├── tasks.ts # Task store: CRUD, state machine, optimistic locking
│ ├── chat.ts # Chat store: rooms, history
│ ├── machines.ts # Machine registry: heartbeat, circuit breaker
│ └── permissions.ts # Permission request/grant flow (in-memory)
└── store/
├── db.ts # SQLite setup, WAL mode, migrations
├── schema.ts # Table definitions
└── audit.ts # Append-only audit log
- 模块化单片 --具有明确边界、单一进程的域模块
- 双模 --主机（HTTP服务器）或客户端（SSE订阅者），启动时自动检测
- SQLite WAL --持久存储，每秒约50000次写入
- 乐观锁定 --
version 任务列可防止并发更新冲突 - 断路器 --连续3次故障将机器标记为
degraded - 指数回退+抖动 --SSE重新连接：
min(30s, 1s * 2^attempt * random)
发展
npm run dev # Watch mode with tsx
npm run build # Compile TypeScript
npm test # Run tests (48 tests across 7 suites)
路线图
- 人在循环审查UI --用于评估代理输出的三面板仪表板
- 法学硕士作为法官 --人工干预的自动评分规则
- 故障分类 --用于发现代理中断位置的结构化标记
- 黑曜石出口 --将评估数据导出到vault进行反射
- Ack协议 --带有重试和死信队列的送达确认
看 计划.md 对于完整的v2设计。
相关项目
作者
格莱布·卡利宁 --教育家、产品设计师、人类人工智能协作工具的构建者。
许可证
Apache 2.0——请参阅 许可证.
