【WorkBuddy · 三件套：技能/专家/技能】第 17 章 · 配置 MCP 服务器

【WorkBuddy · 三件套：技能/专家/技能】第 17 章 · 配置 MCP 服务器

---

技能和专家都是"WorkBuddy 自己的事"。但你电脑里 99% 的工具是"别人写的"------比如 Playwright、Notion、Figma。这一章只要改一个 JSON 文件，就能把这些工具变成 WorkBuddy 随时可调用的能力。

一、学习目标

读完本章并跟做完课后任务，你将能够：

• 说出 MCP 是什么、为什么需要
• 修改 ~/.workbuddy/mcp.json 加一个新服务器
• 用 Playwright MCP 做一次真实的网页抓取
• 自己排查找不到 npx、端口冲突等常见报错

预计耗时：40 分钟。

---

二、前置准备

• 已经完成第 14 章，电脑里有 fortune-teller/
• 已经装好 Node.js（任意 LTS 版本都行）
• 能正常访问 npm 镜像
• 工作空间能联网

小白提示：检查 Node 是否装好，打开终端输入 node --version，能打印版本号就行。如果提示"找不到命令"，请先去 nodejs.org 装一个 LTS。

---

三、什么是 MCP------一张图说清

MCP（Model Context Protocol）是 WorkBuddy 跟外部工具之间的"对话协议"。一个 MCP 服务器就是一个"小进程"，跑在你电脑上某个端口，WorkBuddy 跟它说话，它去操作真正的工具。

WorkBuddy  ⇄  [MCP 协议]  ⇄  MCP 服务器进程  ⇄  真实工具
                                            （如 Playwright）

你不用懂协议。你只需要：

WorkBuddy → MCP 协议 → MCP Server → 真实工具。3 个核心组件分工明确。

1. 在 ~/.workbuddy/mcp.json 里写一个配置
2. WorkBuddy 自动启动那个进程
3. 在对话里用

---

四、操作步骤

我们分 7 步走。本章以 Playwright MCP 为案例（官方文档最完整，调试最方便）。

步骤 1：打开 mcp.json 文件

文件位置：~/.workbuddy/mcp.json

• Windows：C:\Users\你的用户名\.workbuddy\mcp.json
• macOS/Linux：~/.workbuddy/mcp.json

如果文件不存在，新建它。初始内容长这样：

{
  "mcpServers": {}
}

图 17-1：当前的 mcp.json

---

步骤 2：找官方配置

浏览器打开 Playwright MCP 的官方文档（搜索 "Playwright MCP server"）。

https://github.com/microsoft/playwright-mcp

官方给的 npx 配置是：

{
  "command": "npx",
  "args": [ "@playwright/mcp@latest"]
}

把这段抄下来。

图 17-2：官方文档截图

（这是官方推荐的零配置启动方式）

小贴士：每个 MCP 服务器的官方文档都会给出 command 和 args，抄过来就行。不要凭想象写------参数错了就启动失败。

---

步骤 3：把配置写进 mcp.json

编辑 mcp.json，把内容替换为：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

保存。

图 17-3：写好的 mcp.json

（键名"playwright"就是以后对话里叫它的方式，别拼错）

如果不行，配置改为如下试试：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ],
      "disabled": false
    }
  }
}

---

步骤 4：让 WorkBuddy 重新加载

回到 WorkBuddy 对话窗口输入：

重新加载 mcp 配置

WorkBuddy 会尝试启动 playwright 进程。第一次启动会下载 Playwright 浏览器内核，可能需要 1~3 分钟。

终端会打印：

[playwright] Installing Playwright browsers...
[playwright] Done in 167s.
[playwright] Listening on stdio

图 17-4：MCP 启动过程

---

步骤 5：第一次调用

加载成功后输入：

用 playwright 打开 https://example.com，告诉我页面上有什么

WorkBuddy 会自动通过 MCP 调 Playwright，去访问页面，把页面内容拉回来。

预期回复：

页面标题：Example Domain

页面包含：一个 H1 "Example Domain"，一段说明文字"This domain is for use in illustrative examples..."，以及一个跳转到 iana.org 的链接。

图 17-5：调用成功截图

🎉 Playwright MCP 接入成功。

