th-hotel-simple/mcp-server/README.md

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 客户端配置模板。