78 lines
2.8 KiB
Markdown
78 lines
2.8 KiB
Markdown
# TH Hotel SuperAgent MCP 文档入口
|
||
|
||
## 1. 目录定位
|
||
|
||
`mcp-server/` 当前只作为 MCP 方案入口指针，不承载运行时代码。
|
||
|
||
完整 MCP 对外资料包已经集中到：
|
||
|
||
```text
|
||
docs/project/integrations/superagent-mcp/
|
||
```
|
||
|
||
项目已经选择 **现有 Spring Boot 后端内嵌 MCP endpoint** 的实现方式，运行时代码位于：
|
||
|
||
```text
|
||
server/src/main/java/cn/nianxx/thhotel/integrations/mcp/superagent/
|
||
```
|
||
|
||
## 2. 当前调用链
|
||
|
||
```text
|
||
SuperAgent
|
||
-> HTTP MCP /mcp
|
||
-> server/ 内嵌 SuperAgentMcpController
|
||
-> 现有 Reservation / SuperAgent Service
|
||
-> 数据库和业务规则
|
||
```
|
||
|
||
中文说明：
|
||
|
||
- 不需要额外部署一个独立 MCP 服务。
|
||
- 不需要 MCP 层再绕一圈 HMAC REST 调用当前后端。
|
||
- 原有 HMAC REST 接口继续保留，供直接 REST 对接或排查使用。
|
||
- MCP endpoint 使用独立 Bearer Token 做 SuperAgent 到后端的访问控制。
|
||
|
||
## 3. 职责边界
|
||
|
||
内嵌 MCP endpoint 负责：
|
||
|
||
- 对 SuperAgent 暴露 MCP tools。
|
||
- 解析 MCP JSON-RPC 请求。
|
||
- 校验 MCP Bearer Token。
|
||
- 将 tool arguments 转为现有 Service 请求 DTO。
|
||
- 统一包装 MCP tool result。
|
||
|
||
内嵌 MCP endpoint 不负责：
|
||
|
||
- 不绕过现有业务 Service。
|
||
- 不直接访问 Mapper 或数据库。
|
||
- 不接收或保存后端 HMAC secret。
|
||
- 不把原始邮件正文、附件 URL、Secret 写入日志。
|
||
|
||
## 4. 一期 MCP Tools
|
||
|
||
一期暴露 5 个工具：
|
||
|
||
| Tool | 中文用途 | 性质 |
|
||
| --- | --- | --- |
|
||
| `th_hotel_query_case_context` | 查询订单上下文 | 只读 |
|
||
| `th_hotel_query_object_detail` | 查询对象详情 | 只读 |
|
||
| `th_hotel_list_message_conversation_tasks` | 查询邮件会话下任务 | 只读 |
|
||
| `th_hotel_list_message_conversation_messages` | 查询邮件会话下受控正文 | 只读，读取正文会触发后端审计 |
|
||
| `th_hotel_submit_task_results` | 提交 SuperAgent AI 任务结果 | 写入 |
|
||
|
||
第 5 个工具会写入 AI 过渡层、订单、任务和任务卡。生产启用必须受
|
||
`MCP_ENABLE_SUBMIT_TASK_RESULTS` 控制。
|
||
|
||
## 5. 文档索引
|
||
|
||
- `docs/project/integrations/superagent-api-contract.md`：现有 REST API 契约。
|
||
- `docs/project/integrations/superagent-mcp/README.md`：MCP 对外资料包入口。
|
||
- `docs/project/integrations/superagent-mcp/integration-guide.md`：MCP 总体接入说明。
|
||
- `docs/project/integrations/superagent-mcp/tools.md`：5 个 MCP tools 的工具契约。
|
||
- `docs/project/integrations/superagent-mcp/security-policy.md`：安全、权限和日志边界。
|
||
- `docs/project/integrations/superagent-mcp/deployment-guide.md`：部署配置和运行参数。
|
||
- `docs/project/integrations/superagent-mcp/test-cases.md`：联调测试用例。
|
||
- `docs/project/integrations/superagent-mcp/mcp-client-config.example.json`：SuperAgent HTTP MCP 客户端配置模板。
|