Browser MCP 研究与替代方案

本工作区包含对 Browser MCP（browsermcp.io）的完整调研、一个修复版复刻，以及最终的替代方案落位。

安装为插件（v1.0.0 起）

本仓库同时是一个 ZCode 插件市场，提供可一键安装的 browser-mcp-lab 插件 （= 固定版本的 Playwright MCP 服务器 + 浏览器自动化技能 + /browser-doctor 体检命令）：

• 图形界面：Settings → Plugin Management → Discover → + → 添加本仓库地址 https://github.com/ashu0729will/browser-mcp-lab → 在卡片上点 Get

• 让 agent 自动装：把 AGENT_PROMPT.md 代码块里的内容整段复制给任何 AI agent

• 发布版：见 Releases（v1.0.0）

Related MCP server: Playwright MCP

自研浏览器扩展（v0.2.0 实验版，原创核心）

extension/ + server/ 是我们自己的浏览器扩展和配套 MCP 服务器——目标是替换掉链路上 微软的两个组件，形成 100% 原创闭环。11 个工具（navigate/snapshot/click/type/evaluate/ screenshot/tabs…），自有 WS 协议，零依赖，server 侧 17 项自动化断言全部通过。

• 设计与里程碑：docs/EXTENSION_DESIGN.md

• 装扩展：Firefox 用 about:debugging 临时加载；Edge/Chrome 用 edge://extensions 加载解压缩 extension/ 目录

• 跑 server：node server/mcp-server.js（扩展弹窗里点 Connect 配对）

• 状态：v0.2.1 已在 Firefox 真机端到端打通（配对/跳转/读取/求值/截图）；Chrome/Edge 代码就绪待真机验证。生产用途请继续用上面的插件（v1.0.0）

目录结构

主力方案：Playwright MCP 扩展模式

构思与 Browser MCP 完全相同（扩展连接你当前标签页、复用登录态），但由 Microsoft 维护、 工具是 Browser MCP 的严格超集（核心 23 个 + 可选 20 个，含多标签页、执行 JS、网络审查、 表单填写、文件上传等）。

一次性准备（只能手动做）： 在 Chrome/Edge 安装官方扩展 Playwright Extension。

之后每次使用： 打开要操控的标签页 → 对 AI 说话即可。工具以 mcp__playwright__* 出现 （browser_navigate / browser_snapshot / browser_click / browser_type / browser_console_messages / …）。

配置位于 .zcode/config.json（本机已调好；令牌是敏感信息，只放你本地的 config，勿提交到任何仓库）：

{
  "mcp": {
    "servers": {
      "playwright": {
        "command": "node",
        "args": [
          "<本仓库的绝对路径>\\node_modules\\@playwright\\mcp\\cli.js",
          "--extension",
          "--browser",
          "msedge"
        ],
        "env": {
          "PLAYWRIGHT_MCP_EXTENSION_TOKEN": "<你的扩展连接令牌>"
        }
      }
    }
  }
}

• 版本固定 + 本地安装：先 npm i（本仓库锁定实测通过的 @playwright/mcp@0.0.80）， 配置直接指向本地 cli.js——启动离线、确定、秒级，不会因上游发新版而与扩展协议漂移。

• --browser msedge：扩展模式默认找 Chrome 的用户数据目录，只有 Edge 的机器必须指定； 有 Chrome 的机器改回 chrome 即可。

• PLAYWRIGHT_MCP_EXTENSION_TOKEN：设置后跳过每次连接时扩展的「Allow & select」批准弹窗。 令牌可在扩展连接页里重新生成（作废旧令牌），届时同步改这里。

• 安全提醒：此令牌等于把整个浏览器（含登录态）交给持有它的客户端，勿外传、勿提交到公共仓库。

• 想全局可用（所有工作区）：把上面这段挪到 ~/.zcode/cli/config.json 的 mcp.servers 下。

• 想临时用「独立浏览器」模式（不依赖扩展，Playwright 自己启动 Chrome）：删掉 --extension 和 env。

• 扩展连接偶发超时的自救：重启 MCP server + 扩展重新连接（对比 Browser MCP 时代这属于偶发且上游会修的 bug，而非永久失联）。

连接稳定性优化（2026-09-09 落地）

针对「扩展连接偶发超时/断连」做的三层加固：

1. 版本固定 + 本地化安装：npm i @playwright/mcp@0.0.80 装进本工作区， .zcode/config.json 的启动命令从 npx @playwright/mcp@latest 改为 node <本地路径>\cli.js。消除两个断连根源：@latest 漂移（上游发新版后与 Edge 里的扩展协议不匹配）和每次启动的 registry 网络查询（代理不稳时表现为 「连不上」）。启动变成纯本地、确定性、秒级。 升级流程：npm run doctor:upstream 看到 新版本 → 读 changelog 确认兼容 → npm i @playwright/mcp@<版本> → 重开会话。

2. 原创体检脚本 mcp-doctor.js（方向 A 的第一块砖，零依赖）：

   • node mcp-doctor.js：体检配置/令牌/本地安装/孤儿进程，附断连自救四步

   • --check-upstream：连网对比 npm 最新版，提醒版本漂移

   • --kill：清掉残留 server 进程（会互相抢占扩展配对）

   • 判定要点：npx 包装进程（npx-cli.js）不是 server 本体；server 命令行是 ...\cli.js --extension ...，后面带参数，不能锚定行尾。

