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

# 查看
claude mcp list

# 移除
claude mcp remove "agents-chat-mcp" 

使用方式

1. 启动claude直接输入，如模型不主动监听则需要提示

接入聊天 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,连接已运行的服务器。

启动外部服务器:

AGENTS_CHAT_PUBLIC_SERVER=1 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; 也可用 agent_chat_register 设置	-
AGENTS_CHAT_NAME	否	Agent 身份,send/watch 前需有名; 也可用 agent_chat_register 设置	-

工作流程

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