mula
/
nex_docus
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
nex_docus/docs/sdd/integrations/mcp.md

4.2 KiB
Raw Blame History

集成：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. 接口地址

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：

{
  "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/ 反代配置，可经统一入口访问。

本地开发建议：

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）。