huangting/th-hotel-simple
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e12bfd77e1fa18d28ee574863d06bc4a3550b491
th-hotel-simple/docs/project/integrations/superagent-mcp/deployment-guide.md

4.1 KiB
Raw Blame History

TH Hotel SuperAgent MCP 部署指南

1. 文档信息

项目 内容
文档版本 0.2
日期 2026-07-09
状态 已调整为 Spring Boot 内嵌 MCP endpoint
适用范围 server/ 内嵌 SuperAgent MCP endpoint 的部署配置

2. 部署拓扑

当前不新增独立 MCP 服务，仍部署现有后端：

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 提供：

MCP URL: https://<server-domain>/mcp
Authorization: Bearer <由安全渠道交付的 MCP_AUTH_TOKEN>

也可以提供本目录下的配置模板：

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. 本地启动

本地启动仍使用后端命令：

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 服务。