内容
# chrome-devtools-mcp-rs
纯 Rust 实现的单二进制文件，可直接替换 [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp)：一个 MCP 服务器，通过 Chrome DevTools 协议为编码代理提供对 Chrome 浏览器的控制。工具名称、模式、响应文本和命令行标志相同 — 只需在 MCP 配置中更改一行，现有的提示即可无缝工作。
**状态 — 与 chrome-devtools-mcp 1.3.0 兼容，已在 CI 中验证：**
- **完整的工具集** — 所有 46 个参考工具和模式均已实现（默认集中的 29 个，其余在实验性标志后）。
- **字节相同的 `tools/list`** — 在每个标志组合中（精简版、全功能版、页面 ID 路由、互操作、导航允许列表和 URL 过滤）与 1.3.0 匹配，通过捕获的固定件和实时的 `tools/list` 差异验证。
- **所有实验性标志均已实现** — `--redactNetworkHeaders`、 `--experimentalInteropTools`（`get_tab_id`）、 `--experimentalNavigationAllowlist`、 `--blockedUrlPattern` / `--allowedUrlPattern`、 `--experimentalStructuredContent`、 `--experimentalToonFormat`、 `--experimentalIncludeAllPages` 和 `--experimentalDevtools` 均驱动实际行为。仅剩下的 noop 是遥测/兼容性退出标志（ `--no-usageStatistics`、 `--viaCli`、 `--clearcut*` ） — 接受这些标志不会报错，因为此服务器从不收集遥测数据，因此无需采取任何操作。
- **实时响应一致性** — 覆盖的工具生成与参考实现相同的标准化输出，包括参数验证错误，通过 CI 中的 golden-output 套件在每个类别中进行测试（参见 [一致性矩阵](#工具一致性矩阵)）。
- **比 Node 参考实现轻约 20 倍，冷启动速度快约 140 倍** （参见 [性能](#性能)）。
- **`lighthouse_audit`** 通过 npm 包中附带的 Node.js 边车运行，由其自己的场景测试覆盖（ `lighthouse.yaml` ）；参见 [已知限制](#已知限制) 以获取非 npm 回退。
## 安装
```sh
npm install -g chrome-devtools-mcp-rs # 或按需运行： npx chrome-devtools-mcp-rs
```
npm 包（ `npm-wrapper/` ）是主要的分发渠道：一个薄的启动器，其 postinstall 过程会为您的平台（ macOS arm64/x64、 Linux x64、 Windows x64 ）从匹配的 GitHub 版本中获取预构建的静态二进制文件。也可以通过 `cargo install --git https://github.com/nhtera/chrome-devtools-mcp-rs` 、 Homebrew 软件包或每个 GitHub 版本中附带的二进制文件获取。
## 从 chrome-devtools-mcp 迁移
只需更改您的 MCP 配置中的一行 `command` 命令：
```diff
"chrome-devtools": {
- "command": "npx",
- "args": ["chrome-devtools-mcp@latest"]
+ "command": "npx",
+ "args": ["chrome-devtools-mcp-rs"]
}
```
## 用法
```json
{
"mcpServers": {
"chrome-devtools": {
"command": "chrome-devtools-mcp-rs",
"args": ["--headless", "--isolated"]
}
}
}
```
所有参考服务器的命令行标志均被接受（ camelCase 和 kebab-case 拼写），包括 `--autoConnect` （ Chrome 144+ ）和 `--experimentalPageIdRouting` （在页面范围的工具中添加 `pageId` 参数，以便一个服务器可以同时驱动多个页面）。每个文档化的标志 — 包括 `--experimentalDevtools`、 `--experimentalToonFormat` 和 `--experimentalIncludeAllPages` — 均驱动实际行为；只有遥测/兼容性退出标志（ `--no-usageStatistics`、 `--viaCli`、 `--clearcut*` ）被接受为无声 noop。参见 [已知限制](#已知限制) 以获取 `--experimentalDevtools` 页面 ID 警告。
完整的内存调试功能与 1.3.0 匹配： `--memoryDebugging` 暴露了所有九个堆读取器，包括 `get_heapsnapshot_dominators` 、 `get_heapsnapshot_edges` 和 `get_heapsnapshot_retaining_paths` （在 1.3.0 中新增，依赖于 `memoryDebugging` ）。
支持 1.3.0 的截图尺寸上限： `--screenshotFormat` （ `jpeg` / `png` / `webp` ）、 `--screenshotQuality` （ 0-100，仅 JPEG/WebP ）、 `--screenshotMaxWidth` 和 `--screenshotMaxHeight` 设置了 `take_screenshot` 在调用中省略它们时的默认行为。超大捕获会通过 Chrome DevTools 协议的原生剪辑缩放来缩小以保持长宽比（较小的宽度/高度比例为准）。
## 性能
服务器进程测量值与固定的参考 `chrome-devtools-mcp@1.3.0` 进行比较，取 3 次冷启动的中位数（ macOS arm64， Chrome 149 headless， `scripts/measure-rss.mjs` + 冷启动套件）。 RSS 是 **仅服务器进程** — Chrome 自己的内存是相同的，并且被排除在外。 `loaded` / `peak` = 导航后 + 10 次截图。精简版 = `--slim --headless --isolated` （ 3 个工具 ）；完整版则去掉 `--slim` （ 29 个工具 ）。
| 指标 | chrome-devtools-mcp-rs （发布版） | chrome-devtools-mcp 1.3.0 （ Node 22 ） | 比率 |
|---|---|---|---|
| 空闲 RSS （精简版/完整版） | **4.9 / 5.5 MiB** | 109 / 108 MiB | ~20 倍 |
| 峰值 RSS （精简版/完整版） | **7.4 / 7.2 MiB** | 109 / 108 MiB | ~15 倍 |
| 启动时间 （ spawn → `initialize` ） | **~4.5 ms** | ~645 ms | ~140 倍 |
浏览器驱动的吞吐量（导航 + 截图）基本相同 — 两者驱动的 Chrome 相同。添加 26 个工具（从精简版到完整版）仅需 +0.6 MiB 空闲内存和启动时间； Node 基线保持在 ~108 MiB 不变。差距在于运行时 — 静态二进制文件与 V8 加捆绑的 JS — 而不是工具列表的大小。
CI 强制执行发布二进制文件的三个 RSS 上限（ `.github/workflows/memory.yml` ）： **< 15 MB 空闲** （在 `initialize` + `tools/list` 之后，在 Chrome 启动之前）， **< 100 MB 加载后** （在核心场景套件之后），以及 **< 200 MB 在 ~100 MB 跟踪解析期间** 。
## 构建
```sh
cargo build --release
cargo test # 集成测试需要本地 Chrome（或 CHROME_PATH）
```
## 一致性验证
两层，均在 CI 中启用：
- **捕获的固定件** — `parity/fixtures/reference/` 持有从参考服务器（版本固定在 `capture-meta.json` 中）捕获的响应，通过 `parity/capture/capture-slim-reference.mjs`。测试断言与这些固定件一致；当更新固定版本时，会重新捕获。
- **实时 golden-output 套件** — `cargo run -p parity` 同时启动此服务器和固定的 npm 参考服务器，从 `parity/scenarios/*.yaml` 驱动相同的工具调用，并在本地固定件页面上进行，并对规范化的响应进行差异比较（ `.github/workflows/parity.yml` ， macOS + Linux ）。
参见 `parity/README.md` 以创建场景和固定版本更新过程。
### 工具一致性矩阵
每行映射到 CI 中启用的场景文件（ `.github/workflows/parity.yml` （或 `memory.yml` 以获取 RSS 网关））并与固定的参考版本进行差异比较。
| 类别（参考） | 一致性场景（ CI 启用） | 状态 |
|---|---|---|
| 输入自动化 | `input.yaml` | ✅ 实时一致 |
| 导航自动化 | `navigation.yaml` 、 `slim.yaml` 、 `navigation-allowlist.yaml` | ✅ 实时一致 |
| 模拟 | `emulation.yaml` | ✅ 实时一致 |
| 性能 | `performance.yaml` | ✅ 实时一致 |
| 网络 | `network.yaml` 、 `network-redirect.yaml` 、 `network-redact.yaml` | ✅ 实时一致 |
| URL 过滤 | `url-block.yaml` 、 `url-block-subresource.yaml` 、 `url-allow.yaml` | ✅ 实时一致¹ |
| 调试 | `snapshot.yaml` 、 `console.yaml` 、 `slim.yaml` 、 `lighthouse.yaml` | ✅ 实时一致（ `lighthouse_audit` 通过 npm 边车，参见下文） |
| 内存 | `memory.yaml` 、 `memory-idle.yaml` （ RSS ）、 `structured-content-heap.yaml` | ✅ RSS 网关 + 实时一致（包括 v1.3.0 `get_heapsnapshot_dominators` / `_edges` / `_retaining_paths` 读取器） |
| 截图尺寸上限（ 1.3.0 ） | `screenshot-size-caps.yaml` | ✅ 实时一致（ `--screenshotMaxWidth` 缩放， PNG + JPEG ） |
| 互操作 / 页面 ID 路由 | `interop.yaml` 、 `page-id-routing.yaml` | ✅ 实时一致 |
| 结构化内容 | `structured-content.yaml` | ✅ 实时一致 |
| TOON 格式（ `--experimentalToonFormat` ） | `toon.yaml` 、 `toon-console.yaml` | ✅ 实时一致 |
| 包含所有页面（ `--experimentalIncludeAllPages` ） | `include-all-pages.yaml` | ✅ 实时一致² |
| 参数验证 | `tool-argument-validation.yaml` | ✅ 实时一致 |
¹ `url-block-subresource` 依赖于重试： Chrome 异步发出离线子资源失败，因此被阻止的请求可能会暂时读取 `pending` 。套件的单次重试吸收了它（重试后通过会标记在报告中）；参见场景文件。
² 仅在形状上启用 — headless CI 固定件未暴露任何 `webview` / `background_page` 目标，因此场景在标志下验证页面列表形状而不是非 `page` 目标。
场景文件存在但 **未** 在 CI 中启用 — `extensions.yaml` 、 `thirdparty.yaml` 、 `webmcp.yaml` 、 `screencast.yaml` 和 `devtools.yaml` — 需要 headless CI 镜像无法确定性地提供的固定件（加载的扩展、第三方源、 WebMCP 页面、 ffmpeg 屏幕录制或 DevTools 目标附件）。在本地使用 `cargo run -p parity -- --scenarios parity/scenarios/<file>` 运行它们。所有五个文件都已在本地针对 npm `chrome-devtools-mcp@1.3.0` （ Chrome 149 + ffmpeg ）进行了验证，包括 1.3.0 `screencast_stop` 无活动录制行、未支持的扩展拒绝和 WebMCP 功能标志重命名。
`devtools.yaml` （ `--experimentalDevtools` ）另外是一个已知的差异 — 参见 [已知限制](#已知限制) 。
## 已知限制
- **`lighthouse_audit`** 通过 npm 包中附带的 **Node.js 边车** 运行（将 `lighthouse` 和 `puppeteer-core` 与二进制文件捆绑在一起）。在 npm 安装中，审核运行与驱动的 Chrome 相同，并返回与参考实现相同的分数/报告。 Lighthouse 是一个 Node.js 引擎，没有稳定的 CDP 等价物，因此它不能嵌入二进制文件中： **独立 / cargo / homebrew** 安装（无 Node 引擎）该工具仍然可发现，但调用返回一个明确的回退错误：
> lighthouse_audit 在此构建中不可用。 Lighthouse 作为捆绑的 Node.js 引擎运行，而此构建不提供此引擎，而 Chrome 公开的 CDP 接口不稳定，无法重现。 请通过 npm 包安装（该包捆绑了 Lighthouse 边车），或使用官方的基于 Node 的 chrome-devtools-mcp、 Lighthouse CLI 或 Chrome DevTools 中的 Lighthouse 面板。 对于性能审计，请运行 performance_start_trace。
通过 `performance_start_trace` / `performance_stop_trace` / `performance_analyze_insight` 支持性能审计。
- **Windows** （ x64 ）提供了一个使用 `x86_64-pc-windows-msvc` 构建的 `.zip` 发布资产；发布网关覆盖了 macOS （ arm64/x64 ）、 Linux （ x64 ）和 Windows （ x64 ）。 Windows 构建在 CI 中受到保护（ `cargo build --release` ）； Chrome 驱动的测试套件仍仅在 Linux 上运行。
- **`--experimentalDevtools`** 实现了参考页面的过滤器（ DevTools `devtools://` 目标变得可列出/可选，单元测试），但在 CI 中 **未进行字节对齐** 。在标志下，参考 — 通过 puppeteer 始终启用的 `handleDevToolsAsPage` — 表面一个额外的 DevTools/启动目标，占用页面 ID 1，将第一个真实页面移至 ID 2；此服务器的会话模型永远不会附加到该目标，因此它将页面列为 ID 1。仅页面 ID 编号不同（ URL 和选择匹配）。 `devtools.yaml` 被保留为文档和本地重现套件，而不是 CI 网关。
## 许可
Apache-2.0。有关第三方归属，请参见 `NOTICE` 。
