MCP 使用指南(基于 CodeBuddy 实战)

本文档以我在 CodeBuddy 中的真实使用案例为主线,说明 MCP(Model Context Protocol)的概念、配置与使用方法,并补充五个常用 MCP Server 的用法。

参考:Awesome-MCP-ZH / MCP 官网


一、MCP 是什么

MCP(Model Context Protocol,模型上下文协议)是 Anthropic 于 2024 年 11 月推出的开放协议,被称为 AI 应用的 "USB-C 接口"——让大模型以统一方式连接外部工具、数据与系统。

核心角色:

角色 说明
MCP Server(服务器) 提供工具能力的进程,如 chrome-devtools-mcp、context7-mcp
MCP Client(客户端) 承载大模型的宿主,如 CodeBuddy、Claude Desktop、Cursor
Tools(工具) Server 暴露给 Client 的具体能力,如 query-docs、take_screenshot

一句话理解:你在 CodeBuddy 对话框说"查 Python 文档",CodeBuddy 背后的模型会自动调用 MCP Server 暴露的工具去完成任务,你无需关心中间的协议交互。


二、我的真实案例:用 Context7 查 Python asyncio 文档

2.1 背景

我在 CodeBuddy 中配置了 context7 MCP Server。配置方式是在用户级 MCP 配置文件 C:\Users\Administrator\.codebuddy\mcp.json 中添加:

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

配置完成后,CodeBuddy 的 MCP 面板显示 context7 已连接,暴露 2 个工具:

  • resolve-library-id —— 把库名解析成 Context7 兼容的库 ID
  • query-docs —— 用库 ID 查询具体文档内容

2.2 使用过程(两步走)

第一步:我在对话框输入了一句话

用 context7 查 Python3 asyncio 的怎么用

第二步:CodeBuddy 自动执行了两步工具调用

Step 1 — resolve-library-id 解析库 ID:

{
  "libraryName": "Python 3",
  "query": "Python 3 standard library and language documentation"
}

返回了 5 个候选库(含代码片段数量与质量评分):

候选 库 ID 代码片段数 评分
Python 3.14.0 /websites/python_3_14 39269 82.56
Python 3.13.7 /websites/python_3_13 22422 81.77
Python 3.12 /websites/python_3_12 39452 59.23
Python 3.11 /websites/python_3_11 23679 67.05
Python 标准库 /websites/python_3_library 17183 81.63

模型自动选择了评分最高、片段最丰富的 /websites/python_3_14。

Step 2 — query-docs 查询具体主题:

{
  "libraryId": "/websites/python_3_14",
  "query": "asyncio tutorial: async await syntax, define coroutine, create_task, event loop basics"
}

返回了 Python 3.14 官方文档中关于 asyncio 的完整示例(asyncio.run、asyncio.create_task、await 心智模型等)。

第三步:CodeBuddy 基于文档给出总结回答

模型将原始文档整理成"核心三件套 + 关键心智模型 + API 速查表"的回答,直接呈现给我。

2.3 案例总结:MCP 使用流程

用户一句话需求
      ↓
CodeBuddy(MCP Client)理解意图
      ↓
自动选择工具 → resolve-library-id → 得到库 ID
      ↓
自动调用工具 → query-docs → 得到文档
      ↓
整合文档 → 回答用户

关键点:

  1. 用户无需手动调用工具,说人话即可("查 xxx 文档")
  2. 模型自动做多步决策:选哪个候选库、查什么关键词、如何整合
  3. 文档始终最新:Context7 拉取的是官方实时文档,解决了模型训练数据过时的问题

三、五个常用 MCP Server 详解

3.1 Context7 MCP —— 文档查询(上文案例)

项目 说明
用途 为 LLM 提供最新版本的库文档与代码示例,解决依赖文档过时问题
维护方 Upstash
地址 https://github.com/upstash/context7

配置:

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

典型使用场景:

  • "查一下 vant 的 Toast 组件用法"
  • "Next.js 14 的 middleware 怎么写"
  • "React useEffect cleanup 的示例代码"

使用技巧:

  • 查询要具体、单一主题(好:"JWT auth in Express";坏:"auth"、"routing and auth and caching")
  • 直接给 /org/project 格式 ID 可跳过解析步骤
  • 需要特定版本时明确说明(如"查 Python 3.12 的 pathlib")

