agents-chat-mcp

概述

agents-chat-mcp 是一个基于 MCP（Model Context Protocol）的聊天桥接服务器，将多个 Agent 接入同一个 ChatRoom，实现对话式协作。

之前我一直认为有 SubAgent 模式就足够了，直到某一天我需要垮设备联调，所以花了两天写了一个最小化聊天MCP。

安装

以 claude 为例：

# 当前项目安装
claude mcp add agents-chat-mcp -- npx -y @eos./agents-chat-mcp

# 全局安装
claude mcp add agents-chat-mcp -s user -- npx -y @eos./agents-chat-mcp

# 移除
mcp remove agents-chat-mcp

使用

1. chat直接输入：

接入聊天 room:chat-test name:leader

2. 配置环境变量(编辑 ~/.claude/settings.json):

{
  "mcpServers": {
    "agents-chat-mcp": {
      "command": "npx",
      "args": ["-y", "@eos./agents-chat-mcp"],
      "env": {
        "AGENTS_CHAT_ROOM_NAME": "project-name",
        "AGENTS_CHAT_NAME": "leader"
      }
    }
  }
}

架构

Claude Code (alice) ──MCP──▶ server.mjs ──┐
Claude Code (bob)   ──MCP──▶ server.mjs ──┼──▶ ChatRoomServer (127.0.0.1:11666)
Claude Code (carol) ──MCP──▶ server.mjs ──┘       HTTP REST + SSE
                                               └─ rooms / messages / events

多个 MCP 实例共享同一个 ChatRoom 服务器：首个实例启动内置服务器，后续实例自动检测并连接。

文件结构

├── server.mjs                    # MCP 入口，注册 4 个工具 + 内置服务器启动
└── lib/
    ├── chat-room-server.mjs      # 内置 ChatRoom HTTP/SSE 服务器
    ├── chat-room-client.mjs      # ChatRoom HTTP/SSE 客户端
    └── protocol.mjs              # 状态常量、唤醒 Prompt 构建、消息过滤

部署模式

模式 A:内置服务器(默认)

不设置 AGENTS_CHAT_SERVER_URL,自动在 127.0.0.1:11666 启动内置服务器。

如需让局域网或其他机器访问内置服务器,设置 AGENTS_CHAT_PUBLIC_SERVER=1 后会监听 0.0.0.0:11666。只在可信网络中开启,避免把未鉴权的 ChatRoom 服务暴露到公网。

模式 B:外部服务器

设置 AGENTS_CHAT_SERVER_URL,连接已运行的服务器。

启动外部服务器:

node server.mjs

客户端配置:

{
  "mcpServers": {
    "agents-chat-mcp": {
      "env": {
        "AGENTS_CHAT_SERVER_URL": "http://x.x.x.x:11666"
      }
    }
  }
}

| 环境变量 | 必填 | 说明 | 默认值 | |---|---|---|---| | AGENTS_CHAT_SERVER_URL | 否 | ChatRoom 服务器地址 | 不设置 → 启动内置服务器 | | AGENTS_CHAT_PUBLIC_SERVER | 否 | 设置为 1 时内置服务器监听 0.0.0.0 | 不设置 → 127.0.0.1 | | AGENTS_CHAT_ROOM_NAME | 是 | 房间名,自动 slug 化为 room ID | - | | AGENTS_CHAT_NAME | 是 | Agent 身份,用于身份发送和本地存储隔离 | - |

工作流程

1. 调用 agent_chat_register(user, room) 注册身份
2. 调用 agent_chat_send(text="我已成功接入", status="idle") 发送接入确认
3. 调用 agent_chat_watch() 持续等待 @ 消息
4. 出错或错过消息后,调用 agent_chat_helper(action="history") 回补最近消息

agent_chat_register

注册身份,首次使用或切换房间时调用。

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | user | string | 是 | Agent 名称,用于 @ 触发 | | room | string | 是 | 房间名称,自动 slug 化为 ID |

agent_chat_helper

查询房间、代理、历史消息、搜索消息、查看状态。

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | action | enum | 是 | help/room/agents/history/search/status | | query | string | 否 | 搜索关键词,action=search 时必填 | | room_id | string | 否 | 房间 ID,action=agents/history/search 时使用 | | limit | number | 否 | 历史消息条数,action=history 时使用,默认 10 |

agent_chat_watch

阻塞等待 @ 本 Agent 的消息,超时返回 { "timeout": true }。

| 参数 | 类型 | 默认值 | 说明 | |---|---|---|---| | timeout_ms | number | 300000 | 最大等待时间(毫秒),默认 5 分钟 |

典型用法:/loop agent_chat_watch → 执行任务 → agent_chat_send 回写

agent_chat_send

发送消息或广播状态。要唤醒其他 Agent,消息正文必须包含 @username 或 @all。

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | text | string | 是 | 消息正文 | | status | enum | 是 | idle / working / awaiting / blocked |

消息协议

Agent 通过 @ 机制接收消息:

• @username - 仅该用户接收
• @all - 所有用户接收

示例:

@alice 请帮我审查代码        # 仅 alice 接收
@all 会议即将开始            # 所有人接收

Agent 通过 agent_chat_watch 阻塞等待,只有匹配的消息才会唤醒。

测试

使用浏览器打开 tests/test_api.html,可视化测试所有 API 和 MCP 工具。

node server.mjs &
open tests/test_api.html