WorkBuddy 接入外部 MCP 完整图文避坑指南

为什么需要 MCP？

在日常使用中，WorkBuddy 原生具备代码阅读、文件修改和终端执行能力。但当你需要直接连通外部生产力系统（例如本地 SQLite 数据库、GitHub 代码仓库、甚至自动化驱动真实 Chromium 浏览器）时，Model Context Protocol (MCP) 就是最核心的连接桥梁。

flowchart LR
    User[用户任务需求] --> WB[WorkBuddy 桌面端 / Agent]
    subgraph MCPClient[MCP 客户端通信层]
        WB --> Runtime[WorkBuddy MCP Runtime]
    end
    subgraph MCPServers[外部服务能力扩展]
        Runtime -->|STDIO / HTTP| S1[SQLite 数据库服务]
        Runtime -->|API 鉴权| S2[GitHub 服务]
        Runtime -->|DevTools 协议| S3[Playwright 浏览器自动化]
    end

---

核心配置：mcp.json 实战模板

WorkBuddy 会在项目或全局配置目录查找 mcp.json（注意：文件名必须是 mcp.json，而不是 .mcp.json）。

以下是实测 100% 跑通的高频三合一配置模板：

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "./data/database.sqlite"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

---

完整接入四步走

阶段	关键动作	核心检查点
Step 1: 依赖准备	确保本地安装 uv（Python）或 node/npx（Node.js）	终端运行 uvx --version 或 npx -v 验证正常
Step 2: 配置文件放置	放置在当前工作区根目录下的 mcp.json	检查 JSON 语法，尾部绝不能有多余逗号
Step 3: 授权与信任	进入 WorkBuddy「连接器 / 扩展管理」面板	必须显式点击「信任 (Trust)」，否则进程不启动
Step 4: 运行时探测	对 WorkBuddy 发送测试指令探测工具是否注入	输入：请列出当前可用的 MCP 工具清单

---

4 大高频断连排查手册 (Troubleshooting)

flowchart TD
    Err[MCP 显示 Not connected / 连不上] --> C1{检查文件名}
    C1 -->|是 .mcp.json| F1[重命名为 mcp.json]
    C1 -->|是 mcp.json| C2{检查连接器面板}
    C2 -->|未授权| F2[点击「信任」以激活插件]
    C2 -->|已授权| C3{检查命令与全局路径}
    C3 -->|npx / uvx 找不到| F3[配置命令绝对路径或配置系统 PATH]
    C3 -->|正常| C4[查看 WorkBuddy 控制台日志排查报错]

1. 状态常驻 “Not connected”

• 根因：写完 mcp.json 后，未在可视化面板点击「信任」。WorkBuddy 出于安全隔离，不会静默执行第三方二进制脚本。
• 解法：在侧边栏或插件设置中找到对应 Server，点击 Enable / Trust。

2. 沙箱网络拦截与 Token 超时

• 根因：境外 API（如 GitHub / Cloudflare）在部分受限网络环境中握手失败。
• 解法：为终端配置稳定代理，或在 env 显式传入 HTTP_PROXY 与 HTTPS_PROXY。

3. node_modules 与 npx 缓存锁死

• 解法：加 -y 参数强制确认下载，例如 npx -y @modelcontextprotocol/...，避免在后台等待交互确认导致挂起。

4. 浏览器自动化方案替代建议

• 经验之谈：某些 MCP 版 Puppeteer 稳定度一般。若需要高并发或长周期网页爬取，建议直接让 WorkBuddy 编写本地原生 Playwright 脚本（绑定本机已有的 Chromium 路径），执行效率更高。