docs: 更新MCP服务器管理等相关文档

docs/latest/advanced/agents-config.md

@@ -106,117 +106,108 @@ async def get_graph(self):
 
 系统会根据配置自动组装工具集合，涵盖知识图谱查询、向量检索生成的动态工具、MySQL 只读查询能力、Tavily 搜索以及所有注册的 MCP 工具。
 
-工具的启用状态和描述由配置文件或环境变量决定，当依赖缺失时会被中间件自动忽略，从而避免在图中加载不可用能力。MCP Server 的接入方式保持不变，只需在 `src/services/mcp_service.py` 的 `MCP_SERVERS` 中填入服务地址与 `transport` 类型，如需更多范式可参阅 LangChain 官方文档。
+MCP (Model Context Protocol) 服务的配置现已全面支持通过系统管理界面或 API 进行动态管理，数据持久化存储在数据库中。`src/services/mcp_service.py` 仅作为核心逻辑层和默认配置的存放处，不再建议直接修改代码来添加服务器。
 
-### MCP 服务器配置方式
+### MCP 服务器管理
 
-系统支持四种 MCP 服务器配置方式，可根据具体场景选择：
+系统提供了完善的 API (`/system/mcp-servers`) 和管理界面来执行 MCP 服务器的增删改查操作。
 
-#### 1. 远程 HTTP 服务器
+#### 支持的传输协议
 
-```python
+系统支持三种 MCP 传输协议：
-MCP_SERVERS = {
+
-    "sequentialthinking": {
+1.  **SSE (Server-Sent Events)**: 标准的 HTTP SSE 连接
-        "url": "https://remote.mcpservers.org/sequentialthinking/mcp",
+2.  **Streamable HTTP**: 支持流式传输的 HTTP 连接（远程）
-        "transport": "streamable_http",
+3.  **Stdio**: 通过标准输入/输出运行本地进程（支持 Python/Node.js 等）
-    }
+
-}
+#### 配置示例
-```
+
+以下是通过管理界面添加 MCP 服务器时的常见配置参数示例（对应 API 请求体）：
+
+##### 1. 远程 HTTP/SSE 服务器
+
+*   **Server Name**: `sequentialthinking`
+*   **Transport**: `streamable_http` (或 `sse`)
+*   **URL**: `https://remote.mcpservers.org/sequentialthinking/mcp`
 
 **特点**：
-- 通过 HTTP 远程访问，无需本地安装，适合公开可用的 MCP 服务
+- 无需本地安装，适合公开可用的 MCP 服务
 - 启动速度快，无需本地依赖
 
-#### 2. 使用 npx 运行 Node.js 包
+##### 2. 使用 npx 运行 Node.js 包
 
-```python
+*   **Server Name**: `mcp-server-chart`
-MCP_SERVERS = {
+*   **Transport**: `stdio`
-    "mcp-server-chart": {
+*   **Command**: `npx`
-        "command": "npx",
+*   **Args**: `["-y", "@antv/mcp-server-chart"]`
-        "args": ["-y", "@antv/mcp-server-chart"],
-        "transport": "stdio"
-    },
-}
-```
 
 **特点**：
-- 使用 npx 直接运行 Node.js 包，`-y` 参数自动下载并运行指定包
+- 自动下载并运行 Node.js 包
-- 适合 Node.js 生态的 MCP 服务，需要确保 npx 可以使用
+- 适合 Node.js 生态的 MCP 服务
 
-#### 3. 使用 uvx 运行 Python 包
+##### 3. 使用 uvx 运行 Python 包
 
-```python
+*   **Server Name**: `mysql-mcp-server`
-MCP_SERVERS = {
+*   **Transport**: `stdio`
-    "mysql-mcp-server": {
+*   **Command**: `uvx`
-        "command": "uvx",
+*   **Args**: `["mysql_mcp_server"]`
-        "args": ["mysql_mcp_server"],
+*   **Environment Variables**:
-        "env": {
+    ```json
-            "MYSQL_DATABASE": "your_database",
+    {
-            "MYSQL_HOST": "localhost",
+        "MYSQL_DATABASE": "your_database",
-            "MYSQL_PASSWORD": "your_password",
+        "MYSQL_HOST": "localhost",
-            "MYSQL_PORT": "3306",
+        "MYSQL_PASSWORD": "your_password",
-            "MYSQL_USER": "your_username"
+        "MYSQL_PORT": "3306",
-        },
+        "MYSQL_USER": "your_username"
-        "transport": "stdio"
     }
