nex_docus/docs/MCP_HTTP_INTEGRATION.md

NexDocs MCP 使用文档

1. 方案说明

NexDocs 现在不再使用项目根目录下的独立 mcp_server/。

当前方案为后端内集成 MCP：

• 业务 REST API 继续走 /api/v1/...
• MCP 入口挂载在同一个 backend 服务上
• 传输协议为 streamableHttp
• MCP 地址为 /mcp/
• 认证方式为 X-Bot-Id + X-Bot-Secret

这意味着：

• 不需要单独部署一套 MCP 服务
• 不需要让 MCP client 传业务账号密码
• 不需要让远程 agent 访问本地脚本进程

2. 接口地址

MCP 对外地址：

http://<backend-host>:<backend-port>/mcp/

例如：

http://backend.internal:8000/mcp/

说明：

• 请直接使用带尾部 / 的地址
• 请求 /mcp 会被后端重定向到 /mcp/
• 未携带 bot 凭证时，访问 /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 用户名
• NexDocs 密码
• NexDocs access token

4. 用户如何获取凭证

每个用户可在个人中心管理自己的 MCP 凭证。

页面位置：

1. 登录 NexDocs
2. 打开个人中心
3. 进入 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 Tools

5.1 获取当前用户创建的项目列表

工具名：

list_created_projects

参数：

• keyword: 可选，按项目名/描述过滤
• limit: 可选，默认 100

5.2 获取指定项目文件树

工具名：

get_project_tree

参数：

• project_id: 必填

5.3 获取指定文件内容

工具名：

get_file

参数：

• project_id: 必填
• path: 必填，项目内相对路径

5.4 在项目中创建新文件

工具名：

create_file

参数：

• project_id: 必填
• path: 必填，项目内相对路径
• content: 可选，文件初始内容，默认空字符串

说明：

• 目标路径已存在时会报错
• 会自动创建缺失的上级目录
• 会校验项目写权限
• 写入 Markdown 文件时会更新搜索索引
• 会记录操作日志
• 会通知项目成员

5.5 修改指定文件

工具名：

update_file

参数：

• project_id: 必填
• path: 必填，项目内相对路径
• content: 必填，新的文件内容

说明：

• 目标文件不存在时会报错
• 只允许更新文件，不允许更新目录
• 会校验项目写权限
• 写入 Markdown 文件时会更新搜索索引
• 会记录操作日志
• 会通知项目成员

5.6 删除指定文件

工具名：

delete_file

参数：

• project_id: 必填
• path: 必填，项目内相对路径

说明：

• 目标文件不存在时会报错
• 只允许删除文件，不允许删除目录
• 删除 Markdown 文件时会同步删除搜索索引
• 会记录操作日志
• 会通知项目成员

6. 调用端配置示例

如果调用端内置的是 MCP client，并支持 streamableHttp，可以这样配置：

{
  "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 只应发给受信任的调用端

7. 后端部署要求

7.1 Python 版本

后端运行环境需要 Python 3.12。

本地开发建议：

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

说明：

• 当前 backend 的 MCP 依赖要求 Python 3.10+
• 本项目已在本地按 Python 3.12 调试通过

7.2 Docker

backend/Dockerfile 已切换到 Python 3.12 基线。

7.3 数据表

mcp_bots 表需要存在。

如果你已经执行过建表脚本，这一步可以跳过。

相关文件：

• create_mcp_bots_table.sql
• init_database.sql

8. 已验证结果

本地调试已验证：

• Python 3.12 环境可正常启动 backend
• /health 返回 200
• /mcp/ 已挂载成功
• 未传 X-Bot-Id / X-Bot-Secret 时返回 401

调试使用地址：

http://127.0.0.1:8012/mcp/

生产或测试环境请替换为你的 backend 实际域名或 IP。

9. 相关代码位置

• MCP 挂载入口： main.py
• MCP 服务实现： server.py
• MCP Bot 模型： mcp_bot.py
• 用户凭证管理接口： auth.py
• 个人中心凭证管理页面： ProfilePage.jsx