# 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](AGENT_PROMPT.md) 代码块里的内容整段复制给任何 AI agent
- **发布版**：见 [Releases](https://github.com/ashu0729will/browser-mcp-lab/releases)（v1.0.0）

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

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

- 设计与里程碑：[docs/EXTENSION_DESIGN.md](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）

## 目录结构

| 目录 | 内容 |
|------|------|
| `plugin/` | **插件本体**：`.zcode-plugin/plugin.json` 清单、浏览器自动化技能、`/browser-doctor` 命令、体检脚本 |
| `.zcode-plugin/marketplace.json` | 插件市场清单——使本仓库可被 ZCode 一键添加安装 |
| `AGENT_PROMPT.md` | 给任何 AI agent 的复制粘贴安装说明 |
| `.zcode/config.json` | **本工作区的 MCP 配置**——已注册 Playwright MCP（扩展模式），新会话自动连接（含令牌，不入库） |
| `browsermcp-fixed/` | Browser MCP 的修复版替代 server（零依赖，保留作兜底） |
| `mcp-doctor.js` | **原创**：MCP 连接体检/修复脚本（`node mcp-doctor.js`），与 `plugin/scripts/` 内副本同源 |
| `cua-lab/` | **原创**：本地交互实验页（进阶点击计数器 + iframe 嵌套），配 `python -m http.server` 使用 |
| `mcp-main/` | Browser MCP 原始源码（调研用，仅本地不入库） |
| `package/` | 官方 npm 包 `@browsermcp/mcp@0.1.3` 的发布产物（协议逆向用，仅本地不入库） |

## 主力方案：Playwright MCP 扩展模式

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

**一次性准备（只能手动做）：** 在 Chrome/Edge 安装官方扩展
[Playwright Extension](https://chromewebstore.google.com/detail/playwright-extension/mmlmfjhmonkocbjadbfplnigmagldckm)。

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

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

```json
{
  "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](browsermcp-fixed/README.md)。

## 调研结论备查

- Browser MCP 原版三大致命伤：`server.close()` 递归崩溃（#163）、MV3 worker 被杀连接假死（#192）、
  9009 端口互杀；2025-05 起上游停更，146 个 issue 无人处理。
- 落选者：chrome-devtools-mcp（新版 Chrome 禁止附着默认日常配置文件，定位是调试补充）、
  browser-tools-mcp（只监控不操控）、real-browser 系 fork（成熟度与原版同级）。