# 百姓惠智能客服 MCP Server 打包说明

本文档说明如何将当前百姓惠旅行社知识图谱智能客服能力封装为一个 MCP Server，供 DeerFlow、Agent 平台或其他支持 MCP 的智能体调用。

## 1. 改造目标

当前系统已经提供普通 HTTP 问答接口：

```text
POST http://8.163.40.99:8102/v1/openapi/knowledge-qa/query
```

MCP Server 不需要重写现有问答 engine，只需要在现有接口外增加一层适配：

```text
Agent / DeerFlow
  -> MCP Client
  -> 百姓惠 MCP Server
  -> 现有智能客服问答 API
  -> 知识图谱 / FalkorDB / LLM
```

这层 MCP Server 负责：

- 暴露 Agent 可调用的 tools。
- 将 tool call 转换为当前项目已有 HTTP API 请求。
- 将智能客服 API 返回值整理成稳定的 MCP tool result。
- 统一处理鉴权、超时、错误、日志和审计。

## 2. MCP Server 推荐入口

建议新增远程 HTTP MCP Server：

```text
http://8.163.40.99:8102/mcp
```

如果后续需要 SSE：

```text
http://8.163.40.99:8102/mcp/sse
```

推荐优先使用 `http` 类型，便于 DeerFlow 或企业 Agent 平台远程接入。

## 3. DeerFlow 接入配置示例

`extensions_config.json` 示例：

```json
{
  "mcpServers": {
    "baixinghui_customer_service": {
      "enabled": true,
      "type": "http",
      "url": "http://8.163.40.99:8102/mcp",
      "headers": {
        "Authorization": "Bearer $BXH_MCP_TOKEN"
      },
      "description": "百姓惠旅行社知识图谱智能客服 MCP 工具"
    }
  },
  "skills": {}
}
```

环境变量示例：

```bash
export BXH_MCP_TOKEN="<MCP_SERVER_TOKEN>"
```

说明：

- `BXH_MCP_TOKEN` 是 MCP Server 的访问令牌。
- MCP Server 内部再使用当前系统配置的 `X-KG-API-Key` 调用现有问答 API。
- 不建议让 DeerFlow 或 Agent 直接持有现有 `X-KG-API-Key`。

## 4. MCP Server 内部调用的现有接口

MCP Server 内部统一调用：

```text
POST http://127.0.0.1:8102/v1/openapi/knowledge-qa/query
```

请求头：

```http
Content-Type: application/json
X-KG-API-Key: <INTERNAL_KG_API_KEY>
```

如果 MCP Server 与业务 API 分开部署，则改为：

```text
POST http://8.163.40.99:8102/v1/openapi/knowledge-qa/query
```

## 5. MCP 工具设计原则

不要暴露通用工具，例如：

```text
call_api
execute_cypher
execute_sql
request_url
```

推荐暴露明确、受控的业务工具：

| 工具名 | 用途 | 读/写 | 风险等级 |
| --- | --- | --- | --- |
| `ask_customer_service` | 通用智能客服问答 | 读 | 低 |
| `query_route_price` | 查询线路价格 | 读 | 低 |
| `list_travel_routes` | 查询旅行线路清单 | 读 | 低 |
| `query_route_detail` | 查询线路天数、景区、酒店等详情 | 读 | 低 |
| `compare_routes` | 对比线路适配度或景点数量 | 读 | 中 |

当前阶段建议全部为只读工具，不提供写操作。

## 6. Tool 1：ask_customer_service

### 用途

通用客服问答工具。Agent 不确定该调用哪个细分工具时，可以使用该工具。

### Tool 定义

```json
{
  "name": "ask_customer_service",
  "description": "向百姓惠旅行社知识图谱智能客服提问。适用于线路价格、行程天数、景区、酒店、费用、车型、线路推荐和复杂多跳问答。该工具只读，不承诺最终价格、余位、房型或景区政策。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "question": {
        "type": "string",
        "description": "用户自然语言问题"
      },
      "session_id": {
        "type": "string",
        "description": "外部会话 ID，可选"
      },
      "request_id": {
        "type": "string",
        "description": "外部请求 ID，可选"
      },
      "customer_context": {
        "type": "object",
        "description": "客户上下文，例如人数、预算、出发日期、偏好，可选"
      }
    },
    "required": ["question"]
  }
}
```

### 内部 API 请求示例

```json
{
  "request_id": "mcp-req-0001",
  "session_id": "mcp-session-a01",
  "channel": "mcp",
  "graph_name": "baixinghui_travel_agency",
  "question": "轻奢黄小西纯玩3日游多少钱，可以玩几天，期间可以去哪些景区，小七孔附近可以入住什么酒店？"
}
```

### MCP Tool Result 示例

