# 集成：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`）。