-}
+    ```
-```
 
 **特点**：
-- 使用 uvx 运行已发布的 Python 包，自动管理虚拟环境和依赖
+- 自动管理 Python 虚拟环境和依赖
 - 适合 PyPI 上已发布的 MCP 服务
 
-#### 4. 使用 uv 运行本地仓库
+##### 4. 使用 uv 运行本地仓库
 
-```python
+*   **Server Name**: `arxiv-mcp-server`
-MCP_SERVERS = {
+*   **Transport**: `stdio`
-    "arxiv-mcp-server": {
+*   **Command**: `uv`
-        "command": "uv",
+*   **Args**:
-        "args": [
+    ```json
-            "tool",
+    [
-            "run",
+        "tool",
-            "arxiv-mcp-server",
+        "run",
-            "--storage-path", "src/agents/mcp_repos/arxiv-mcp-server"
+        "arxiv-mcp-server",
-        ],
+        "--storage-path", "src/agents/mcp_repos/arxiv-mcp-server"
-        "transport": "stdio"
+    ]
-    }
+    ```
-}
-```
 
 **特点**：
 - 直接运行本地 git 仓库中的 MCP 服务
-- 加载速度快，支持热重载，适合开发调试和自定义 MCP 服务
+- 支持热重载，适合开发调试
-- 需要先 git clone 对应仓库到指定路径
 
-### 配置参数说明
+### 动态工具加载与管理
-
-- `url`: 远程 HTTP 服务器的 URL（仅 streamable_http 传输）
-- `command`: 启动 MCP 服务的命令
-- `args`: 启动参数列表
-- `env`: 环境变量配置，用于数据库连接等敏感信息
-- `transport`: 传输协议，支持 `stdio`（本地）和 `streamable_http`（远程）
-
-### 动态工具加载
 
 系统提供统一的 MCP 服务层 (`src/services/mcp_service.py`) 封装所有 MCP 相关操作。
 
-#### 智能体获取工具（自动过滤禁用工具）
+#### 1. 智能体获取工具
 
-智能体应使用 `get_enabled_mcp_tools()` 获取工具，该函数会自动过滤 `disabled_tools` 中的工具：
+智能体开发时，应使用 `get_enabled_mcp_tools()` 获取工具。该函数会自动根据数据库中的配置，过滤掉被禁用的工具。
 
 ```python
-from src.services.mcp_service import get_enabled_mcp_tools, add_mcp_server
+from src.services.mcp_service import get_enabled_mcp_tools
 
-# 获取指定服务器的工具（自动过滤 disabled_tools）
+# 获取指定服务器的工具（自动过滤掉在管理界面禁用的工具）
 tools = await get_enabled_mcp_tools("sequentialthinking")
-
-# 动态添加新的 MCP 服务器
-add_mcp_server("custom-server", {
-    "url": "https://your-mcp-server.com/mcp",
-    "transport": "streamable_http"
-})
 ```
 
+#### 2. 工具粒度控制
+
+通过管理界面或 API (`PUT /system/mcp-servers/{name}/tools/{tool_name}/toggle`)，管理员可以启用或禁用特定的 MCP 工具。禁用后的工具不会出现在 `get_enabled_mcp_tools` 的返回列表中，从而防止智能体调用不需要的能力。
+
+#### 3. 默认服务器配置
+
+系统首次启动时，会加载 `src/services/mcp_service.py` 中 `_DEFAULT_MCP_SERVERS` 定义的默认服务器（如 `sequentialthinking` 和 `mcp-server-chart`）到数据库中。后续的修改将以数据库为准。
+
 ### MySQL 数据库
 
 在 数据库报表助手（SqlReporterAgent） 中，可以通过配置下面环境变量，让 Agent 能够连接到 MySQL 数据库。并通过执行 SQL 查询，获取数据库中的数据。