# 野火机器人 MCP Server

Wildfire Robot MCP Server — 将野火IM机器人 SDK 封装为 [MCP (Model Context Protocol)](https://modelcontextprotocol.io) 服务，供 AI 智能体（Agent）调用野火IM机器人接口。

## 功能特性

基于野火IM的 `RobotService`，提供以下功能的 MCP Tool 接口：

- **消息**：发送消息、回复消息、撤回消息、更新消息，以及便捷的文本/图片/文件消息接口
- **用户**：获取用户信息（通过用户ID/手机号/用户名）、搜索用户、获取好友列表、获取用户机器人列表
- **资料**：获取机器人资料
- **群组**：创建/解散/转让群组、修改群信息、成员管理（添加/踢出/禁言/管理员/别名等）
- **文件上传**：上传文件

共 **34 个 MCP 工具**。

## 安全说明

此 MCP 服务仅对接野火IM的 **机器人 API**（`/robot/` 路径），机器人可执行的操作受 IM 服务端控制，权限范围有限。

### 关于认证

本 MCP 服务**不需要额外的认证机制**，因为每次调用工具时，请求参数中都包含了野火IM机器人的 `robotId` 和 `robotSecret`，由野火IM服务端负责鉴权。

> ⚠️ **部署到公网时必须使用 HTTPS**：由于 `robotId` 和 `robotSecret` 随每个请求明文传输，如果通过 HTTP 部署在公网，凭证会被中间人截获。生产环境务必通过 HTTPS、VPN 或内网访问。

### 关于本地文件操作

以下工具涉及**服务端本地文件系统**，要求 MCP 服务与调用方在同一台机器上（或至少能访问相同的文件路径）：

- `upload_file`
- `send_image_message` / `send_image_message_with_options` 的 `filePath` 模式
- `send_file_message` / `send_file_message_with_options` 的 `filePath` 模式

**部署到远程服务器时**：
- `filePath` 模式不可用（客户端提供的本地路径在服务器上不存在）
- 请改用 `imageUrl` / `fileUrl` 模式，传入可被 MCP 服务端访问的网络链接

### 不建议暴露管理 API

野火IM还提供 **管理后台 API**（`/admin/` 路径），可用于创建用户、删除消息、销毁群组等高级操作。但管理 API 权限极大，一旦暴露给 AI Agent 使用，可能造成严重安全风险。**强烈不建议**将管理 API 暴露给 Agent，如果出错会造成很大危害。

如果需要管理 API 的 MCP 服务，可以参考本项目自行封装，但务必注意：

- 管理密钥（admin secret）一旦泄露，整个 IM 服务将被控制
- AI Agent 可能误解用户意图执行危险操作（如批量删用户、删消息）
- 建议仅在内网可信环境使用，或对工具做严格的参数校验和白名单

一般情况下，使用本项目的 **机器人 MCP** 即可满足大多数业务需求。

## 快速开始

### 环境要求

- Node.js >= 18
- npm >= 8

### 安装

```bash
git clone <your-repo-url>
cd wf-robot-mcp-server.ts

# 安装依赖
npm install

# 构建
npm run build
```

### 配置

通过环境变量配置：

```bash
# 设置野火IM服务器地址（默认 http://localhost，端口80）
# 注意：机器人接口默认端口是80，不是18080（18080是管理后台端口）
export WF_IM_SERVER_URL=http://your-im-server
```

### 启动

支持两种运行模式：

#### 1. stdio 模式（默认，适用于 Claude Desktop 等本地 Agent）

```bash
npm start
# 或直接运行编译后的文件
node dist/index.js
```

#### 2. HTTP 模式（适用于部署在服务器上，供远程客户端连接）

```bash
# 设置端口，即启动 HTTP 服务
export WF_MCP_PORT=3100
npm start
```

启动后 MCP 服务监听在 `http://localhost:3100/mcp`，客户端可通过 Streamable HTTP 协议连接。

> **注意**：HTTP 模式支持需要客户端实现 [MCP Streamable HTTP 传输](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/transports/#streamable-http)。本地 Agent（如 Claude Desktop）通常使用 stdio 模式，不需要 HTTP。

### 多会话支持

HTTP 模式下，每个 Agent 初始化时会分配独立的 Session ID，**互不干扰**：

- 每个会话拥有独立的 `McpServer` 和 `Transport` 实例
- 会话间完全隔离，一个 Agent 的调用不影响其他 Agent
- 无效 Session ID 的请求会被拒绝（400）
- 空闲会话超时（10分钟）后自动清理，防止内存泄漏

### 验证

#### stdio 模式验证

启动后可通过标准输入/输出与客户端通信：

```bash
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}\n{"jsonrpc":"2.0","method":"notifications/initialized"}\n{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | node dist/index.js 2>/dev/null
```

#### HTTP 模式验证

```bash
# 健康检查
curl http://localhost:3100/

# 初始化
curl -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

# 列出工具（需要带上 Initialize 返回的 Mcp-Session-Id）
curl -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: <session-id>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
```

### 自动化测试脚本

项目提供了 `scripts/test-http.mjs`，可自动验证 MCP 协议、工具注册以及各工具调用。

```bash
# 先启动 HTTP 模式服务（示例端口 3100）
WF_MCP_PORT=3100 npm start

# 另开终端，运行测试
npm test                    # 仅验证协议 + 34 个工具是否注册
npm test -- --port 3100     # 指定端口
npm run test:tools          # 测试所有工具调用（需配置凭证）
```

不带凭证时，脚本只验证健康检查、初始化、会话管理和工具列表。要测试实际工具调用，设置以下环境变量：

```bash
export WF_TEST_ROBOT_ID=your_robot_id
export WF_TEST_ROBOT_SECRET=your_robot_secret
export WF_TEST_TARGET_USER=existing_user_id      # 用于用户/消息相关工具
export WF_TEST_TARGET_GROUP=existing_group_id    # 用于群组只读工具
export WF_TEST_TARGET_MESSAGE_UID=123456         # 用于 reply/recall/update
export WF_TEST_IMAGE_URL=https://example.com/test.png
export WF_TEST_FILE_URL=https://example.com/test.txt
export WF_TEST_FILE_NAME=test.txt
```

测试写操作时，显式开启对应范围：

```bash
# 测试消息发送工具
npm test -- --send

# 测试群组创建/修改等（会在 IM 服务器上创建一个测试群组）
npm test -- --group

# 测试解散/踢人/转让等高风险群组操作
npm test -- --destructive

# 测试全部工具
npm run test:tools
```

> 安全提示：`--destructive` 会实际执行解散群组、踢出成员、转让群主等操作，请确保在测试环境使用。

## API 接口说明

所有工具的前两个参数均为认证信息：

| 参数 | 类型 | 说明 |
|------|------|------|
| `robotId` | `string` | 机器人ID |
| `robotSecret` | `string` | 机器人密钥 |

### 消息工具

#### send_message
发送消息。

| 参数 | 类型 | 说明 |
|------|------|------|
| `sender` | `string` | 发送者用户ID |
| `conversation_type` | `number` | 会话类型：0-单聊, 1-群聊, 2-聊天室, 3-频道, 4-客服 |
| `conversation_target` | `string` | 会话目标ID |
| `conversation_line` | `number` | 会话线路（默认0） |
| `payload` | `string` (JSON) | 消息内容JSON字符串 |

> payload 示例：`{"type":1,"searchableContent":"hello"}`

#### reply_message
回复消息。

| 参数 | 类型 | 说明 |
|------|------|------|
| `messageUid` | `number` | 消息UID |
| `only2Sender` | `boolean` | 是否只回复给发送者（默认false） |
| `payload` | `string` (JSON) | 消息内容JSON字符串 |

#### recall_message
撤回消息。

| 参数 | 类型 | 说明 |
|------|------|------|
| `messageUid` | `number` | 消息UID |

#### update_message
更新消息内容。

| 参数 | 类型 | 说明 |
|------|------|------|
| `messageUid` | `number` | 消息UID |
| `payload` | `string` (JSON) | 新的消息内容JSON字符串 |

### 便捷消息工具

#### send_text_message
发送文本消息（便捷接口，自动构造消息 payload）。

| 参数 | 类型 | 说明 |
|------|------|------|
| `sender` | `string` | 发送者用户ID |
| `conversation_type` | `number` | 会话类型：0-单聊, 1-群聊, 2-聊天室, 3-频道, 4-客服 |
| `conversation_target` | `string` | 会话目标ID |
| `conversation_line` | `number` | 会话线路（默认0） |
| `text` | `string` | 文本消息内容 |

#### send_image_message
发送图片消息，支持 MCP 服务端本地文件或网络图片 URL。自动生成缩略图并上传到 IM 服务器后发送。

| 参数 | 类型 | 说明 |
|------|------|------|
| `sender` | `string` | 发送者用户ID |
| `conversation_type` | `number` | 会话类型 |
| `conversation_target` | `string` | 会话目标ID |
| `conversation_line` | `number` | 会话线路（默认0） |
| `filePath` | `string` | **MCP 服务端本地图片路径**（与 imageUrl 二选一）。远程部署时不可用 |
| `imageUrl` | `string` | 网络图片 URL（与 filePath 二选一）。远程部署时请使用此参数 |

处理流程：
- 本地图片：读取 MCP 服务端文件 → 生成缩略图 → 上传原图 → 发送图片消息
- 网络图片：下载图片 → 生成缩略图 → 上传原图 → 发送图片消息

#### send_file_message
发送文件消息。MCP 服务端本地文件自动上传后发送，网络链接直接发送。

| 参数 | 类型 | 说明 |
|------|------|------|
| `sender` | `string` | 发送者用户ID |
| `conversation_type` | `number` | 会话类型 |
| `conversation_target` | `string` | 会话目标ID |
| `conversation_line` | `number` | 会话线路（默认0） |
| `filePath` | `string` | **MCP 服务端本地文件路径**（与 fileUrl 二选一）。远程部署时不可用 |
| `fileUrl` | `string` | 文件网络链接（与 filePath 二选一）。远程部署时请使用此参数 |
| `fileName` | `string` | 文件名（fileUrl 模式下必填） |
| `fileSize` | `number` | 文件大小，单位字节（可选） |

#### send_text_message_with_options
发送文本消息（便捷接口，可指定接收用户）。

| 参数 | 类型 | 说明 |
|------|------|------|
| `sender` | `string` | 发送者用户ID |
| `conversation_type` | `number` | 会话类型 |
| `conversation_target` | `string` | 会话目标ID |
| `conversation_line` | `number` | 会话线路（默认0） |
| `text` | `string` | 文本消息内容 |
| `to_users` | `string` (JSON) | 指定接收用户ID列表（可选），如 `["uid1","uid2"]` |

#### send_image_message_with_options
发送图片消息（支持 MCP 服务端本地文件或网络图片 URL，可指定接收用户，自动生成缩略图并上传）。

| 参数 | 类型 | 说明 |
|------|------|------|
| `sender` | `string` | 发送者用户ID |
| `conversation_type` | `number` | 会话类型 |
| `conversation_target` | `string` | 会话目标ID |
| `conversation_line` | `number` | 会话线路（默认0） |
| `filePath` | `string` | **MCP 服务端本地图片路径**（与 imageUrl 二选一）。远程部署时不可用 |
| `imageUrl` | `string` | 网络图片 URL（与 imageUrl 二选一）。远程部署时请使用此参数 |
| `to_users` | `string` (JSON) | 指定接收用户ID列表（可选） |

#### send_file_message_with_options
发送文件消息（MCP 服务端本地文件自动上传、网络链接直接发送，可指定接收用户）。

| 参数 | 类型 | 说明 |
|------|------|------|
| `sender` | `string` | 发送者用户ID |
| `conversation_type` | `number` | 会话类型 |
| `conversation_target` | `string` | 会话目标ID |
| `conversation_line` | `number` | 会话线路（默认0） |
| `filePath` | `string` | **MCP 服务端本地文件路径**（与 fileUrl 二选一）。远程部署时不可用 |
| `fileUrl` | `string` | 文件网络链接（与 filePath 二选一） |
| `fileName` | `string` | 文件名（fileUrl 模式下必填） |
| `fileSize` | `number` | 文件大小，单位字节（可选） |
| `to_users` | `string` (JSON) | 指定接收用户ID列表（可选） |

### 用户工具

#### get_user_info
通过用户ID获取用户信息。

| 参数 | 类型 | 说明 |
|------|------|------|
| `userId` | `string` | 用户ID |

#### get_user_info_by_mobile
通过手机号获取用户信息。

| 参数 | 类型 | 说明 |
|------|------|------|
| `mobile` | `string` | 手机号 |

#### get_user_info_by_name
通过用户名获取用户信息。

| 参数 | 类型 | 说明 |
|------|------|------|
| `userName` | `string` | 用户名 |

#### get_owner_friend_list
获取机器人 owner 的好友列表。

无额外参数。

#### search_user_by_display_name
根据昵称搜索用户。

| 参数 | 类型 | 说明 |
|------|------|------|
| `keyword` | `string` | 搜索关键词（用户昵称） |

#### get_user_robots
获取指定用户拥有的机器人列表。

| 参数 | 类型 | 说明 |
|------|------|------|
| `userId` | `string` | 用户ID |

### 资料工具

#### get_robot_profile
获取机器人资料。

### 群组工具

#### create_group
创建群组。

| 参数 | 类型 | 说明 |
|------|------|------|
| `groupInfo` | `string` (JSON) | 群组信息，如 `{"name":"群名","portrait":"","type":0,"extra":""}` |
| `members` | `string` (JSON) | 成员列表（可选），如 `[{"member_id":"uid","type":0,"alias":""}]` |
| `memberExtra` | `string` | 成员额外信息（可选） |

#### get_group_info
获取群组信息。

| 参数 | 类型 | 说明 |
|------|------|------|
| `groupId` | `string` | 群组ID |

#### dismiss_group
解散群组。

| 参数 | 类型 | 说明 |
|------|------|------|
| `groupId` | `string` | 群组ID |

#### transfer_group
转让群组。

| 参数 | 类型 | 说明 |
|------|------|------|
| `groupId` | `string` | 群组ID |
| `newOwner` | `string` | 新群主用户ID |

#### modify_group_info
修改群组信息。

| 参数 | 类型 | 说明 |
|------|------|------|
| `groupId` | `string` | 群组ID |
| `type` | `number` | 修改类型：0-群名, 1-群头像, 2-群extra, 3-群禁言, 4-群允许发言, 5-群类型, 6-群搜索类型, 7-群自动同意加入, 8-群加入权限 |
| `value` | `string` | 新值 |

#### get_group_members
获取群组成员列表。

| 参数 | 类型 | 说明 |
|------|------|------|
| `groupId` | `string` | 群组ID |

#### get_group_member
获取群组成员信息。

| 参数 | 类型 | 说明 |
|------|------|------|
| `groupId` | `string` | 群组ID |
| `memberId` | `string` | 成员用户ID |

#### add_group_members
添加群组成员。

| 参数 | 类型 | 说明 |
|------|------|------|
| `groupId` | `string` | 群组ID |
| `members` | `string` (JSON) | 成员列表，如 `[{"member_id":"uid1","type":0,"alias":""}]` |
| `memberExtra` | `string` | 成员额外信息（可选） |

#### set_group_manager
设置/取消群组管理员。

| 参数 | 类型 | 说明 |
|------|------|------|
| `groupId` | `string` | 群组ID |
| `memberIds` | `string` (JSON) | 成员ID列表，如 `["uid1","uid2"]` |
| `isManager` | `boolean` | true-设置管理员, false-取消管理员 |

#### mute_group_member
禁言/取消禁言群组成员。

| 参数 | 类型 | 说明 |
|------|------|------|
| `groupId` | `string` | 群组ID |
| `memberIds` | `string` (JSON) | 成员ID列表 |
| `isMute` | `boolean` | true-禁言, false-取消禁言 |

#### allow_group_member
设置/取消群组成员发言权限。

| 参数 | 类型 | 说明 |
|------|------|------|
| `groupId` | `string` | 群组ID |
| `memberIds` | `string` (JSON) | 成员ID列表 |
| `isAllow` | `boolean` | true-允许发言, false-禁止发言 |

#### kickoff_group_members
踢出群组成员。

| 参数 | 类型 | 说明 |
|------|------|------|
| `groupId` | `string` | 群组ID |
| `memberIds` | `string` (JSON) | 要踢出的成员ID列表 |

#### quit_group
机器人退出群组。

| 参数 | 类型 | 说明 |
|------|------|------|
| `groupId` | `string` | 群组ID |

#### set_group_member_alias
设置群组成员别名。

| 参数 | 类型 | 说明 |
|------|------|------|
| `groupId` | `string` | 群组ID |
| `memberId` | `string` | 成员用户ID |
| `alias` | `string` | 别名 |

#### set_group_member_extra
设置群组成员额外信息。

| 参数 | 类型 | 说明 |
|------|------|------|
| `groupId` | `string` | 群组ID |
| `memberId` | `string` | 成员用户ID |
| `extra` | `string` | 额外信息 |

### 文件上传工具

#### upload_file
上传 **MCP 服务端本地文件** 到 IM 服务器（传入服务端本地文件路径，自动完成预签名获取和上传）。

| 参数 | 类型 | 说明 |
|------|------|------|
| `filePath` | `string` | **MCP 服务端本地文件路径**，如 `/path/to/image.png`。远程部署时不可用 |
| `mediaType` | `number` | 媒体类型（默认4-文件）：1-图片, 2-音频, 3-视频, 4-文件, 5-链接, 6-存储, 7-位置 |
| `contentType` | `string` (可选) | 文件 Content-Type，不传则根据文件扩展名自动识别 |

> ⚠️ 此工具读取的是 **MCP 服务端本地文件系统** 上的文件，因此仅在 MCP 服务与客户端在同一台机器时可用。远程部署时请先将文件上传到可被服务端访问的位置，或使用 `send_image_message` / `send_file_message` 的 `imageUrl` / `fileUrl` 模式。

## 部署到服务器

MCP 服务支持部署到服务器上，通过 HTTP 供远程客户端连接。

> ⚠️ **公网部署务必使用 HTTPS**：本服务不实现额外的认证层，机器人凭证 `robotId` / `robotSecret` 随每次工具调用明文传输。HTTP 部署在公网会导致凭证泄露。建议通过 Nginx/Caddy 等反向代理开启 HTTPS，或仅在 VPN/内网环境使用。

> ⚠️ **远程服务器不支持 `filePath` 模式**：`upload_file` 以及 `send_image_message` / `send_file_message` 的 `filePath` 模式依赖 MCP 服务端本地文件系统。远程部署时，请让客户端使用 `imageUrl` / `fileUrl` 模式传入可被服务端访问的网络链接。

### 使用 PM2 守护进程

```bash
npm install -g pm2
WF_MCP_PORT=3100 WF_IM_SERVER_URL=http://your-im-server pm2 start dist/index.js --name wf-robot-mcp
pm2 save
pm2 startup
```

### 使用 nohup

```bash
nohup env WF_MCP_PORT=3100 WF_IM_SERVER_URL=http://your-im-server node dist/index.js > mcp.log 2>&1 &
```

### 使用 systemd（Linux）

创建 `/etc/systemd/system/wf-robot-mcp.service`：

```ini
[Unit]
Description=Wildfire Robot MCP Server
After=network.target

[Service]
Type=simple
User=nobody
Environment=WF_MCP_PORT=3100
Environment=WF_IM_SERVER_URL=http://your-im-server
ExecStart=/usr/bin/node /path/to/wf-robot-mcp-server.ts/dist/index.js
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl daemon-reload
sudo systemctl enable wf-robot-mcp
sudo systemctl start wf-robot-mcp
```

## 在常见 Agent 中配置使用

### 本地模式（stdio，默认）

对于本地 Agent（如 Claude Desktop），MCP 服务以子进程方式运行，通过 stdio 通信。

#### Claude Desktop

编辑 Claude Desktop 配置文件（macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`，Windows: `%APPDATA%\Claude\claude_desktop_config.json`）：

```json
{
  "mcpServers": {
    "wf-robot": {
      "command": "node",
      "args": ["/path/to/wf-robot-mcp-server.ts/dist/index.js"],
      "env": {
        "WF_IM_SERVER_URL": "http://your-im-server"
      }
    }
  }
}
```

重启 Claude Desktop 后，即可在对话中使用野火机器人相关工具。

> **注意**：机器人 API 端口默认是 **80**，不是 18080。`18080` 是管理后台端口，不要混淆。如果 IM 服务在本地，不设置 `WF_IM_SERVER_URL` 即可默认使用 `http://localhost`。

### Cursor

在 Cursor 的 MCP 配置中添加：

```json
{
  "mcpServers": {
    "wf-robot": {
      "command": "node",
      "args": ["/path/to/wf-robot-mcp-server.ts/dist/index.js"],
      "env": {
        "WF_IM_SERVER_URL": "http://your-im-server"
      }
    }
  }
}
```

### Windsurf

在 Windsurf 的 MCP 配置中添加：

```json
{
  "mcpServers": {
    "wf-robot": {
      "command": "node",
      "args": ["/path/to/wf-robot-mcp-server.ts/dist/index.js"],
      "env": {
        "WF_IM_SERVER_URL": "http://your-im-server"
      }
    }
  }
}
```

### 通用 MCP 客户端（如 mcp-cli）

使用 npx 或直接运行：

```bash
# 使用 npx
WF_IM_SERVER_URL=http://your-im-server npx /path/to/wf-robot-mcp-server.ts

# 或通过 MCP 客户端配置
mcp add wf-robot --cmd "node" --args "/path/to/wf-robot-mcp-server.ts/dist/index.js" --env WF_IM_SERVER_URL=http://your-im-server

### 使用 uvx（Python 生态）

如果通过 Python 的 MCP 客户端工具连接：

```json
{
  "mcpServers": {
    "wf-robot": {
      "command": "node",
      "args": ["/path/to/wf-robot-mcp-server.ts/dist/index.js"],
      "env": {
        "WF_IM_SERVER_URL": "http://your-im-server"
      }
    }
  }
}
```

### 远程 HTTP 连接

如果 MCP 服务已部署到服务器（HTTP 模式），支持 HTTP 的 MCP 客户端可远程连接：

```json
{
  "mcpServers": {
    "wf-robot": {
      "url": "http://your-server-ip:3100/mcp"
    }
  }
}
```

> 注意：不是所有 MCP 客户端都支持远程 HTTP 连接。Claude Desktop 等本地 Agent 仅支持 stdio 模式，需要在运行 MCP 服务的同一台机器上配置。

### 使用说明

1. **IM 服务地址**：需配置可访问的野火IM服务器地址。如果 IM 服务在本地，可用 `http://localhost`；如果在远程，请替换为实际地址。
2. **机器人认证**：每次调用工具时，都需要提供 `robotId` 和 `robotSecret`。Agent 会要求用户提供这些信息。
3. **JSON 参数**：部分工具的参数需要以 JSON 字符串形式传入（如消息 payload、群组信息等），Agent 会自动处理序列化。

## 开发

### 目录结构

```
src/
  index.ts         # MCP 服务主代码
  types.d.ts       # 类型声明
package.json       # 依赖和脚本
tsconfig.json      # TypeScript 配置
```

### 构建

```bash
npm run build
```

### 添加新工具

在 `src/index.ts` 中调用 `registerTool()` 函数即可添加新工具：

```typescript
registerTool(server, "tool_name", "工具描述", {
  param1: z.string().describe("参数1说明"),
  param2: z.number().describe("参数2说明"),
}, async (args, _extra) => {
  return handleToolCall(args.robotId, args.robotSecret, async (service) => {
    // 调用 service 的对应方法
    return service.someMethod(args.param1, args.param2);
  });
});
```

## 许可证

MIT