Files

2026-07-12 19:39:14 +08:00

5.8 KiB

Raw Blame History

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 协议细节以官方文档为准：

3. 总体架构

当前选择 现有 Spring Boot 后端内嵌 MCP endpoint，不额外部署独立 MCP 服务。

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：

POST {SERVER_BASE_URL}/mcp

SuperAgent 连接时携带 MCP 层鉴权 Header：

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，但调用链不同：

MCP tool input
-> MCP endpoint 校验和补充默认值
-> 现有 Service 请求 DTO
-> 现有业务 Service
-> MCP tool result

REST 直接对接仍走：

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. 调用顺序建议

典型邮件处理流程：

SuperAgent 从 AgentBus payload 中拿到外部 source_message_id 和业务候选字段。
调用 th_hotel_query_case_context 判断订单上下文。
必要时调用 th_hotel_query_object_detail 查看对象详情。
必要时调用 th_hotel_list_message_conversation_messages 读取受控历史正文。
必要时调用 th_hotel_list_message_conversation_tasks 查询同一邮件会话下已有任务。
最终只在明确产出任务结果时调用 th_hotel_submit_task_results。

写入工具里的 source_message_id 必须来自 AgentBus payload 的 source.external_message_id。SuperAgent 不需要传数据库层 provider/channel；TH Hotel 后端按系统酒店和外部消息 ID 匹配唯一 SourceMessage Inbox，真实 channel 可能是 OUTLOOK。

M002 V3 后，写入工具优先接收结构化 S10/S99 或 source_message + message_events[] 业务根。message_events[].source_event_index 可以是 SuperAgent 内部事件 ID，例如 E_CHILD_1；MCP adapter 会在提交前按数组顺序映射为本系统一基数字索引，并校验跨事件关系是否悬空或重复。详细映射规则见 submit-payload-mapping.md。

V3 业务根写入成功时，MCP tool result 会返回 mapping_diagnostics.source_event_index_mapping[]，用于联调排查原始事件 ID 到本系统索引的映射；该字段不是业务任务字段，不会写入 TH Hotel 业务 payload。

9. 当前 checkpoint

当前 checkpoint：

checkpoint-superagent-mcp-embedded-endpoint

验收标准：

server/ 提供内嵌 POST /mcp endpoint。
5 个 MCP tools 均可通过 tools/list 发现。
只读 tool 直接复用现有查询 Service。
写入 tool 受 MCP_ENABLE_SUBMIT_TASK_RESULTS 开关控制。
写入 tool 已提供 V3/P0.1 submit payload adapter 和提交前 schema validator。
MCP endpoint 使用 Bearer Token 鉴权。
文档不包含生产 Secret、真实客户数据、附件 URL 或原始邮件正文。

5.8 KiB Raw Blame History Unescape Escape