企业微信机器人 MCP HTTP 服务器

这是一个基于 Model Context Protocol (MCP) 的企业微信机器人服务器，支持 streamable-http 调用方式和双向通信。

功能特性

• 🚀 Streamable HTTP API: 支持标准的 HTTP REST API 调用
• 🔄 双向通信: 支持发送消息到企业微信和接收企业微信回调
• 📱 多种消息类型: 支持文本、Markdown、图片、图文、文件等消息类型
• 🛡️ 安全性: 内置 API 密钥验证、CORS 配置、安全头等
• 📊 日志记录: 完整的请求/响应日志和错误追踪
• 🔧 易于集成: 提供简洁的 REST API 接口

快速开始

1. 安装依赖

cd wecom-bot-mcp-http-server
npm install

2. 配置环境变量

复制 .env.example 到 .env 并填写配置：

cp .env.example .env

编辑 .env 文件：

# 企业微信机器人配置
WECOM_WEBHOOK_URL=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=your_webhook_key
WECOM_WEBHOOK_KEY=your_webhook_key

# 企业微信应用配置（用于双向调用）
WECOM_CORP_ID=your_corp_id
WECOM_CORP_SECRET=your_corp_secret
WECOM_AGENT_ID=your_agent_id

# HTTP服务器配置
PORT=3000
HOST=localhost

# 安全配置
API_SECRET=your_api_secret_for_authentication

3. 构建和启动

# 开发模式
npm run dev

# 生产模式
npm run build
npm start

API 接口

基础接口

健康检查

GET /health

获取可用工具列表

GET /api/tools/list

消息发送接口

发送文本消息

POST /api/wecom/send/text
Content-Type: application/json

{
  "content": "Hello, World!",
  "mentionUsers": ["@all"],
  "mentionMobiles": ["13800138000"]
}

发送 Markdown 消息

POST /api/wecom/send/markdown
Content-Type: application/json

{
  "content": "## 标题\n这是一条 **Markdown** 消息"
}

发送图片消息

POST /api/wecom/send/image
Content-Type: application/json

{
  "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

发送图文消息

POST /api/wecom/send/news
Content-Type: application/json

{
  "articles": [
    {
      "title": "标题",
      "description": "描述",
      "url": "https://example.com",
      "picurl": "https://example.com/image.jpg"
    }
  ]
}

MCP 工具调用接口

通用工具调用

POST /api/tools/call
Content-Type: application/json

{
  "method": "send_wework_message",
  "params": {
    "content": "Hello from MCP!",
    "type": "text"
  },
  "id": "optional-request-id"
}

企业微信回调接口

回调验证（GET）

GET /api/wecom/callback?msg_signature=xxx&timestamp=xxx&nonce=xxx&echostr=xxx

接收回调事件（POST）

POST /api/wecom/callback
Content-Type: application/json

{
  "ToUserName": "企业微信CorpID",
  "FromUserName": "发送方UserID",
  "CreateTime": 1234567890,
  "MsgType": "text",
  "Content": "消息内容",
  "MsgId": "消息ID",
  "AgentID": 1000002
}

支持的 MCP 工具

工具名称	描述	参数
send_wework_message	发送文本或Markdown消息	content, type, mentionUsers, mentionMobiles
send_wework_news	发送图文消息	articles
send_wework_image	发送图片消息	base64
send_wework_file	发送文件消息	filePath
test_wework_connection	测试连接	无

双向通信

发送消息到企业微信

使用任何上述 API 接口发送消息到企业微信群或应用。

接收企业微信消息

1. 配置企业微信应用的回调 URL 为 http://your-server:3000/api/wecom/callback
2. 服务器会自动处理回调验证和消息接收
3. 可以在 handleWeComCallback 方法中实现自定义的自动回复逻辑

安全配置

API 密钥验证

如果设置了 API_SECRET 环境变量，所有 /api/* 接口都需要提供 API 密钥：

# 通过 Header
X-API-Key: your_api_secret

# 或通过查询参数
GET /api/tools/list?api_key=your_api_secret

CORS 配置

通过 ALLOWED_ORIGINS 环境变量配置允许的源：

ALLOWED_ORIGINS=https://example.com,https://app.example.com

错误处理

所有 API 响应都遵循统一的格式：

{
  "success": true,
  "data": {
    // 响应数据
  },
  "id": "optional-request-id"
}

错误响应：

{
  "success": false,
  "error": "错误描述",
  "id": "optional-request-id"
}

日志

日志文件保存在 logs/ 目录下：

• logs/combined.log: 所有日志
• logs/error.log: 错误日志

日志级别可通过 LOG_LEVEL 环境变量配置（debug, info, warn, error）。

开发

项目结构

src/
├── index.ts          # 主入口文件
├── http-server.ts    # HTTP 服务器
├── mcp-server.ts     # MCP 服务器
├── wecom-client.ts   # 企业微信客户端
├── types.ts          # 类型定义
└── logger.ts         # 日志配置

添加新功能

1. 在 types.ts 中定义新的类型
2. 在 wecom-client.ts 中实现企业微信 API 调用
3. 在 mcp-server.ts 中添加新的 MCP 工具
4. 在 http-server.ts 中添加对应的 HTTP 接口

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

支持

如果您在使用过程中遇到问题，请：

1. 检查日志文件中的错误信息
2. 确认环境变量配置正确
3. 验证企业微信机器人配置
4. 提交 Issue 描述问题详情