cdp-toolkit 3.1.0 → 3.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +32 -0
- package/README.md +69 -16
- package/dist/bidi/mux-daemon.js +560 -137
- package/dist/cli.js +1236 -493
- package/dist/index.js +708 -79
- package/dist/mcp.js +1229 -486
- package/package.json +3 -1
- package/src/bidi/driver.ts +346 -54
- package/src/bidi/protocol.ts +27 -9
- package/src/bidi/snapshot.ts +123 -113
- package/src/bidi-browser-tools.ts +366 -0
- package/src/bidi-tools.ts +29 -2
- package/src/cdp/driver.ts +36 -33
- package/src/cdp/endpoint.ts +200 -0
- package/src/cdp/session.ts +246 -0
- package/src/client.ts +118 -10
- package/src/driver.ts +22 -5
- package/src/firefox-tools.ts +6 -3
- package/src/manifest.ts +2 -2
- package/src/policy.ts +2 -2
- package/src/shared-tools.ts +96 -24
- package/src/toolDocs.ts +7 -7
- package/src/tools/dispatch-mouse.ts +6 -1
- package/src/tools/downloads.ts +5 -6
- package/src/tools/evaluate.ts +3 -3
- package/src/tools/navigation.ts +3 -3
- package/src/tools/network_mock.ts +2 -2
- package/src/tools/performance.ts +5 -5
- package/src/tools/permissions.ts +5 -5
- package/src/tools/recorder.ts +3 -3
- package/src/tools/screencast.ts +46 -6
- package/src/tools/snapshot.ts +2 -2
- package/src/version.ts +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,38 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [3.3.0] - 2026-11-16
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- **Firefox 160 parity.** Eight capabilities the BiDi backend lacked on Firefox 153 now work on Firefox 160 or newer, each measured against a real Firefox 160.0. They are version-gated (`BIDI_CAPABILITY_MIN_FIREFOX`, `src/bidi/driver.ts`): on an older Firefox the same call returns `unsupported` naming the version it needs. Under `--browser firefox`, 38 of the 48 tools are now available (was 35).
|
|
15
|
+
- `dispatch_mouse` (`input.raw`), with a press held across calls. `clickCount` is ignored on Firefox.
|
|
16
|
+
- `click` `modifiers` (new capability token `input.modifierClick`, also declared by Chrome). On macOS, Firefox turns Ctrl+click into a context-menu gesture with no `click`.
|
|
17
|
+
- `emulate` `mediaFeatures` and offline `networkConditions`. Latency/throughput throttling and a media type are refused `unsupported`, never ignored.
|
|
18
|
+
- `wait_for_download` (`browser.setDownloadBehavior`, re-armed per call) and `grant_permissions` (`permissions.setPermission`, with a W3C name mapping and restore-on-reset/dispose, because Firefox grants persist in the profile). New `src/bidi-browser-tools.ts`.
|
|
19
|
+
- `get_network_request` `includeBody` reads a body fetched before any capture call (`network.addDataCollector`, 2 MB per response, Firefox-managed total budget). Evicted or unknown bodies are clear errors. Chrome does not have this.
|
|
20
|
+
- `take_screenshot` `scale` via a one-capture `devicePixelRatio` change that is then restored.
|
|
21
|
+
- `CDP_FIREFOX_BODY_COLLECTOR=off` skips the session-wide response-body collector.
|
|
22
|
+
|
|
23
|
+
### Notes
|
|
24
|
+
|
|
25
|
+
- Still unimplemented in Firefox 160: forced-colors emulation, disabling scripting, touch emulation, `locateNodes` by `innerText`, and HTML5 drag (a BiDi pointer drag never fires `drop` or `dragend`).
|
|
26
|
+
|
|
27
|
+
## [3.2.0] - 2026-11-10
|
|
28
|
+
|
|
29
|
+
### Added
|
|
30
|
+
|
|
31
|
+
- Action results now say what they touched, not just where. `click`, `hover`, `fill`, `type_text` and `upload_file` return an `element` field with a snapshot-style `role "name"` string (`{"clicked":true,"element":"button \"Save\"","x":85,"y":95}`), so a transcript shows "clicked button Save" instead of a bare uid. `fill_form` returns `elements` (one per field, `null` where none could be read) and `drag` returns `element` for the source plus `target_element` when `to` is an element. The description is read in the page before the action (a click can navigate or unmount its node; `fill` reports the field's label, not the new value), is bounded to 2s, and is omitted rather than thrown on failure, so it can never break or mask the action's own result or error. Additive: no existing field changed. (`src/shared-tools.ts`, `test/describe-element.test.ts`)
|
|
32
|
+
- The role and accessible-name heuristics behind the Firefox snapshot walker are now one shared in-page source (`ACCNAME_HELPERS_SOURCE`, `src/bidi/snapshot.ts`) used by both the walker and the new describe step; the walker's generated function is byte-identical modulo whitespace. Caveat: on Chrome the snapshot comes from the native accessibility tree while `element` uses this DOM heuristic, so the two agree for buttons, links, tabs and labelled inputs but can differ on exotic accname cases.
|
|
33
|
+
- **Browser-WebSocket transport: attach to a Chrome that serves no `/json`.** A Chrome that had debugging turned on at runtime, through the toggle on `chrome://inspect/#remote-debugging`, serves only the browser-level socket — measured on Chrome 153, `/devtools/browser/<uuid>` returns 101 while `/devtools/page/<targetId>` returns 403 and `/json/version`+`/json/list` both return 404. That is the transport a user gets when they attach to the browser they were already using rather than relaunching it, and the toolkit could not reach it at all. Discovery now falls back to `Target.getTargets` over that one socket, and each call reaches its page through a flat `Target.attachToTarget` session on it. **The HTTP path is byte-for-byte unchanged**: `listTargets` issues its original `GET /json/list` first and unconditionally, and only a request that did not answer reaches the fallback — no added round-trip, no added failure mode, and the transport is cached after the first listing. The switch happens only when detection confirms the endpoint serves no `/json`: on a Chrome that does, a single failed `/json/list` (a restart, a timeout) is reported and the next call tries HTTP again, and `/json/version` is still asked on every call, so a restarted Chrome's new browser uuid is picked up. A cached browser-socket URL that stops answering is detected again once, which picks up a restarted Chrome's new `DevToolsActivePort`. The one-target-per-call guarantee holds: `Target.getTargets` is metadata-only and attaches to nothing, so a browser with hundreds of tabs costs one round trip rather than one attach per tab. Nothing is auto-discovered — a runtime-toggled Chrome raises a modal consent prompt for each new client, so the browser is named explicitly with `CDP_BROWSER_WS` (the socket URL) or `CDP_USER_DATA_DIR` (the profile whose `DevToolsActivePort` holds it), and the default profile is never scanned. (`src/cdp/endpoint.ts`, `src/cdp/session.ts`, `src/client.ts`, `src/cdp/driver.ts`)
|
|
34
|
+
- **`bun run browser-ws:smoke` and `bun run browser-ws:wedge`.** Both spawn their own disposable headless Chrome and front it with a proxy that removes exactly what the runtime-toggle mode removes (`test/browser-ws-only-proxy.ts`), because that mode cannot be requested with a flag and puts a consent dialog in front of every client. The smoke drives discovery and per-tab work against a confirmed `/json/version=404 /json/list=404 page-ws=403` endpoint, with every phase capped at the real 60s MCP tool timeout: at `TABS=200` it listed 201 pages (410 targets across 6 types) in 0.08s, evaluated in 0.09s, snapshotted in 0.03s, and drove 5 consecutive tabs in 0.03s. The wedge proves the timeout bound survives socket sharing, which `bench:wedge` cannot — that benchmark gives every page its own socket, where a hung renderer can only block the one socket dialed into it, while this transport puts every page on ONE socket. Observed in CI on headless Chrome 156 against a 5s bound: the blackholed tab rejected at 5.00s while a witness tab answered in 3ms, `list_pages` in 4ms and a freshly opened tab in 13ms, all on the same socket. (An earlier "under 1ms" figure was an artifact: the wedge read the clock before awaiting the call, so every success measured about 0ms.) Both scripts now run in CI, in their own job. (`test/browser-ws-smoke.ts`, `test/browser-ws-wedge.ts`)
|
|
35
|
+
- With named endpoints, transport detection runs per endpoint. `CDP_BROWSER_WS` and `CDP_USER_DATA_DIR` each name one browser, so they apply to the default endpoint only. (`src/cdp/endpoint.ts`)
|
|
36
|
+
|
|
37
|
+
### Fixed
|
|
38
|
+
|
|
39
|
+
- `stop_screen_recording` failed on new ffmpeg (9.0.1 on Homebrew) with `Unrecognized option 'vsync'`, because `-vsync` is gone there. The encoder probe now also reads `ffmpeg -version` and uses `-fps_mode vfr` on ffmpeg 5.1 and later (and git snapshots), keeping `-vsync vfr` for 4.4 and 5.0. If `-version` fails or prints no readable version, the probe reads the option list from `-h full` instead, and if that fails too it picks `-fps_mode`, never the removed `-vsync`. Verified on ffmpeg 9.0.1: a 4 s two-frame ledger encoded to 4.04 s with `-fps_mode`; the old argv exited 8. (`src/tools/screencast.ts` `supportsFpsMode`, `test/screencast.test.ts`)
|
|
40
|
+
- Tests could reach the developer's own browser on the default DevTools port. A stub that fails `/json/list` on purpose sent the browser-ws fallback to the real `/json/version`, and the transport learned there stayed cached for the rest of the run, so later stubbed listing tests read live tabs. A `bun test` preload (`test/helpers/no-live-browser.ts`, wired in `bunfig.toml`) now refuses any fetch or WebSocket to the default endpoint's port and clears the transport caches before each test.
|
|
41
|
+
|
|
10
42
|
## [3.1.0] - 2026-11-10
|
|
11
43
|
|
|
12
44
|
### Added
|
package/README.md
CHANGED
|
@@ -211,7 +211,7 @@ cdp take_screenshot --target url:example --fullPage true
|
|
|
211
211
|
# taken as vertical bands and stitched into one lossless PNG. No flag needed — this is the
|
|
212
212
|
# default — and the result says so: {"width":2780,"height":281964,"tiled":true,"bands":18}.
|
|
213
213
|
cdp take_screenshot --target url:example --fullPage true --savePath /tmp/whole-page.png
|
|
214
|
-
# 3x output pixels for one capture (Chrome
|
|
214
|
+
# 3x output pixels for one capture (Chrome, or Firefox 160+). The page is not told anything changed.
|
|
215
215
|
cdp take_screenshot --target url:example --scale 3
|
|
216
216
|
# Shoot a responsive page at desktop width from a tab that isn't that size, then restore it.
|
|
217
217
|
cdp take_screenshot --target url:example --renderWidth 1920 --renderHeight 1080
|
|
@@ -239,6 +239,8 @@ await TOOLS.navigate_page({ target: "index:0", url: "https://example.com" });
|
|
|
239
239
|
| `CDP_ENDPOINTS` | unset | Chrome only. Extra named endpoints, `name=url` comma-separated, e.g. `browser=http://127.0.0.1:9222,teams=http://127.0.0.1:9333?mode=read`. See "Named endpoints" below. |
|
|
240
240
|
| `CDP_ENDPOINTS_FILE` | unset | Chrome only. Path to a JSON file defining named endpoints (same meaning as `CDP_ENDPOINTS`, merged with it). See "Named endpoints" below. |
|
|
241
241
|
| `CDP_TIMEOUT_MS` | `15000` | Per-command timeout. |
|
|
242
|
+
| `CDP_BROWSER_WS` | unset | The `ws://…/devtools/browser/<uuid>` URL, for a Chrome that serves no `/json`. Only consulted after an HTTP listing has already failed. See "Attaching to a Chrome that serves no `/json`" below. |
|
|
243
|
+
| `CDP_USER_DATA_DIR` | unset | Profile directory to read `DevToolsActivePort` from, to find that browser socket without naming its uuid. Opt-in on purpose: nothing is scanned unless you name it. |
|
|
242
244
|
| `CDP_ARTIFACT_DIR` | `/tmp/cdp-toolkit` | Screenshots, traces, heap snapshots, lighthouse reports, recorder buffers. |
|
|
243
245
|
| `CDP_STATE_DIR` | `/tmp/cdp-toolkit` | `select_page` selected-target file, in-flight trace state. |
|
|
244
246
|
| `CDP_EXTRACT_BASE_URL` | `http://127.0.0.1:8090/v1` | `extract_page` only. Base URL of the OpenAI-compatible extraction endpoint (the server appends `/chat/completions`). The default is loopback llm-ferry, so page content never leaves the machine; overriding it sends page content wherever the operator points. |
|
|
@@ -255,6 +257,7 @@ await TOOLS.navigate_page({ target: "index:0", url: "https://example.com" });
|
|
|
255
257
|
| `CDP_FIREFOX_SESSION_WAIT_MS` | `10000` | Firefox backend only. How long a second process waits for a live holder to release Firefox's one BiDi session before returning the distinguishable "held by a live process" error. See "Firefox" below. |
|
|
256
258
|
| `CDP_FIREFOX_MUX` | `daemon` when attaching, `host` when launching | Firefox backend only. Which process hosts the loopback BiDi multiplexer that lets several cdp-toolkit processes drive one Firefox: `daemon` (attach-mode default) spawns/joins a detached process that owns the real session for as long as anyone needs it; `host` makes THIS process the holder (launch mode's default, since a launched Firefox and its holder already share a lifetime); `off` restores pre-mux behavior — one live session per Firefox, a second process refused after the wait. See "Firefox" below and "Parallel tabs" below. |
|
|
257
259
|
| `CDP_FIREFOX_MUX_IDLE_MS` | `15000` | Firefox backend only, daemon mode. How long the mux daemon stays up with zero connected clients before it exits on its own (also counted from its own startup, so a spawner that never connects can't strand one). |
|
|
260
|
+
| `CDP_FIREFOX_BODY_COLLECTOR` | on | Firefox 160+ only. `off` skips the session-wide response-body collector, so Firefox keeps no response bodies for this toolkit; `get_network_request` `includeBody` then reads only bodies armed by a capture call first, like Chrome. |
|
|
258
261
|
| `CDP_FIREFOX_MUX_DAEMON` | resolved from the running module's location | Firefox backend only, tests only. Absolute path override for the daemon script the driver spawns, in place of the built-in resolution (`./mux-daemon.ts` in source, `dist/bidi/mux-daemon.js` in the published package). |
|
|
259
262
|
|
|
260
263
|
## Progressive disclosure
|
|
@@ -338,6 +341,42 @@ The server serves **both** eras off the same stdio transport, and the era is pin
|
|
|
338
341
|
|
|
339
342
|
Measured 2026-09-01: Claude Code 2.1.258 and Codex CLI 0.147.0 both connect and both pin the **legacy** era — their binaries carry the 2026-07-28 client strings, but neither opens with `server/discover` by default, and the MCP SDK's own `Client` behaves the same unless it opts in. So serving both eras is load-bearing, not courtesy, and today the `ttlMs`/`cacheScope` hints reach only clients that ask for the modern era. The static listing pays off on either one — no mid-session tool churn, and no prompt-cache invalidation.
|
|
340
343
|
|
|
344
|
+
## Attaching to a Chrome that serves no `/json`
|
|
345
|
+
|
|
346
|
+
Chrome has two ways in, and until recently every build served both: (A) the HTTP discovery endpoints `/json/version` and `/json/list`, plus a per-target socket at `/devtools/page/<targetId>`; and (B) one browser-level socket at `/devtools/browser/<uuid>`, over which `Target.getTargets` lists and `Target.attachToTarget` reaches a page.
|
|
347
|
+
|
|
348
|
+
A Chrome started with `--remote-debugging-port` serves both, and nothing below is reached on one. A Chrome that had debugging turned on **at runtime**, through the toggle on `chrome://inspect/#remote-debugging`, serves only (B) — measured on Chrome 153:
|
|
349
|
+
|
|
350
|
+
| Request | `--remote-debugging-port` Chrome | runtime-toggled Chrome |
|
|
351
|
+
|---|---|---|
|
|
352
|
+
| `ws://127.0.0.1:<port>/devtools/browser/<uuid>` | 101 | **101** |
|
|
353
|
+
| `ws://127.0.0.1:<port>/devtools/page/<targetId>` | 101 | **403** |
|
|
354
|
+
| `http://127.0.0.1:<port>/json/version`, `/json/list` | 200 | **404** |
|
|
355
|
+
|
|
356
|
+
That is the transport a user gets when they attach to the browser they were *already using* rather than relaunching it — a logged-in profile with their real tabs — so it is worth supporting rather than working around. cdp-toolkit reaches it with `Target.getTargets` for discovery and one flat `Target.attachToTarget` session per call for the work, over a single refcounted browser socket.
|
|
357
|
+
|
|
358
|
+
**The HTTP path is untouched.** `list_pages` issues its original `GET /json/list` first and unconditionally; only a request that did *not* answer reaches the fallback. On a Chrome that serves (A) the code path is the one that shipped, with no added round-trip and no added failure mode. The transport is then cached, so the 404 is paid once per process.
|
|
359
|
+
|
|
360
|
+
**Nothing is auto-discovered — you name the browser.** Connecting to a DevTools endpoint is not a neutral act: a runtime-toggled Chrome raises a modal *"Allow remote debugging?"* prompt on the user's screen for each new client, and that prompt grants full access to a logged-in session. So cdp-toolkit never scans the default profile looking for a browser socket. Point it at one explicitly:
|
|
361
|
+
|
|
362
|
+
```bash
|
|
363
|
+
# the browser socket directly (its uuid is minted fresh on every Chrome start)
|
|
364
|
+
CDP_BROWSER_WS=ws://127.0.0.1:9222/devtools/browser/<uuid> cdp list_pages
|
|
365
|
+
|
|
366
|
+
# or name the profile, and the uuid is read from its DevToolsActivePort file
|
|
367
|
+
CDP_USER_DATA_DIR="$HOME/Library/Application Support/Google/Chrome" cdp list_pages
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
**The one-target-per-call guarantee still holds.** Discovery is one `Target.getTargets` — metadata only, it attaches to nothing — so a browser with hundreds of tabs costs one round trip, not one attach per tab. Each call then attaches to the one target it named and detaches on close. Every command still carries `CDP_TIMEOUT_MS`, per command id rather than per socket, so a wedged tab rejects at the bound and the shared socket stays clear for everyone else. `bun run browser-ws:wedge` proves exactly that: it blackholes one tab, then measures a witness tab, `list_pages`, and a freshly opened tab on the same socket.
|
|
371
|
+
|
|
372
|
+
```bash
|
|
373
|
+
bun run browser-ws:smoke # drives discovery + per-tab work on a browser-ws-only endpoint
|
|
374
|
+
TABS=200 bun run browser-ws:smoke
|
|
375
|
+
bun run browser-ws:wedge # one stuck tab must not wedge the shared socket
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
Both spawn their own disposable headless Chrome and front it with a proxy that removes exactly what the runtime-toggle mode removes (`test/browser-ws-only-proxy.ts`), because the real mode cannot be requested with a flag and puts a consent dialog in front of every client. They never look for a Chrome you are already running.
|
|
379
|
+
|
|
341
380
|
## Structured page extraction (`extract_page`)
|
|
342
381
|
|
|
343
382
|
`extract_page` turns a page into **schema-conformant JSON** instead of prose: it grabs the target page's HTML, cleans it (scripts, styles, hidden elements and other non-content noise stripped), and sends it to an OpenAI-compatible `/chat/completions` endpoint along with your JSON Schema, returning JSON that matches the schema — fields you name, not a paragraph you have to parse. A `selector` scopes extraction to one subtree (piercing open shadow roots), so you can extract the article or the table rather than the whole page.
|
|
@@ -440,27 +479,41 @@ This coordinates and recovers **around** Firefox's one-session limit; it does no
|
|
|
440
479
|
|
|
441
480
|
**Attaching is not relaunching.** The one thing that is genuinely impossible is handing a debug port to an *already-running* Firefox process after the fact: the `--remote-debugging-port` flag only takes effect on a process's original launch, so relaunching the `firefox` binary against a running instance hands off to it and exits silently, opening no port (verified against Firefox 153.0.3). That is a real, narrow limitation of the Firefox binary itself. It is not the same claim as "Firefox cannot be attached to" — a Firefox that was launched *with* the debug port open, whether by this toolkit or by your own hand, exposes a plain BiDi endpoint that any number of fresh clients can connect to later, which is exactly what `--connect`/`CDP_FIREFOX_ENDPOINT` does.
|
|
442
481
|
|
|
443
|
-
**Tool availability is filtered per backend**, not per call: `tools/list` (MCP) and `--list`/`--capabilities` (CLI) only ever advertise a tool the selected browser can actually run. A tool is never listed and then thrown from at call time. On the MCP server a second filter composes on top: a tool is listed only when the backend can run it *and* the startup profile includes it — backend availability first, `CDP_TOOL_PROFILE` second (see [Progressive disclosure](#progressive-disclosure)). Under Firefox,
|
|
482
|
+
**Tool availability is filtered per backend**, not per call: `tools/list` (MCP) and `--list`/`--capabilities` (CLI) only ever advertise a tool the selected browser can actually run. A tool is never listed and then thrown from at call time. On the MCP server a second filter composes on top: a tool is listed only when the backend can run it *and* the startup profile includes it — backend availability first, `CDP_TOOL_PROFILE` second (see [Progressive disclosure](#progressive-disclosure)). Under Firefox, five capability areas are absent because WebDriver BiDi (as of Firefox 160) has no equivalent domain:
|
|
444
483
|
|
|
445
484
|
- `performance_start_trace`, `performance_stop_trace`, `performance_analyze_insight`, `performance_trace` (needs `trace.performance`)
|
|
446
485
|
- `take_heapsnapshot` (needs `heap.snapshot`)
|
|
447
486
|
- `lighthouse_audit` (needs `audit.lighthouse`)
|
|
448
487
|
- `start_screen_recording`, `stop_screen_recording` (needs `capture.screencast`): BiDi has no streamed-frame primitive at all, only the one-shot `browsingContext.captureScreenshot`.
|
|
449
|
-
- `
|
|
450
|
-
|
|
488
|
+
- `focus_emulation`, `click_focus_gated` (need `emulate.focus`): no BiDi command keeps a background tab reporting focus.
|
|
489
|
+
|
|
490
|
+
**Firefox 160 closed several gaps (cdp-toolkit 3.3.0).** Each was measured against a real Firefox 160.0 and is version-gated: on an older Firefox the same call returns an `unsupported` error naming the Firefox version it needs, never a half-applied change.
|
|
491
|
+
|
|
492
|
+
| Capability | Tools / parameters | Firefox-side behavior to know |
|
|
493
|
+
|---|---|---|
|
|
494
|
+
| `input.raw` | `dispatch_mouse` | A `down` in one call stays held for an `up` in a later call. Each event is preceded by a move to its point, so expect an extra `mousemove`. `clickCount` is ignored (BiDi has no such field). |
|
|
495
|
+
| `input.modifierClick` | `click` `modifiers` | Alt/Control/Meta/Shift reach the page. On macOS, Firefox treats Ctrl+click as a context-menu gesture: the page gets `mousedown` + `contextmenu` with `ctrlKey`, and no `click`. |
|
|
496
|
+
| `emulate.mediaFeatures` | `emulate` `mediaFeatures` | e.g. `prefers-color-scheme`. A media *type* (`media: "print"`) is refused `unsupported`. |
|
|
497
|
+
| `emulate.networkConditions` | `emulate` `networkConditions` | **Offline only.** Any latency/throughput throttle is refused `unsupported`, never silently ignored. |
|
|
498
|
+
| `browser.downloads` | `wait_for_download` | Same arguments and result as Chrome. Firefox stays redirected only until the call returns or times out, then later downloads go back to the profile's normal folder, so arm before *every* download. While armed, a download the user starts in that Firefox is redirected too. |
|
|
499
|
+
| `browser.permissions` | `grant_permissions` | Firefox grants **persist in the profile** across sessions, so `reset` and session shutdown put back the state the page saw before the first grant. A process killed with `SIGKILL` leaves its grants behind. Names are mapped to W3C names (`audioCapture`→`microphone`, `videoCapture`→`camera`, `durableStorage`→`persistent-storage`, `wakeLockScreen`→`screen-wake-lock`, plus `geolocation`, `notifications`, `midi`, `midiSysex`). Anything else (e.g. `clipboardReadWrite`, which Firefox rejects) is refused `unsupported`. Only the named permissions are touched, unlike Chrome's grant. |
|
|
500
|
+
| `network.responseBodyPostHoc` | `get_network_request` `includeBody` | A body the page fetched *before* the body call is readable by request id, with no capture call first; the id must come from a network event this process observed (`list_network_requests`, `get_network_request`). A request that predates this process has no id here. One collector is armed when the session is created (2 MB cap per response). Firefox owns the total budget (measured ~100–200 MB) and evicts the oldest bodies first; an evicted or unknown body is a clear error, never empty text. Chrome still does not have this. `CDP_FIREFOX_BODY_COLLECTOR=off` turns the collector off. |
|
|
501
|
+
| `screenshot.scale` | `take_screenshot` `scale` | Rides `browsingContext.setViewport {devicePixelRatio}` for one capture, then restores the previous ratio. |
|
|
502
|
+
|
|
503
|
+
Still unimplemented in Firefox 160 (the commands return `unknown command`): forced-colors emulation, disabling scripting, touch emulation, and `locateNodes` by `innerText`.
|
|
451
504
|
|
|
452
|
-
Everything else, including `mock_request`/`list_mocks`/`clear_mocks` (Firefox's `network.addIntercept` covers the same fake-backend use case as Chrome's `Fetch` domain), the `claim_page`/`release_page`/`list_leases` lease group, the `extract_page` extraction tool (its page work runs entirely through the driver's evaluate, no CDP-only capability), and the new `scroll` tool (Chrome dispatches `Input.dispatchMouseEvent{type:'mouseWheel'}`, Firefox uses BiDi's `wheel` input source — both live-verified), is available under both backends:
|
|
505
|
+
Everything else, including `mock_request`/`list_mocks`/`clear_mocks` (Firefox's `network.addIntercept` covers the same fake-backend use case as Chrome's `Fetch` domain), the `claim_page`/`release_page`/`list_leases` lease group, the `extract_page` extraction tool (its page work runs entirely through the driver's evaluate, no CDP-only capability), and the new `scroll` tool (Chrome dispatches `Input.dispatchMouseEvent{type:'mouseWheel'}`, Firefox uses BiDi's `wheel` input source — both live-verified), is available under both backends: 38 of the 48 tools on Firefox 160 or newer. Under `CDP_BROWSER=firefox` the MCP server's `CDP_TOOL_PROFILE=full` listing is therefore 40 entries — those 38 plus `search_tools` and `call_tool` — while the 3.0 default (`gateway`) lists 7 under either browser; the profile filter applies after this backend filter. One asymmetry to know before expecting Chrome-style concurrency: the lease group fences *tabs* on both backends, but Firefox permits only **one BiDi session per browser instance**, so multiple agent PROCESSES under Firefox share that one session rather than opening independent ones the way Chrome's unlimited CDP connections allow — coordinated by the cross-process session lease and, by default, joined through the BiDi multiplexer above, so sharing no longer means waiting a turn — see "Parallel tabs" below.
|
|
453
506
|
|
|
454
507
|
**Honest capability gaps, not oversold parity:**
|
|
455
508
|
|
|
456
|
-
- **No accessibility tree.** `take_snapshot` under Chrome reads a native a11y tree (`Accessibility.getFullAXTree`). Firefox
|
|
509
|
+
- **No accessibility tree.** `take_snapshot` under Chrome reads a native a11y tree (`Accessibility.getFullAXTree`). Firefox's BiDi (still as of 160) has no equivalent domain, so the Firefox snapshot is a DOM-heuristic walk that infers roles from tag/attribute conventions. It is good enough to find and click things; it is not a substitute for a real accessibility audit.
|
|
457
510
|
- **No atomic text insert.** Chrome's `fill`/`type_text` commit a value in one `Input.insertText` call. BiDi has no equivalent primitive, so Firefox always synthesizes real per-character keystrokes via `input.performActions` (one `<select>` exception: an exact-match value/index assignment, since typeahead-by-first-letter cannot reliably commit an arbitrary option).
|
|
458
|
-
- **
|
|
511
|
+
- **Partial emulation.** Viewport size/DPR, `userAgent`, media features and offline mode are applied (the last two on Firefox 160+). CPU throttling and latency/throughput throttling are not available: BiDi has no command for either.
|
|
459
512
|
- **No tracing, heap snapshots, or Lighthouse.** See the capability list above; there is no BiDi equivalent for any of the three.
|
|
460
|
-
- **`locate.text` is not available** (Firefox
|
|
461
|
-
- **
|
|
462
|
-
- **No real HTML5 drag-and-drop mode.** `drag`'s `mode:"html5"` requires capability `input.html5Drag` and is rejected with a clear error under Firefox; `mode:"mouse"` (the default) works on both.
|
|
463
|
-
- **
|
|
513
|
+
- **`locate.text` is not available** (Firefox 160's `browsingContext.locateNodes` still rejects the `innerText` locator type as unsupported), unlike Chrome, which has it via `DOM.performSearch`.
|
|
514
|
+
- **Modifier-key clicks need Firefox 160.** On an older Firefox a non-empty `modifiers` array throws rather than being silently dropped. A plain click works on every version.
|
|
515
|
+
- **No real HTML5 drag-and-drop mode.** `drag`'s `mode:"html5"` requires capability `input.html5Drag` and is rejected with a clear error under Firefox; `mode:"mouse"` (the default) works on both. Measured on Firefox 160.0: a BiDi pointer drag fires `dragstart`, `dragenter` and `dragover`, but never `drop` or `dragend`, so the capability stays undeclared.
|
|
516
|
+
- **Screenshot `scale` needs Firefox 160; band tiling is a Chrome-only workaround Firefox has no use for.** `scale` (`screenshot.scale`) rides a one-capture `devicePixelRatio` change on Firefox 160+ (see the table above); on older Firefox it is refused and the refusal points at `emulate {deviceScaleFactor}` + a scale-1 capture instead. `tile:true` (`screenshot.tile`) is **not** a Firefox gap: measured against Firefox 153.0.3, `take_screenshot --fullPage true` on a 20,000px-tall page returned one 1366×20000 PNG at scale 1 from a single BiDi `captureScreenshot(origin:"document")` call — verified complete top-to-bottom (a marker at y=0, a marker at y=20000, an unbroken ruler through the middle, no truncation). Chrome's banding exists solely to route around its 16384-device-px encode cap; Firefox has no such cap, so there is nothing for tiling to work around, and auto-tiling correctly never fires there — a Firefox `fullPage` capture is already the whole page in one shot, however long. **`renderWidth`/`renderHeight` (`screenshot.renderSize`) are available on both backends** — that one is not a gap.
|
|
464
517
|
|
|
465
518
|
## The tools (29 parity + 19 superset = 48)
|
|
466
519
|
|
|
@@ -481,11 +534,11 @@ The 29 parity tools are 1:1 with `chrome-devtools-mcp`; the 19 superset tools (`
|
|
|
481
534
|
| `set_cookie` *(superset)* | `Network.setCookie` | Writes one cookie, httpOnly and secure ones included, which `document.cookie` cannot create. Either `url` or `domain` is required and the call is refused with an error when neither is given. Chrome's `success:false` refusal is raised as an error rather than reported as a write. Answers `{set:true,target}` and never echoes the value back. `path` is passed through as given, never defaulted. |
|
|
482
535
|
| `delete_cookies` *(superset)* | `Network.deleteCookies` | Removes the named cookie, httpOnly ones included. Requires `name` plus `url` or `domain`, so a name-only call cannot sweep the store; optional `path` narrows further. Answers `{deleted:true,target}` with no count, because neither protocol reports one; read `list_cookies` before and after for a real count. |
|
|
483
536
|
| `take_snapshot` | `Accessibility.getFullAXTree` | uid is the raw `backendDOMNodeId` (stateless, non-sequential). Full tree in one shot; frames flattened. `interactiveOnly` is a toolkit addition. |
|
|
484
|
-
| `click` | `Input.dispatchMouseEvent` | No implicit auto-wait/retry; resolves and acts once; re-snapshot between steps. `clickCount:3` triple-clicks (selects a paragraph/line in most editors). `modifiers` (Alt/Control/Meta/Shift) holds keys for the press and release, e.g. a shift-click —
|
|
537
|
+
| `click` | `Input.dispatchMouseEvent` | No implicit auto-wait/retry; resolves and acts once; re-snapshot between steps. `clickCount:3` triple-clicks (selects a paragraph/line in most editors). `modifiers` (Alt/Control/Meta/Shift) holds keys for the press and release, e.g. a shift-click — On Firefox it needs Firefox 160+ (`input.modifierClick`); an older Firefox throws rather than dropping the keys. |
|
|
485
538
|
| `hover` | `Input.dispatchMouseEvent` (`mouseMoved`) | Same single-shot model as `click`. |
|
|
486
539
|
| `scroll` *(superset)* | Chrome: `Input.dispatchMouseEvent{type:'mouseWheel'}`; Firefox: BiDi's `wheel` input source | Anchor at `uid`/`selector`/`x`+`y`, or the viewport center if all three are omitted; an element anchor is scrolled into view first. At least one of `deltaX`/`deltaY` is required (positive `deltaY` scrolls down, positive `deltaX` scrolls right — wheel convention). Returns `{x,y,deltaX,deltaY,target}`. Works on both backends. |
|
|
487
540
|
| `drag` | Chrome: `Input.dispatchMouseEvent` (press→move→release), or `mode:"html5"`: `Input.setInterceptDrags` + `Input.dispatchDragEvent` | `mode:"mouse"` (default) sends a synthetic mouse drag; Chrome does turn this into a real HTML5 drag too, but which `dragenter`/`dragover`/`drop` events reach the page depends on where the interpolated pointer path lands — at the default `steps:2`, a standard HTML5 drop zone (`preventDefault` inside `dragover`) sees zero `dragover` events and refuses the drop. `mode:"html5"` replays the page's own drag data as `dragEnter`/`dragOver`/`drop` exactly at the destination, so it works regardless of pointer path — **Chrome-only** (`input.html5Drag`), rejected with a clear error under Firefox. `steps` (default 2) sets the interpolated-move count for mouse mode. Destination is `to:{uid\|selector\|x,y}` or a new `by:{dx,dy}` offset (sliders, map panning); exactly one of `to`/`by` is required. |
|
|
488
|
-
| `dispatch_mouse` *(superset)* | `Input.dispatchMouseEvent` (one event per call) | The raw primitive: dispatch exactly one `move`/`down`/`up` at absolute viewport coordinates (`x`/`y` required on every call — CDP has no notion of a "current pointer position"). Compose your own move/down/move/up sequences for anything a physical mouse can do that `click`/`drag`'s fixed sequences can't: canvas drag-painting, marquee/rubber-band selection, a custom-hit-testing widget. Takes the same `button`/`clickCount`/`modifiers` as `click`.
|
|
541
|
+
| `dispatch_mouse` *(superset)* | `Input.dispatchMouseEvent` (one event per call) | The raw primitive: dispatch exactly one `move`/`down`/`up` at absolute viewport coordinates (`x`/`y` required on every call — CDP has no notion of a "current pointer position"). Compose your own move/down/move/up sequences for anything a physical mouse can do that `click`/`drag`'s fixed sequences can't: canvas drag-painting, marquee/rubber-band selection, a custom-hit-testing widget. Takes the same `button`/`clickCount`/`modifiers` as `click`. Firefox 160+ too (`input.raw`, via `input.performActions`; `clickCount` ignored there), refused `unsupported` on an older Firefox. |
|
|
489
542
|
| `focus_emulation` *(superset)* | `Emulation.setFocusEmulationEnabled` | Makes the tab *believe* it is focused (`document.hasFocus()`→true, visibility stays `visible`, focus events fire) while the real OS window stays put — no focus theft. The primitive that unlocks focus-gated UI (a button a site disables unless its tab is focused, e.g. the Claude Code OAuth **Authorize** button) on a background tab. Call with `enabled:false` to restore. **Chrome-only** (`emulate.focus`): BiDi's emulation module has no focus primitive, so absent from `tools/list` under `--browser firefox`. |
|
|
490
543
|
| `click_focus_gated` *(superset)* | `Emulation.setFocusEmulationEnabled` + `Input.dispatchMouseEvent` | The one-call compose: enable focus emulation, poll until the button (CSS selector or exact visible-text match, e.g. `"Authorize"`) exists **and** is enabled, deliver a **trusted** click (`isTrusted:true` — a content script's synthesized events can never satisfy a focus gate), then restore emulation (always, unless `keepFocus`, even on throw). Timeout error names the failure mode ("never located" vs "found but stayed disabled"). Same **Chrome-only** gap as `focus_emulation`. |
|
|
491
544
|
| `fill` | `Input.insertText` | Atomic paste-like commit, not per-character keystrokes. |
|
|
@@ -493,7 +546,7 @@ The 29 parity tools are 1:1 with `chrome-devtools-mcp`; the 19 superset tools (`
|
|
|
493
546
|
| `type_text` | `Input.insertText` | Appends (does not clear first); insertText, not per-key. |
|
|
494
547
|
| `press_key` | `Input.dispatchKeyEvent` | Curated named-key table + single chars; not the full Puppeteer KeyInput enum. |
|
|
495
548
|
| `upload_file` | `DOM.setFileInputFiles` | Requires a resolvable `<input type=file>` (uid or selector). |
|
|
496
|
-
| `take_screenshot` | `Page.captureScreenshot` (+ `Page.getLayoutMetrics` on **every** capture) | Full-page uses `captureBeyondViewport` + a layout-metrics clip. `scale` (>0, ≤8
|
|
549
|
+
| `take_screenshot` | `Page.captureScreenshot` (+ `Page.getLayoutMetrics` on **every** capture) | Full-page uses `captureBeyondViewport` + a layout-metrics clip. `scale` (>0, ≤8; Firefox 160+ via a one-capture `devicePixelRatio`) multiplies output pixels for one capture: output px = `ceil(css × scale × devicePixelRatio)`, and the page is never told (`devicePixelRatio`/`innerWidth` are unmoved). `renderWidth`+`renderHeight` (**both backends**, required together) emulate a viewport for one capture and restore it after — media queries flip, so this is how you shoot a responsive page at 1920×1080 from a tab that isn't. Chrome cannot encode past **16384 device px per side** and does not refuse politely there, so past the cap the capture is taken as vertical bands and stitched losslessly into one PNG (`tile`, auto by default; `tiled`/`bands` on the result): a 140,982 CSS px page returns 2780×281964 px in 18 bands instead of hanging and wedging the tab. Banding is vertical only (an over-wide projection is refused, not split), PNG-only, and never with `returnBase64`; content the page loads only on real scroll renders blank past the first viewport. `width`/`height` are decoded from the encoded bytes and omitted when undecodable. |
|
|
497
550
|
| `start_screen_recording` *(superset)* | `Page.startScreencast` / `Page.screencastFrame` / `Page.screencastFrameAck` | **Toolkit addition; chrome-devtools-mcp has no screen-recording tool.** Opens a persistent per-target connection and spools frames to a ledger on disk; pairs with `stop_screen_recording` in the SAME process, for the same cross-process reason as `performance_start_trace`. ffmpeg is probed here so a missing encoder fails before a recording is captured. Chrome only: absent from `tools/list` under `--browser firefox` (needs `capture.screencast`, which BiDi has no primitive for). |
|
|
498
551
|
| `stop_screen_recording` *(superset)* | `Page.stopScreencast` (+ ffmpeg encode) | Assembles the spooled frames into an H.265 (`hevc_videotoolbox`, falling back to `h264_videotoolbox` → `libx265` → `libx264`) MP4 using per-frame durations from the capture ledger, coalesced onto ffmpeg's 40ms concat-demuxer grid. Returns `{path,bytes,durationMs,frameCount,encodedFrames,codec,encoder,width,height,droppedFrames,target}` (`frameCount` captured vs. `encodedFrames` in the video). On an ffmpeg failure the spool is kept and the exact re-run command is named in the error. |
|
|
499
552
|
| `emulate` | `Emulation.*` / `Network.emulateNetworkConditions` | Stateless: UA/CPU/media/network overrides reset when the per-call connection closes. No named device presets. |
|
|
@@ -515,8 +568,8 @@ The 29 parity tools are 1:1 with `chrome-devtools-mcp`; the 19 superset tools (`
|
|
|
515
568
|
| `claim_page` *(superset)* | `Target.createTarget` + lease file | Opens a fresh tab and claims it (no `target`/`targetId`), or takes over a tab that is already open (`target`, any selector, or the exact-id `targetId`) and returns an opaque lease token plus `opened` (true only when this call created the tab). Never steals a tab another live process holds. Also returns `humanActiveMs` (ms since input this server did not dispatch; `null` means no data, never "no human") and, on a takeover of a tab a human used within the last 30s, a `contention` warning — the claim is never refused for it. MCP only; the CLI refuses it. The `search_tools` and `call_tool` meta-tools are likewise MCP-only. |
|
|
516
569
|
| `release_page` *(superset)* | lease file | Gives a lease back via `lease` (the token) or `target` (a selector, for a lease the gate auto-acquired and so never handed out a token for). Idempotent. Closes the tab by default when this toolkit's creation ledger says it opened it; leaves a merely-claimed tab open. Override either way with `close`. |
|
|
517
570
|
| `list_leases` *(superset)* | lease file | Who holds what, with pid liveness and reclaimability, plus computed `idleMs`/`expiresAt` and, where the tab's beacon answers, `humanActiveMs` (absent, not null, when there's no answer). Needs no token; never returns the nonce. A lease file that could not be read or parsed is reported as an `unreadable` row instead of being skipped (with `idleMs`/`expiresAt` omitted). Under `CDP_REQUIRE_LEASE` also reaps abandoned agent tabs, reporting closures in an additive `reaped` array. |
|
|
518
|
-
| `wait_for_download` *(superset)* | `Browser.setDownloadBehavior` + `Browser.downloadWillBegin`/`downloadProgress` on a standing browser-endpoint connection | Waits for a download to finish and returns it as a real file on disk: `{path,suggestedFilename,bytes,url,target}`. **Ordering rule, not optional:** call `wait_for_download{arm:true}` *before* the click that starts the download, then click, then call `wait_for_download` again to collect it — arming this late is not a preference, it's because Chrome reverts the download-behavior override the instant the arming client disconnects, and denies an unarmed download outright. **Browser-global side effect:** while armed, *every* download in the browser is redirected into the toolkit's downloads directory. **MCP-server only:** the arm lives on a connection this server process holds open; the one-shot CLI's connection dies with the process, so nothing is captured there.
|
|
519
|
-
| `grant_permissions` *(superset)* | `Browser.grantPermissions` / `Browser.resetPermissions` on the same standing connection | Grants permissions (`geolocation`, `notifications`, `clipboardReadWrite`, ...) for an origin up front, so a page doesn't show a prompt no agent can click. Keyed by **origin**, not tab — every tab on that origin is affected, including ones opened later. `reset:true` clears this server's previous grants first (or instead); note CDP's reset is not origin-scoped, so it clears every origin at once. Same MCP-server-only reasoning as `wait_for_download`: Chrome discards the grant the moment the granting connection closes.
|
|
571
|
+
| `wait_for_download` *(superset)* | `Browser.setDownloadBehavior` + `Browser.downloadWillBegin`/`downloadProgress` on a standing browser-endpoint connection | Waits for a download to finish and returns it as a real file on disk: `{path,suggestedFilename,bytes,url,target}`. **Ordering rule, not optional:** call `wait_for_download{arm:true}` *before* the click that starts the download, then click, then call `wait_for_download` again to collect it — arming this late is not a preference, it's because Chrome reverts the download-behavior override the instant the arming client disconnects, and denies an unarmed download outright. **Browser-global side effect:** while armed, *every* download in the browser is redirected into the toolkit's downloads directory. **MCP-server only:** the arm lives on a connection this server process holds open; the one-shot CLI's connection dies with the process, so nothing is captured there. Firefox 160+ too (`browser.setDownloadBehavior`), where each call re-arms and the profile's normal download folder is restored when it returns. |
|
|
572
|
+
| `grant_permissions` *(superset)* | `Browser.grantPermissions` / `Browser.resetPermissions` on the same standing connection | Grants permissions (`geolocation`, `notifications`, `clipboardReadWrite`, ...) for an origin up front, so a page doesn't show a prompt no agent can click. Keyed by **origin**, not tab — every tab on that origin is affected, including ones opened later. `reset:true` clears this server's previous grants first (or instead); note CDP's reset is not origin-scoped, so it clears every origin at once. Same MCP-server-only reasoning as `wait_for_download`: Chrome discards the grant the moment the granting connection closes. Firefox 160+ too (`permissions.setPermission`), with the name mapping and persistence notes in the Firefox section. |
|
|
520
573
|
| `extract_page` *(superset)* | `Runtime.evaluate` (clean the HTML in-page) → **non-CDP** `fetch` of an OpenAI-compatible `/chat/completions` endpoint | Sends the page's cleaned HTML plus your JSON Schema to the endpoint and returns **schema-conformant JSON** instead of prose. **The default endpoint is loopback** — llm-ferry at `http://127.0.0.1:8090/v1`, model `schematron` — so page content stays on this machine unless the operator points `baseUrl`/`CDP_EXTRACT_BASE_URL` elsewhere (see [Structured page extraction](#structured-page-extraction-extract_page)). The extraction *instructions* live in the schema's property `description`s; a schema whose properties carry none is rejected up front. Over `maxChars` (default 300000) it fails with `html_too_large` rather than truncating — shrink with `selector`/`clean:"aggressive"` or raise the cap. `usage` tokens (and cost, when the endpoint reports it) come back inline on every call; `savePath` keeps large payloads out of the transcript. `prompt:"schematron"` (or `CDP_EXTRACT_PROMPT`) swaps the default HTML-only user message for the open-weight Schematron model-card prompt with the schema inline — needed when `baseUrl` points at a locally served open-weight Schematron. Works on both backends. |
|
|
521
574
|
|
|
522
575
|
## Driving MV3 extensions
|