3.2 Chrome DevTools MCP —— 浏览器调试与性能分析

项目 说明
用途 让 AI 控制 Chrome 做调试、性能分析、网络请求分析,这是它与 Playwright MCP 的核心差异
维护方 Google Chrome DevTools 团队(官方)
地址 https://github.com/ChromeDevTools/chrome-devtools-mcp

配置:

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

⚠️ 注意:不要使用 --autoConnect 参数——该参数不存在,会导致服务启动失败、面板显示 0 tools。连接已运行的 Chrome 实例应使用 --browserUrl http://127.0.0.1:9222。

常用参数:

参数 说明
--headless 无头模式运行
--browserUrl 连接已运行的 Chrome(需开启 --remote-debugging-port=9222)
--isolated 隔离模式,使用临时用户数据目录
--viewport 设置视口大小,如 --viewport 1920x1080
--executablePath 指定 Chrome 可执行文件路径

环境要求(查证自 README 与 npm registry):

项 要求
Node.js LTS 版本(package.json engines:^20.19.0 || ^22.12.0 || >=23)
Chrome 当前稳定版或更新;官方保证 Google Chrome 正式版与 Chrome for Testing,Edge/Brave 等 Chromium 系可能能跑但不保证
浏览器插件 不需要——内嵌 puppeteer-core 走 CDP 直连,全程无扩展参与
浏览器二进制 不像 Playwright MCP 那样绑定下载浏览器目录(无 chromium-1200 类版本坑),直接用系统安装的 Chrome

典型使用场景:

  • "帮我分析 xxx 页面的性能瓶颈" → 录制 performance trace 并提取优化建议
  • "看看页面有什么报错" → 读取 console 消息(含 source-mapped 堆栈)
  • "检查这个请求为什么失败" → 分析网络请求详情

验证是否配置成功: 输入 "Check the performance of https://developers.chrome.com",应自动打开浏览器并录制性能追踪。

实战:连接本地 dev server 调试(真实流程)

场景:本地 3000 端口跑着前端应用,想看 console 报错。两种模式按需选:

模式一(默认,最省事):mcp.json 只写基础配置即可,Server 在首次调用需要浏览器的工具时自动拉起 Chrome 实例。目标页面 URL 不写进 mcp.json,对话时直接说:

用 chrome-devtools 打开 http://localhost:3000,看看 console 有什么报错

模式二(接管手动开的 Chrome,保留登录态与操作状态):Chrome 以调试端口启动。CMD 写法:

start "" "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir=C:\chrome-debug

Git Bash 下不能照抄上面的命令:C:\chrome-debug 中的 \c 会被 bash 当转义符吃掉,实际传给 Chrome 的是 C:chrome-debug(驱动器相对路径),Chrome 无法创建数据目录,弹"无法对其数据目录 C:chrome-debug 执行读写操作"。正确写法二选一(结尾 & 后台运行——Git Bash 没有 start,不加会占住前台):

# 写法一:路径用正斜杠(Chrome 原生接受,与 C:\chrome-debug 是同一目录)
"/c/Program Files/Google/Chrome/Application/chrome.exe" --remote-debugging-port=9222 --user-data-dir=C:/chrome-debug &

# 写法二:单引号保护反斜杠
"/c/Program Files/Google/Chrome/Application/chrome.exe" --remote-debugging-port=9222 --user-data-dir='C:\chrome-debug' &

嫌长可加进 ~/.bashrc 当别名:

alias chrome-debug='"/c/Program Files/Google/Chrome/Application/chrome.exe" --remote-debugging-port=9222 --user-data-dir=C:/chrome-debug &'

mcp.json 增加连接参数:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--browserUrl=http://127.0.0.1:9222"]
    }
  }
}

验证 Chrome 调试端口就绪:curl http://127.0.0.1:9222/json/version,返回 Browser / Protocol-Version 即连通。

本次实战踩过的五个坑:

坑 现象 解法
chrome.exe 不在 PATH bash 报 chrome.exe: command not found 写全路径 C:\Program Files\Google\Chrome\Application\chrome.exe
Git Bash 反斜杠转义 弹"无法对数据目录 C:chrome-debug 执行读写操作"——\c 被当转义符吃掉,变驱动器相对路径 路径用正斜杠 C:/chrome-debug 或单引号包裹,见上文模式二
调试端口参数被吞 已有 Chrome 在跑时带参启动,参数转交给旧实例,9222 不生效 加 --user-data-dir=C:\chrome-debug 起独立实例
browserUrl 端口混淆 误填 http://127.0.0.1:3000(前端应用端口) --browserUrl 指向 Chrome 的 CDP 端点 9222;要调试的页面 URL 在对话时说,不写进配置
配置当轮不生效 mcp.json 改完,当前会话工具列表里没有 chrome-devtools 重启 CodeBuddy(或 MCP 面板重连)后才挂载

独立 --user-data-dir 是全新目录,不带日常 Chrome 的登录态,需要登录的调试场景先在该实例手动登录一次(之后会保留)。

复用日常 Chrome(带插件和书签)调试:

想让 MCP 接管的浏览器带上原有的全部插件、书签、登录态,用默认用户目录 + 调试端口启动:

# 前提:先完全退出日常 Chrome(确认无 chrome.exe 残留进程,否则参数被吞,见坑 3)
"/c/Program Files/Google/Chrome/Application/chrome.exe" --remote-debugging-port=9222 &

不加 --user-data-dir 就用默认 profile,插件书签全在;mcp.json 仍连 9222,无需改动。调试完关掉窗口即可,日常启动不受影响。安全提醒:9222 开启期间任何本地进程都能完全控制该浏览器(含已登录账号),个人开发机可接受,公用机器或长期常开改用独立目录方案。

调试 dev / test / 生产环境页面: mcp.json 一套配置通吃,环境差异只体现在对话时给的 URL——dev 是 http://localhost:3000/xxx,test / 生产是对应域名页面,说"看看 xxx 页面的 console 报错"即可,不为此改配置。

工具调用套路(chrome-devtools):

步骤 工具 说明
1 list_pages 取 pageId——多数工具的必填参数
2 navigate_page 打开目标 URL
3 list_console_messages 读 console,types 可过滤 error/warn
4 take_snapshot a11y 树看页面结构,比截图省 token
5 evaluate_script 页面内跑 JS,精确定位元素
按需 take_screenshot 内联返回;filePath 只能写工作区内路径,写 Downloads 会被拒

能力全景(32 个工具,按开发场景分类):

场景 工具 能干什么
页面/页签管理 list_pages / new_page / select_page / close_page / navigate_page / resize_page 列页签取 pageId、开新页签、切换、关闭、导航、改视口
看页面内容 take_snapshot / take_screenshot / get_css_styles a11y 树快照(节点带 uid 可定位)、截图、取元素计算样式
Console list_console_messages / get_console_message 全量消息(可按 error/warn 过滤)/ 单条详情
网络分析 list_network_requests / get_network_request 请求列表 / 单请求完整详情(headers、响应体)
交互模拟 click / hover / drag / fill / fill_form / type_text / press_key / upload_file / handle_dialog / wait_for 点、悬停、拖拽、填字段、整表填写、键入、按键、传文件、处理弹窗、等条件成立
性能与审计 performance_start_trace / performance_stop_trace / performance_analyze_insight / take_heapsnapshot / lighthouse_audit / emulate 录制/停止性能 trace、洞察分析、堆内存快照、Lighthouse 评分、CPU/网络/设备模拟
执行脚本 evaluate_script 页面上下文执行 JS,读任意运行时数据
录屏复现 screencast_start / screencast_stop 录制页面过程,复现 bug / 给同事演示用

关于 a11y 树: a11y 是 accessibility(可访问性)的数字缩写——a + 省略的 11 个字母 + y。浏览器为屏幕阅读器等辅助技术维护一棵语义树,节点带角色(button/link/textbox)、名称、状态(disabled/selected)。take_snapshot 返回这棵树,AI 靠它精确理解页面结构并用 uid 定位元素,比截图更准更省 token——所以套路表里 snapshot 排在 screenshot 前面,截图只做视觉确认,不能用于操作定位。

真实使用示例:

示例一(本地 dev server)——"用 chrome-devtools 打开 http://localhost:3000 看报错"。实际结果:console 无 error,只有 Vite HMR 两条 debug、业务金额换算两条 log,加一条 issue;用 evaluate_script 定位出该 issue 是 el-color-picker 的 label[for] 指向了 DIV(非可标记表单元素),Element Plus 层面小瑕疵。

示例二(掘金 console)——打开 juejin.cn 后 list_console_messages 返回 23 条:15 条 parseImageXUrl error(ImageX 图片 URL 的 base64 水印段解析失败,掘金自身 bug)、3 条 unload Permissions Policy 违规、一条 %c 样式化招聘彩蛋 log。要点:console 数据来自 CDP 事件推送,DevTools 面板开不开都能拿到——面板和 MCP Server 是同一协议的两个客户端。

隐私说明: 默认收集使用统计(工具调用成功率、延迟、环境信息),--no-usage-statistics 可关闭;性能分析可能将 trace URL 发送给 Google CrUX API,--no-performance-crux 禁用。该工具会把浏览器实例内容完整暴露给模型,调试实例里别开着不想让 AI 访问的敏感页签(或用 --isolated 走临时用户数据目录)。

实战:Node 多版本共存(MCP 固定 node 22,项目照用 node 16)

背景:chrome-devtools-mcp 的 engines 要求 ^20.19.0 || ^22.12.0 || >=23,而本机不少老项目必须跑 node 16,日常会用 nvm use 16 切全局版本。原配置 command: "cmd", args: ["/c", "npx", ...] 里的 npx 走 PATH 解析,拿到的是当前全局 node——一切到 16,MCP Server 启动即挂。

核心认知:MCP Server 是 Client(CodeBuddy)独立拉起的进程,跟项目用什么 Node 无关。command 填可执行文件完整路径,进程就用那个 Node 启动,PATH 里是哪个版本、nvm 切到几都不影响。项目继续 node 16 跑构建,MCP 用 node 22 运行,互不干扰。

解法(mcp.json,node 22.12.0 的绝对路径直连,已验证可用):

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "C:\\Users\\Administrator\\AppData\\Roaming\\nvm\\v22.12.0\\node.exe",
      "args": [
        "C:\\Users\\Administrator\\AppData\\Roaming\\nvm\\v22.12.0\\node_modules\\npm\\bin\\npx-cli.js",
        "-y",
        "chrome-devtools-mcp@1.12.0",
        "--browserUrl=http://127.0.0.1:9222"
      ]
    }
  }
}

链路验证(返回 npm 版本号即通):

"C:\Users\Administrator\AppData\Roaming\nvm\v22.12.0\node.exe" "C:\Users\Administrator\AppData\Roaming\nvm\v22.12.0\node_modules\npm\bin\npx-cli.js" --version

要点:

点 说明
为什么直接跑 npx-cli.js nvm root 下的 npx.cmd 内部用 %~dp0\node.exe(同目录 node,不看 PATH),写它的完整路径也可以;直接 node.exe + npx-cli.js 少一层 cmd 包装,更干净
不推荐 nvm use 22 切全局 全局版本一变,node 16 项目构建全挂,来回切麻烦;固化绝对路径后全局版本随意切
没装 nvm 时 下载 node 22 zip 版解压到任意目录,command 指向该目录的 node.exe,同样生效且不写注册表不占 PATH
生效方式 mcp.json 改完需重启 CodeBuddy(或 MCP 面板重连),同"配置当轮不生效"坑
举一反三 任何对 Node 版本有要求的 MCP Server(如 Playwright MCP)遇到同样问题,照此法固化即可

3.3 Playwright MCP —— 浏览器自动化

项目 说明
用途 让 AI 驱动浏览器执行自动化操作:导航、点击、填表、截图
与 Chrome DevTools MCP 的区别 Playwright 基于可访问性树驱动浏览器,不做性能分析;适合端到端测试与操作自动化
生态现状 同领域有两个包,工具命名完全不同,配置与文档不能混用
官方包 @playwright/mcp(Microsoft Playwright 团队),工具前缀 browser_,仓库 github.com/microsoft/playwright-mcp
社区包 @executeautomation/playwright-mcp-server(ExecuteAutomation,v1.0.12 依赖锁定 playwright 1.57.0),工具前缀 playwright_,仓库 github.com/executeautomation/mcp-playwright