---

步骤 6：跑个真实任务

试试抓一个更具体的网站：

用 playwright 打开 https://news.ycombinator.com，把首页前 5 条新闻标题给我

预期结果：列 5 条标题。

图 17-6：实战任务截图

（这就是你 1 句话抓到的实时数据）

---

步骤 7：常见报错速查

下面 4 个是新手最常踩的：

报错	原因	修法
command not found: npx	Node 没装或没在 PATH	装 Node，确认 npx --version 能跑
EACCES permission denied	npm 全局目录没权限	sudo chown -R $USER /usr/local/lib/node_modules（Mac/Linux）
EADDRINUSE 端口占用	MCP 进程端口被占了	关掉占端口的进程，或换一个端口
Failed to fetch 但配置没错	网络问题或代理	终端里手动跑一次 npx -y @playwright/mcp@latest，看真实报错

---

五、小贴士

1. 改完 mcp.json 必须重启 WorkBuddy（或至少让它"重新加载 mcp"）。配置文件改了不重启等于白改。
2. 第一次启动慢很正常。Playwright 要下载浏览器内核（~150MB），后面调用就快了。
3. 多个 MCP 可以同时存在 。在 mcpServers 里再加一个键就行，例如同时配 playwright 和 notion。
4. 凭据不要写在 mcp.json 里 。如果某个 MCP 需要 API key，存到环境变量，在 args 里引用 ${ENV_VAR}。
5. 找不到 MCP 的官方文档怎么办？优先看 GitHub README；次优看工具官网"Integrations"页；都不行就在 WorkBuddy 对话里问"我要接 X，有没有现成 MCP"。

---

六、课后任务

任务难度：★★★☆☆

任务 ：在 mcp.json 里再加一个 MCP 服务器，自己挑一个（比如 filesystem / github / notion）。

参考检查清单：

• 找到官方给的 command 和 args
• 写进 mcp.json
• 让 WorkBuddy 重新加载
• 跑通一次真实调用
• 把调用截图存档

完成后你就有了一个"小工具百宝箱"------以后任何有官方 MCP 的工具，30 秒接入。

---

七、本章小结

你做了	你学到了
打开 mcp.json	配置文件就一处，所有 MCP 都加这里
抄官方配置	command + args 是 MCP 的"启动口令"
重新加载 MCP	改完必须重启/重载
跑通 Playwright	网页抓取不用写代码
排 4 类常见错	npx 找不到 / 权限 / 端口 / 网络

至此"造工具篇"的 4 章技能/专家/MCP 都跑通了。下一章（第 18 章）我们把这一篇收尾------怎么把自己的成果打包、上架、分享给别的用户用。

---

八、读者问答 Q&A（10 个真实问题）

Q1：MCP 服务器和 HTTP API 有什么区别？

MCP 是长期运行进程 ，HTTP API 是请求-响应模式。

MCP：WorkBuddy 启动一个 python xxx.py 进程，进程在后台跑，每次调用就发条消息过去。

HTTP：每次调用要新建 TCP 连接，断开。

简单判断：需要"持续状态"（如浏览器 session、长轮询、订阅）→ 用 MCP；只需要"一次性查询"→ 用 HTTP。

Q2：装 MCP 时被杀毒软件拦了怎么办？

正常。WorkBuddy 启动 MCP 时是 node / python 子进程，杀软会审计。两种处理：

1. 把 node 和 python 加入杀软白名单
2. 用 --no-sandbox 启动参数（一般 MCP 工具会自动加）

Q3：MCP 服务会自己更新吗？

默认不会 。MCP 启动时下载当前版本，除非你用 @latest 标签。建议锁定具体版本号（如 @1.2.0），避免更新造成不兼容。

Q4：能同时装多个 MCP 吗？

可以，端口不能冲突。mcp.json 里每个 MCP 都默认用 stdio（标准输入输出）通信，不占端口------这是 MCP 的妙处。如果你用的是 SSE 模式（HTTP 风格），端口必须不同。

Q5：MCP 服务慢怎么排查？

按 3 步排查：

1. 资源 ：CPU、内存够不够？top 看
2. 网络：MCP 工具访问外网慢 → 配代理；MCP 互相调用慢 → 减少嵌套
3. 日志 ：开 DEBUG=mcp:* 看具体哪步慢

