# TH Hotel SuperAgent MCP 资料包

## 1. 目录定位

本目录集中放置当前项目提供给 SuperAgent 对接方、测试和运维参考的 MCP 文档。

运行时代码不在本目录，代码位于：

```text
server/src/main/java/cn/nianxx/thhotel/integrations/mcp/superagent/
```

中文说明：

- 当前 MCP endpoint 内嵌在现有 Spring Boot 后端中。
- 不需要额外部署独立 MCP 服务。
- 文档可以按本目录整体交付给对接方，但 Secret 必须通过安全通道单独交付。

## 2. 文档索引

| 文档 | 中文说明 |
| --- | --- |
| `integration-guide.md` | MCP 总体接入说明和调用顺序 |
| `tools.md` | 5 个 MCP tools 的工具契约 |
| `security-policy.md` | 鉴权、权限、正文、附件和日志边界 |
| `deployment-guide.md` | 部署参数、环境变量和上线顺序 |
| `test-cases.md` | SuperAgent 联调测试用例 |
| `mcp-client-config.example.json` | SuperAgent HTTP MCP 客户端配置模板，不包含真实 Secret |

## 3. 一期工具

| Tool | 中文用途 | 性质 |
| --- | --- | --- |
| `th_hotel_query_case_context` | 查询订单上下文 | 只读 |
| `th_hotel_query_object_detail` | 查询对象详情 | 只读 |
| `th_hotel_list_message_conversation_tasks` | 查询邮件会话下任务 | 只读 |
| `th_hotel_list_message_conversation_messages` | 查询邮件会话下受控正文 | 只读，读取正文会触发后端审计 |
| `th_hotel_submit_task_results` | 提交 SuperAgent AI 任务结果 | 写入，受开关控制 |

## 4. 对外交付提醒

可以交付：

- 本目录下的 MCP 文档。
- `mcp-client-config.example.json` 配置模板。
- dev/test MCP 地址。
- 通过安全通道交付的 `MCP_AUTH_TOKEN`。

不能交付：

- REST HMAC secret。
- 数据库连接信息。
- 生产客户数据、原始邮件正文或附件 URL。
- 能绕过 MCP endpoint 直接调用后端写接口的凭证。