```json
{
  "success": true,
  "data": {
    "customer_reply": "亲，轻奢黄小西纯玩3日游是3天线路；成人参考610-2350元/人，儿童参考340-700元/人；可玩多彩贵州风、荔波小七孔景区、西江千户苗寨景区、黄果树旅游景区；附近可参考荔波天泰酒店、三力丽呈、荔波滨江。具体价格、房型和余位需要按出发日期再确认。",
    "answer": "完整回答内容",
    "confidence": 0.88,
    "follow_up_questions": ["请提供出发日期和人数。"],
    "risk_notes": ["价格、余位、房型和景区政策需按具体团期二次核实。"],
    "evidence": [],
    "plans": [],
    "response_mode": "fast_graph_template"
  },
  "trace_id": "trc_xxx"
}
```

## 7. Tool 2：query_route_price

### 用途

专门查询某条线路价格，例如成人价、儿童价、单房差。

### Tool 定义

```json
{
  "name": "query_route_price",
  "description": "查询百姓惠旅行社指定线路的参考价格、成人价、儿童价和单房差。该工具返回图谱参考价，最终价格需按出发日期、人数和住宿档位二次核实。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "route_name": {
        "type": "string",
        "description": "线路名称或关键词，例如 黄小西、轻奢黄小西纯玩3日游"
      },
      "days": {
        "type": "integer",
        "description": "行程天数，可选"
      },
      "request_id": {
        "type": "string",
        "description": "请求 ID，可选"
      }
    },
    "required": ["route_name"]
  }
}
```

### 内部 question 生成规则

```text
{route_name}{days_text}多少钱？成人价、儿童价和单房差是多少？
```

示例：

```json
{
  "question": "黄小西3日游多少钱？成人价、儿童价和单房差是多少？"
}
```

## 8. Tool 3：list_travel_routes

### 用途

查询当前图谱中有哪些旅行线路。

### Tool 定义

```json
{
  "name": "list_travel_routes",
  "description": "查询百姓惠旅行社当前图谱中的旅行线路清单。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "keyword": {
        "type": "string",
        "description": "线路关键词，可选，例如 黄小西、小西镇梵、旅行车"
      },
      "request_id": {
        "type": "string",
        "description": "请求 ID，可选"
      }
    }
  }
}
```

### 内部 question 生成规则

无关键词：

```text
旅行车线路有哪些？
```

有关键词：

```text
{keyword}相关线路有哪些？
```

## 9. Tool 4：query_route_detail

### 用途

查询某条线路的天数、价格、途经景区、某景区附近酒店等多跳图谱信息。

### Tool 定义

```json
{
  "name": "query_route_detail",
  "description": "查询指定线路的价格、行程天数、途经景区和景区附近酒店。适合多跳图谱问题。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "route_name": {
        "type": "string",
        "description": "线路名称或关键词"
      },
      "scenic_name": {
        "type": "string",
        "description": "需要查询附近酒店的景区名称，可选，例如 小七孔、西江、黄果树"
      },
      "request_id": {
        "type": "string",
        "description": "请求 ID，可选"
      }
    },
    "required": ["route_name"]
  }
}
```

### 内部 question 生成规则

```text
{route_name}多少钱，可以玩几天，期间可以去哪些景区，{scenic_name}附近可以入住什么酒店？
```

示例：

```json
{
  "question": "轻奢黄小西纯玩3日游多少钱，可以玩几天，期间可以去哪些景区，小七孔附近可以入住什么酒店？"
}
```

## 10. Tool 5：compare_routes

### 用途

对比两条或多条线路，例如哪个更适合老人小孩、哪个景点更多、哪个更轻松。

### Tool 定义

```json
{
  "name": "compare_routes",
  "description": "对比百姓惠旅行社线路的适配度、景区数量、轻松程度、老人小孩适合度等。只做图谱证据对比，不做最终承诺。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "route_names": {
        "type": "array",
        "items": {"type": "string"},
        "description": "需要对比的线路关键词，例如 [\"黄小西\", \"小西镇梵\"]"
      },
      "compare_focus": {
        "type": "string",
        "description": "对比重点，例如 老人小孩适合度、景点数量、价格、轻松程度"
      },
      "request_id": {
        "type": "string",
        "description": "请求 ID，可选"
      }
    },
    "required": ["route_names", "compare_focus"]
  }
}
```

### 内部 question 生成规则

```text
{route_names}哪个更适合{compare_focus}，为什么？
```

示例：

```json
{
  "question": "黄小西和小西镇梵哪个更适合老人小孩、不要太累，为什么？"
}
```

## 11. 统一 MCP Tool Result 格式

所有工具建议统一返回：

