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

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

@@ -0,0 +1,131 @@
+# TH Hotel SuperAgent MCP 部署指南
+
+## 1. 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 文档版本 | 0.2 |
+| 日期 | 2026-07-09 |
+| 状态 | 已调整为 Spring Boot 内嵌 MCP endpoint |
+| 适用范围 | `server/` 内嵌 SuperAgent MCP endpoint 的部署配置 |
+
+## 2. 部署拓扑
+
+当前不新增独立 MCP 服务，仍部署现有后端：
+
+```text
+SuperAgent
+-> HTTPS
+-> th-hotel-simple-server /mcp
+-> 现有业务 Service
+-> 数据库和业务规则
+```
+
+中文说明：
+
+- `POST /mcp` 与现有后端 API 同进程。
+- MCP endpoint 不再通过 HMAC REST 调用本后端。
+- 原有 REST HMAC 接口继续保留。
+- 部署包仍是 `server/` 的 Spring Boot 应用。
+
+## 3. HTTP 端点
+
+| Endpoint | 中文说明 |
+| --- | --- |
+| `POST /mcp` | MCP HTTP 入口，路径可用 `MCP_HTTP_PATH` 覆盖 |
+| `GET /api/health` | 当前后端健康检查 |
+
+## 4. 环境变量
+
+| 变量 | 是否必填 | 是否 Secret | 中文说明 |
+| --- | --- | --- | --- |
+| `MCP_ENABLED` | 是 | 否 | 是否启用内嵌 MCP endpoint |
+| `MCP_HTTP_PATH` | 否 | 否 | MCP HTTP path，默认 `/mcp` |
+| `MCP_AUTH_TOKEN` | 是 | 是 | SuperAgent 到 MCP endpoint 的访问凭证 |
+| `MCP_ENABLE_SUBMIT_TASK_RESULTS` | 是 | 否 | 是否启用写入工具 |
+| `MCP_MAX_BODY_BYTES` | 否 | 否 | MCP 单次请求体最大字节数，默认 `10485760`，即 10MB |
+
+生产要求：
+
+- `MCP_AUTH_TOKEN` 必须通过 Secret 注入。
+- `MCP_AUTH_TOKEN` 应使用高熵随机字符串，建议至少 32 字节随机值，例如 `openssl rand -base64 32` 或 `openssl rand -hex 32`。
+- dev、test、prod 必须使用不同的 `MCP_AUTH_TOKEN`。
+- `MCP_ENABLED` 生产启用前必须经过联调验证。
+- `MCP_ENABLE_SUBMIT_TASK_RESULTS` 生产启用前必须单独审批。
+- 不得把生产 Secret 写入 `.env.example`、README、SuperAgent skill、镜像或普通日志。
+
+说明：
+
+- REST HMAC 相关变量仍用于原有 REST API，不是 MCP endpoint 的鉴权方式。
+- SuperAgent 使用 MCP 时只需要 `MCP_AUTH_TOKEN`，不需要 REST HMAC secret。
+
+## 5. SuperAgent 连接配置
+
+建议给 SuperAgent 提供：
+
+```text
+MCP URL: https://<server-domain>/mcp
+Authorization: Bearer <由安全渠道交付的 MCP_AUTH_TOKEN>
+```
+
+也可以提供本目录下的配置模板：
+
+```text
+docs/project/integrations/superagent-mcp/mcp-client-config.example.json
+```
+
+中文说明：
+
+- 模板中的 `https://<server-domain>/mcp` 需要替换为 dev/test/prod 对应后端地址。
+- 模板中的 `${MCP_AUTH_TOKEN}` 只是占位符，真实 token 通过部署平台 Secret 或安全通道注入。
+- 如果 SuperAgent 平台有自己的 MCP 配置 schema，以平台字段名为准，但连接地址、鉴权 Header、10MB 请求限制和 tool allowlist 应保持一致。
+
+不要给 SuperAgent 提供：
+
+- REST HMAC secret。
+- 数据库地址。
+- 邮件原文样本和附件 URL。
+- 可以绕过 MCP endpoint 的写接口调用凭证。
+
+## 6. 本地启动
+
+本地启动仍使用后端命令：
+
+```bash
+cd server
+MCP_ENABLED=true MCP_AUTH_TOKEN=test-token MCP_ENABLE_SUBMIT_TASK_RESULTS=false ./mvnw spring-boot:run
+```
+
+中文说明：
+
+- `MCP_ENABLE_SUBMIT_TASK_RESULTS=false` 时，写入 tool 会返回 `MCP_TOOL_DISABLED`。
+- `MCP_MAX_BODY_BYTES` 默认 10MB，通常不需要本地覆盖。
+- dev/test 联调确认写入链路时，可临时启用写入 tool。
+
+## 7. 监控指标
+
+建议监控：
+
+- `/mcp` 请求总数。
+- 每个 tool 的调用次数。
+- 每个 tool 的成功率和失败率。
+- `MCP_AUTH_INVALID` 数量。
+- `MCP_TOOL_DISABLED` 数量。
+- `th_hotel_submit_task_results` 写入成功和失败数量。
+- 受控正文读取量和后端原文访问审计记录。
+
+## 8. 灰度和回滚
+
+建议上线顺序：
+
+1. dev 启用 `MCP_ENABLED=true`。
+2. dev 连接 SuperAgent 联调 5 个工具。
+3. test 环境跑完整测试用例。
+4. prod 先启用 MCP endpoint 和 4 个只读工具。
+5. 确认日志、监控和告警正常后启用写入工具。
+
+回滚策略：
+
+- 可通过 `MCP_ENABLED=false` 关闭 MCP endpoint。
+- 可通过 `MCP_ENABLE_SUBMIT_TASK_RESULTS=false` 快速禁用写入工具。
+- 不需要单独下线一个 MCP 服务。