# TH Hotel SuperAgent MCP 安全策略

## 1. 文档信息

| 项目 | 内容 |
| --- | --- |
| 文档版本 | 0.1 |
| 日期 | 2026-07-09 |
| 状态 | 草案 |
| 适用范围 | `server/` 内嵌 SuperAgent MCP endpoint 安全、权限和日志边界 |

## 2. 安全目标

内嵌 MCP endpoint 的安全目标是：

- 让 SuperAgent 通过语义化工具调用业务能力。
- 不让 SuperAgent 直接接触后端 HMAC secret。
- 不绕过现有后端鉴权、幂等、审计和业务校验。
- 不返回附件 URL、原始未清洗 HTML、客户敏感信息或生产 Secret。
- 对写操作建立清晰边界。

## 3. 两层鉴权

### 3.1 SuperAgent 到 MCP Endpoint

建议使用 MCP 层访问凭证：

```text
Authorization: Bearer <MCP_AUTH_TOKEN>
```

中文说明：

- `MCP_AUTH_TOKEN` 用于限制谁可以调用后端内嵌 MCP endpoint。
- 该 token 与后端 HMAC secret 不是同一个值。
- 该 token 应是高熵随机字符串，不使用手机号、项目名、酒店名、固定短语或可猜测文本。
- dev、test、prod 必须使用不同 token，生产 token 建议至少 32 字节随机值。
- token 应通过部署平台 Secret 或安全通道交付，不写入仓库。

### 3.2 MCP Endpoint 到业务 Service

MCP endpoint 与后端业务 Service 同进程，不再通过 HMAC REST 调用本后端。

中文说明：

- REST HMAC 规则继续用于原有 REST API。
- MCP endpoint 只校验 MCP Bearer Token。
- MCP endpoint 必须通过现有 Service 进入业务逻辑，不能直接访问 Mapper 或数据库。
- SuperAgent 不需要知道 REST HMAC 签名串，也不能拿到 REST HMAC secret。

## 4. Tool 权限边界

| Tool | 权限级别 | 安全说明 |
| --- | --- | --- |
| `th_hotel_query_case_context` | 只读 | 不写订单、不写任务、不写 OPERA |
| `th_hotel_query_object_detail` | 只读 | 不写订单、不写任务、不写 OPERA |
| `th_hotel_list_message_conversation_tasks` | 只读 | 不创建任务、不修改任务 |
| `th_hotel_list_message_conversation_messages` | 受控读取 | 读取正文会写后端访问审计 |
| `th_hotel_submit_task_results` | 写入 | 写 AI 过渡层、订单、任务和任务卡 |

写入工具要求：

- dev/test 可以用于联调。
- prod 必须经过上线审批后启用。
- 生产建议保留独立开关，例如 `MCP_ENABLE_SUBMIT_TASK_RESULTS=true`。
- 日志必须能定位调用方、request id、trace id 和 source message，但不能输出正文和 Secret。

## 5. 邮件正文和附件边界

`th_hotel_list_message_conversation_messages` 只允许返回受控正文。

禁止返回：

- 原始未清洗 HTML。
- 附件 URL。
- 内嵌图片 URL。
- `attachments`、`inline_images`、`external_url`。
- HTML 中的 `href/src` 外链属性。

如果 SuperAgent 后续需要附件内容，应新增独立的受控附件接口和权限策略，不能复用当前正文工具绕过限制。

## 6. ID 边界

SuperAgent 可以使用：

- `hotel_id`
- 外部 `source_message_id`
- `external_conversation_id`
- 业务 key，例如 `group_code`、`confirmation_number`

SuperAgent 不应依赖：

- 内部 SourceMessage Inbox ID。
- 数据库主键表达业务含义。
- 前端内部路由或展示字段。

接口响应中如果出现内部 ID，只能用于本系统排查或后续本系统 API 的对象定位，不应当作外部系统稳定业务 ID。

## 7. 日志与脱敏

MCP endpoint 日志允许记录：

- tool 名称。
- request id。
- trace id。
- hotel id。
- 外部 source message id。
- HTTP 状态码。
- 错误码。
- 调用耗时。

禁止记录：

- REST HMAC secret。
- MCP auth token。
- 完整 HMAC signature。
- 原始邮件正文。
- 附件 URL。
- 客户证件、支付信息、Token、Cookie。
- 未清洗 HTML。

## 8. 重试策略

只读工具：

- MCP endpoint 与业务 Service 同进程，不做 HTTP 重试。
- 如果内部 Service 返回受控错误，应原样包装为 tool result。

写入工具：

- 默认不自动重试已发送的写请求。
- MCP submit payload adapter 校验失败时，不调用业务写入 Service，也不触发自动重试。
- 如果调用方需要重试，必须依赖后端幂等机制和任务结果中的幂等信息。
- 对于响应丢失但请求可能已到达后端的场景，应优先查询已有任务或人工排查，避免重复写入。

## 9. 生产上线前检查

上线前必须确认：

- 生产 `MCP_AUTH_TOKEN` 已通过 Secret 注入。
- `MCP_MAX_BODY_BYTES` 已确认，默认 10MB。
- dev/test 临时 token 没有进入生产。
- 日志脱敏规则已经生效。
- 写入工具生产开关已经明确。
- 所有接口只暴露在 HTTPS 和可信网络边界内。
- 监控覆盖 `/mcp` 可用性、tool 调用失败率和写入错误率。