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