野火机器人 MCP Server

Wildfire Robot MCP Server — 将野火IM机器人 SDK 封装为 MCP (Model Context Protocol) 服务，供 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

安装

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

# 安装依赖
npm install

# 构建
npm run build

配置

通过环境变量配置：

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

启动

支持两种运行模式：

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

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

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

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

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

注意：HTTP 模式支持需要客户端实现 MCP Streamable HTTP 传输。本地 Agent（如 Claude Desktop）通常使用 stdio 模式，不需要 HTTP。

多会话支持

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

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

验证

#### stdio 模式验证

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

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 模式验证

# 健康检查
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 协议、工具注册以及各工具调用。

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

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

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

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

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

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

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

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

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

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

API 接口说明

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

消息工具

#### send_message 发送消息。

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

#### reply_message 回复消息。

#### recall_message 撤回消息。

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

便捷消息工具

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

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

处理流程：

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

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

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

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

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

用户工具

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

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

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

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

无额外参数。

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

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

资料工具

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

群组工具

#### create_group 创建群组。

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

#### dismiss_group 解散群组。

#### transfer_group 转让群组。

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

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

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

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

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

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

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

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

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

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

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

文件上传工具

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

⚠️ 此工具读取的是 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 守护进程

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

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：

[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

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）：

{
  "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 配置中添加：

{
  "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 配置中添加：

{
  "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 或直接运行：

# 使用 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 客户端工具连接：

{ "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 客户端可远程连接：

{ "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 配置

### 构建

npm run build

### 添加新工具

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

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