增加 SuperAgent MCP 内嵌接口和配置文档

docs/project/integrations/superagent-mcp/integration-guide.md

@@ -0,0 +1,148 @@
+# 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 或原始邮件正文。