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

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

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/企微API插件-配置手册.md

@@ -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) — 编码验收一句

docs/杜康好客-v3-现状对照.md

@@ -70,9 +70,11 @@
 | 3.5.14 | [`提交订单/支付成功日志端回填 USER_MINI`](./杜康好客-v3.5.14-开发文档.md) | 🔶 开发完成 |
 | 3.5.16 | [`企微智能机器人 API 插件`](./杜康好客-v3.5.16-开发文档.md) | 🔶 开发完成 |
 | 3.5.17 | [`企微 API 插件迁入 HQ 后台`](./杜康好客-v3.5.17-开发文档.md) | 🔶 开发完成 |
+| 3.5.18 | [`企微 API 插件 MCP 端点`](./杜康好客-v3.5.18-开发文档.md) | 🔶 开发完成 |
 
 | 日期 | 说明 |
 |------|------|
+| 2026-09-08 | v3.5.18：企微插件增加 Streamable HTTP MCP 端点 `/api/v1/wecom/plugin/mcp`，与 REST/OpenAPI 并存 |
 | 2026-09-08 | HQ「门店账户」主账号详情可 CRUD 店员子账号（`/admin/store-accounts/:id/staff`） |
 | 2026-09-06 | v3.5.17：企微 API 插件迁入 HQ「企微机器人 → API 插件」；多实例 Key + 工具权限；不再依赖 `WECOM_PLUGIN_*` env |
 | 2026-09-03 | v3.5.16：企微 API 插件只读数据面 `GET /api/v1/wecom/plugin/*`（X-Api-Key）；与长连接 Bot 独立 |

docs/杜康好客-v3.5.17-开发文档.md

@@ -75,7 +75,7 @@
 
 ## 6. 企微侧怎么配
 
-详见 **[企微 API 插件 · 配置手册](./企微API插件-配置手册.md)**（第 1 步插件、第 2 步工具/OpenAPI 导入、全接口参数表）。
+详见 **[企微 API 插件 · 配置手册](./企微API插件-配置手册.md)**。v3.5.18 起优先配 MCP 插件；本节 API + OpenAPI 仍可用。
 
 1. 插件 URL = HQ 页展示的 Base URL（全实例相同）
 2. Header `X-Api-Key` = 该实例密钥

docs/杜康好客-v3.5.18-开发文档.md

@@ -0,0 +1,50 @@
+# 杜康好客 · v3.5.18 开发文档
+
+> **2026-09-08** · integrations/wecom · admin-web · shared-types  
+> **主题**：企微智能机器人 **MCP 插件**（Streamable HTTP），与 REST API 插件并存
+
+---
+
+## 1. 版本目标
+
+企微后台「添加 MCP 插件」可对接本系统：托管大模型按 MCP `tools/list` / `tools/call` 拉数。不改长连接 Bot、不删 REST/OpenAPI。
+
+**不做**：写操作、明文手机/地址、把 `/admin/*` JWT 暴露给企微、第一期 SSE 传输。
+
+---
+
+## 2. 端点
+
+| 项 | 值 |
+|----|-----|
+| MCP URL | `/api/v1/wecom/plugin/mcp` |
+| 传输 | Streamable HTTP，无状态（每请求新建 `McpServer`） |
+| 鉴权 | Header `X-Api-Key`（与 REST 同一套 HQ 实例） |
+| 响应 | JSON-RPC；**无** `{code,message,data}` 信封 |
+| 工具结果 | `JSON.stringify(查询结果)` |
+| 权限 | `tools/list` 只注册已勾选权限；QueryService 仍 `requirePerm` |
+
+生产：`https://api.dukanghaoke.com/api/v1/wecom/plugin/mcp`  
+测试：`https://api-test.dukanghaoke.com/api/v1/wecom/plugin/mcp`
+
+---
+
+## 3. 变更面
+
+| 层 | 路径 |
+|----|------|
+| shared-types | `WECOM_PLUGIN_MCP_*`、`allowedWecomPluginMcpTools` |
+| API | `wecom-plugin-mcp.*`；`WecomPluginMcpFactory`；Interceptor skip MCP |
+| HQ | `WecomApiPluginsPage` 展示 MCP URL |
+| 文档 | [`企微API插件-配置手册.md`](./企微API插件-配置手册.md) |
+
+---
+
+## 4. 验收
+
+- [ ] 无 Key / 错 Key → MCP 入口 401
+- [ ] 带 Key `tools/list` 仅含该实例已勾选权限
+- [ ] `tools/call` 查询口径与 REST 一致，结果无 REST 信封
+- [ ] HQ 日志 `botKey=plugin:{id}`
+- [ ] 现有 API 插件机器人行为不变
+- [ ] 长连接 Bot 不变

