MCP 集成指南

Doforu 支持 Model Context Protocol (MCP)，让你可以将外部工具和服务无缝接入本地 AI 编程助手。通过 MCP，Agent 可以调用外部能力，如数据库查询、网页搜索和浏览器自动化等。

什么是 MCP

MCP 是一个开放协议，标准化了 AI 助手与外部工具之间的通信。任何实现了 MCP 的服务器都可以被 Doforu 发现和使用，而你的敏感数据和凭证始终保留在本地。

配置文件

MCP 通过 mcp.json 进行配置：

{
  "mcpServers": {
    "time": {
      "transport": "stdio",
      "command": "node",
      "args": ["./mcp-servers/time-server/index.js"]
    },
    "similarweb": {
      "transport": "stdio",
      "command": "node",
      "args": ["mcp-servers/similarweb-server.js"],
      "env": {
        "API_KEY": "your-api-key"
      },
      "disabled": false,
      "timeout": 5000
    }
  }
}

字段说明

字段	类型	描述
`transport`	`string`	通信类型：`stdio`、`http` 或 `sse`
`command`	`string`	仅 stdio，可执行命令
`args`	`string[]`	仅 stdio，命令参数
`env`	`object`	仅 stdio，环境变量
`cwd`	`string`	stdio 可选，工作目录
`url`	`string`	仅 http/sse，服务器 URL
`headers`	`object`	仅 http/sse，自定义请求头
`disabled`	`boolean`	是否禁用该服务器（默认 `false`）
`timeout`	`number`	连接和调用超时时间（毫秒，默认 `30000`）

配置文件查找位置

Doforu 按以下优先级查找 mcp.json（首个存在的文件胜出）：

CLI 参数：--mcp-config /path/to/mcp.json
环境变量：MCP_CONFIG_PATH=/path/to/mcp.json
用户配置：~/.doforu/mcp.json（推荐桌面应用用户使用）
项目配置：当前工作目录下的 mcp.json

提示：桌面用户应将 mcp.json 放在 ~/.doforu/mcp.json，这样就不会被项目代码意外覆盖。

多客户端兼容

除了自身的配置文件，Doforu 还可以检测并导入其他主流 MCP 客户端的设置：

客户端	配置文件路径
Cursor（项目）	`.cursor/mcp.json`
Cursor（全局）	`~/.cursor/mcp.json`
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`（macOS） `%APPDATA%\Claude\claude_desktop_config.json`（Windows）

在设置页面，你可以一键切换配置来源，并从 Cursor 或 Claude Desktop 导入 MCP 服务器到 Doforu。

环境变量插值

mcp.json 支持 ${ENV_VAR} 语法来引用环境变量：

{
  "mcpServers": {
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

特殊变量 ${HOME} 和 ${USERPROFILE} 会自动映射到当前用户的主目录，实现跨平台兼容。

stdio 路径解析

对于 stdio 服务器，Doforu 会自动解析 args 中的路径：

绝对路径：标准化后直接使用
相对路径：相对于 backend 目录进行解析（在 Electron 中运行时，使用 BACKEND_DIR 环境变量）
如果解析后的路径不存在，则原值保持不变

禁用与启用服务器

你可以通过设置 disabled: true 临时禁用某个 MCP 服务器，而无需删除其配置：

{
  "mcpServers": {
    "experimental-server": {
      "transport": "stdio",
      "command": "node",
      "args": ["./experimental.js"],
      "disabled": true
    }
  }
}

被禁用的服务器会在启动时跳过，不消耗任何资源。

重新加载 MCP 配置

修改 mcp.json 后，可通过以下方式应用更改：

设置页面：设置 → MCP → 保存配置会自动触发重新加载
API 端点：POST /api/mcp/reload

重新加载过程中，Doforu 将：

关闭现有的 MCP 连接
读取最新的配置
重新连接所有已启用的服务器
获取可用工具列表并注册到 Agent

故障排除

如果某个 MCP 服务器连接失败，检查日志以了解具体原因：

ENOENT / not found：命令或脚本路径不存在
timeout / ETIMEDOUT：连接超时，尝试增加 timeout 值
其他错误：在 Doforu 日志中查找来自 MCP 模块的 connect_failed 事件

连接失败的服务器会被跳过，不会影响其他服务器或 Agent 的正常运行。