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