docs/杜康好客-v3编码手册.md

@@ -48,7 +48,7 @@ C 端购酒核销 · 门店扫码核销+打款 · 合伙人拓店履约 · WebAd
 
 **HQ 企微报告（v3.5.15）**：企微机器人下「报告」与「消息推送」分开。日报/周报/月报各配 Webhook 与发送时刻；走群机器人 markdown。账期截在发送日北京 0 点（前一天 24 点），不含发送当天：日报=昨日存量+当日新增；周报/月报=上一自然周/月期末存量+本期新增。用户=有效未合并；合伙人=主账号；订单笔数与金额均排除待支付 / 已取消 / 退款中；订单金额=已付 `payAmount`（`paidAt`）；核销=`RedeemRecord`。
 
-**企微 API 插件（v3.5.17）**：实例在 HQ「企微机器人 → API 插件」维护；共用 `GET /api/v1/wecom/plugin/*`，Header `X-Api-Key` 区分实例并按权限放行。经营指标含新增门店（`newStores`）；门店搜索含经营数据；支持门店/信息/套餐审核对照只读查询；支持按合伙人查关联用户/门店/订单（`from`/`to` 时间筛选）。
+**企微 API 插件（v3.5.17 / MCP v3.5.18）**：实例在 HQ「企微机器人 → API 插件」维护；共用 Header `X-Api-Key`。REST `GET /api/v1/wecom/plugin/*` 与 MCP `POST /api/v1/wecom/plugin/mcp`（Streamable HTTP 无状态）并存；MCP 按权限自动 `tools/list`。经营指标含新增门店（`newStores`）；门店搜索含经营数据；支持门店/信息/套餐审核对照只读查询；支持按合伙人查关联用户/门店/订单（`from`/`to` 时间筛选）。
 
 **HQ 列表（v3.5.9）**：主表不省略号、可横滑；最左序号；列设置（显隐/顺序）与列宽（拖表头）存 `hq_account.list_column_prefs`。主展示列下划线，点击进编辑或详情。门店列表「累计核销好客权益」= 该店 `RedeemRecord.amount` 合计。用户列表昵称只读（点击进详情）；双击「备注」离开即保存（`hq_remark`）；列表手机号不脱敏。
 

docs/杜康好客-知识库.md

@@ -151,6 +151,7 @@ HQ 账号/角色(`hq-permissions`，生效=(角色∪追加)−撤销；可绑
 |------|------|
 | 智能机器人 | `/wecom/bots` 长连接指令 |
 | API 插件 | HQ `/wecom/plugins` 多实例；`/api/v1/wecom/plugin` Header `X-Api-Key` 只读查询（与长连接独立） |
+| MCP 插件 | 同上 Key；`POST /api/v1/wecom/plugin/mcp` Streamable HTTP；`tools/list` 按权限过滤 |
 | 消息推送 | `/wecom/pushes` Webhook+eventKey |
 | 日志 | `/logs/wecom-bots` |
 | C 端微信客服 | 系统设置 `CUSTOMER_SERVICE_WECOM_URL` + `WECOM_CORP_ID`；小程序须已关联该企业微信客服 |