cdp-toolkit 3.2.0 → 3.4.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 +31 -0
- package/CONTRACT.md +1 -1
- package/README.md +35 -19
- package/dist/bidi/mux-daemon.js +263 -24
- package/dist/cli.js +633 -80
- package/dist/index.js +144 -38
- package/dist/mcp.js +641 -85
- package/package.json +1 -1
- package/src/bidi/driver.ts +367 -60
- package/src/bidi/protocol.ts +27 -9
- package/src/bidi-browser-tools.ts +366 -0
- package/src/bidi-tools.ts +29 -2
- package/src/cdp/driver.ts +119 -18
- package/src/driver.ts +42 -10
- package/src/firefox-tools.ts +6 -3
- package/src/frontApp.ts +62 -0
- package/src/leases-tools.ts +3 -2
- package/src/manifest.ts +17 -5
- package/src/origins.ts +3 -2
- package/src/policy.ts +4 -3
- package/src/shared-tools.ts +47 -24
- package/src/toolDocs.ts +18 -15
- package/src/tools/dispatch-mouse.ts +6 -1
- package/src/tools/downloads.ts +5 -6
- package/src/tools/permissions.ts +5 -5
- package/src/version.ts +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,37 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [3.4.0] - 2026-11-18
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
|
|
14
|
+
- **Nothing the toolkit does implicitly takes focus or switches the user's visible tab any more.** This is a behavior change:
|
|
15
|
+
- `new_page`, and `claim_page` when it opens a fresh tab, now open the tab in the background (CDP `Target.createTarget` `background:true`; Firefox `browsingContext.create` `background:true`). Before, Chromium browsers foregrounded every new tab. New optional `focus` boolean (default false) opens it in the foreground as before. `claim_page` ignores `focus` on takeover.
|
|
16
|
+
- On macOS a background `Target.createTarget` still brings the browser app in front of the user's current app (measured on Vivaldi: the active tab stays put, the window comes forward). `new_page` / `claim_page` (opening a background tab) and `close_page` (closing a tab, which raises the app too) now note the frontmost app first and put it back if it lost the front (`lsappinfo` to read, System Events to restore). `CDP_RESTORE_FRONT_APP=0` turns this off; it never runs off macOS or with `focus:true`.
|
|
17
|
+
- `select_page` now only writes the selected-state file by default and no longer sends `Target.activateTarget` / `browsingContext.activate`. New optional `focus` boolean (default false) raises the tab as before. The result gains `focused`.
|
|
18
|
+
|
|
19
|
+
### Fixed
|
|
20
|
+
|
|
21
|
+
- **Text input on a background tab (Chrome).** A background tab that never had a trusted click receives no trusted keyboard input at all (measured on Vivaldi: `Input.insertText` and `Input.dispatchKeyEvent` changed nothing and fired no keydown, with or without focus emulation), so `fill` reported success while the field stayed empty. `fill`, `fill_form` and `type_text` still try the trusted commit first, then verify it (text changed, or a `beforeinput`/`input` event fired) and fall back in-page: `document.execCommand('insertText')`, else the native value setter plus `input`/`change` events. The result carries `inputPath` (`inputPaths` for `fill_form`) only when the fallback ran or `type_text` skipped the element (disabled, read-only, non-text); a fallback that changes nothing is an error. `press_key` fakes nothing: on a definite miss the result says `delivered:false` with a note. A trusted `click` on the page gives the tab focus, after which trusted keys land (measured). Firefox is unchanged and not measured live.
|
|
22
|
+
- **`fill` / `fill_form` on a disabled or read-only field.** The clear step ran before the edit check, so the field's value was wiped and the result still said `filled:true` (`inputPath:"skipped"`). Both drivers now refuse such a field before touching it, with a `page-error` ("cannot fill a readonly field: it was left unchanged"); `fill_form` stops at that field.
|
|
23
|
+
|
|
24
|
+
## [3.3.0] - 2026-11-16
|
|
25
|
+
|
|
26
|
+
### Added
|
|
27
|
+
|
|
28
|
+
- **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).
|
|
29
|
+
- `dispatch_mouse` (`input.raw`), with a press held across calls. `clickCount` is ignored on Firefox.
|
|
30
|
+
- `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`.
|
|
31
|
+
- `emulate` `mediaFeatures` and offline `networkConditions`. Latency/throughput throttling and a media type are refused `unsupported`, never ignored.
|
|
32
|
+
- `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`.
|
|
33
|
+
- `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.
|
|
34
|
+
- `take_screenshot` `scale` via a one-capture `devicePixelRatio` change that is then restored.
|
|
35
|
+
- `CDP_FIREFOX_BODY_COLLECTOR=off` skips the session-wide response-body collector.
|
|
36
|
+
|
|
37
|
+
### Notes
|
|
38
|
+
|
|
39
|
+
- 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`).
|
|
40
|
+
|
|
10
41
|
## [3.2.0] - 2026-11-10
|
|
11
42
|
|
|
12
43
|
### Added
|
package/CONTRACT.md
CHANGED
|
@@ -166,7 +166,7 @@ A `Uid` **is** a CDP `backendDOMNodeId` (a number). This makes refs stateless:
|
|
|
166
166
|
|
|
167
167
|
| Module file | Tools (MCP name → fn) | Notes |
|
|
168
168
|
|---|---|---|
|
|
169
|
-
| `src/tools/pages.ts` | `list_pages`→`listPages`, `new_page`→`newPage`, `close_page`→`closePage`, `select_page`→`selectPage` | **Browser endpoint** (`openBrowser`, `Target.*`). `new_page`=`Target.createTarget
|
|
169
|
+
| `src/tools/pages.ts` | `list_pages`→`listPages`, `new_page`→`newPage`, `close_page`→`closePage`, `select_page`→`selectPage` | **Browser endpoint** (`openBrowser`, `Target.*`). `new_page`=`Target.createTarget` with `background:true` (foreground only on `focus:true`). `close_page`=`Target.closeTarget`. `select_page`=write selected state file, plus `Target.activateTarget` only on `focus:true`. `list_pages` may reuse `listTargets()`. |
|
|
170
170
|
| `src/tools/navigation.ts` | `navigate_page`→`navigatePage`, `wait_for`→`waitForText` (export as `waitFor` too) | `Page.enable` then `Page.navigate` (or `Page.reload` + `Page.getFrameTree` when `reload:true`; `ignoreCache:true` = hard reload); await `Page.frameStoppedLoading`/`Page.loadEventFired`. `wait_for` polls `Runtime.evaluate` for `document.body.innerText.includes(text)` with timeout, OR waits for a given event. |
|
|
171
171
|
| `src/tools/evaluate.ts` | `evaluate_script`→`evaluateScript` | `Runtime.enable` + `Runtime.evaluate` (`returnByValue`, `awaitPromise`). Support optional `args` via `Runtime.callFunctionOn` on a uid/selector. Surface `exceptionDetails` as thrown error. |
|
|
172
172
|
| `src/tools/snapshot.ts` | `take_snapshot`→`takeSnapshot` **+ export `resolveUid`** | a11y tree + ref scheme above. |
|
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
|
|
@@ -243,6 +243,7 @@ await TOOLS.navigate_page({ target: "index:0", url: "https://example.com" });
|
|
|
243
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. |
|
|
244
244
|
| `CDP_ARTIFACT_DIR` | `/tmp/cdp-toolkit` | Screenshots, traces, heap snapshots, lighthouse reports, recorder buffers. |
|
|
245
245
|
| `CDP_STATE_DIR` | `/tmp/cdp-toolkit` | `select_page` selected-target file, in-flight trace state. |
|
|
246
|
+
| `CDP_RESTORE_FRONT_APP` | on (macOS only) | `0` stops `new_page` / `claim_page` / `close_page` from putting the user's frontmost app back after a background tab brings the browser forward. |
|
|
246
247
|
| `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. |
|
|
247
248
|
| `CDP_EXTRACT_MODEL` | `schematron` | `extract_page` only. Model name for the extraction endpoint call. |
|
|
248
249
|
| `CDP_EXTRACT_API_KEY` | unset | `extract_page` only. Bearer token for the endpoint. Never logged and redacted from every error; the response never contains it. |
|
|
@@ -257,6 +258,7 @@ await TOOLS.navigate_page({ target: "index:0", url: "https://example.com" });
|
|
|
257
258
|
| `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. |
|
|
258
259
|
| `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. |
|
|
259
260
|
| `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). |
|
|
261
|
+
| `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. |
|
|
260
262
|
| `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). |
|
|
261
263
|
|
|
262
264
|
## Progressive disclosure
|
|
@@ -478,27 +480,41 @@ This coordinates and recovers **around** Firefox's one-session limit; it does no
|
|
|
478
480
|
|
|
479
481
|
**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.
|
|
480
482
|
|
|
481
|
-
**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,
|
|
483
|
+
**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:
|
|
482
484
|
|
|
483
485
|
- `performance_start_trace`, `performance_stop_trace`, `performance_analyze_insight`, `performance_trace` (needs `trace.performance`)
|
|
484
486
|
- `take_heapsnapshot` (needs `heap.snapshot`)
|
|
485
487
|
- `lighthouse_audit` (needs `audit.lighthouse`)
|
|
486
488
|
- `start_screen_recording`, `stop_screen_recording` (needs `capture.screencast`): BiDi has no streamed-frame primitive at all, only the one-shot `browsingContext.captureScreenshot`.
|
|
487
|
-
- `
|
|
488
|
-
- `wait_for_download`, `grant_permissions` (need `browser.downloads` / `browser.permissions`): both drive Chrome's `Browser.*` domain; WebDriver BiDi has no command to redirect a download or pre-grant a permission.
|
|
489
|
+
- `focus_emulation`, `click_focus_gated` (need `emulate.focus`): no BiDi command keeps a background tab reporting focus.
|
|
489
490
|
|
|
490
|
-
|
|
491
|
+
**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.
|
|
492
|
+
|
|
493
|
+
| Capability | Tools / parameters | Firefox-side behavior to know |
|
|
494
|
+
|---|---|---|
|
|
495
|
+
| `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). |
|
|
496
|
+
| `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`. |
|
|
497
|
+
| `emulate.mediaFeatures` | `emulate` `mediaFeatures` | e.g. `prefers-color-scheme`. A media *type* (`media: "print"`) is refused `unsupported`. |
|
|
498
|
+
| `emulate.networkConditions` | `emulate` `networkConditions` | **Offline only.** Any latency/throughput throttle is refused `unsupported`, never silently ignored. |
|
|
499
|
+
| `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. |
|
|
500
|
+
| `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. |
|
|
501
|
+
| `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. |
|
|
502
|
+
| `screenshot.scale` | `take_screenshot` `scale` | Rides `browsingContext.setViewport {devicePixelRatio}` for one capture, then restores the previous ratio. |
|
|
503
|
+
|
|
504
|
+
Still unimplemented in Firefox 160 (the commands return `unknown command`): forced-colors emulation, disabling scripting, touch emulation, and `locateNodes` by `innerText`.
|
|
505
|
+
|
|
506
|
+
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.
|
|
491
507
|
|
|
492
508
|
**Honest capability gaps, not oversold parity:**
|
|
493
509
|
|
|
494
|
-
- **No accessibility tree.** `take_snapshot` under Chrome reads a native a11y tree (`Accessibility.getFullAXTree`). Firefox
|
|
510
|
+
- **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.
|
|
495
511
|
- **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).
|
|
496
|
-
- **
|
|
512
|
+
- **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.
|
|
497
513
|
- **No tracing, heap snapshots, or Lighthouse.** See the capability list above; there is no BiDi equivalent for any of the three.
|
|
498
|
-
- **`locate.text` is not available** (Firefox
|
|
499
|
-
- **
|
|
500
|
-
- **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.
|
|
501
|
-
- **
|
|
514
|
+
- **`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`.
|
|
515
|
+
- **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.
|
|
516
|
+
- **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.
|
|
517
|
+
- **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.
|
|
502
518
|
|
|
503
519
|
## The tools (29 parity + 19 superset = 48)
|
|
504
520
|
|
|
@@ -509,9 +525,9 @@ The 29 parity tools are 1:1 with `chrome-devtools-mcp`; the 19 superset tools (`
|
|
|
509
525
|
| MCP name | CDP method(s) | Parity notes / gaps |
|
|
510
526
|
|---|---|---|
|
|
511
527
|
| `list_pages` | `GET /json/list` | `all` flag also exposes worker/background and out-of-process (OOPIF) iframe targets; MCP lists only page tabs. A non-page targetId from this listing is accepted by any tool's `target` param as a bare id, and `take_snapshot` marks a cross-origin iframe node with `frame:"<targetId>"` (input inside such an iframe is invisible to the activity beacon — see "Staleness" below — but the frame itself is fully driveable as its own target). Each row additionally carries `origin` (`agent` or `unknown`, never `human`) plus `label`/`createdAt` for tabs this toolkit created, and, for a tab under an active lease of this backend, a `lease:{label,pid,idleMs,expiresAt,stale}` field (unconditional on `probe`). `probe:true` pings each page-type target's renderer (one bounded 500ms `Runtime.evaluate`, never more) and adds `responsive:boolean` plus `humanActiveMs` where that round trip found human-attributed input; a wedged/unreachable tab reports `responsive:false`, never an error for the whole call. Under `CDP_REQUIRE_LEASE` also reaps abandoned agent tabs first (destructively, only once a lease is `CDP_REAP_GRACE_MS` past its TTL — see "Staleness" below), reporting closures in an additive `reaped` array. |
|
|
512
|
-
| `new_page` | `Target.createTarget` (+ lease file) | Returns `{targetId,url}`; does not await navigation (use `navigate_page`). `claim:true` also claims the new tab and returns a `lease` token (`label`/`ttlMs` optional). Under `CDP_REQUIRE_LEASE` the tab is claimed and a `lease` returned even without `claim:true`. |
|
|
528
|
+
| `new_page` | `Target.createTarget` (+ lease file) | Opens the tab in the background (`background:true`), so the user's visible tab and focus stay put; `focus:true` opens it in the foreground. Returns `{targetId,url}`; does not await navigation (use `navigate_page`). `claim:true` also claims the new tab and returns a `lease` token (`label`/`ttlMs` optional). Under `CDP_REQUIRE_LEASE` the tab is claimed and a `lease` returned even without `claim:true`. |
|
|
513
529
|
| `close_page` | `Target.closeTarget` (+ lease file) | Reports `success:true` on the empty result newer Chromium returns. A successful close also releases that tab's lease; a failed close leaves it in place. |
|
|
514
|
-
| `select_page` | `Target.activateTarget`
|
|
530
|
+
| `select_page` | selected-state file (+ `Target.activateTarget` with `focus:true`) | Writes a flat-file selected target and returns `{selected,focused}`; it raises the tab only with `focus:true`; `resolveTarget` does not read it, so `active` still means `index:0` unless a tool opts in. |
|
|
515
531
|
| `navigate_page` | `Page.navigate` / `Page.reload` + load events, or `history:'back'\|'forward'` (Chrome: `Page.getNavigationHistory` + `Page.navigateToHistoryEntry`; Firefox: `browsingContext.traverseHistory`) | Returns `{url,frameId,waitedFor}` (no auto-snapshot; a history move also returns `traversed:'back'\|'forward'`). `waitUntil` supports `load`/`domcontentloaded`. `reload:true` (+ `ignoreCache:true` for a hard reload). `url`/`reload`/`history` are mutually exclusive; going back from the first entry (or forward from the last) is an error naming the direction, never a silent no-op. Works on both backends. |
|
|
516
532
|
| `wait_for` | `Runtime.evaluate` (poll `innerText`) | Text-substring waiting only; throws on timeout rather than returning `{found:false}`. |
|
|
517
533
|
| `evaluate_script` | `Runtime.evaluate` / `callFunctionOn` | No live `page`/element handle; `args` are plain JSON. Main-world context only. Toolkit addition: optional `savePath` writes the value to a JSON file and keeps it out of the response entirely. If `expression` is missing/empty and the call instead carries `function`/`code`/`js`/`script`/`fn`/`body`, the error names the wrong key and points at `expression`. One of four tools that also accept `target: "worker:<substring>"` (Chrome only, capability `worker.targets`) to reach an MV3 extension's background service worker — see "Driving MV3 extensions" below. |
|
|
@@ -519,11 +535,11 @@ The 29 parity tools are 1:1 with `chrome-devtools-mcp`; the 19 superset tools (`
|
|
|
519
535
|
| `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. |
|
|
520
536
|
| `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. |
|
|
521
537
|
| `take_snapshot` | `Accessibility.getFullAXTree` | uid is the raw `backendDOMNodeId` (stateless, non-sequential). Full tree in one shot; frames flattened. `interactiveOnly` is a toolkit addition. |
|
|
522
|
-
| `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 —
|
|
538
|
+
| `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. |
|
|
523
539
|
| `hover` | `Input.dispatchMouseEvent` (`mouseMoved`) | Same single-shot model as `click`. |
|
|
524
540
|
| `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. |
|
|
525
541
|
| `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. |
|
|
526
|
-
| `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`.
|
|
542
|
+
| `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. |
|
|
527
543
|
| `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`. |
|
|
528
544
|
| `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`. |
|
|
529
545
|
| `fill` | `Input.insertText` | Atomic paste-like commit, not per-character keystrokes. |
|
|
@@ -531,7 +547,7 @@ The 29 parity tools are 1:1 with `chrome-devtools-mcp`; the 19 superset tools (`
|
|
|
531
547
|
| `type_text` | `Input.insertText` | Appends (does not clear first); insertText, not per-key. |
|
|
532
548
|
| `press_key` | `Input.dispatchKeyEvent` | Curated named-key table + single chars; not the full Puppeteer KeyInput enum. |
|
|
533
549
|
| `upload_file` | `DOM.setFileInputFiles` | Requires a resolvable `<input type=file>` (uid or selector). |
|
|
534
|
-
| `take_screenshot` | `Page.captureScreenshot` (+ `Page.getLayoutMetrics` on **every** capture) | Full-page uses `captureBeyondViewport` + a layout-metrics clip. `scale` (>0, ≤8
|
|
550
|
+
| `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. |
|
|
535
551
|
| `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). |
|
|
536
552
|
| `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. |
|
|
537
553
|
| `emulate` | `Emulation.*` / `Network.emulateNetworkConditions` | Stateless: UA/CPU/media/network overrides reset when the per-call connection closes. No named device presets. |
|
|
@@ -550,11 +566,11 @@ The 29 parity tools are 1:1 with `chrome-devtools-mcp`; the 19 superset tools (`
|
|
|
550
566
|
| `mock_request` *(superset)* | `Fetch.*` (+ `Page.reload`) | **A fake backend.** Registers a rule on a target's persistent session: fulfill with a canned response, fail, or continue (with optional `delayMs`/`failRate`). Persists across reloads until `clear_mocks`. Request-stage only. Cached requests aren't intercepted (use `reload:true`). |
|
|
551
567
|
| `list_mocks` *(superset)* | `Runtime.evaluate` (liveness probe) | Lists active mock sessions with rules + hit counts; prunes sessions whose tab closed. |
|
|
552
568
|
| `clear_mocks` *(superset)* | `Fetch.disable` | Tears down the resolved target's mock session (or all with `all:true`). |
|
|
553
|
-
| `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
|
|
569
|
+
| `claim_page` *(superset)* | `Target.createTarget` + lease file | Opens a fresh tab in the background and claims it (no `target`/`targetId`; `focus:true` opens it in the foreground), 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. |
|
|
554
570
|
| `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`. |
|
|
555
571
|
| `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. |
|
|
556
|
-
| `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.
|
|
557
|
-
| `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.
|
|
572
|
+
| `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. |
|
|
573
|
+
| `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. |
|
|
558
574
|
| `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. |
|
|
559
575
|
|
|
560
576
|
## Driving MV3 extensions
|