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

杜康好客 · 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
开发计划	dev_plan.read → query_versions、query_tasks（任务按 TODO/IN_PROGRESS/DEVELOPED/RELEASED/STOPPED 筛选）

生产：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

---

4. 验收

• 无 Key / 错 Key → MCP 入口 401
• 带 Key tools/list 仅含该实例已勾选权限
• tools/call 查询口径与 REST 一致，结果无 REST 信封
• HQ 日志 botKey=plugin:{id}
• 现有 API 插件机器人行为不变
• 长连接 Bot 不变