Add Cloud Tour Libo knowledge graph platform

2026-07-30 10:08:04 +08:00
parent 9e05b09a38
commit bae5197d62
103 changed files with 14036 additions and 160 deletions
--- a/docs/MCP_TOOL_EXPOSURE_FIX_AND_VERIFICATION.md
+++ b/docs/MCP_TOOL_EXPOSURE_FIX_AND_VERIFICATION.md
@@ -0,0 +1,282 @@
+# MCP 工具未暴露问题修复与验证说明
+
+## 1. 问题现象
+
+MCP 客户端配置了服务地址：
+
+```text
+http://8.163.40.99:8102/mcp
+```
+
+但页面显示：
+
+```text
+工具 0
+该服务还没有发现工具
+```
+
+直接访问服务也返回：
+
+```text
+404 Not Found
+```
+
+说明当前系统只有普通 HTTP 问答接口，还没有真正实现 MCP Server 的工具发现协议。
+
+## 2. 问题归类
+
+这不是知识图谱数据问题，也不是 LLM 问答引擎问题。
+
+这是：
+
+```text
+MCP Server 适配层未实现 / tools/list 未暴露
+```
+
+已有能力：
+
+```text
+POST /v1/openapi/knowledge-qa/query
+```
+
+缺少能力：
+
+```text
+POST /mcp
+  initialize
+  ping
+  tools/list
+  tools/call
+```
+
+## 3. 修复方式
+
+新增 FastAPI MCP 适配层：
+
+```text
+app/api/mcp_server.py
+```
+
+并在主应用挂载：
+
+```text
+app.include_router(mcp_router)
+```
+
+MCP 层不重写业务逻辑，只把 MCP 工具调用转换成现有百姓惠客服问答接口的内部调用：
+
+```text
+MCP Client
+  -> POST /mcp tools/call
+  -> ask_customer_service 等工具
+  -> 现有百姓惠客服问答 engine
+  -> FalkorDB / 图谱 / LLM
+```
+
+## 4. 已暴露工具
+
+当前 `/mcp` 暴露 5 个只读工具：
+
+| 工具名 | 作用 |
+| --- | --- |
+| `ask_customer_service` | 通用百姓惠智能客服问答 |
+| `query_route_price` | 查询线路参考价格 |
+| `list_travel_routes` | 查询旅行线路清单 |
+| `query_route_detail` | 查询线路天数、景区、酒店、费用等详情 |
+| `compare_routes` | 对比两条线路适配度、景点数量、轻松程度等 |
+
+## 5. MCP 初始化验证
+
+请求：
+
+```bash
+curl -sS http://8.163.40.99:8102/mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  --data '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "initialize",
+    "params": {
+      "protocolVersion": "2025-06-18",
+      "capabilities": {},
+      "clientInfo": {
+        "name": "manual-check",
+        "version": "1.0.0"
+      }
+    }
+  }'
+```
+
+预期返回：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "protocolVersion": "2025-06-18",
+    "capabilities": {
+      "tools": {
+        "listChanged": false
+      }
+    },
+    "serverInfo": {
+      "name": "baixinghui-customer-service-mcp",
+      "version": "0.1.0"
+    }
+  }
+}
+```
+
+## 6. 工具发现验证
+
+请求：
+
+```bash
+curl -sS http://8.163.40.99:8102/mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  --data '{
+    "jsonrpc": "2.0",
+    "id": 2,
+    "method": "tools/list"
+  }'
+```
+
+预期结果：
+
+```text
+tools 数量 = 5
+```
+
+并能看到：
+
+```text
+ask_customer_service
+query_route_price
+list_travel_routes
+query_route_detail
+compare_routes
+```
+
+## 7. 工具调用验证
+
+请求：
+
+```bash
+curl -sS http://8.163.40.99:8102/mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  --data '{
+    "jsonrpc": "2.0",
+    "id": 3,
+    "method": "tools/call",
+    "params": {
+      "name": "ask_customer_service",
+      "arguments": {
+        "question": "黄小西三日游多少钱？",
+        "session_id": "mcp-test-session"
+      }
+    }
+  }'
+```
+
+预期返回结构：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "客服可直接回复的话术"
+      }
+    ],
+    "structuredContent": {
+      "customer_reply": "客服可直接回复的话术",
+      "answer": "完整答案",
+      "knowledge": {
+        "plans": [],
+        "evidence": []
+      },
+      "trace_id": "排查链路 ID"
+    },
+    "isError": false
+  }
+}
+```
+
+## 8. 客户端侧证明
+
+修复后，MCP 客户端刷新服务配置，应从：
+
+```text
+工具 0
+该服务还没有发现工具
+```
+
+变为：
+
+```text
+工具 5
+```
+
+如果客户端仍显示 0，按顺序检查：
+
+1. 服务地址是否为 `http://8.163.40.99:8102/mcp`。
+2. 服务是否已经重新构建并重启。
+3. 客户端是否点击了“刷新”或重新检查连接。
+4. 如果启用了鉴权，客户端是否带了正确的 `Authorization: Bearer <token>`。
+
+## 9. 鉴权说明
+
+当前 MCP 适配层支持可选鉴权。
+
+未设置环境变量时：
+
+```text
+BXH_MCP_TOKEN 为空
+```
+
+则 `/mcp` 不强制鉴权，方便内测。
+
+如果设置：
+
+```bash
+export BXH_MCP_TOKEN="<your-token>"
+```
+
+客户端需要传：
+
+```http
+Authorization: Bearer <your-token>
+```
+
+或：
+
+```http
+X-MCP-API-Key: <your-token>
+```
+
+## 10. 结论
+
+这次修复解决的是 MCP 协议层工具暴露问题。
+
+修复前：
+
+```text
+/mcp 404
+tools/list 无法执行
+客户端工具数 0
+```
+
+修复后：
+
+```text
+/mcp 可响应 JSON-RPC
+tools/list 返回 5 个工具
+tools/call 可调用百姓惠客服问答 engine
+```