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
|
|
```
|