cdp-toolkit 3.4.0 → 3.6.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 +22 -0
- package/CONTRACT.md +1 -0
- package/README.md +54 -18
- package/dist/bidi/mux-daemon.js +184 -5
- package/dist/cli.js +732 -60
- package/dist/index.js +566 -21
- package/dist/mcp.js +763 -51
- package/package.json +4 -3
- package/src/cdp/driver.ts +75 -7
- package/src/cdp/hiddenTabs.ts +285 -0
- package/src/client.ts +12 -3
- package/src/driver.ts +11 -1
- package/src/focusPolicy.ts +16 -0
- package/src/index.ts +8 -1
- package/src/leases-tools.ts +6 -0
- package/src/leases.ts +6 -0
- package/src/manifest.ts +124 -0
- package/src/mcp.ts +4 -0
- package/src/origins.ts +4 -2
- package/src/policy.ts +4 -0
- package/src/shared-tools.ts +46 -10
- package/src/toolDocs.ts +38 -6
- package/src/toolGroups.ts +2 -1
- package/src/tools/screencast.ts +3 -1
- package/src/tools/tab-groups.ts +435 -0
- package/src/types.ts +3 -0
- package/src/version.ts +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,28 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [3.6.0] - 2026-11-20
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- **Tab groups: `list_tab_groups`, `group_tabs`, `ungroup_tabs` (#17).** Read and build the browser's native tab groups (named, colored chips in the tab strip). CDP has no tab-group domain, so the toolkit installs a small MV3 helper extension with `Extensions.loadUnpacked` and calls `chrome.tabGroups` from its service worker; a pinned manifest key keeps its id stable, and every call wakes the worker and replaces a stale copy. Rows carry each tab's CDP `targetId`, so a group's tabs feed straight into the other tools.
|
|
15
|
+
- `group_tabs` selects with exactly one of `tabIds`, `targetIds` or `urlMatch`, creates a group (`title`, `color`, `collapsed`) or adds to one (`groupId`). Chrome moves a multi-window selection into whatever window was focused last, so such a selection is refused unless `windowId` names the target window; moved tabs are reported in `moved`.
|
|
16
|
+
- No focus change: measured on Helium, the frontmost app never changed while grouping and moving tabs across windows.
|
|
17
|
+
- Chrome-family only (new `browser.tabGroups` capability; absent under Firefox). Vivaldi answers the API but keeps its own tab stacks, so `group_tabs` there fails with an error instead of reporting a group that does not exist.
|
|
18
|
+
- The helper stays installed in the browser profile; it needs the browser on the same machine. New `tabs` profile group; the three tools count as mutating for read-only endpoints. `bun run tab-groups:smoke` is the live check.
|
|
19
|
+
|
|
20
|
+
- **`CDP_DENY_FOCUS=1` refuses every tab raise, even an explicit one.** Since 3.4.0 nothing raises a tab implicitly, but `new_page` / `claim_page` `focus:true`, `select_page` `focus:true` and screencast `bringToFront:true` still pull the browser over the user's work when an agent follows a hint to use them. With the switch on they take the background path, and `new_page` / `select_page` return `focusDenied: true`. Default off; output is unchanged unless a raise was refused. The `press_key` not-delivered note now says that `new_page focus:true` raises the browser.
|
|
21
|
+
|
|
22
|
+
## [3.5.0] - 2026-11-18
|
|
23
|
+
|
|
24
|
+
### Added
|
|
25
|
+
|
|
26
|
+
- **Hidden tabs: `new_page` without any flash of the browser (opt-in, `CDP_HIDDEN_TABS=1`).** 3.4.0's restore puts the user's app back, but on macOS the browser still comes forward for a moment: every visible `Target.createTarget` variant activated Vivaldi in a tight `lsappinfo front` sample (`background`, `focus:false`, `newWindow`, a minimized new window, `window.open` from a background tab). Only `hidden:true` targets stayed clean. With `CDP_HIDDEN_TABS=1` in the MCP server, `new_page` and `claim_page` open such a tab on one held owner connection per endpoint, which keeps it alive and sets a 1280x800 viewport at the screen's pixel ratio, so screenshots, clicks and typing work and logins are shared (same browser context). Measured through the MCP server with the restore off: 3/3 `new_page` + `close_page` runs never changed the front app, against a flash on the visible path.
|
|
27
|
+
- `list_pages` marks these tabs `hidden: true` (the user cannot see them) and lists them after visible tabs.
|
|
28
|
+
- `select_page` with `focus:true` on a hidden tab reopens its URL in a visible tab, closes the hidden one, and returns the new id with `revealedFrom`. Page state the URL does not carry (form input, scroll) is lost.
|
|
29
|
+
- At most `CDP_HIDDEN_TABS_MAX` (default 20) hidden tabs; past the cap `new_page` is refused with the open ids. Server shutdown closes them all. A hidden tab dies with the server or the browser and then reports `no-such-target`.
|
|
30
|
+
- Default off, and the one-shot CLI always uses visible tabs (a hidden tab would die when the CLI exits). `focus:true` keeps the visible path.
|
|
31
|
+
|
|
10
32
|
## [3.4.0] - 2026-11-18
|
|
11
33
|
|
|
12
34
|
### Changed
|
package/CONTRACT.md
CHANGED
|
@@ -179,6 +179,7 @@ A `Uid` **is** a CDP `backendDOMNodeId` (a number). This makes refs stateless:
|
|
|
179
179
|
| `src/tools/screencast.ts` | `start_screen_recording`→`startScreenRecording`, `stop_screen_recording`→`stopScreenRecording` | **Toolkit addition (not MCP parity): a tab captured to an H.265 MP4.** Persistent `openPage` conn parked in a module-level `Map` keyed by targetId (recorder.ts's statefulness, performance.ts's registry), `Page.startScreencast` → `Page.screencastFrame` → **ack from the handler, before the disk write** (an unacked frame stalls the stream) → spool file + ledger row `{file,timestamp,width,height}`. Frames arrive on repaint only, so playback timing MUST come from per-frame ffconcat `duration`s off the ledger, never a fixed rate. Encoder ladder probed once from `ffmpeg -encoders`: `hevc_videotoolbox`→`h264_videotoolbox`→`libx265`→`libx264`, `-tag:v hvc1` on HEVC, always `+faststart`/`yuv420p`/even dims. ffmpeg is probed at START (fail before capturing, not after). Pure parts (`frameDurationsMs`/`buildConcatManifest`/`selectEncoder`/`buildFfmpegArgs`/`imageSize`) are unit-tested; live capture via `test/screencast-smoke.ts`. |
|
|
180
180
|
| `src/tools/heap.ts` | `take_heapsnapshot`→`takeHeapsnapshot` | `HeapProfiler.enable` → `HeapProfiler.takeHeapSnapshot`, assemble `HeapProfiler.addHeapSnapshotChunk` events into a `.heapsnapshot` file under ARTIFACT_DIR; return `{ path, bytes }`. |
|
|
181
181
|
| `src/tools/lighthouse.ts` | `lighthouse_audit`→`lighthouseAudit` | **Not pure CDP.** Spawn `npx --yes lighthouse <url> --port=9222 --output=json --output-path=<artifact> --chrome-flags=...` via `node:child_process`. If lighthouse/npx unavailable, throw a clear `CdpError` explaining the dependency. Return `{ path, categories: {performance, accessibility, ...scores} }` parsed from the JSON. Top comment must state this is the one non-CDP tool. |
|
|
182
|
+
| `src/tools/tab-groups.ts` | `list_tab_groups`→`listTabGroups`, `group_tabs`→`groupTabs`, `ungroup_tabs`→`ungroupTabs` | **Toolkit addition (not MCP parity), Chrome-family only (capability `browser.tabGroups`).** CDP has no tab-group domain, so the module writes a fixed-`key` MV3 helper extension (`tabs`, `tabGroups`, `debugger` permissions; id `fnoambimeopboidifdmagpjfihclpilo`) to `${ARTIFACT_DIR}/tab-groups-helper`, installs it with `Extensions.loadUnpacked` on the browser endpoint, and runs each op with `Runtime.evaluate` in the helper's service-worker target. **Every call re-checks the worker** (MV3 idles it out after ~30s, and a restart leaves it stopped) and accepts it only when it reports the content hash of the worker source this build ships (`HELPER_VERSION`), so a stale copy is reloaded rather than called. The worker logic is a plain-JS string unit-tested against a fake `chrome`; `test/tab-groups-smoke.ts` is the live check. Two measured rules the code encodes: `chrome.tabs.group` across windows silently moves tabs to the LAST-FOCUSED window, so a multi-window selection is refused without `windowId`; and Vivaldi returns a group id for a group that never exists (`windowId -1`, no tabs), so an empty result is an error. Lease-free: these tools never open a page connection, and `targetId` comes from `chrome.debugger.getTargets()`, which does not attach. |
|
|
182
183
|
| `src/tools/network_mock.ts` | `mock_request`→`mockRequest`, `list_mocks`→`listMocks`, `clear_mocks`→`clearMocks` | **Toolkit addition (not MCP parity): a persistent fake backend.** Holds a per-target session (module-level `Map`, like `recorder.ts`) with a persistent `openPage` conn and `Fetch.enable` (patterns). `Fetch.requestPaused` → `selectRule` → `Fetch.fulfillRequest`/`failRequest`/`continueRequest` (default-continue unmatched, or page hangs). Pure logic (`urlMatches`/`selectRule`/`buildFulfillParams`/`effectiveAction`) is unit-tested; I/O via `test/mock-smoke.ts`. Persistence is MCP-server-process-scoped (CLI is one-shot). Request-stage only. |
|
|
183
184
|
|
|
184
185
|
## Each module's footer
|
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# cdp-toolkit
|
|
2
2
|
|
|
3
|
-
**A lightweight, drop-in alternative to [`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp) that won't wedge your agent.** It drives the Chrome tabs you point it at over the raw DevTools Protocol: any number of tabs, one explicitly named target per call over one direct socket, with a bounded timeout on every call, so a stuck page returns a clean error instead of hanging your agent and forcing a `/mcp` restart. Same idea, no all-target fan-out, plus tab leases so several agents can work one browser (and know when a human is using it too), plus a built-in network-mocking fake backend. **
|
|
3
|
+
**A lightweight, drop-in alternative to [`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp) that won't wedge your agent.** It drives the Chrome tabs you point it at over the raw DevTools Protocol: any number of tabs, one explicitly named target per call over one direct socket, with a bounded timeout on every call, so a stuck page returns a clean error instead of hanging your agent and forcing a `/mcp` restart. Same idea, no all-target fan-out, plus tab leases so several agents can work one browser (and know when a human is using it too), plus a built-in network-mocking fake backend. **51 tools, behind a 7-entry static, cacheable MCP listing** (5 everyday tools plus `search_tools` and `call_tool` to find and run the rest); `CDP_TOOL_PROFILE=full` lists all of them (see [Progressive disclosure](#progressive-disclosure)). Chrome is the flagship default; a second backend drives Firefox over WebDriver BiDi behind the same tool surface (see below).
|
|
4
4
|
|
|
5
5
|
> For AI-agent developers and Claude Code / Cursor users who need **the tabs they name driven reliably**, not a Puppeteer-managed browser.
|
|
6
6
|
|
|
@@ -76,7 +76,7 @@ One honest caveat the benchmark also reports: while a navigation to a dead endpo
|
|
|
76
76
|
npx -y --package cdp-toolkit cdp install # or `cdp install` from a clone / after a global install
|
|
77
77
|
```
|
|
78
78
|
|
|
79
|
-
It asks for a harness (`claude` | `codex` | `opencode`), a debug port, and a browser (`arc` | `chrome` | `firefox` | `vivaldi`), then writes an idempotent marker block into your `~/.zshrc`/`~/.bashrc`. The same flags drive it non-interactively: `--harness --browser --port --name --no-alias --yes`. The Firefox alias it writes includes `--marionette` (required for cdp-toolkit's orphaned-session auto-recovery — see [Firefox](#firefox-webdriver-bidi)). It is a CLI subcommand, **not** a
|
|
79
|
+
It asks for a harness (`claude` | `codex` | `opencode`), a debug port, and a browser (`arc` | `chrome` | `firefox` | `vivaldi`), then writes an idempotent marker block into your `~/.zshrc`/`~/.bashrc`. The same flags drive it non-interactively: `--harness --browser --port --name --no-alias --yes`. The Firefox alias it writes includes `--marionette` (required for cdp-toolkit's orphaned-session auto-recovery — see [Firefox](#firefox-webdriver-bidi)). It is a CLI subcommand, **not** a 52nd tool: `cdp --list` still shows 51.
|
|
80
80
|
|
|
81
81
|
Prefer to wire it by hand? The manual path is three steps:
|
|
82
82
|
|
|
@@ -146,7 +146,7 @@ bun run mcp:smoke # spawn the server + a real initialize/tools-list/tools-call
|
|
|
146
146
|
|
|
147
147
|
- **One target per call, never a broadcast.** Each call opens one WebSocket to the one target it named, with a bounded timeout on every CDP command, lazy domain enabling, and stateless element refs. Drive as many tabs as you like across calls; there is still no broadcast step that can stall on a wedged tab.
|
|
148
148
|
- **Network mocking: build the UI before the backend exists.** `mock_request` arms a persistent per-target fake backend: return canned responses, force errors, or inject latency/fault rates. Mocks survive reloads and navigations until `clear_mocks`.
|
|
149
|
-
- **Full chrome-devtools-mcp parity + extras.** All 29 upstream tools, plus `performance_trace` (a robust single-call trace), Lighthouse audits, heap snapshots, a cookie group that reads, writes, and deletes httpOnly cookies, real HTML5 drag-and-drop, raw scroll/mouse dispatch, download capture, permission grants,
|
|
149
|
+
- **Full chrome-devtools-mcp parity + extras.** All 29 upstream tools, plus `performance_trace` (a robust single-call trace), Lighthouse audits, heap snapshots, a cookie group that reads, writes, and deletes httpOnly cookies, real HTML5 drag-and-drop, raw scroll/mouse dispatch, download capture, permission grants, tab-to-video screen recording, and native tab groups (list, create, ungroup; Chrome-family only). The MCP server lists 7 of them by default on one static, cacheable `tools/list` (≈1.3k tokens, −86% vs 2.7.0's default) and serves the rest through `search_tools` (find a tool, read its docs and `inputSchema`) and `call_tool` (run it); `CDP_TOOL_PROFILE=full` lists all of them. The CLI exposes all 51 regardless. They coexist with `chrome-devtools-mcp` in a separate namespace.
|
|
150
150
|
- **A whole page is a file, not a wedged tab.** Chrome cannot encode a screenshot past 16384 device px on either side, and past that `Page.captureScreenshot` does not error — it never answers, and leaves the tab resized to the clip it was capturing. On a ratio-2 display that ceiling arrives at about 8192 CSS px: an ordinary long article. `take_screenshot` measures the projection before every capture and, past the cap, takes the page as vertical bands stitched losslessly into one PNG — a 140,982 CSS px page comes back as a 2780×281964 file in 18 bands, in 17 seconds, with the tab still healthy. Also per-capture `scale`, and `renderWidth`/`renderHeight` to shoot one capture at an emulated viewport and restore the tab afterwards.
|
|
151
151
|
- **Many agents, one browser, no stolen tabs.** `claim_page` hands out an opaque lease token for one tab; every other tool checks it at target resolution, so an unqualified call against a leased tab is refused by name rather than silently retargeted to whatever tab a different agent is driving.
|
|
152
152
|
- **Knows when a human is already using the tab you're driving.** An in-page activity beacon distinguishes a person's clicks/keys/scrolls from the toolkit's own dispatched input, so `claim_page` and `list_leases` can report `humanActiveMs` and warn on contention instead of silently fighting someone for the keyboard. See "Staleness: is a human already using this tab?" below.
|
|
@@ -244,6 +244,9 @@ await TOOLS.navigate_page({ target: "index:0", url: "https://example.com" });
|
|
|
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
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. |
|
|
247
|
+
| `CDP_HIDDEN_TABS` | off | `1`: MCP server only, Chrome only. `new_page` / `claim_page` without `focus:true` open a hidden tab (`Target.createTarget {background:true, hidden:true}`), so the browser never flashes in front of the user's app. See "Hidden tabs" below. Ignored by the CLI, where a hidden tab would die at exit. |
|
|
248
|
+
| `CDP_DENY_FOCUS` | off | `1` refuses every tab raise, even an explicit one: `new_page` / `claim_page` `focus:true` open a background tab, `select_page` `focus:true` only selects, screencast `bringToFront:true` is skipped. `new_page` and `select_page` then return `focusDenied: true`. For a shared browser the user is working in. |
|
|
249
|
+
| `CDP_HIDDEN_TABS_MAX` | `20` | Most hidden tabs open at once per endpoint. At the cap `new_page` refuses and names the open hidden ids; it never closes one for you. |
|
|
247
250
|
| `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. |
|
|
248
251
|
| `CDP_EXTRACT_MODEL` | `schematron` | `extract_page` only. Model name for the extraction endpoint call. |
|
|
249
252
|
| `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. |
|
|
@@ -282,10 +285,10 @@ That shape is deliberate. The MCP **2026-07-28** revision puts lazy discovery on
|
|
|
282
285
|
- A `query` that is an exact tool name returns that one tool.
|
|
283
286
|
- Any other `query` ranks the available tools by name (strongest), group, and full docs, and returns JSON `{query, total, matches: [{name, group, listed, description, inputSchema}], next}`. `limit` defaults to 8, max 20.
|
|
284
287
|
|
|
285
|
-
The whole
|
|
288
|
+
The whole 51-tool surface, as `search_tools {}` prints it on the default profile under Chrome:
|
|
286
289
|
|
|
287
290
|
```
|
|
288
|
-
cdp-toolkit 3.0.0 · browser=chrome ·
|
|
291
|
+
cdp-toolkit 3.0.0 · browser=chrome · 51 tools available, 7 in tools/list (CDP_TOOL_PROFILE=gateway)
|
|
289
292
|
[partly listed] core (12): list_pages, new_page, close_page, select_page, navigate_page, wait_for, take_snapshot, click, fill, type_text, evaluate_script, take_screenshot
|
|
290
293
|
[hidden] input (9): hover, drag, scroll, dispatch_mouse, press_key, fill_form, upload_file, focus_emulation, click_focus_gated
|
|
291
294
|
[hidden] cookies (3): list_cookies, set_cookie, delete_cookies
|
|
@@ -300,6 +303,7 @@ cdp-toolkit 3.0.0 · browser=chrome · 48 tools available, 7 in tools/list (CDP_
|
|
|
300
303
|
[hidden] dialogs (1): handle_dialog
|
|
301
304
|
[hidden] downloads (1): wait_for_download
|
|
302
305
|
[hidden] extraction (1): extract_page
|
|
306
|
+
[hidden] tabs (3): list_tab_groups, group_tabs, ungroup_tabs
|
|
303
307
|
Run any tool with call_tool {name, arguments}; search_tools {query:<name>} returns its docs and inputSchema.
|
|
304
308
|
```
|
|
305
309
|
|
|
@@ -318,11 +322,11 @@ Run any tool with call_tool {name, arguments}; search_tools {query:<name>} retur
|
|
|
318
322
|
| `full` | firefox | 37 | 28,899 | ≈7,225 |
|
|
319
323
|
| 2.7.0 default (`full`, for comparison) | chrome | 49 | 37,346 | ≈9,336 |
|
|
320
324
|
|
|
321
|
-
The default listing is **−86.4% bytes** vs 2.7.0's default.
|
|
325
|
+
The default listing is **−86.4% bytes** vs 2.7.0's default. Re-measured the same way at 3.6.0 (51 tools): `full` lists 53 entries / 43,914 bytes under chrome and 40 entries / 34,396 bytes under firefox; the default 7-entry listing is unchanged.
|
|
322
326
|
|
|
323
327
|
**What you trade away for that:**
|
|
324
328
|
|
|
325
|
-
- **Name-keyed host allowlists and per-tool permission prompts.** A tool reached through `call_tool` shows up to the host as `call_tool`, so a host rule like "allow `click`, deny `evaluate_script`" cannot tell apart the
|
|
329
|
+
- **Name-keyed host allowlists and per-tool permission prompts.** A tool reached through `call_tool` shows up to the host as `call_tool`, so a host rule like "allow `click`, deny `evaluate_script`" cannot tell apart the 46 non-gateway tools. If you need per-tool host rules, set `CDP_TOOL_PROFILE=full`.
|
|
326
330
|
- **Drop-in parity with `chrome-devtools-mcp`'s listing.** Its 29 tool names still exist and are still callable under the same names, but only 5 are *listed* by default. `CDP_TOOL_PROFILE=full` restores a listing with all of them.
|
|
327
331
|
|
|
328
332
|
A `CDP_TOOL_PROFILE` value is `gateway` (the default; also what unset or empty means), `full`, `core`, or a comma-separated group list. A list *without* `gateway` always includes `core` (the 2.x behaviour). A list *with* `gateway` adds only the named groups on top of the 5 gateway tools, e.g. `gateway,network,console`. An unknown group is a startup error: `CDP_TOOL_PROFILE: unknown tool group 'x'. Known: gateway, full, core, input, …`, exit 1.
|
|
@@ -330,7 +334,7 @@ A `CDP_TOOL_PROFILE` value is `gateway` (the default; also what unset or empty m
|
|
|
330
334
|
Rules worth knowing:
|
|
331
335
|
|
|
332
336
|
- **Unlisted does not mean blocked.** Only discovery is filtered. Calling an unlisted tool directly by name still works over the wire for SDK and CLI consumers, and `call_tool` reaches it for a model. Only a tool the selected browser cannot run at all is refused by name.
|
|
333
|
-
- **Profiles, `search_tools`, and `call_tool` are MCP-only.** `cdp search_tools` fails as an unknown tool, and the CLI keeps exposing all
|
|
337
|
+
- **Profiles, `search_tools`, and `call_tool` are MCP-only.** `cdp search_tools` fails as an unknown tool, and the CLI keeps exposing all 51 tools no matter how `CDP_TOOL_PROFILE` is set. The 51 underlying tools are unchanged.
|
|
334
338
|
- **`describe_tool` is unlisted but still answered** for 2.x callers, with the same output as 2.x; `describe_tool {}` returns the same catalog as `search_tools {}`.
|
|
335
339
|
|
|
336
340
|
### MCP protocol eras
|
|
@@ -392,7 +396,7 @@ Both spawn their own disposable headless Chrome and front it with a proxy that r
|
|
|
392
396
|
|
|
393
397
|
**Prompt shape (`prompt`, `CDP_EXTRACT_PROMPT`).** By default (`prompt:"html"`) the cleaned HTML is the *only* user message and your schema rides in `response_format` alone — which is what the **hosted** Schematron API expects, since it injects the schema into the prompt server-side. Point `baseUrl` at a **locally served open-weight Schematron** (e.g. an MLX `schematron8B`) and that breaks: the open weights were fine-tuned on a prompt with the schema *inside* the user message, and a bare-HTML prompt returns garbage even under constrained decoding. `prompt:"schematron"` sends the model card's own messages instead — a `You are a helpful assistant` system message plus a user message carrying the compact `JSON.stringify`'d schema, then the HTML, then `MAKE SURE ITS VALID JSON.` That adds roughly the stringified schema's length to the prompt (`maxChars` caps the **HTML** only; the true count still comes back in `usage.promptTokens`). `schematron` mode sends **no `response_format`** at all — the schema already lives in the prompt, and the client validates only that the response parses as JSON. (Measured 2026-09-12 against a locally served open-weight Schematron-8B under llguidance-constrained decoding: identical messages returned `{"stories": []}` in 6 completion tokens with `response_format` present, versus a valid, schema-conformant 5-story result in 285 tokens with it omitted — constrained decoding on top of an already-inlined schema is redundant and, on real markup, harmful.) The per-call arg wins over `CDP_EXTRACT_PROMPT`, and anything but `html`/`schematron` is rejected before any page or network work.
|
|
394
398
|
|
|
395
|
-
Works on both backends (Chrome and Firefox); see the `extract_page` row in [The tools](#the-tools-29-parity--
|
|
399
|
+
Works on both backends (Chrome and Firefox); see the `extract_page` row in [The tools](#the-tools-29-parity--22-superset--51) for the full parameter set.
|
|
396
400
|
|
|
397
401
|
## Firefox (WebDriver BiDi)
|
|
398
402
|
|
|
@@ -480,13 +484,14 @@ This coordinates and recovers **around** Firefox's one-session limit; it does no
|
|
|
480
484
|
|
|
481
485
|
**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.
|
|
482
486
|
|
|
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,
|
|
487
|
+
**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, six capability areas are absent because WebDriver BiDi (as of Firefox 160) has no equivalent domain:
|
|
484
488
|
|
|
485
489
|
- `performance_start_trace`, `performance_stop_trace`, `performance_analyze_insight`, `performance_trace` (needs `trace.performance`)
|
|
486
490
|
- `take_heapsnapshot` (needs `heap.snapshot`)
|
|
487
491
|
- `lighthouse_audit` (needs `audit.lighthouse`)
|
|
488
492
|
- `start_screen_recording`, `stop_screen_recording` (needs `capture.screencast`): BiDi has no streamed-frame primitive at all, only the one-shot `browsingContext.captureScreenshot`.
|
|
489
493
|
- `focus_emulation`, `click_focus_gated` (need `emulate.focus`): no BiDi command keeps a background tab reporting focus.
|
|
494
|
+
- `list_tab_groups`, `group_tabs`, `ungroup_tabs` (need `browser.tabGroups`): Chrome tab groups live in `chrome.tabGroups`, which the toolkit reaches through a helper extension's service worker; BiDi has no way to evaluate in an extension background context, and Firefox's own tab groups have no WebExtension or BiDi API to create them.
|
|
490
495
|
|
|
491
496
|
**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
497
|
|
|
@@ -503,7 +508,7 @@ This coordinates and recovers **around** Firefox's one-session limit; it does no
|
|
|
503
508
|
|
|
504
509
|
Still unimplemented in Firefox 160 (the commands return `unknown command`): forced-colors emulation, disabling scripting, touch emulation, and `locateNodes` by `innerText`.
|
|
505
510
|
|
|
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
|
|
511
|
+
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 51 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.
|
|
507
512
|
|
|
508
513
|
**Honest capability gaps, not oversold parity:**
|
|
509
514
|
|
|
@@ -516,18 +521,18 @@ Everything else, including `mock_request`/`list_mocks`/`clear_mocks` (Firefox's
|
|
|
516
521
|
- **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
522
|
- **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.
|
|
518
523
|
|
|
519
|
-
## The tools (29 parity +
|
|
524
|
+
## The tools (29 parity + 22 superset = 51)
|
|
520
525
|
|
|
521
|
-
This table is the **full view** — all
|
|
526
|
+
This table is the **full view** — all 51 tools, which is what `cdp --list` and the MCP server's `CDP_TOOL_PROFILE=full` listing show (the MCP default lists only 7; see [Progressive disclosure](#progressive-disclosure)). They are partitioned into 15 static profile groups: `core` (12: list_pages, new_page, close_page, select_page, navigate_page, wait_for, take_snapshot, click, fill, type_text, evaluate_script, take_screenshot), `input` (9: hover, drag, scroll, dispatch_mouse, press_key, fill_form, upload_file, focus_emulation, click_focus_gated), `cookies` (3: list/set/delete_cookies), `network` (2: list/get_network_request), `console` (2: list/get_console_message), `mocking` (3: mock_request, list_mocks, clear_mocks), `emulation` (2: emulate, resize_page), `performance` (6: the four trace tools, take_heapsnapshot, lighthouse_audit), `recording` (2: start/stop_screen_recording), `leases` (3: claim_page, release_page, list_leases), `permissions` (1: grant_permissions), `dialogs` (1: handle_dialog), `downloads` (1: wait_for_download), `extraction` (1: extract_page), `tabs` (3: list_tab_groups, group_tabs, ungroup_tabs). `CDP_TOOL_PROFILE=core` narrows the MCP listing to the first group; any group it leaves out stays callable by name. See [Progressive disclosure](#progressive-disclosure).
|
|
522
527
|
|
|
523
|
-
The 29 parity tools are 1:1 with `chrome-devtools-mcp`; the
|
|
528
|
+
The 29 parity tools are 1:1 with `chrome-devtools-mcp`; the 22 superset tools (`performance_trace`, the `list_cookies`/`set_cookie`/`delete_cookies` cookie group, the `mock_request`/`list_mocks`/`clear_mocks` group, the `claim_page`/`release_page`/`list_leases` lease group, the `start_screen_recording`/`stop_screen_recording` screen-recording pair, `scroll`, `dispatch_mouse`, `wait_for_download`, `grant_permissions`, the `focus_emulation`/`click_focus_gated` focus pair, `extract_page`, and the `list_tab_groups`/`group_tabs`/`ungroup_tabs` tab-group trio) are toolkit additions. Each row notes the underlying CDP method(s) and the precise parity gaps.
|
|
524
529
|
|
|
525
530
|
| MCP name | CDP method(s) | Parity notes / gaps |
|
|
526
531
|
|---|---|---|
|
|
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. |
|
|
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`. |
|
|
532
|
+
| `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. This server's hidden tabs (`CDP_HIDDEN_TABS`) are listed last with `hidden:true`. |
|
|
533
|
+
| `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`. Under `CDP_HIDDEN_TABS=1` (MCP server) a non-focus `new_page` opens a hidden tab instead and returns `hidden:true`; see "Hidden tabs". |
|
|
529
534
|
| `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. |
|
|
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. |
|
|
535
|
+
| `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. On a hidden tab, `focus:true` reopens its URL in a new visible tab, closes the hidden one, and returns the new id as `selected` plus `revealedFrom`. |
|
|
531
536
|
| `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. |
|
|
532
537
|
| `wait_for` | `Runtime.evaluate` (poll `innerText`) | Text-substring waiting only; throws on timeout rather than returning `{found:false}`. |
|
|
533
538
|
| `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. |
|
|
@@ -572,6 +577,24 @@ The 29 parity tools are 1:1 with `chrome-devtools-mcp`; the 19 superset tools (`
|
|
|
572
577
|
| `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
578
|
| `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. |
|
|
574
579
|
| `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. |
|
|
580
|
+
| `list_tab_groups` *(superset)* | helper extension: `chrome.tabGroups.query` + `chrome.tabs.query` + `chrome.debugger.getTargets` | Every window's tab groups: `{groupId, title, color, collapsed, tabs:[{tabId, targetId, index, url, title}]}`, plus each window's ungrouped count (`includeUngrouped:true` lists those tabs too). `targetId` is the CDP id every other tool takes as `target`. Installs the helper on first use (see [Tab groups](#tab-groups-chrome-family)). **Chrome-family only** (`browser.tabGroups`). |
|
|
581
|
+
| `group_tabs` *(superset)* | helper extension: `chrome.tabs.group` + `chrome.tabGroups.update` | Puts tabs (exactly one of `tabIds`, `targetIds`, `urlMatch`) into a new group (optional `title`, `color`, `collapsed`) or an existing one (`groupId`). A selection across several windows is refused unless `windowId` names the window the group goes in; tabs from other windows are then moved there and reported in `moved`. Never focuses a window. Fails loudly on a browser that accepts the call but creates no real group (Vivaldi). |
|
|
582
|
+
| `ungroup_tabs` *(superset)* | helper extension: `chrome.tabs.ungroup` | Takes tabs out of their groups (a selector, or `groupId` for a whole group); an emptied group disappears. Tabs stay open where they are. Returns `ungrouped` (with each tab's former `groupId`) and `alreadyUngrouped`. |
|
|
583
|
+
|
|
584
|
+
## Tab groups (Chrome-family)
|
|
585
|
+
|
|
586
|
+
`list_tab_groups`, `group_tabs` and `ungroup_tabs` read and build the browser's native tab groups: the named, colored chips in the tab strip. CDP has no tab-group domain, so the toolkit installs a tiny MV3 helper extension (permissions `tabs`, `tabGroups`, `debugger`; no host access, no content scripts) and calls `chrome.tabGroups` from its service worker. Facts measured on Helium (Chromium 158) and Vivaldi (Chromium 156) before building it:
|
|
587
|
+
|
|
588
|
+
- **Install is one CDP call.** `Extensions.loadUnpacked` on the browser endpoint installs the helper from `$CDP_ARTIFACT_DIR/tab-groups-helper` (default `/tmp/cdp-toolkit/tab-groups-helper`). A fixed manifest `key` pins its id to `fnoambimeopboidifdmagpjfihclpilo` whatever the path. The helper stays in the profile afterwards; remove it with `Extensions.uninstall {id}` or the browser's extensions page.
|
|
589
|
+
- **The worker sleeps, so every call wakes it.** An idle MV3 worker is evicted after about 30s and a browser restart leaves it stopped; re-running `loadUnpacked` brings it back in milliseconds. The helper reports a content hash of its own code, so a stale copy from an older toolkit is replaced, never called.
|
|
590
|
+
- **No infobar, no focus change.** Tab-to-target mapping uses `chrome.debugger.getTargets()`, which never attaches. Grouping and moving tabs between windows did not change the frontmost app in any run.
|
|
591
|
+
- **Cross-window grouping is explicit.** `chrome.tabs.group` on tabs from several windows silently moves them all into the last-focused window (and closes windows it empties). `group_tabs` refuses such a selection unless you pass `windowId`, and reports every moved tab.
|
|
592
|
+
- **The browser must run on this machine** (the helper directory is a local path the browser reads), and the tools need no lease: they act on tabs by id, not through a page connection.
|
|
593
|
+
- **Vivaldi is not supported.** It answers `chrome.tabs.group` with an id but keeps its own tab stacks: the "group" has `windowId -1` and no tabs, so `group_tabs` fails with an error saying so. Firefox: absent (see above).
|
|
594
|
+
|
|
595
|
+
```json
|
|
596
|
+
{"tool": "group_tabs", "arguments": {"urlMatch": "github.com/myorg", "windowId": 1234, "title": "Reviews", "color": "purple"}}
|
|
597
|
+
```
|
|
575
598
|
|
|
576
599
|
## Driving MV3 extensions
|
|
577
600
|
|
|
@@ -717,6 +740,19 @@ So every tab this toolkit creates is written to a creation ledger, and `list_pag
|
|
|
717
740
|
- No protection from humans. The lease is enforced against cdp-toolkit's own tool calls. It cannot stop someone clicking into the tab.
|
|
718
741
|
- Not for the CLI. A CLI invocation is one process per call, so a lease it claimed would be reclaimable immediately by the dead-pid rule. `claim_page` is refused there. CLI calls can still present a token minted by the MCP server with `--lease`. Strict mode (`CDP_REQUIRE_LEASE`) is likewise MCP-only and for the same underlying reason, doubled: an auto-acquired lease would be reclaimable on arrival, worse than no lease at all, and reap would then be free to read that instantly-dead-pid record as an abandoned tab and close it on the next listing.
|
|
719
742
|
|
|
743
|
+
## Hidden tabs: no browser flash (`CDP_HIDDEN_TABS`)
|
|
744
|
+
|
|
745
|
+
A background tab (`Target.createTarget {background:true}`) leaves the user's active tab alone, but on macOS it still brings the browser **app** in front of whatever the user is working in, for a moment. `CDP_RESTORE_FRONT_APP` puts their app back afterwards; it cannot stop the flash. Measured on Vivaldi (Chromium 156) by sampling the frontmost app around each raw CDP call: `{background:true}`, `{background:true, focus:false}`, a background `newWindow` and a minimized new window all flash. `{background:true, hidden:true}` does not, and neither do `Target.closeTarget` or `Page.navigate` on an existing tab.
|
|
746
|
+
|
|
747
|
+
Set `CDP_HIDDEN_TABS=1` on the **MCP server** and `new_page` / `claim_page` without `focus:true` open hidden tabs:
|
|
748
|
+
|
|
749
|
+
- **Fully drivable.** A hidden tab starts with a 0x0 viewport, where screenshots hang and clicks land nowhere, so the server attaches to it, sets a 1280x800 viewport at the screen's own device pixel ratio (read from the tab), and keeps that session open. Snapshots, screenshots, clicks, typing and navigation then work from any call. It shares the normal browser profile, so cookies and logins carry over.
|
|
750
|
+
- **Invisible.** It is in no window. `list_pages` marks it `hidden:true` and lists it after the visible tabs, so `index:` numbers and the default target are unchanged for the visible ones. Every selector (`url:`, `title:`, `label:`, an id) reaches it.
|
|
751
|
+
- **Tied to this server.** A hidden tab lives only while the server's connection that created it is open. A server restart, a browser restart or a dropped socket takes every hidden tab with it; the next `new_page` reconnects, and calls on a dead id fail fast with `no-such-target`. That is also why the CLI ignores the variable: its tab would die when the command exits.
|
|
752
|
+
- **Showing one to the user.** `select_page {focus:true}` cannot raise a hidden tab (Chromium accepts the activate call and shows nothing), so it opens the tab's current URL in a new visible tab (this one flash is the point), closes the hidden tab, and returns `{selected:<new id>, revealedFrom:<old id>}`. The tab's label moves with it; a lease moves too, and its new token comes back as `lease`. State the URL does not carry (form input, scroll position, a POST result) is lost. `new_page {focus:true}` still opens an ordinary visible tab.
|
|
753
|
+
- **Bounded.** The user cannot see or close these tabs, so at most `CDP_HIDDEN_TABS_MAX` (default 20) are open per endpoint. At the cap `new_page` refuses with an error naming the open hidden ids, oldest first; it never closes a tab another call may still be driving. `close_page` frees one, and server shutdown closes them all.
|
|
754
|
+
- **Scope.** Chrome-family browsers over CDP only (Firefox is unchanged). Only hidden tabs this server opened are marked; another server's hidden tabs list with the browser's own type, `"other"`.
|
|
755
|
+
|
|
720
756
|
## Named endpoints: several browsers or apps from one server
|
|
721
757
|
|
|
722
758
|
One server can drive more than one DevTools port: your browser on `9222` and, say, the Microsoft Teams desktop app (WebView2, launched with `WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=9333`) or an Electron app. Chrome backend only.
|
|
@@ -804,7 +840,7 @@ If Teams is not running when the server starts, `teams` just shows as down in `l
|
|
|
804
840
|
src/
|
|
805
841
|
client.ts # CdpConnection, openPage/withPage/openBrowser, resolveTarget, timeouts
|
|
806
842
|
types.ts # Target, TargetSelector, Uid, CDP envelopes
|
|
807
|
-
index.ts # TOOLS registry (
|
|
843
|
+
index.ts # TOOLS registry (51) + re-exported client primitives
|
|
808
844
|
cli.ts # the Bun CLI
|
|
809
845
|
mcp.ts # stdio MCP server, dual-era (serveStdio): static cacheable tools/list
|
|
810
846
|
version.ts # the VERSION constant, single source of truth with package.json
|
package/dist/bidi/mux-daemon.js
CHANGED
|
@@ -322,6 +322,9 @@ function leaseTtlMs() {
|
|
|
322
322
|
function markLongLivedProcess(value = true) {
|
|
323
323
|
longLived = value;
|
|
324
324
|
}
|
|
325
|
+
function isLongLivedProcess() {
|
|
326
|
+
return longLived;
|
|
327
|
+
}
|
|
325
328
|
function requireLease() {
|
|
326
329
|
if (!longLived)
|
|
327
330
|
return false;
|
|
@@ -847,10 +850,22 @@ var init_driver = __esm(() => {
|
|
|
847
850
|
focus_emulation: ["emulate.focus"],
|
|
848
851
|
click_focus_gated: ["emulate.focus"],
|
|
849
852
|
wait_for_download: ["browser.downloads"],
|
|
850
|
-
grant_permissions: ["browser.permissions"]
|
|
853
|
+
grant_permissions: ["browser.permissions"],
|
|
854
|
+
list_tab_groups: ["browser.tabGroups"],
|
|
855
|
+
group_tabs: ["browser.tabGroups"],
|
|
856
|
+
ungroup_tabs: ["browser.tabGroups"]
|
|
851
857
|
};
|
|
852
858
|
});
|
|
853
859
|
|
|
860
|
+
// src/focusPolicy.ts
|
|
861
|
+
function focusDenied() {
|
|
862
|
+
return TRUTHY.has((process.env.CDP_DENY_FOCUS ?? "").trim().toLowerCase());
|
|
863
|
+
}
|
|
864
|
+
var TRUTHY;
|
|
865
|
+
var init_focusPolicy = __esm(() => {
|
|
866
|
+
TRUTHY = new Set(["1", "true", "yes", "on"]);
|
|
867
|
+
});
|
|
868
|
+
|
|
854
869
|
// src/origins.ts
|
|
855
870
|
import { mkdir as mkdir4, readFile as readFile4, readdir as readdir2, unlink as unlink4, writeFile as writeFile4 } from "node:fs/promises";
|
|
856
871
|
import { join as join4 } from "node:path";
|
|
@@ -950,7 +965,7 @@ async function originIndex(backend, liveIds) {
|
|
|
950
965
|
return index;
|
|
951
966
|
}
|
|
952
967
|
async function newTrackedPage(driver, backend, opts = {}) {
|
|
953
|
-
const page = await driver.newPage(opts.url, { focus: opts.focus === true });
|
|
968
|
+
const page = await driver.newPage(opts.url, { focus: opts.focus === true && !focusDenied() });
|
|
954
969
|
await recordOrigin(backend, page.id, { label: opts.label });
|
|
955
970
|
return page;
|
|
956
971
|
}
|
|
@@ -977,6 +992,7 @@ async function resolveLiveLabel(backend, label, liveIds) {
|
|
|
977
992
|
}
|
|
978
993
|
var ORIGIN_FILE_RE;
|
|
979
994
|
var init_origins = __esm(() => {
|
|
995
|
+
init_focusPolicy();
|
|
980
996
|
init_leases();
|
|
981
997
|
ORIGIN_FILE_RE = new RegExp(`^origin-(${BACKEND_KEY_SOURCE})-(.+)\\.json$`);
|
|
982
998
|
});
|
|
@@ -2506,6 +2522,165 @@ var init_session = __esm(() => {
|
|
|
2506
2522
|
init_endpoint();
|
|
2507
2523
|
});
|
|
2508
2524
|
|
|
2525
|
+
// src/cdp/hiddenTabs.ts
|
|
2526
|
+
function hiddenTabsRequested() {
|
|
2527
|
+
return TRUTHY2.has((process.env.CDP_HIDDEN_TABS ?? "").trim().toLowerCase());
|
|
2528
|
+
}
|
|
2529
|
+
function hiddenTabsMax() {
|
|
2530
|
+
const raw = Number(process.env.CDP_HIDDEN_TABS_MAX);
|
|
2531
|
+
return Number.isFinite(raw) && raw >= 1 ? Math.floor(raw) : DEFAULT_HIDDEN_TABS_MAX;
|
|
2532
|
+
}
|
|
2533
|
+
|
|
2534
|
+
class HiddenTabOwner {
|
|
2535
|
+
deps;
|
|
2536
|
+
conn;
|
|
2537
|
+
connecting;
|
|
2538
|
+
tabs = new Map;
|
|
2539
|
+
reserved = 0;
|
|
2540
|
+
constructor(deps) {
|
|
2541
|
+
this.deps = deps;
|
|
2542
|
+
}
|
|
2543
|
+
sweep() {
|
|
2544
|
+
if (this.conn && !this.conn.isOpen) {
|
|
2545
|
+
this.conn = undefined;
|
|
2546
|
+
this.tabs.clear();
|
|
2547
|
+
}
|
|
2548
|
+
}
|
|
2549
|
+
has(id) {
|
|
2550
|
+
this.sweep();
|
|
2551
|
+
return this.tabs.has(id);
|
|
2552
|
+
}
|
|
2553
|
+
ids() {
|
|
2554
|
+
this.sweep();
|
|
2555
|
+
return [...this.tabs.keys()];
|
|
2556
|
+
}
|
|
2557
|
+
async owner() {
|
|
2558
|
+
this.sweep();
|
|
2559
|
+
if (this.conn)
|
|
2560
|
+
return this.conn;
|
|
2561
|
+
if (!this.connecting) {
|
|
2562
|
+
this.connecting = (async () => {
|
|
2563
|
+
const conn = await this.deps.connect();
|
|
2564
|
+
conn.on("Target.targetDestroyed", (params) => {
|
|
2565
|
+
const id = params.targetId;
|
|
2566
|
+
if (typeof id === "string")
|
|
2567
|
+
this.tabs.delete(id);
|
|
2568
|
+
});
|
|
2569
|
+
this.conn = conn;
|
|
2570
|
+
return conn;
|
|
2571
|
+
})().finally(() => {
|
|
2572
|
+
this.connecting = undefined;
|
|
2573
|
+
});
|
|
2574
|
+
}
|
|
2575
|
+
return this.connecting;
|
|
2576
|
+
}
|
|
2577
|
+
async create(url) {
|
|
2578
|
+
this.sweep();
|
|
2579
|
+
const max = (this.deps.max ?? hiddenTabsMax)();
|
|
2580
|
+
if (this.tabs.size + this.reserved >= max)
|
|
2581
|
+
throw new HiddenTabCapError(max, [...this.tabs.keys()]);
|
|
2582
|
+
this.reserved++;
|
|
2583
|
+
try {
|
|
2584
|
+
const conn = await this.owner();
|
|
2585
|
+
const id = await this.deps.createSettled(conn, url, { hidden: true });
|
|
2586
|
+
try {
|
|
2587
|
+
const { sessionId } = await conn.send("Target.attachToTarget", { targetId: id, flatten: true }, { timeoutMs: OWNER_COMMAND_TIMEOUT_MS });
|
|
2588
|
+
const dpr = await conn.send("Runtime.evaluate", { expression: "devicePixelRatio", returnByValue: true }, { sessionId, timeoutMs: OWNER_COMMAND_TIMEOUT_MS }).then((r) => r.result?.value).catch(() => {
|
|
2589
|
+
return;
|
|
2590
|
+
});
|
|
2591
|
+
await conn.send("Emulation.setDeviceMetricsOverride", {
|
|
2592
|
+
width: HIDDEN_TAB_VIEWPORT.width,
|
|
2593
|
+
height: HIDDEN_TAB_VIEWPORT.height,
|
|
2594
|
+
deviceScaleFactor: typeof dpr === "number" && Number.isFinite(dpr) && dpr > 0 ? dpr : FALLBACK_DEVICE_SCALE_FACTOR,
|
|
2595
|
+
mobile: false
|
|
2596
|
+
}, { sessionId, timeoutMs: OWNER_COMMAND_TIMEOUT_MS });
|
|
2597
|
+
this.tabs.set(id, sessionId);
|
|
2598
|
+
return id;
|
|
2599
|
+
} catch (e) {
|
|
2600
|
+
await conn.send("Target.closeTarget", { targetId: id }, { timeoutMs: OWNER_COMMAND_TIMEOUT_MS }).catch(() => {
|
|
2601
|
+
return;
|
|
2602
|
+
});
|
|
2603
|
+
throw e;
|
|
2604
|
+
}
|
|
2605
|
+
} finally {
|
|
2606
|
+
this.reserved--;
|
|
2607
|
+
}
|
|
2608
|
+
}
|
|
2609
|
+
async close(id) {
|
|
2610
|
+
this.sweep();
|
|
2611
|
+
const conn = this.conn;
|
|
2612
|
+
const held = this.tabs.delete(id);
|
|
2613
|
+
if (!conn || !held)
|
|
2614
|
+
return { success: false };
|
|
2615
|
+
const res = await conn.send("Target.closeTarget", { targetId: id }, { timeoutMs: OWNER_COMMAND_TIMEOUT_MS });
|
|
2616
|
+
return { success: res.success ?? true };
|
|
2617
|
+
}
|
|
2618
|
+
async dispose() {
|
|
2619
|
+
const conn = this.conn;
|
|
2620
|
+
const ids = [...this.tabs.keys()];
|
|
2621
|
+
this.tabs.clear();
|
|
2622
|
+
this.conn = undefined;
|
|
2623
|
+
if (!conn)
|
|
2624
|
+
return;
|
|
2625
|
+
if (conn.isOpen) {
|
|
2626
|
+
await Promise.all(ids.map((targetId) => conn.send("Target.closeTarget", { targetId }, { timeoutMs: OWNER_COMMAND_TIMEOUT_MS }).catch(() => {
|
|
2627
|
+
return;
|
|
2628
|
+
})));
|
|
2629
|
+
}
|
|
2630
|
+
conn.close();
|
|
2631
|
+
}
|
|
2632
|
+
}
|
|
2633
|
+
function hiddenTabOwner(base, deps) {
|
|
2634
|
+
let owner = owners.get(base);
|
|
2635
|
+
if (!owner) {
|
|
2636
|
+
owner = new HiddenTabOwner(deps());
|
|
2637
|
+
owners.set(base, owner);
|
|
2638
|
+
}
|
|
2639
|
+
return owner;
|
|
2640
|
+
}
|
|
2641
|
+
function existingHiddenTabOwner(base) {
|
|
2642
|
+
return owners.get(base);
|
|
2643
|
+
}
|
|
2644
|
+
function markHiddenTargets(base, targets) {
|
|
2645
|
+
const owner = owners.get(base);
|
|
2646
|
+
if (!owner)
|
|
2647
|
+
return targets;
|
|
2648
|
+
const hidden = new Set(owner.ids());
|
|
2649
|
+
if (hidden.size === 0)
|
|
2650
|
+
return targets;
|
|
2651
|
+
const visible = [];
|
|
2652
|
+
const marked = [];
|
|
2653
|
+
for (const t of targets) {
|
|
2654
|
+
if (hidden.has(t.id))
|
|
2655
|
+
marked.push({ ...t, type: "page", hidden: true });
|
|
2656
|
+
else
|
|
2657
|
+
visible.push(t);
|
|
2658
|
+
}
|
|
2659
|
+
return marked.length ? [...visible, ...marked] : targets;
|
|
2660
|
+
}
|
|
2661
|
+
async function disposeHiddenTabs() {
|
|
2662
|
+
const all = [...owners.values()];
|
|
2663
|
+
owners.clear();
|
|
2664
|
+
await Promise.all(all.map((o) => o.dispose()));
|
|
2665
|
+
}
|
|
2666
|
+
var DEFAULT_HIDDEN_TABS_MAX = 20, HIDDEN_TAB_VIEWPORT, FALLBACK_DEVICE_SCALE_FACTOR = 2, OWNER_COMMAND_TIMEOUT_MS = 5000, TRUTHY2, HiddenTabCapError, owners;
|
|
2667
|
+
var init_hiddenTabs = __esm(() => {
|
|
2668
|
+
HIDDEN_TAB_VIEWPORT = { width: 1280, height: 800 };
|
|
2669
|
+
TRUTHY2 = new Set(["1", "true", "yes", "on"]);
|
|
2670
|
+
HiddenTabCapError = class HiddenTabCapError extends Error {
|
|
2671
|
+
max;
|
|
2672
|
+
openIds;
|
|
2673
|
+
code = "page-error";
|
|
2674
|
+
constructor(max, openIds) {
|
|
2675
|
+
super(`hidden-tab cap reached: ${openIds.length} hidden tabs are open (CDP_HIDDEN_TABS_MAX=${max}). ` + `Close one with close_page (open hidden tabs, oldest first: ${openIds.join(", ")}), ` + `or pass focus:true to open a visible tab instead.`);
|
|
2676
|
+
this.max = max;
|
|
2677
|
+
this.openIds = openIds;
|
|
2678
|
+
this.name = "HiddenTabCapError";
|
|
2679
|
+
}
|
|
2680
|
+
};
|
|
2681
|
+
owners = new Map;
|
|
2682
|
+
});
|
|
2683
|
+
|
|
2509
2684
|
// src/client.ts
|
|
2510
2685
|
class CdpConnection {
|
|
2511
2686
|
wsUrl;
|
|
@@ -2624,6 +2799,9 @@ class CdpConnection {
|
|
|
2624
2799
|
});
|
|
2625
2800
|
});
|
|
2626
2801
|
}
|
|
2802
|
+
get isOpen() {
|
|
2803
|
+
return !this.closed && this.ws !== undefined;
|
|
2804
|
+
}
|
|
2627
2805
|
close() {
|
|
2628
2806
|
this.closed = true;
|
|
2629
2807
|
this.rejectAll(new CdpError("closed by caller"));
|
|
@@ -2652,11 +2830,11 @@ async function getTargetsOverBrowserWs() {
|
|
|
2652
2830
|
async function listTargets() {
|
|
2653
2831
|
const base = currentEndpoint().base;
|
|
2654
2832
|
if (knownTransports.get(base) === "browser-ws")
|
|
2655
|
-
return getTargetsOverBrowserWs();
|
|
2833
|
+
return markHiddenTargets(base, await getTargetsOverBrowserWs());
|
|
2656
2834
|
try {
|
|
2657
2835
|
const listing = await httpJson("/json/list");
|
|
2658
2836
|
knownTransports.set(base, "http");
|
|
2659
|
-
return listing;
|
|
2837
|
+
return markHiddenTargets(base, listing);
|
|
2660
2838
|
} catch (httpError) {
|
|
2661
2839
|
const detected = await detectEndpoint().catch(() => {
|
|
2662
2840
|
return;
|
|
@@ -2667,7 +2845,7 @@ async function listTargets() {
|
|
|
2667
2845
|
throw httpError;
|
|
2668
2846
|
});
|
|
2669
2847
|
knownTransports.set(base, "browser-ws");
|
|
2670
|
-
return targets;
|
|
2848
|
+
return markHiddenTargets(base, targets);
|
|
2671
2849
|
}
|
|
2672
2850
|
}
|
|
2673
2851
|
async function browserWsUrl() {
|
|
@@ -2780,6 +2958,7 @@ var init_client2 = __esm(() => {
|
|
|
2780
2958
|
init_frames();
|
|
2781
2959
|
init_endpoint();
|
|
2782
2960
|
init_session();
|
|
2961
|
+
init_hiddenTabs();
|
|
2783
2962
|
init_session();
|
|
2784
2963
|
BASE = (() => {
|
|
2785
2964
|
try {
|