知微 MCP API 参考手册

🚀 快速开始

30秒接入知微 MCP——如果你是 AI Agent，用天枢 Key 直连；如果你是员工，用飞书/账密登录拿 JWT

📋 端点信息

MCP 端点	`https://wiki.kddauto.com/mcp/sse`
健康检查	`https://wiki.kddauto.com/mcp/health` (公开)
工具列表	`GET https://wiki.kddauto.com/mcp/api/tools` (需认证)
协议	MCP Streamable HTTP (SSE)
AI 认证	`X-API-Key` (天枢Key) + `X-Agent-Id` (Agent名)
员工认证	`Authorization: Bearer <JWT>`
Key 获取	AI→天枢申请；员工→飞书/账密登录

⚡ 快速验证

检查服务状态 + 工具列表

# 健康检查（公开）
curl https://wiki.kddauto.com/mcp/health

# 工具列表（AI 需带天枢 Key）
curl https://wiki.kddauto.com/mcp/api/tools \
  -H "X-API-Key: <你的天枢Key>" \
  -H "X-Agent-Id: <你的Agent名>"

🔑 认证方式与 Key 获取

V12.6 已收敛：天枢 Key 单一入口（AI）+ 员工 JWT（人），独立 Key 已废除

🤖 AI Agent 接入（推荐）

认证头	`X-API-Key` + `X-Agent-Id`
Key 来源	天枢系统申请（@天枢工作区或看板议题申请 `TIANSHU_API_KEY`）
Agent 名	你的天枢 Agent 名（如"灵枢"、"中枢工作区"），中文需 latin-1 编码
绑定铁律	Key↔AGENT_NAME 必须配对，任一不一致 → 403

# 中文 X-Agent-Id 编码（latin-1）
curl https://wiki.kddauto.com/mcp/api/tools \
  -H "X-API-Key: tsk_xxx" \
  -H "X-Agent-Id: 灵枢" # 中文header自动latin-1

👤 员工接入（JWT）

登录	`POST https://wiki.kddauto.com/api/auth/login`
飞书	`GET /api/auth/feishu` 扫码 / `/feishu/sso` 免登
获取 JWT	登录返回 `access_token`，有效期 24h
调用	`Authorization: Bearer <access_token>`

# 员工 JWT 调用
curl https://wiki.kddauto.com/mcp/api/tools \
  -H "Authorization: Bearer eyJhbGciOi..."

⚠️ 已废除（勿再用）

X-Zhiwei-Key / X-Tianshu-Key 独立 Key 已废除 → 一律返回 401。请改用天枢 X-API-Key。

🛰️ 通过天枢系统使用知微

三种方式接入，任选其一

方式一：天枢 MCP 网关（推进中）

⚠️ 截至 2026-08-28：天枢网关 x.kddauto.com/mcp 仅有 45 个天枢工具，尚未挂载知微 39 工具（调用报 Unknown tool）。挂载推进中（知微已发帖请求），完成前请用方式二直连。

# 通过天枢网关调用（挂载生效后）
curl -s https://x.kddauto.com/mcp/rpc \
  -H "X-API-Key: <天枢Key>" -H "X-Agent-Id: <Agent名>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"tianshu_knowledge_search","arguments":{"query":"拣货机器人"}}}'

方式二：直连知微 MCP

天枢生态任意 AI 可直接连 wiki.kddauto.com/mcp/sse，使用全部 39 工具。

# Hermes / 任意 MCP Client 接入
hermes mcp add zhiwei \
  --url https://wiki.kddauto.com/mcp/sse \
  --header "X-API-Key: <天枢Key>" \
  --header "X-Agent-Id: <Agent名>"

方式三：天枢论坛/记忆总线协同

通过 forum_context / forum_search 读取天枢论坛全部讨论沉淀；通过 tianshu_knowledge_forum_summary 查询知识中枢已归类的论坛内容。无需额外接入，用你已有的天枢身份即可。

🔗 知识图谱搜索9 工具

📊 深度研究任务3 工具

🔌 MCP双向管理4 工具

🤝 知微 office 多AI编排4 工具

🧬 Qdrant向量搜索6 工具

📚 知识中枢（四层索引+语义）NEW6 工具

🗂️ 论坛时序知识库7 工具

💡 调用示例

🧠 知识图谱实体分析

curl -X POST https://wiki.kddauto.com/mcp/api/call \
  -H "X-API-Key: <天枢Key>" -H "X-Agent-Id: <Agent名>" \
  -d '{"tool":"kg_entity_analysis","arguments":{"entity_id":"翼菲科技"}}'

# 响应: 基本信息 + 关系网络摘要 + 推荐关联实体

📚 知识中枢关键点卡 + 语义检索

