jacy/dukang
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(wecom): 企微 API 插件增加 MCP Streamable HTTP 端点

Browse Source 
与 REST/OpenAPI 并存，按实例权限自动 tools/list，免手填工具。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
jacy
2026-09-08 16:57:42 +08:00
parent cae426fbc2
commit 976bde37cc
23 changed files with 1212 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/企微API插件-配置手册.md
+84 -27
View File
@@ -1,28 +1,75 @@
# 企微 API 插件 · 配置手册
# 企微 API / MCP 插件 · 配置手册
> 面向运营/技术：在企微后台「智能机器人 → 添加 API 插件」逐步填表。
> 后端前缀：`/api/v1/wecom/plugin` · 鉴权 Header `X-Api-Key` · 与 HQ 长连接 Bot **独立**。
> 密钥与权限在 HQ **企微机器人 → API 插件** 维护（v3.5.17+）。
> 面向运营/技术：在企微后台「智能机器人 → 添加插件」填表。
> 后端前缀：`/api/v1/wecom/plugin` · MCP：`/api/v1/wecom/plugin/mcp` · 鉴权 Header `X-Api-Key` · 与 HQ 长连接 Bot **独立**。
> 密钥与权限在 HQ **企微机器人 → API 插件** 维护（v3.5.17+；MCP 端点 v3.5.18）。
---
## 1. 推荐流程（优先 OpenAPI 导入）
## 1. 推荐流程（MCP 插件）
**不要 17 个工具全手填。** 推荐：
企微 5.0.6+ 支持 **MCP 插件**：自动 `tools/list` 拉工具，不必手填、也不必导入 OpenAPI。REST API 插件仍保留，已配好的机器人不用改。
1. HQ → **企微机器人 → API 插件** → 新建实例，勾选工具权限，复制 **Key**（只显示一次）。
2. 企微 **第 1 步**：填插件 URL + Header Key（见 §2）。
2. 企微工作台 → 智能机器人 → **插件** → **添加 MCP 插件**：
- **插件 URL**：见下表（必须是企业域名，localhost 无法注入成员身份）
- **传输协议**：Streamable HTTP
- **授权方式**：Service token / API key
- **位置**：Header
- **Parameter name**：`X-Api-Key`
- **Service token**：该实例 Key
3. 企微会自动拉取已授权工具；把插件挂到「运营查询」类智能机器人即可。
4. 白名单会话试问：「查一下今日经营指标」「订单 DK…」。HQ **日志 → 智能机器人日志** 应出现 `botKey=plugin:{id}`。
| 企微表单字段 | 测试环境 | 生产环境 |
|-------------|---------|---------|
| **MCP 插件 URL** | `https://api-test.dukanghaoke.com/api/v1/wecom/plugin/mcp` | `https://api.dukanghaoke.com/api/v1/wecom/plugin/mcp` |
| **传输协议** | Streamable HTTP | 同左 |
| **Header** | `X-Api-Key` | 同左 |
**自检（JSON-RPC，无 `{code,message,data}` 信封）：**
```bash
# 无 Key → 401
curl -sS -o /dev/null -w '%{http_code}\n' \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' \
"https://api-test.dukanghaoke.com/api/v1/wecom/plugin/mcp"
# 带 Key：initialize
curl -sS -H "X-Api-Key: <你的Key>" -H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' \
"https://api-test.dukanghaoke.com/api/v1/wecom/plugin/mcp"
# 带 Key：tools/list（仅含本实例已勾选权限）
curl -sS -H "X-Api-Key: <你的Key>" -H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
"https://api-test.dukanghaoke.com/api/v1/wecom/plugin/mcp"
```
若「添加插件」拉不到工具，再试传输协议 **SSE**（需运维给 `/api/v1/wecom/plugin/mcp` 关 `proxy_buffering`）；第一期默认 Streamable HTTP 无状态即可。
---
## 2. 兼容流程（API 插件 + OpenAPI 导入）
**不要 17 个工具全手填。** API 插件推荐：
1. HQ 建实例并复制 Key（同上）。
2. 企微 **第 1 步**：填 API 插件 URL + Header Key（见 §3）。
3. 企微 **第 2 步**：**OpenAPI 导入**
- URL：`{Base URL}/openapi.json`
- **同样带 Header `X-Api-Key`**（与第 1 步相同 Key）
- 服务端按该 Key 的权限**只返回已授权路径**，与 HQ 勾选一致。
4. 导入后逐条核对 §3「全局规则」；类型不对时按 §5 手工修正。
4. 导入后逐条核对 §4「全局规则」；类型不对时按 §6 手工修正。
手填仅适用于：导入失败，或只加 2～3 个高频工具。
---
## 2. 第 1 步：添加 API 插件
## 3. 第 1 步：添加 API 插件
| 企微表单字段 | 测试环境 | 生产环境 |
|-------------|---------|---------|
@@ -43,7 +90,7 @@ HQ 页也会展示 Base URL 与 Header 名（不含密钥）。
---
## 3. 全局规则（调试不过先看这里）
## 4. 全局规则（调试不过先看这里）
| 项 | 正确 | 错误 |
|----|------|------|
@@ -69,20 +116,20 @@ HQ 页也会展示 Base URL 与 Header 名（不含密钥）。
---
## 4. HQ 权限与工具对照
## 5. HQ 权限与工具对照
只添加 HQ **已勾选**权限对应的工具；未授权返回 **403**。
只添加 HQ **已勾选**权限对应的工具；未授权 REST 返回 **403**，MCP 则不出现在 `tools/list`。
| HQ 权限 | 路径 | 建议工具名 |
|---------|------|-----------|
| `metrics.read` | `/metrics` | 查询经营指标 |
| `order.read` | `/orders` | 查询订单 |
| `user.read` | `/users` | 查询用户 |
| `store.read` | `/stores` | 查询门店 |
| `redeem.read` | `/redeems` | 查询核销 |
| `promo.read` | `/promo-codes`、`/promo-codes/{code}/stats` | 查询推广码、推广码统计 |
| `store.audit.read` | `/store-audits`、`/store-info-audits`、`/store-info-audits/{id}`、`/store-package-audits`、`/store-package-audits/{id}` | 门店/信息/套餐审核 |
| `partner.read` | `/partners`、`/partners/{partnerId}/users|stores|orders` | 合伙人及关联数据 |
| HQ 权限 | REST 路径 | MCP 工具名 |
|---------|-----------|-----------|
| `metrics.read` | `/metrics` | `query_metrics` |
| `order.read` | `/orders` | `query_orders` |
| `user.read` | `/users` | `query_users` |
| `store.read` | `/stores` | `query_stores` |
| `redeem.read` | `/redeems` | `query_redeems` |
| `promo.read` | `/promo-codes`、`/promo-codes/{code}/stats` | `query_promo_codes`、`query_promo_code_stats` |
| `store.audit.read` | `/store-audits`、`/store-info-audits`、`/store-info-audits/{id}`、`/store-package-audits`、`/store-package-audits/{id}` | `query_store_audits` 等 5 个 |
| `partner.read` | `/partners`、`/partners/{partnerId}/users|stores|orders` | `query_partners` 等 4 个 |
**实例建议：**
@@ -94,7 +141,7 @@ HQ 页也会展示 Base URL 与 Header 名（不含密钥）。
---
## 5. 第 2 步：工具参数明细
## 6. 第 2 步：工具参数明细
以下均为 **GET**。Base URL 与 §2 相同，路径为相对路径。
@@ -332,7 +379,7 @@ HQ 页也会展示 Base URL 与 Header 名（不含密钥）。
---
## 6. OpenAPI 导入
## 7. OpenAPI 导入
| 项 | 值 |
|----|-----|
@@ -350,7 +397,16 @@ curl -H "X-Api-Key: <Key>" \
---
## 7. 调试检查清单
## 8. 调试检查清单
### MCP 插件
- [ ] 无 Key / 错 Key → 401
- [ ] `initialize` + `tools/list` 仅含 HQ 已勾选权限对应工具
- [ ] 企微后台能自动拉到工具（Streamable HTTP）
- [ ] 白名单会话能问到真实数据；HQ 日志 `botKey=plugin:{id}`
### API 插件（兼容）
- [ ] 第 1 步 Key 与 HQ 实例一致，实例 **已启用**
- [ ] curl 带 Key 返回 `code: 0`
@@ -363,7 +419,7 @@ curl -H "X-Api-Key: <Key>" \
---
## 8. 多实例与分工
## 9. 多实例与分工
| 企微插件 | HQ 实例 | 说明 |
|----------|---------|------|
@@ -373,8 +429,9 @@ curl -H "X-Api-Key: <Key>" \
---
## 9. 相关文档
## 10. 相关文档
- [杜康好客-v3.5.18-开发文档](./杜康好客-v3.5.18-开发文档.md) — MCP Streamable HTTP 端点
- [杜康好客-v3.5.17-开发文档](./杜康好客-v3.5.17-开发文档.md) — 表结构、Admin API、权限目录
- [杜康好客-v3.5.16-开发文档](./杜康好客-v3.5.16-开发文档.md) — 插件初版与 curl 示例
- [杜康好客-v3编码手册](./杜康好客-v3编码手册.md) — 编码验收一句