官方包与社区包怎么区分(看 MCP 面板的工具名即可):

维度 官方 @playwright/mcp 社区 @executeautomation/playwright-mcp-server
工具前缀 browser_* playwright_*
工具数量 核心 26 个,--caps 按网络/存储/DevTools/视觉/PDF/断言分组扩展,约 72 个 固定 33 个,无能力开关
看页面方式 browser_snapshot 无障碍快照(截图明确声明不能用于操作) playwright_screenshot + get_visible_text / get_visible_html
特色工具 browser_find(快照内文本检索,省 token)、browser_verify_* 断言组 start_codegen_session / end_codegen_session 等 4 个 codegen 录制工具
维护方 Microsoft,随 Playwright 版本同步 第三方组织维护

配置(官方包):

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

配置(社区包,本文实战环境实际在用的就是这个):

{
  "mcpServers": {
    "Playwright MCP Server": {
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"]
    }
  }
}

两个包都通过 npx 以 stdio 方式启动,区别在于工具集与参数。查官方文档(--caps、--device、--isolated 等)时先确认自己装的是哪个,否则会发现参数对不上。

常用参数(官方包):

参数 说明
--browser 指定浏览器(chrome、firefox、webkit)
--headless 无头模式
--device 模拟设备,如 --device "iPhone 15"
--viewport-size 视口大小
--save-trace 保存 Playwright trace 便于回放调试

社区包参数集与上表不同,配置前用 npx @executeautomation/playwright-mcp-server --help 确认实际支持的参数,不要照抄官方文档。

能力全景(社区包 33 个工具,按开发场景分类):

场景 工具 能干什么
页面/标签管理 navigate_page / new_page / select_page / close_page / list_pages / resize_page 导航、开/切/关标签页、改视口
看页面内容 take_snapshot / take_screenshot / get_visible_text / get_visible_html / get_css_styles 截图、可见文本、原始 HTML、元素样式
Console list_console_messages / get_console_message 消息列表(可按 error/warn 过滤)/ 单条详情
网络分析 list_network_requests / get_network_request 请求列表 / 单请求详情
交互模拟 click / hover / drag / fill / fill_form / type_text / press_key / upload_file / handle_dialog / wait_for 点、悬停、拖拽、填字段、整表填写、键入、按键、传文件、处理弹窗、等条件成立
性能与审计 performance_start_trace / performance_stop_trace / performance_analyze_insight / take_heapsnapshot / lighthouse_audit / emulate 录制/停止/分析性能 trace、堆快照、Lighthouse 评分、设备模拟
执行脚本 evaluate_script 页面上下文执行 JS,读任意运行时数据
录屏 screencast_start / screencast_stop 录制页面操作过程
代码生成 start_codegen_session / end_codegen_session / get_codegen_session / clear_codegen_session 录制浏览器操作生成 Playwright 测试代码(特色能力,chrome-devtools 没有)

社区包与 chrome-devtools 的工具面几乎重叠(毕竟底层都是浏览器协议),实操差异在三点:

  1. 工具名带 playwright_ 前缀;多数工具不需要 pageId(单页面上下文自动维护),chrome-devtools 多数工具必须先 list_pages 拿 pageId
  2. take_screenshot 的 savePng 可落盘到 Downloads 等任意目录,chrome-devtools 的 filePath 限制在工作区内
  3. codegen 四件套是社区包独有的测试代码生成能力

真实使用示例(掘金频道抓取):playwright_navigate 打开 https://juejin.cn/ai → playwright_evaluate 在页面内跑一段选择器脚本(.entry-list .item 提取标题/作者/阅读数/链接,去重取前 10)→ 数据直接 JSON 返回。要点:结构化提取优先 evaluate_script(比截图+肉眼读准且省 token);console 用 playwright_console_logs 的 type: error 过滤报错。首次使用若报浏览器二进制缺失,见下文"实战"小节的目录顶替解法。

典型使用场景:

  • "打开 xxx 页面,点击登录按钮,填入用户名密码"
  • "对这个页面截图"
  • "端到端跑一遍下单流程,验证按钮是否可点"