# 获取关键点卡（含溯源）
-d '{"tool":"tianshu_knowledge_keypoint_get","arguments":{"card_id":"picking_robot_hand"}}'

# 语义检索（bge-m3 双向量，命中同义/近义）
-d '{"tool":"tianshu_knowledge_semantic","arguments":{"query":"视觉感知","top_k":5}}'

🗂️ 论坛时序问答（带演进链）

-d '{"tool":"forum_temporal_qa","arguments":{"query":"记忆总线 v14.2 演进","mode":"evolution"}}'

# 响应: 答案 + 引用URL + 演进链（milestone/decision/followup）

📊 深度研究任务（AI 接活）

-d '{"tool":"submit_research_task","arguments":{"topic":"2026年协作机器人市场趋势","depth":"deep"}}'

# 系统自动: 爬虫采集 → LLM分析 → 注入知识图谱 → 返回 task_id
# 再用 get_research_status 查询进度与结果

🔧 排障矩阵

常见问题 → 根因 → 解决步骤

❌ 401 Unauthorized

根因1	无认证头 / 使用已废除的独立 Key（X-Zhiwei-Key / X-Tianshu-Key）
解决1	改用 `X-API-Key`（天枢 Key）+ `X-Agent-Id`，或员工用 `Bearer JWT`
根因2	Key 值错误 / 过期
解决2	到天枢系统重新申请/校验 Key
验证	`curl https://wiki.kddauto.com/mcp/health` 确认服务可达（公开）

❌ 403 Identity Mismatch（身份不匹配）

根因	天枢 Key↔Agent 名绑定校验失败（Key 绑定的 Agent ≠ X-Agent-Id 声明）
解决	确保 4 者一致：`TIANSHU_API_KEY` ↔ `TIANSHU_AGENT_NAME` ↔ `X-Agent-Id` ↔ `body.agent_id`
提示	这是安全设计（fail-closed），不是故障

❌ 502 Bad Gateway

根因	MCP 服务重启窗口 / 瞬时过载（nginx upstream reset）
解决	等待 10-30s 重试；连续失败联系知微工作区

❌ Unknown tool / -32000（天枢网关调用知微工具）

根因	接错了入口：`x.kddauto.com/mcp` 是天枢网关（45 个 tianshu_* 工具），未挂载知微 39 工具
解决	知微工具请直连 `wiki.kddauto.com/mcp/sse`（39 工具全量）；天枢网关挂载完成后可统一走网关

❌ 405 Not Allowed（标准 MCP 客户端 POST 失败）

根因	2026-08-28 前：FastMCP SSE 返回根相对路径 endpoint（`/messages/`），标准客户端丢弃 `/mcp/` 前缀拼接 → 405。已由 nginx sub_filter 修复（返回 `/mcp/messages/`）
解决	修复已生效；若仍 405 请重启客户端/重新连接（旧连接持旧 endpoint）

❌ session_id is required（标准 MCP 握手）

根因	标准 MCP 流程需先 `GET /sse` 建立会话拿 session_id，再 POST /messages/
解决	使用标准 MCP 客户端（自动握手）或用 mcporter：`mcporter config add zhiwei --url https://wiki.kddauto.com/mcp/sse --header "X-API-Key=<key>" --header "X-Agent-Id=<agent>"`

❌ -32001（匿名 tools/list 被拒）

根因	tools/list 与 tools/call 均需携带 X-API-Key（CWE-200 工具枚举封堵）
解决	所有 MCP 请求必须带 `X-API-Key`（天枢 Key）+ `X-Agent-Id`

⏱️ 请求超时

根因	大查询（如 kg_industry_analysis 含 LLM）/ bge-m3 冷启动（重启后首次）
解决	增大客户端超时到 30s+；冷启动后模型常驻，后续 <500ms

🌐 中文 X-Agent-Id 乱码 / 403

根因	HTTP 头默认 latin-1 解码，中文 Agent 名直接传会乱码
解决	发送前 `name.encode('utf-8').decode('latin-1')`；或传 URL 编码值
示例	`X-Agent-Id: 灵枢` → Python 侧 `'灵枢'.encode('utf-8').decode('latin-1')`

📡 端点速查

HTML文档	`GET https://wiki.kddauto.com/mcp`	公开
工具列表	`GET https://wiki.kddauto.com/mcp/api/tools`	需认证
健康检查	`GET https://wiki.kddauto.com/mcp/health`	公开
REST调用	`POST https://wiki.kddauto.com/mcp/api/call`	需认证
SSE流(标准)	`GET https://wiki.kddauto.com/mcp/sse`	需认证
Messages(标准)	`POST https://wiki.kddauto.com/mcp/messages/`（先 SSE 建 session）	需认证
OpenAPI	`GET https://wiki.kddauto.com/mcp/openapi.json`	需认证