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

写入工具里的 `source_message_id` 必须来自 AgentBus payload 的 `source.external_message_id`。SuperAgent 不需要传数据库层 provider/channel；TH Hotel 后端按系统酒店和外部消息 ID 匹配唯一 SourceMessage Inbox，真实 channel 可能是 `OUTLOOK`。

## 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 或原始邮件正文。