Q6：怎么卸载 MCP？

从 ~/.workbuddy/mcp.json 删除对应条目，不需要单独卸载命令。WorkBuddy 重新加载时自动停掉。

Q7：MCP 服务里能放公司密码吗？

不建议。MCP 配置文件是明文 JSON，任何人读了你的 home 目录都能看到 password。应该用环境变量：

"env": { "API_KEY": "${MY_API_KEY}" }

WorkBuddy 启动时从环境变量读取。

Q8：MCP 能和现有 Python 项目集成吗？

可以。你的脚本只要能"被外部调用"------用 stdin/stdout 收发 JSON 消息，就符合 MCP 协议。完整协议看 MCP 官方文档。

Q9：MCP 服务挂了怎么重启？

WorkBuddy 自动检测进程死亡，会重启 3 次。如果 3 次都失败，会把对应 MCP 标灰。你可以手动 mcp-restart 命令恢复。

Q10：MCP 和技能/专家能组合用吗？

可以。比如"用 Playwright MCP 抓网页 + 用 csv-to-md 技能转表格 + 让评审专家给反馈"------这就是第 19 章综合实战的工作流。MCP 不抢技能/专家的角色，各管各的。

---

九、三个常见误区

误区 1：装 MCP = 装功能

有人以为"装上 GitHub MCP 就自动能用所有 GitHub 功能"。错------MCP 只是"接通了通信渠道"，具体能做什么要看 MCP 工具支持的"动作"（tools）。一个 MCP 通常提供 5~30 个 tool，但不一定覆盖你需要的全部------很多高级功能还得自己写。

误区 2：MCP 越多越好

不是。MCP 多会让 WorkBuddy 启动慢、占内存。单个对话只需要 2~3 个 MCP------多了互相干扰，工具选择困难。如果你有 10 个 MCP 需求，考虑用"按需加载"------用哪个开哪个。

误区 3：以为 MCP 是 WorkBuddy 独家的

不是。MCP 是开放协议，任何 AI Agent 都可以用。WorkBuddy、Claude Desktop、Cursor 等都支持。MCP 生态的繁荣意味着你写的 MCP 可以"一处写、处处跑"。

---

十、3 类开发者接 MCP 的不同方式

场景 1：前端工程师

小王做 React 项目，需要"截图 + 控制台错误抓取"。

他接：

• Playwright MCP：浏览器自动化
• Console MCP：浏览器控制台日志聚合

跑通后，他可以让 WorkBuddy"打开页面 → 等加载 → 截图 → 看报错 → 给出修复建议"------这是他以前要 30 分钟手动操作才能完成的事。

场景 2：后端工程师

小李做 API 开发，需要"用 curl 测接口 + 用 SQL 查 DB"。

他接：

• HTTP MCP：发送 HTTP 请求
• SQLite MCP：查询数据库
• Files MCP：读配置文件

跑通后，他可以"调这个接口 → 看 SQL 行为 → 看返回头 → 看缓存命中"------完整调试链路一句话触发。

场景 3：数据分析师

小张做 BI 工作，需要"读数据库 + 生成图表"。

他接：

• PostgreSQL MCP：连数据仓库
• QuickChart MCP：自动生成图表

跑通后，他可以"拉上周订单数据 → 生成日活趋势图 → 输出 PNG 文件"------以前 1 小时，现在 30 秒。

共同点：让 AI Agent 能直接操作工具，而不是只能"聊工具"。

---

十一、踩坑实录：node 版本不兼容事故

场景：小王按官方文档装了 Playwright MCP，但启动报错。

过程：

1. 安装：npm install -g @playwright/mcp
2. 配 mcp.json：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

3. 重新加载 MCP
4. WorkBuddy 报：Error: Cannot find module '@playwright/mcp'
5. 手动运行 npx -y @playwright/mcp 也报错

根因排查：

• 小王机器上有 2 个 node：一个是系统 node 16，一个是 WorkBuddy 自带的 node 22
• npx 默认用 PATH 里靠前的 node 16，但 @playwright/mcp 需要 node 18+
• → 找不到模块

修复：

