296 lines
5.5 KiB
Markdown
296 lines
5.5 KiB
Markdown
# 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 对外地址：
|
||
|
||
```text
|
||
http://<backend-host>:<backend-port>/mcp/
|
||
```
|
||
|
||
例如：
|
||
|
||
```text
|
||
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 获取当前用户创建的项目列表
|
||
|
||
工具名：
|
||
|
||
```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` 只应发给受信任的调用端
|
||
|
||
|
||
## 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/` 已挂载成功
|
||
- 未传 `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)
|