283 lines
4.7 KiB
Markdown
283 lines
4.7 KiB
Markdown
# 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
|
||
```
|