132 lines
4.1 KiB
Markdown
132 lines
4.1 KiB
Markdown
# 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 服务。
|