野火机器人 MCP Server

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

功能特性

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

• 消息：发送消息、回复消息、撤回消息、更新消息，以及便捷的文本/图片/文件消息接口

• 用户：获取用户信息（通过用户ID/手机号/用户名）、搜索用户、获取好友列表、获取用户机器人列表

• 资料：获取机器人资料

• 群组：创建/解散/转让群组、修改群信息、成员管理（添加/踢出/禁言/管理员/别名等）

• 文件上传：上传文件

共 34 个 MCP 工具。

Related MCP server: dws-cli-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 客户端工具连接：

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

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