3. 自救口径：扩展点 Connect → 重启会话 → --kill + 重开会话 → 令牌重生成则 同步 config。断连优先跑 node mcp-doctor.js，先看报告再动手。

注意：config 改动只对新会话生效；npm i 会产生 package.json/package-lock.json/ node_modules/，属正常。

已验证（2026-09-08，本机实测）

两个测试驱动（playwright-e2e.js / playwright-phase2.js，stdio 上模拟真实 MCP 客户端）完成两轮端到端验证：

第一轮（基础链路）：扩展安装 → MCP 握手 + 24 工具枚举 → 首次配对（点一次「Allow & select」）→ 令牌免弹窗 → browser_navigate（真实跳转 example.com）→ browser_snapshot（ARIA 快照 + ref）→ browser_click（真实点击跳转 iana.org，after-click.png 为证）→ browser_console_messages → browser_take_screenshot → 干净退出。

第二轮（增量工具，8/8 通过）：

• browser_type + browser_press_key：在 Bing 搜索框输入并回车，真实出结果页

• browser_evaluate：页面内执行 JS（取 title/链接数；history.forward() 也能当前进键用）

• browser_network_requests：列出页面真实网络请求及状态码

• browser_navigate_back：真实后退

• browser_tabs（new / list / select）：多标签页管理真实可用

• browser_wait_for（text / time）：按文本或时间等待

已知差异（诚实记录）：0.0.80 没有独立的「前进」工具（Browser MCP 反而有），用 browser_evaluate 执行 history.forward() 等效。

唯一确认不可用的工具：browser_file_upload。 扩展模式下报 DOM.setFileInputFiles: Not allowed（扩展的 CDP 会话不允许直接设置文件输入框，安全限制）。 替代路径：browser_evaluate 用 DataTransfer 构造 File 塞进 input.files 并派发 change 事件 （2026-09-09 已验证可走通表单提交；但文件内容是 JS 生成的，不是磁盘真文件）。

其余复杂工具已于 2026-09-09 在真实会话中逐一实测通过（Selenium 官方表单页 + the-internet.herokuapp.com， 全程用屏幕截图交叉验证）：

• browser_fill_form：一次调用填 5 字段（文本/密码/中文多行 textarea/复选/单选），提交后服务端回显完整

• browser_select_option：选「Three」→ value=3，随表单提交验证

• browser_handle_dialog：3/3 —— prompt（接受并带中文文字，页面回显完整）、confirm（拒绝 → "You clicked: Cancel"）、alert（接受）

• browser_hover：悬停后仅目标头像的隐藏信息显现（屏幕截图证实）

• browser_drag：A/B 方块真实交换位置（坐标 + 屏幕截图证实）

复合场景实测（2026-09-09 第二轮，真实会话）：

• 登录状态流（the-internet /login）：错误密码 → 红色「Your password is invalid!」；正确密码 → 跳转 /secure + 绿色横幅；登出 → 回登录页。全链路带状态验证。

• 嵌套 iframe：browser_snapshot 能完整枚举 3 层 frameset（LEFT/MIDDLE/RIGHT/BOTTOM）， ref 前缀按 frame 深度编码；跨 frame 输入 + 点击 iframe 内按钮实测通过（本地实验页）。 the-internet 的 TinyMCE 编辑器因站点云配额耗尽处于只读模式，非工具问题。

• 进阶点击：doubleClick / button:"right" / modifiers:["Control"] / ["Shift"] 四种变体 均被页面事件处理器真实捕获。

• 表格排序：点击「Due」列头，升序（稳定排序）与降序均验证。

• browser_resize：扩展模式下是模拟视口（page.setViewportSize），不改 OS 窗口尺寸， innerWidth/Height 精确生效。

• file:// 被 MCP server 主动拦截（"Access to file: protocol is blocked"），本地页面需起 HTTP 服务（python -m http.server）。本地实验页在 cua-lab/。

• 杂项：browser_click 的 target 除 ref 外直接接受 CSS 选择器；填密码触发的 Edge「保存密码？」 浏览器弹窗需用电脑操作技能关闭（MCP 够不到浏览器 UI）。

注意：此版本的工具参数是 target（元素 ref 或选择器），不再是旧版的 element/ref 双字段； browser_click 还支持 doubleClick/button/modifiers。

另记：填密码表单会触发 Edge 的「保存密码？」弹窗（浏览器 UI，与 MCP 无关），可用电脑操作技能顺手关掉。

兜底方案：browsermcp-fixed

如果扩展模式临时抽风，可切回 browsermcp-fixed/（与官方 Browser MCP 扩展兼容的修复版 server，修掉了原版的崩溃、假死、端口互杀三大缺陷）。详见其 README。

调研结论备查

• Browser MCP 原版三大致命伤：server.close() 递归崩溃（#163）、MV3 worker 被杀连接假死（#192）、 9009 端口互杀；2025-05 起上游停更，146 个 issue 无人处理。

• 落选者：chrome-devtools-mcp（新版 Chrome 禁止附着默认日常配置文件，定位是调试补充）、 browser-tools-mcp（只监控不操控）、real-browser 系 fork（成熟度与原版同级）。