122 lines
4.2 KiB
Markdown
122 lines
4.2 KiB
Markdown
# 集成：MCP Streamable HTTP（DV-0011 支撑）
|
||
|
||
> 本页为 MCP 接入的规格化工作说明，**整合自原 `docs/MCP_HTTP_INTEGRATION.md`（已并入）** 与 DV-0011 规格。实现代码：`backend/app/mcp/server.py`、`backend/app/mcp/context.py`、`backend/app/models/mcp_bot.py`。
|
||
|
||
## 1. 方案说明（决策摘要）
|
||
|
||
- 不再使用项目根目录独立 `mcp_server/`；改为**后端内集成**。
|
||
- 业务 REST API 继续走 `/api/v1/...`；MCP 入口挂载在同一个 backend 服务上。
|
||
- 传输协议：`streamableHttp`；MCP 地址 `/mcp`（`/mcp/` 也兼容）。
|
||
- 认证：`X-Bot-Id` + `X-Bot-Secret`。
|
||
|
||
这意味着：
|
||
- 不需要单独部署一套 MCP 服务；
|
||
- 不需要让 MCP client 传业务账号密码；
|
||
- 不需要让远程 agent 访问本地脚本进程。
|
||
|
||
## 2. 接口地址
|
||
|
||
```text
|
||
http://<backend-host>:<backend-port>/mcp
|
||
```
|
||
|
||
说明：
|
||
- 推荐优先使用 `/mcp`；`/mcp/` 也兼容。
|
||
- 前面有 Nginx/网关时，**不要对 `/mcp` 做 301/302 重定向**。
|
||
- 未携带 bot 凭证访问 `/mcp` 或 `/mcp/` 返回 `401`。
|
||
|
||
## 3. 认证模型
|
||
|
||
MCP client 只传两个 header：`X-Bot-Id`、`X-Bot-Secret`。后端逻辑：
|
||
|
||
1. 根据 `X-Bot-Id` 查询 `mcp_bots`；
|
||
2. 校验 `X-Bot-Secret`；
|
||
3. 将该 bot 映射到 NexDocs 用户；
|
||
4. 以该用户身份执行 MCP 工具。
|
||
|
||
因此 client 不需要再传：NexDocs 用户名、密码、access token。
|
||
|
||
## 4. 用户如何获取凭证
|
||
|
||
个人中心 → `MCP 接入` 标签页：
|
||
- 查看 `X-Bot-Id`；
|
||
- 查看并复制 `X-Bot-Secret`；
|
||
- 重新生成 `X-Bot-Secret`。
|
||
|
||
后端接口：
|
||
- `GET /api/v1/auth/mcp-credentials`
|
||
- `POST /api/v1/auth/mcp-credentials/rotate-secret`
|
||
|
||
## 5. 当前支持的 MCP 工具
|
||
|
||
| 工具 | 说明 | 关键参数 |
|
||
| --- | --- | --- |
|
||
| `list_created_projects` | 列出当前用户创建的项目 | keyword(可选), limit(默认100) |
|
||
| `get_project_tree` | 项目文件树 | project_id(必填) |
|
||
| `get_file` | 获取文件内容 | project_id, path |
|
||
| `create_file` | 创建新文件 | project_id, path, content(可选) |
|
||
| `update_file` | 修改文件 | project_id, path, content |
|
||
| `delete_file` | 删除文件 | project_id, path |
|
||
|
||
### 文件类工具的语义
|
||
- `create_file`：目标已存在报错；自动创建缺失上级目录；校验项目写权限；写 Markdown 更新搜索索引；记录操作日志；通知项目成员。
|
||
- `update_file`：目标不存在报错；只允许更新文件（非目录）；校验写权限；写 Markdown 更新索引；记日志；通知。
|
||
- `delete_file`：目标不存在报错；只允许删除文件（非目录）；删除 Markdown 同步删搜索索引；记日志；通知。
|
||
|
||
## 6. 调用端配置示例
|
||
|
||
支持 streamableHttp 的 MCP client：
|
||
|
||
```json
|
||
{
|
||
"tools": {
|
||
"mcpServers": {
|
||
"biz_mcp": {
|
||
"type": "streamableHttp",
|
||
"url": "http://backend.internal:8000/mcp",
|
||
"headers": {
|
||
"X-Bot-Id": "nexbot_xxxxxxxxxxxxxxxx",
|
||
"X-Bot-Secret": "nxbotsec_xxxxxxxxxxxxxxxxxxxxxxxx"
|
||
},
|
||
"toolTimeout": 60
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
注意：
|
||
- `url` 建议使用 `/mcp`；
|
||
- `headers` 中不需再放业务用户名密码；
|
||
- `X-Bot-Secret` 只应发给受信任调用端；
|
||
- 浏览器环境客户端需把站点加入后端 `CORS_ORIGINS`。
|
||
|
||
## 7. 后端部署要求
|
||
|
||
- **Python 版本**：backend 需要 Python 3.12（MCP SDK 要求 3.10+；本项目按 3.12 调试）。
|
||
- **Docker**：`backend/Dockerfile` 基于 Python 3.12。
|
||
- **数据表**：需要 `mcp_bots` 表（通过建表脚本/init 创建）。
|
||
- **Nginx 统一入口**：前端 Nginx 已加 `/mcp`、`/mcp/` 反代配置，可经统一入口访问。
|
||
|
||
本地开发建议：
|
||
```bash
|
||
cd backend
|
||
/opt/homebrew/bin/python3.12 -m venv venv312
|
||
env -u HTTP_PROXY -u HTTPS_PROXY ./venv312/bin/pip install -r requirements.txt
|
||
./venv312/bin/uvicorn main:app --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
## 8. 验证结果
|
||
|
||
本地已验证：
|
||
- Python 3.12 启动 backend 正常；
|
||
- `/health` 返回 200；
|
||
- `/mcp`、`/mcp/` 均可访问；
|
||
- 未传 `X-Bot-Id`/`X-Bot-Secret` 返回 401。
|
||
|
||
## 9. 规格映射
|
||
|
||
- 关联 ADR：ADR-0005（开放接入/可溯源）。
|
||
- 功能规格：FR-18（见 DV-0011）。
|
||
- 验证证据：见 DV-0011/verification.md；详细集成说明已并入本页（原 `docs/MCP_HTTP_INTEGRATION.md`）。
|