# agents-chat-mcp

## 概述

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

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

## 安装
以 `claude` 为例：
```bash
# 当前项目安装
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直接输入，如模型不主动监听则需要提示
```text
接入聊天 room:chat-test name:leader
```

2. 配置化(编辑 `~/.claude/settings.json`):
```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`,连接已运行的服务器。

**启动外部服务器:**

```bash
AGENTS_CHAT_PUBLIC_SERVER=1 node server.mjs
```

**客户端配置:**

```json
{
  "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 工具。

```bash
node server.mjs &
open tests/test_api.html
```