xuelong/Cloud-Tour-to-Libo

Fork 0

Files

3452078359-xuexue bae5197d62 Add Cloud Tour Libo knowledge graph platform

2026-07-30 10:09:16 +08:00

4.7 KiB

Raw Blame History

MCP 工具未暴露问题修复与验证说明

1. 问题现象

MCP 客户端配置了服务地址：

http://8.163.40.99:8102/mcp

但页面显示：

工具 0
该服务还没有发现工具

直接访问服务也返回：

404 Not Found

说明当前系统只有普通 HTTP 问答接口，还没有真正实现 MCP Server 的工具发现协议。

2. 问题归类

这不是知识图谱数据问题，也不是 LLM 问答引擎问题。

这是：

MCP Server 适配层未实现 / tools/list 未暴露

已有能力：

POST /v1/openapi/knowledge-qa/query

缺少能力：

POST /mcp
  initialize
  ping
  tools/list
  tools/call

3. 修复方式

新增 FastAPI MCP 适配层：

app/api/mcp_server.py

并在主应用挂载：

app.include_router(mcp_router)

MCP 层不重写业务逻辑，只把 MCP 工具调用转换成现有百姓惠客服问答接口的内部调用：

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 初始化验证

请求：

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"
      }
    }
  }'

预期返回：

{
  "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. 工具发现验证

请求：

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"
  }'

预期结果：

tools 数量 = 5

并能看到：

ask_customer_service
query_route_price
list_travel_routes
query_route_detail
compare_routes

7. 工具调用验证

请求：

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"
      }
    }
  }'

预期返回结构：

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "客服可直接回复的话术"
      }
    ],
    "structuredContent": {
      "customer_reply": "客服可直接回复的话术",
      "answer": "完整答案",
      "knowledge": {
        "plans": [],
        "evidence": []
      },
      "trace_id": "排查链路 ID"
    },
    "isError": false
  }
}

8. 客户端侧证明

修复后，MCP 客户端刷新服务配置，应从：

工具 0
该服务还没有发现工具

变为：

工具 5

如果客户端仍显示 0，按顺序检查：

服务地址是否为 http://8.163.40.99:8102/mcp。
服务是否已经重新构建并重启。
客户端是否点击了“刷新”或重新检查连接。
如果启用了鉴权，客户端是否带了正确的 Authorization: Bearer <token>。

9. 鉴权说明

当前 MCP 适配层支持可选鉴权。

未设置环境变量时：

BXH_MCP_TOKEN 为空

则 /mcp 不强制鉴权，方便内测。

如果设置：

export BXH_MCP_TOKEN="<your-token>"

客户端需要传：

Authorization: Bearer <your-token>

或：

X-MCP-API-Key: <your-token>

10. 结论

这次修复解决的是 MCP 协议层工具暴露问题。

修复前：

/mcp 404
tools/list 无法执行
客户端工具数 0

修复后：

/mcp 可响应 JSON-RPC
tools/list 返回 5 个工具
tools/call 可调用百姓惠客服问答 engine

4.7 KiB Raw Blame History Unescape Escape