# TH Hotel SuperAgent MCP 文档入口

## 1. 目录定位

`mcp-server/` 当前只作为 MCP 方案入口指针，不承载运行时代码。

完整 MCP 对外资料包已经集中到：

```text
docs/project/integrations/superagent-mcp/
```

项目已经选择 **现有 Spring Boot 后端内嵌 MCP endpoint** 的实现方式，运行时代码位于：

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

## 2. 当前调用链

```text
SuperAgent
-> HTTP MCP /mcp
-> server/ 内嵌 SuperAgentMcpController
-> 现有 Reservation / SuperAgent Service
-> 数据库和业务规则
```

中文说明：

- 不需要额外部署一个独立 MCP 服务。
- 不需要 MCP 层再绕一圈 HMAC REST 调用当前后端。
- 原有 HMAC REST 接口继续保留，供直接 REST 对接或排查使用。
- MCP endpoint 使用独立 Bearer Token 做 SuperAgent 到后端的访问控制。

## 3. 职责边界

内嵌 MCP endpoint 负责：

- 对 SuperAgent 暴露 MCP tools。
- 解析 MCP JSON-RPC 请求。
- 校验 MCP Bearer Token。
- 将 tool arguments 转为现有 Service 请求 DTO。
- 统一包装 MCP tool result。

内嵌 MCP endpoint 不负责：

- 不绕过现有业务 Service。
- 不直接访问 Mapper 或数据库。
- 不接收或保存后端 HMAC secret。
- 不把原始邮件正文、附件 URL、Secret 写入日志。

## 4. 一期 MCP Tools

一期暴露 5 个工具：

| 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 任务结果 | 写入 |

第 5 个工具会写入 AI 过渡层、订单、任务和任务卡。生产启用必须受
`MCP_ENABLE_SUBMIT_TASK_RESULTS` 控制。

## 5. 文档索引

- `docs/project/integrations/superagent-api-contract.md`：现有 REST API 契约。
- `docs/project/integrations/superagent-mcp/README.md`：MCP 对外资料包入口。
- `docs/project/integrations/superagent-mcp/integration-guide.md`：MCP 总体接入说明。
- `docs/project/integrations/superagent-mcp/tools.md`：5 个 MCP tools 的工具契约。
- `docs/project/integrations/superagent-mcp/security-policy.md`：安全、权限和日志边界。
- `docs/project/integrations/superagent-mcp/deployment-guide.md`：部署配置和运行参数。
- `docs/project/integrations/superagent-mcp/test-cases.md`：联调测试用例。
- `docs/project/integrations/superagent-mcp/mcp-client-config.example.json`：SuperAgent HTTP MCP 客户端配置模板。