工作原理(三层链路):

层 机制 说明
传输层 stdio 子进程 Client(CodeBuddy)按 command: npx 拉起 Server 进程,JSON-RPC 消息走 stdin/stdout;npx -y 每次启动临时安装/复用 npm 包
驱动层 可访问性树(Accessibility Tree) Playwright 不靠截图+坐标猜界面,而是让模型读到结构化的角色/名称/状态,点击目标是真实 DOM 节点,所以定位稳、可断言
浏览器层 版本强绑定的二进制管理 playwright npm 包内写死了浏览器目录名(如 chromium-1200),启动时到 %LOCALAPPDATA%\ms-playwright\ 按目录找 chrome.exe,找不到直接报错

实战:浏览器二进制版本缺口的极简解法

一次真实调用 playwright_navigate 报错:

Executable doesn't exist at C:\Users\Administrator\AppData\Local\ms-playwright\chromium-1200\chrome-win64\chrome.exe

排障过程三步:

  1. 定位因果:社区包 @executeautomation/playwright-mcp-server@1.0.12 依赖锁定 playwright@1.57.0,该版本对应 chromium-1200;而 npx playwright install chromium 装的是最新版 playwright(1.64.1)对应的 chromium-1248,目录名对不上,报错依旧
  2. npx -y playwright@1.57.0 install chromium —— 版本猜对了,但下载失败:网络代理中途失效(Proxy connection ended before receiving CONNECT response)
  3. 极简解法:CDP(Chrome DevTools Protocol)向后兼容,高版本 Chrome 可以被旧版本驱动,直接复制目录顶替:
robocopy C:\Users\Administrator\AppData\Local\ms-playwright\chromium-1248 C:\Users\Administrator\AppData\Local\ms-playwright\chromium-1200 /E

复制完成后 navigate 立即恢复正常。注意 robocopy 的退出码 1 表示"有文件被复制",属于成功;0~7 都算成功,≥8 才是失败。

排障启示:Playwright 报浏览器缺失时,先看报错里它要的目录名(如 chromium-1200),再 dir %LOCALAPPDATA%\ms-playwright 盘点本地已有版本。需要的目录名由 MCP Server 依赖的 playwright 版本决定,查 registry.npmjs.org/<包名> 的 dependencies 即可确认。网络受阻时,目录顶替比反复下载快得多;根本解法是装与 Server 依赖同大版本的浏览器。

选择建议:

  • 要调试/分析页面(性能、网络、console)→ Chrome DevTools MCP
  • 要自动化操作/测试页面(点击、填表、断言)→ Playwright MCP

3.4 Firecrawl MCP —— 网页抓取与结构化提取

项目 说明
用途 网页抓取、批量爬取、结构化数据提取,输出干净的 Markdown
维护方 Mendable(官方)
地址 https://github.com/mendableai/firecrawl-mcp-server
部署方式 云端(firecrawl.dev,需 API Key)或自托管

配置:

{
  "mcpServers": {
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "你的API Key"
      }
    }
  }
}

核心工具:

工具 说明
firecrawl_scrape 抓取单个 URL,输出 Markdown / HTML / 截图
firecrawl_crawl 批量爬取整个站点
firecrawl_search 搜索引擎 + 抓取结果
firecrawl_extract 用 LLM 从网页提取结构化数据(JSON)

典型使用场景:

  • "把这个网页内容抓下来整理成 Markdown"
  • "爬取这个网站所有产品页的标题和价格,输出成表格"
  • "搜索关于 xxx 的最新文章并总结"

与普通 web_fetch 的区别: Firecrawl 能处理 JS 渲染的动态页面、批量爬取整个站点、并做结构化提取,普通 fetch 只能拿静态 HTML。


3.5 vite-plugin-vue-mcp —— Vue 应用运行时状态

项目 说明
用途 让 AI 读取/修改运行中 Vue 应用的组件树、组件状态、路由、Pinia 状态
维护方 Arlo(webfansplz,Vue/Vite 生态贡献者)
地址 https://github.com/webfansplz/vite-plugin-vue-mcp
与前四个的本质区别 不是独立进程的 MCP Server,而是 Vite 插件:随 dev server 启动,通过 SSE 端点对外服务;灵感来自 @antfu 的 vite-plugin-mcp

