201 lines
5.6 KiB
Markdown
201 lines
5.6 KiB
Markdown
# 本项目新增 MCP 工具配置指南
|
||
|
||
> 最后更新：2026-04-26
|
||
> 适用目录：`/Users/jojo/Desktop/agents/正在修复中/agents`
|
||
|
||
本文面向后续维护者，说明如何在当前项目里新增并接入一个 MCP 工具（MCP Server）。
|
||
|
||
---
|
||
|
||
## 1. 先了解本项目里的 MCP 架构
|
||
|
||
当前实现是「**本项目作为 MCP 客户端桥接层**」：
|
||
|
||
1. 在后台配置一个或多个 MCP Server（stdio / streamable_http）
|
||
2. 系统通过 `tools/list` 拉取远端工具
|
||
3. 本地自动生成工具别名：`mcp__<server_id>__<tool_name>`
|
||
4. 模型调用该别名时，桥接层转发到对应服务的 `tools/call`
|
||
5. 对于同一服务，桥接层会复用长连接会话（避免每次调用都重启 MCP 进程），并处理常见 Server→Client 请求（如 `ping`、`roots/list`）
|
||
|
||
内置了一个原生工具：
|
||
|
||
- `list_mcp_servers`：查看服务、缓存工具和别名映射（可选刷新）
|
||
|
||
---
|
||
|
||
## 2. 配置入口（推荐）
|
||
|
||
### 2.1 管理后台入口（推荐）
|
||
|
||
- 打开：`/admin/policy`
|
||
- 页面中的「**MCP 服务配置（统一工具扩展）**」区域可做增删改查、同步工具
|
||
|
||
### 2.2 个人空间入口（宿主机管理员）
|
||
|
||
- 个人空间里有单独的「**MCP 配置**」入口
|
||
- 仅在 **宿主机模式 + 管理员** 时显示
|
||
- 点击后会跳转到 `/admin/policy`
|
||
|
||
> 管理 API 受管理员权限和二级密码校验保护，建议优先使用页面配置，不建议直接手改请求。
|
||
|
||
---
|
||
|
||
## 3. 第一步：先写一个可运行的 MCP Server
|
||
|
||
仓库已有可直接参考的测试服务：
|
||
|
||
- `/Users/jojo/Desktop/agents/正在修复中/agents/scripts/mcp_calculator_server.py`
|
||
|
||
这个示例使用 stdio，支持：
|
||
|
||
- `initialize`
|
||
- `tools/list`
|
||
- `tools/call`
|
||
|
||
如果你写新服务，至少要保证上述 3 个方法可用。
|
||
|
||
---
|
||
|
||
## 4. 第二步：在后台新增服务配置
|
||
|
||
在 `/admin/policy` 的 MCP 区域点击“新增 MCP 服务”，填写核心字段：
|
||
|
||
- `id`：必须以字母开头，仅允许字母/数字/`_`/`-`
|
||
- `transport`：`stdio` 或 `streamable_http`
|
||
- `enabled`：是否启用
|
||
- `timeout(s)`：调用超时
|
||
|
||
### 4.1 stdio 示例
|
||
|
||
- `transport`: `stdio`
|
||
- `command`: `python3`（或绝对路径）
|
||
- `args`: 每行一个参数（常见是服务脚本绝对路径）
|
||
- `cwd`: 可选
|
||
- `env`: 可选 JSON
|
||
|
||
示例：
|
||
|
||
```json
|
||
{
|
||
"id": "calc_stdio",
|
||
"name": "Calculator MCP",
|
||
"enabled": true,
|
||
"transport": "stdio",
|
||
"command": "python3",
|
||
"args": ["/abs/path/scripts/mcp_calculator_server.py"],
|
||
"timeout_seconds": 12
|
||
}
|
||
```
|
||
|
||
### 4.2 streamable_http 示例
|
||
|
||
```json
|
||
{
|
||
"id": "my_http_mcp",
|
||
"name": "My HTTP MCP",
|
||
"enabled": true,
|
||
"transport": "streamable_http",
|
||
"url": "http://127.0.0.1:8000/mcp",
|
||
"headers": {
|
||
"Authorization": "Bearer <token>"
|
||
},
|
||
"timeout_seconds": 25
|
||
}
|
||
```
|
||
|
||
### 4.3 可选过滤
|
||
|
||
- `include_tools`：仅放行这些工具名
|
||
- `exclude_tools`：屏蔽这些工具名
|
||
|
||
---
|
||
|
||
## 5. 第三步：同步工具缓存
|
||
|
||
保存后点击：
|
||
|
||
- “同步工具”（单服务）
|
||
- 或“同步全部工具”
|
||
|
||
同步成功后会写入缓存字段（页面可见）：
|
||
|
||
- `tools_cache_count`
|
||
- `tools_cache_updated_at`
|
||
- `last_error`
|
||
|
||
---
|
||
|
||
## 6. 第四步：在对话里验证是否接入成功
|
||
|
||
让模型先调用 `list_mcp_servers`（可 `refresh=true`），确认：
|
||
|
||
1. 目标服务在列表中
|
||
2. `tools_cache_names` 有你新工具
|
||
3. `tool_aliases` 已生成（通常是 `mcp__...`）
|
||
|
||
再让模型调用对应别名工具即可。
|
||
|
||
---
|
||
|
||
## 7. 环境变量（可选）
|
||
|
||
见 `.env.example`：
|
||
|
||
- `MCP_TOOLS_ENABLED=1`
|
||
- `MCP_SERVERS_FILE=./data/mcp_servers.json`
|
||
- `MCP_PROTOCOL_VERSION=2025-06-18`
|
||
- `MCP_DEFAULT_TIMEOUT_SECONDS=25`
|
||
|
||
默认配置文件是运行态文件：
|
||
|
||
- `/Users/jojo/Desktop/agents/正在修复中/agents/data/mcp_servers.json`
|
||
|
||
---
|
||
|
||
## 8. Docker 模式下的 stdio MCP（重要）
|
||
|
||
当前策略已收敛为：**MCP 仅在宿主机模式支持**。
|
||
|
||
当会话运行在 docker 模式时：
|
||
|
||
1. 调用 `list_mcp_servers` 会直接返回：`当前为docker模式，MCP仅支持宿主机模式`。
|
||
2. 调用任意 `mcp__...` 工具别名也会返回同样提示。
|
||
3. 不再在 docker 模式执行 MCP 服务同步与调用。
|
||
|
||
如果需要使用 MCP，请先切换到宿主机模式后再进行配置/调用。
|
||
|
||
---
|
||
|
||
## 9. 常见问题排查
|
||
|
||
1. **服务保存失败**
|
||
- 检查 `id` 格式、transport 必填项（stdio 要 `command`，HTTP 要 `url`）
|
||
|
||
2. **同步失败 / 无工具**
|
||
- 看 `last_error`
|
||
- 检查服务是否能独立启动
|
||
- 检查 `include_tools/exclude_tools`
|
||
|
||
3. **工具在页面有，但模型看不到**
|
||
- 确认服务 `enabled=true`
|
||
- 确认管理策略没禁用 MCP 分类
|
||
- 重新“同步工具”后再试
|
||
|
||
4. **调用时报超时**
|
||
- 提高 `timeout_seconds`
|
||
- 优化 MCP Server 响应速度
|
||
|
||
---
|
||
|
||
## 10. 关键代码位置（便于二次开发）
|
||
|
||
- MCP 配置：`/Users/jojo/Desktop/agents/正在修复中/agents/config/mcp.py`
|
||
- 服务注册表：`/Users/jojo/Desktop/agents/正在修复中/agents/modules/mcp_server_registry.py`
|
||
- MCP 客户端桥接：`/Users/jojo/Desktop/agents/正在修复中/agents/modules/mcp_client_manager.py`
|
||
- 管理 API：`/Users/jojo/Desktop/agents/正在修复中/agents/server/admin.py`
|
||
- 工具定义/执行：
|
||
- `/Users/jojo/Desktop/agents/正在修复中/agents/core/main_terminal_parts/tools_definition.py`
|
||
- `/Users/jojo/Desktop/agents/正在修复中/agents/core/main_terminal_parts/tools_execution.py`
|
||
- 管理端页面：`/Users/jojo/Desktop/agents/正在修复中/agents/static/src/admin/PolicyApp.vue`
|
||
- 测试示例服务：`/Users/jojo/Desktop/agents/正在修复中/agents/scripts/mcp_calculator_server.py`
|