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

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}

【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 个核心组件分工明确。

四、操作步骤

我们分 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 个是新手最常踩的：

五、小贴士

六、课后任务

任务难度：★★★☆☆

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

参考检查清单：

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

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

七、本章小结

至此"造工具篇"的 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 子进程，杀软会审计。两种处理：

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

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

Q4：能同时装多个 MCP 吗？

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

Q5：MCP 服务慢怎么排查？

按 3 步排查：

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，但启动报错。

过程：

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

根因排查：

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

修复：

教训： 多版本 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 分制）：

常见扣分：

• 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 变成一个真正属于你自己的助理。