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

mcp-server/README.md

@@ -0,0 +1,77 @@
+# 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 客户端配置模板。