149 lines
4.8 KiB
Markdown
149 lines
4.8 KiB
Markdown
# TH Hotel SuperAgent MCP 接入指南
|
||
|
||
## 1. 文档信息
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 文档版本 | 0.2 |
|
||
| 日期 | 2026-07-09 |
|
||
| 状态 | 已调整为 Spring Boot 内嵌 MCP endpoint |
|
||
| 适用范围 | SuperAgent 通过 HTTP MCP 调用 TH Hotel 后端内嵌 MCP endpoint |
|
||
| 主要读者 | SuperAgent 对接方、后端、测试、运维 |
|
||
|
||
## 2. 文档定位
|
||
|
||
本文说明如何把 `superagent-api-contract.md` 中的 5 个 REST 能力以 MCP tools 暴露给
|
||
SuperAgent。
|
||
|
||
本文不是 MCP 官方规范。MCP 协议细节以官方文档为准：
|
||
|
||
- https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
|
||
- https://modelcontextprotocol.io/specification/2025-06-18/server/tools
|
||
|
||
## 3. 总体架构
|
||
|
||
当前选择 **现有 Spring Boot 后端内嵌 MCP endpoint**，不额外部署独立 MCP 服务。
|
||
|
||
```text
|
||
SuperAgent
|
||
-> HTTP MCP /mcp
|
||
-> th-hotel-simple/server
|
||
-> integrations.mcp.superagent
|
||
-> Reservation / SuperAgent Service
|
||
-> 数据库和业务规则
|
||
```
|
||
|
||
中文说明：
|
||
|
||
- SuperAgent 只感知 MCP tools。
|
||
- MCP endpoint 与现有后端同进程部署。
|
||
- MCP endpoint 直接复用已有 Service，不通过 HTTP 再调本机 REST。
|
||
- 原有 HMAC REST 接口继续保留，供直接 REST 对接或排查使用。
|
||
- MCP 层使用独立 Bearer Token；SuperAgent 不需要知道 REST HMAC 规则。
|
||
|
||
## 4. HTTP MCP 连接约定
|
||
|
||
后端暴露统一 HTTP MCP endpoint：
|
||
|
||
```text
|
||
POST {SERVER_BASE_URL}/mcp
|
||
```
|
||
|
||
SuperAgent 连接时携带 MCP 层鉴权 Header：
|
||
|
||
```text
|
||
Authorization: Bearer <MCP_AUTH_TOKEN>
|
||
```
|
||
|
||
中文说明：
|
||
|
||
- `MCP_AUTH_TOKEN` 是 SuperAgent 到当前后端 MCP endpoint 的访问凭证。
|
||
- `MCP_AUTH_TOKEN` 应使用高熵随机字符串，dev、test、prod 分环境配置。
|
||
- REST HMAC secret 仍只用于原有 REST API，不用于 MCP endpoint。
|
||
- `MCP_AUTH_TOKEN` 不应写入 SuperAgent prompt、skill 文件、仓库文档或普通日志。
|
||
- MCP 单次请求体默认限制为 10MB，超过后返回受控错误。
|
||
|
||
## 5. 一期工具范围
|
||
|
||
一期开放 5 个 MCP tools：
|
||
|
||
| Tool | 对应后端能力 | 性质 |
|
||
| --- | --- | --- |
|
||
| `th_hotel_query_case_context` | `ReservationAiQueryService.queryCaseContext` | 只读 |
|
||
| `th_hotel_query_object_detail` | `ReservationAiQueryService.queryObjectDetail` | 只读 |
|
||
| `th_hotel_list_message_conversation_tasks` | `ReservationAiQueryService.queryMessageConversationTasks` | 只读 |
|
||
| `th_hotel_list_message_conversation_messages` | `ReservationAiQueryService.queryMessageConversationMessages` | 只读，读取正文会触发后端审计 |
|
||
| `th_hotel_submit_task_results` | `ReservationAiTaskIntakeService.accept` | 写入 |
|
||
|
||
`th_hotel_submit_task_results` 会写入业务数据，不能当作普通查询工具使用。
|
||
|
||
## 6. 与 REST 契约的关系
|
||
|
||
MCP tools 与 REST API 共享业务语义和 DTO，但调用链不同：
|
||
|
||
```text
|
||
MCP tool input
|
||
-> MCP endpoint 校验和补充默认值
|
||
-> 现有 Service 请求 DTO
|
||
-> 现有业务 Service
|
||
-> MCP tool result
|
||
```
|
||
|
||
REST 直接对接仍走：
|
||
|
||
```text
|
||
REST request
|
||
-> HMAC 校验
|
||
-> Controller
|
||
-> 现有业务 Service
|
||
-> REST response
|
||
```
|
||
|
||
若 REST 契约或 Service DTO 升级，必须同步检查 MCP tools 文档和实现。
|
||
|
||
## 7. SuperAgent 需要拿到的资料
|
||
|
||
给 SuperAgent 对接方的资料包建议包含：
|
||
|
||
- `docs/project/integrations/superagent-mcp/README.md`
|
||
- `docs/project/integrations/superagent-mcp/integration-guide.md`
|
||
- `docs/project/integrations/superagent-mcp/tools.md`
|
||
- `docs/project/integrations/superagent-mcp/security-policy.md`
|
||
- `docs/project/integrations/superagent-mcp/test-cases.md`
|
||
- dev/test 后端 MCP 地址
|
||
- MCP 层访问凭证的安全交付方式
|
||
|
||
不要提供：
|
||
|
||
- REST HMAC secret 明文。
|
||
- 生产数据库、邮件正文、附件 URL 或客户个人信息样本。
|
||
- 可以绕过 MCP endpoint 直接调用后端写接口的普通凭证。
|
||
|
||
## 8. 调用顺序建议
|
||
|
||
典型邮件处理流程：
|
||
|
||
1. SuperAgent 从 AgentBus payload 中拿到外部 `source_message_id` 和业务候选字段。
|
||
2. 调用 `th_hotel_query_case_context` 判断订单上下文。
|
||
3. 必要时调用 `th_hotel_query_object_detail` 查看对象详情。
|
||
4. 必要时调用 `th_hotel_list_message_conversation_messages` 读取受控历史正文。
|
||
5. 必要时调用 `th_hotel_list_message_conversation_tasks` 查询同一邮件会话下已有任务。
|
||
6. 最终只在明确产出任务结果时调用 `th_hotel_submit_task_results`。
|
||
|
||
## 9. 当前 checkpoint
|
||
|
||
当前 checkpoint：
|
||
|
||
```text
|
||
checkpoint-superagent-mcp-embedded-endpoint
|
||
```
|
||
|
||
验收标准：
|
||
|
||
- `server/` 提供内嵌 `POST /mcp` endpoint。
|
||
- 5 个 MCP tools 均可通过 `tools/list` 发现。
|
||
- 只读 tool 直接复用现有查询 Service。
|
||
- 写入 tool 受 `MCP_ENABLE_SUBMIT_TASK_RESULTS` 开关控制。
|
||
- MCP endpoint 使用 Bearer Token 鉴权。
|
||
- 文档不包含生产 Secret、真实客户数据、附件 URL 或原始邮件正文。
|