nex_docus/docs/MCP_HTTP_INTEGRATION.md

# NexDocs MCP 使用文档

## 1. 方案说明

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

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

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

这意味着：

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


## 2. 接口地址

MCP 对外地址：

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

例如：

```text
http://backend.internal:8000/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 用户名
- 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 获取当前用户创建的项目列表

工具名：

```text
list_created_projects
```

参数：

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


### 5.2 获取指定项目文件树

工具名：

```text
get_project_tree
```

参数：

- `project_id`: 必填


### 5.3 获取指定文件内容

工具名：

```text
get_file
```

参数：

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


### 5.4 在项目中创建新文件

工具名：

```text
create_file
```

参数：

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

说明：

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


### 5.5 修改指定文件

工具名：

```text
update_file
```

参数：

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

说明：

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


### 5.6 删除指定文件

工具名：

```text
delete_file
```

参数：

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

说明：

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


## 6. 调用端配置示例

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

```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. 后端部署要求

### 7.1 Python 版本

后端运行环境需要 Python 3.12。

本地开发建议：

```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
```

说明：

- 当前 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](/Users/jiliu/工作/projects/NexDocus/backend/scripts/create_mcp_bots_table.sql)
- [init_database.sql](/Users/jiliu/工作/projects/NexDocus/backend/scripts/init_database.sql)


## 8. 已验证结果

本地调试已验证：

- Python 3.12 环境可正常启动 backend
- `/health` 返回 `200`
- `/mcp` 与 `/mcp/` 均可访问
- 未传 `X-Bot-Id` / `X-Bot-Secret` 时返回 `401`

调试使用地址：

```text
http://127.0.0.1:8012/mcp
```

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


## 9. 相关代码位置

- MCP 挂载入口：
  [main.py](/Users/jiliu/工作/projects/NexDocus/backend/main.py)
- MCP 服务实现：
  [server.py](/Users/jiliu/工作/projects/NexDocus/backend/app/mcp/server.py)
- MCP Bot 模型：
  [mcp_bot.py](/Users/jiliu/工作/projects/NexDocus/backend/app/models/mcp_bot.py)
- 用户凭证管理接口：
  [auth.py](/Users/jiliu/工作/projects/NexDocus/backend/app/api/v1/auth.py)
- 个人中心凭证管理页面：
  [ProfilePage.jsx](/Users/jiliu/工作/projects/NexDocus/frontend/src/pages/Profile/ProfilePage.jsx)