TH Hotel SuperAgent MCP 文档入口
1. 目录定位
mcp-server/ 当前只作为 MCP 方案入口指针，不承载运行时代码。
完整 MCP 对外资料包已经集中到：
docs/project/integrations/superagent-mcp/
项目已经选择 现有 Spring Boot 后端内嵌 MCP endpoint 的实现方式，运行时代码位于：
server/src/main/java/cn/nianxx/thhotel/integrations/mcp/superagent/
2. 当前调用链
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 客户端配置模板。