1. 用绝对路径指定 node："command": "/c/Users/.../node.exe"
2. 或升级系统 node 到 18+
3. 或在 mcp.json 里 env.NODE_PATH 指向正确的 node_modules

教训 ：

多版本 node 是 MCP 配置的最大坑。WorkBuddy 自带 node，但 npx 用的是 PATH 里的 node------两者可能不一致。

预防：

• mcp.json 里永远用绝对路径指定 command（npx、python、node 都一样）
• 把 WorkBuddy 自带的 node 加到 PATH 最前面
• 配完跑一次 npx --version 和 node --version，确认是同一个

---

十二、延伸阅读：stdio vs SSE 模式

MCP 有两种通信模式：

stdio（标准输入输出）：

• MCP 进程和 WorkBuddy 父子关系
• 通信走 stdin/stdout
• 适合本地工具（浏览器、本地文件、本地服务）
• 优点：简单、快、安全
• 缺点：不能跨机器

SSE（Server-Sent Events）：

• MCP 跑成独立服务，监听端口
• 通信走 HTTP
• 适合远程服务（公司内网工具、托管服务）
• 优点：可远程、可横向扩展
• 缺点：要管端口、要处理鉴权

怎么选：默认 stdio。需要"远程访问"、"团队共享 MCP"、"跟某个 SaaS 集成"------用 SSE。

mcp.json 配置示例（SSE）：

{
  "mcpServers": {
    "remote-mcp": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

官方资源：

• MCP 协议规范
• Playwright MCP GitHub
• Awesome MCP Servers

---

十三、课后任务参考答案详解

任务：给你的 WorkBuddy 加一个 files MCP。

评分要点（12 分制）：

评分项	分值	满分示范
1. mcp.json 加正确条目	3 分	command + args 匹配官方文档
2. 重新加载生效	3 分	WorkBuddy 列出 files MCP 的 tools
3. 至少成功调用 1 次	4 分	"读 xxx.txt"返回文件内容
4. 错误回退路径清晰	2 分	失败时报错信息友好

常见扣分：

• command 是相对路径（依赖 PATH，跨机器不能用，-2 分）
• 没重启 MCP（-3 分）
• 调了不存在的 tool 名（-3 分）

高阶加分：

• 配 env.ALLOWED_DIRS 限制访问目录（+2 分）
• 配 timeout（+1 分）
• 加注释说明每个 MCP 的用途（+1 分）

完整参考配置：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"],
      "timeout": 30000
    }
  }
}

---

十四、本章成本与 ROI

学习成本：30~45 分钟

• 看官方文档挑 MCP：10 分钟
• 配 mcp.json：10 分钟
• 调试常见错：10~25 分钟

长期价值：

• 你掌握"JSON 配置文件"这个核心机制------WorkBuddy 所有配置（技能、专家、连接器）都类似
• 你能接"任何外部工具"------这是 WorkBuddy 最强大的能力
• 你的"插件式开发"思维成熟------以后任何 SaaS 工具你都能"接进来"

ROI 估算 ：

假设你日常工作中"截图给文档"、"读配置文件"、"调接口"每月各 50 次：

• 每次省 5 分钟
• 每月省 750 分钟 ≈ 12.5 小时
• 一年 150 小时 ≈ 18.75 天

这 18.75 天几乎是零成本获得------只需要一份 mcp.json。

---

十五、本章小结（扩充版）

核心收获：

• 理解 MCP = 让 AI Agent 能直接操作工具的协议
• 掌握"改一个 JSON 文件"接入任意工具的能力
• 排错能力（MCP 大部分问题都是版本/路径/网络）

你可以接着做的：

• 浏览 https://github.com/punkpeye/awesome-mcp 找适合你的 MCP
• 把公司内部工具接成 MCP，团队共享
• 写自己的 MCP 服务器（高级，第 19 章实战篇会演示）

至此"造工具篇"的 4 章技能/专家/MCP 都跑通了。下一章（第 18 章）我们把这一篇收尾------怎么把自己的成果打包、上架、分享给别的用户用。

一句话总结：技能做"事"，专家当"人"，MCP 接"外部"。三个加在一起，你就能让 WorkBuddy 变成一个真正属于你自己的助理。