```json
{
  "success": true,
  "data": {
    "customer_reply": "客服可直接发送的话术",
    "answer": "完整回答",
    "confidence": 0.88,
    "follow_up_questions": [],
    "risk_notes": [],
    "plans": [],
    "evidence": [],
    "response_mode": "fast_graph_template",
    "latency_ms": 35
  },
  "trace_id": "trc_xxx"
}
```

失败时返回：

```json
{
  "success": false,
  "error": {
    "code": "CUSTOMER_SERVICE_QUERY_FAILED",
    "message": "智能客服查询失败",
    "retryable": true
  },
  "trace_id": "trc_xxx"
}
```

如果业务 API 返回受控兜底，也建议作为 `success: true` 返回，并在 `data.response_mode` 中标记：

```json
{
  "success": true,
  "data": {
    "customer_reply": "亲，这个问题当前图谱暂未查到可确认答案，需要补充更具体的线路、景区或套餐名称后再核实。",
    "response_mode": "llm_graph_qa_controlled_failure",
    "risk_notes": ["当前回复为受控兜底，不代表图谱已有明确业务证据。"]
  },
  "trace_id": "trc_xxx"
}
```

## 12. MCP Server 环境变量

建议 MCP Server 使用以下环境变量：

```bash
export BXH_MCP_TOKEN="<MCP_SERVER_TOKEN>"
export BXH_KG_API_BASE="http://127.0.0.1:8102"
export BXH_KG_API_KEY="<INTERNAL_KG_API_KEY>"
export BXH_DEFAULT_GRAPH="baixinghui_travel_agency"
export BXH_MCP_TIMEOUT_SECONDS="15"
```

说明：

| 变量名 | 说明 |
| --- | --- |
| `BXH_MCP_TOKEN` | 外部 Agent 调用 MCP Server 的鉴权令牌 |
| `BXH_KG_API_BASE` | 当前项目 HTTP API 地址 |
| `BXH_KG_API_KEY` | 当前项目外部图谱问答 API Key |
| `BXH_DEFAULT_GRAPH` | 默认图谱 |
| `BXH_MCP_TIMEOUT_SECONDS` | MCP Server 调用业务 API 的超时时间 |

## 13. 安全要求

- MCP Server 只暴露业务工具，不暴露任意 URL、任意 SQL、任意 Cypher。
- 所有工具当前均为只读工具。
- MCP Server 必须校验 `Authorization` 或其他服务令牌。
- 不向 Agent 返回内部 API Key、数据库地址、原始异常栈。
- `risk_notes` 必须保留给 Agent，用于提示价格、余位、房型、政策需二次核实。
- 记录工具调用日志，至少包含 tool name、request id、trace id、耗时、调用结果。

## 14. 超时和重试建议

| 场景 | 建议 |
| --- | --- |
| MCP Server 调用业务 API 超时 | 15 秒 |
| 高频模板问题 | 通常几十毫秒到数百毫秒 |
| LLM 长尾问题 | 可能数秒，超过预算返回受控兜底 |
| Agent 重试 | 仅对网络错误或 `retryable: true` 的错误重试 |
| 空结果 | 不建议重试，应追问用户补充信息 |

## 15. 最小验收用例

### 15.1 查询线路价格

工具：

```text
query_route_price
```

输入：

```json
{
  "route_name": "黄小西",
  "days": 3
}
```

预期：

- 返回 `success: true`
- `data.customer_reply` 有客服话术
- `data.risk_notes` 提醒价格需二次核实

### 15.2 查询线路详情和酒店

工具：

```text
query_route_detail
```

输入：

```json
{
  "route_name": "轻奢黄小西纯玩3日游",
  "scenic_name": "小七孔"
}
```

预期：

- 返回线路天数
- 返回参考价格
- 返回途经景区
- 返回小七孔附近酒店

### 15.3 对比线路适配度

工具：

```text
compare_routes
```

输入：

```json
{
  "route_names": ["黄小西", "小西镇梵"],
  "compare_focus": "老人小孩、不要太累"
}
```

预期：

- 返回更推荐的线路
- 返回推荐理由
- 提醒最终需按团期和客户情况核实

### 15.4 长尾无命中问题

工具：

```text
ask_customer_service
```

输入：

```json
{
  "question": "美酒中秋有什么活动或者套餐？"
}
```

预期：

- 返回 `success: true`
- `data.response_mode` 可能为 `llm_graph_qa_controlled_failure`
- `customer_reply` 提示补充更具体信息

## 16. 推荐结论

当前项目不需要把现有智能客服接口重写为 MCP。推荐方式是新增一个轻量 MCP Server 适配层，把现有：

```text
/v1/openapi/knowledge-qa/query
```

封装为多个明确的 MCP tools。这样 Agent 可以稳定调用百姓惠知识图谱客服能力，同时业务系统仍保留自己的鉴权、超时、图谱查询、LLM 兜底和审计边界。