工作原理:

vite.config 挂 VueMcp() 插件
      ↓
dev server 启动 → 挂载 SSE 端点 http://localhost:[port]/__mcp/sse
      ↓
向页面注入采集脚本(@vue/devtools-kit)→ 采集组件树/状态/路由/Pinia
      ↓
AI 客户端以 SSE 传输连接该端点 → 模型调用 7 个工具读写运行时状态

安装与配置(两端):

pnpm install vite-plugin-vue-mcp -D

插件端(vite.config.ts):

import { VueMcp } from 'vite-plugin-vue-mcp'

export default defineConfig({
  plugins: [VueMcp()]
})

客户端(CodeBuddy 的 mcp.json,SSE 传输):

{
  "mcpServers": {
    "vue-mcp": {
      "type": "sse",
      "url": "http://localhost:5173/__mcp/sse"
    }
  }
}

端口跟随 dev server 实际端口(5173 仅为示例,以启动时控制台打印的 URL 为准)。Cursor 用户可省去手工配置:项目存在 .cursor 目录时,插件会自动更新 .cursor/mcp.json(updateCursorMcpJson 默认开启)。

暴露的 7 个工具:

工具 功能 关键输入
get-component-tree 获取 Vue 组件树 —
get-component-state 获取组件状态 componentName
edit-component-state 编辑组件状态 componentName / path / value / valueType
highlight-component 在页面上高亮组件 componentName
get-router-info 获取 Vue Router 路由信息 —
get-pinia-tree 获取 Pinia 树 —
get-pinia-state 获取 Pinia 状态 storeName

常用配置项(VueMcpOptions):

配置项 说明 默认值
host 监听主机 'localhost'
mcpPath MCP 服务路径 '/__mcp'
printUrl 控制台打印服务 URL true
updateCursorMcpJson 自动更新 .cursor/mcp.json true
mcpServer 传入自定义 MCP Server(会忽略内置工具) —
mcpServerSetup Server 创建时的钩子,可替换默认实现 —
appendTo 非 HTML 入口项目的注入方式(高级用法,慎用) ''

典型使用场景:

  • "看下当前页面的组件树,找到商品列表是哪个组件"
  • "把 xx store 的 loading 置为 false,看看 UI 什么反应"(AI 直接调 edit-component-state 改运行时状态)
  • "这个页面对应的路由配置是什么"

注意事项:

  1. 应用必须已在浏览器中运行——数据从运行实例采集,页面没打开工具就拿不到东西,这是最常见的"不工作"原因
  2. 版本要求:Vite ^3.1 || ^4 || ^5 || ^6;纯前端调试场景专用,与 Playwright MCP 互补(一个操作页面,一个透视页面内部状态)
  3. edit-component-state 只改运行时状态,刷新即还原,不会写回源码

四、MCP 使用总结

4.1 五个 MCP 的分工

MCP 定位 一句话
Context7 文档查询 "查文档"
Chrome DevTools 浏览器调试 "分析页面性能/报错/网络"
Playwright 浏览器自动化 "操作页面/跑测试"
Firecrawl 网页抓取 "抓网页内容/爬站"
vite-plugin-vue-mcp Vue 运行时调试 "看/改运行中 Vue 应用的组件树与状态"

4.2 通用使用原则

  1. 说人话:直接描述需求,模型自动选择并调用工具
  2. 信任但验证:工具返回结果后,模型会基于真实数据回答(而非编造)
  3. 配置排错:MCP 面板显示 0 tools 通常意味着 Server 启动失败——检查命令、参数、Node 版本
  4. 按需配置:不用装全部 MCP,按日常使用场景挑选

4.3 排查清单(Server 显示 0 tools)

  • 命令是否正确(npx + 完整包名)
  • 参数是否存在(对照官方 README,如 --autoConnect 就不存在)
  • Node.js 版本是否满足要求(多数需要 LTS)
  • 网络/代理是否能访问 npm registry
  • 环境变量(如 API Key)是否配置

参考

留言(0 条)

还没有留言,来写第一条吧

使用 GitHub 登录后即可在下方直接留言