cdp-toolkit 1.11.0 → 2.1.0

package/CHANGELOG.md

@@ -5,6 +5,77 @@ All notable changes to cdp-toolkit are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.0] - 2026-09-01
+
+**Re-based on the MCP 2026-07-28 revision: `tools/list` is now one complete, deterministic, cacheable listing that never changes, and the runtime `browser_tools` activation toggle 2.0.0 shipped three days ago is removed.** The honest headline on cost: the **default** listing grows from ≈2,457 to **≈8,471 tokens** (46 entries, 33,886 bytes, measured over raw stdio against the real entry point), because a standards-conformant list must be complete and static — still **−58% against 1.x's ≈20,200**. `CDP_TOOL_PROFILE=core` keeps the lean ≈2,266-token surface (13 entries, 9,066 bytes, −89% vs 1.x) for hosts that eagerly load every schema. Tool names, parameters, and schema shapes are unchanged, now gated by a durable wire-vs-manifest deep-equal check rather than the one-off strip-descriptions comparison 1.10.0 and 2.0.0 used. No new runtime dependency.
+
+### Added
+
+- **The 2026-07-28 protocol era, actually served.** `src/mcp.ts` connects through `serveStdio` (dual-era, default `legacy: 'serve'`) instead of `Server.connect(new StdioServerTransport())`. A modern client that opens with `server/discover` gets `supportedVersions: ["2026-07-28"]`, `resultType: "complete"`, and the `_meta['io.modelcontextprotocol/serverInfo']` envelope; a 2025-era client that opens with `initialize` still negotiates `2025-11-25` and sees no difference at all. The era is pinned per connection, and the server logs which one it pinned to stderr.
+- **Cache hints on the listing.** `cacheHints` now declares `ttlMs: 3600000` + `cacheScope: "public"` for both `tools/list` and `server/discover` (emitted on modern-era connections), instead of the SDK's conservative `{ ttlMs: 0, cacheScope: 'private' }` default. The listing is identical for every caller — a stdio server has no per-caller auth — and a restart under a different `CDP_TOOL_PROFILE` or `--browser` is a different server configuration, not a mid-life change to this one.
+- **`describe_tool` now doubles as the catalog.** Its `name` parameter became optional; called with no name it returns the grouped catalog of every tool the selected browser supports — a header line (`cdp-toolkit 2.1.0 · browser=chrome · 45 tools available, 46 in tools/list (CDP_TOOL_PROFILE=full)`), then one `[listed]`/`[hidden] <group> (n): names` line per group, then `Unlisted tools are callable by name; describe_tool {name} documents any of them.` The whole 45-tool catalog is 1,141 characters.
+- **`CDP_TOOL_PROFILE` accepts a comma-separated group list** on top of `full` and `core` — e.g. `core,network,console` (17 entries, 11,893 bytes, ≈2,973 tokens). `core` is always included, so a list can never strand the basics, and the label is canonicalised to group order so equivalent spellings read the same. An unknown group name is now a configuration error rather than a silent fallback: the server prints `CDP_TOOL_PROFILE: unknown tool group 'x'. Known: full, core, input, …` and exits 1.
+- **`src/version.ts`** — the `VERSION` constant moved out of `src/mcp.ts` into its own module, and a test asserts it equals `package.json`'s `version`. The two drifted apart between 1.11.0 and 2.0.0; that can no longer happen quietly.
+- **`test/mcp-protocol.test.ts`** — raw-stdio protocol coverage: `server/discover` and `tools/list` field shapes, the cache hints, byte-identical deterministic ordering across repeated calls and connections, the **wire-vs-manifest deep-equal gate** (the durable replacement for the one-off strip-descriptions gate), the legacy `initialize` handshake, a `-32022` negative control, each profile, and proof that an unlisted tool is still callable. **`test/tool-profile.test.ts`** covers `resolveProfile` directly.
+
+### Changed
+
+- **The tool listing is static.** It is computed once at startup — `describe_tool` first, then manifest order, filtered by backend availability and then by the profile — frozen, and returned as the same array to every `tools/list` on every connection. `capabilities.tools.listChanged` is now **`false`**; nothing will ever notify, because nothing ever changes. The 2026-07-28 revision makes it a MUST that a server's tool set not change as a side effect of other requests on the connection, and the client best-practices page notes that adding or removing tool definitions mid-conversation invalidates the host's prompt cache.
+- **`CDP_TOOL_PROFILE` default flipped `core` → `full`.** Three reasons, in order of weight: (1) the standard puts lazy discovery on the **host** — the client runs its own catalog → inspect → execute funnel — and a host that defers schemas (Claude Code lists MCP tool *names* and loads schemas on demand) pays little for a complete list; (2) consumers that hold per-tool permission allowlists, or per-tool interception keyed on the tool NAME, for non-core tools (the console and network readers, `performance_analyze_insight`) were silently broken by a `core` default, because those tools were simply absent from `tools/list`; (3) a list that never changes never invalidates the prompt cache. `core` remains a first-class choice for hosts that eagerly load every schema — it is now a deployment decision, not a default imposed on everyone.
+- **Host protocol eras, MEASURED 2026-09-01.** Two real hosts were pointed at the 2.1 server through a wrapper that tees its stderr: Claude Code 2.1.258 and Codex CLI 0.147.0 both connected and both logged `connection pinned to the legacy protocol era` — today they still open with `initialize` even though their binaries carry the 2026-07-28 client strings (capability present, not exercised by default). The SDK 2.0.0 `Client` does the same unless `versionNegotiation` opts in. So the dual-era default is load-bearing, not courtesy: a modern-only server would be unreachable from every host measured. The modern era is currently exercised by the raw-stdio test suite and by `mcp:smoke`'s pinned client. The static listing pays off on either era; the `ttlMs`/`cacheScope` hints are emitted only on modern connections.
+- **The server `instructions` block** trades the activation walkthrough for how to read a fixed, cacheable listing (`tools/list` is complete and fixed for this process's life — cache it; `describe_tool {name}` / `describe_tool {}`; profile semantics; unlisted tools stay callable). 2,019 → 1,976 characters, still under the 2 KB cap.
+- **SDK usage, deliberately unchanged in shape.** The server stays on the low-level `Server` with string-method `setRequestHandler('tools/list', …)`, which SDK 2.0 still supports for advanced use cases (and which `McpServer` itself is built on; `McpServerFactory` explicitly accepts a `Server`). `McpServer.registerTool` was evaluated and rejected on two grounds: it wants a Standard-Schema (zod) object for `inputSchema`, and `CONTRACT.md` rule 1 forbids any runtime dependency beyond the SDK — our manifest is plain JSON Schema — and it cannot express "unlisted tools remain callable by name", which is the whole point of `CDP_TOOL_PROFILE`.
+- **`test/mcp-smoke.ts`** additionally connects with the SDK client pinned to `2026-07-28` and asserts the modern era end to end, alongside the existing legacy handshake and live `tools/call` round trip.
+- Under `CDP_BROWSER=firefox` the default listing is 35 entries (26,533 bytes, ≈6,633 tokens): the 34 tools Firefox's BiDi surface supports, plus `describe_tool`.
+
+### Removed
+
+- **`browser_tools`** — the `list_groups`/`activate`/`deactivate`/`set_profile` meta-tool, removed three days after 2.0.0 shipped it. Mutating the advertised tool set at runtime and firing `notifications/tools/list_changed` is precisely what the 2026-07-28 revision forbids (the tool set MUST NOT change as a side effect of other requests) and what the client best-practices page warns invalidates the host's prompt cache. Its open question — "does any given client actually re-fetch on `listChanged`?" — becomes moot once the list is static. Calling it now returns `unknown tool: browser_tools`; nothing else needs it, because every tool it could have activated is either already listed under the new `full` default or reachable by name under a narrower profile, and `describe_tool {}` covers what `list_groups` reported.
+
+### Fixed
+
+- **v2.0.0 was not on the current protocol revision, despite running on the 2.0 SDK.** Probed raw over stdio, it answered `server/discover` with `-32601 Method not found` and served a `tools/list` carrying no `resultType`, `ttlMs`, or `cacheScope`: a 2025-11-25 (legacy-era) server, because `Server.connect(new StdioServerTransport())` **is** the legacy path. The `"2026-07-28"` literal that appears inside the SDK packages is `SUPPORTED_MODERN_PROTOCOL_VERSIONS` in `@modelcontextprotocol/server/stdio` — the modern era is reachable only through `serveStdio` (or the HTTP `createMcpHandler`), never through `connect()`. Both eras are now served.
+
+## [2.0.0] - 2026-08-29
+
+**Progressive disclosure: the default `tools/list` an agent loads shrinks ~88% (≈20,200 → ≈2,500 tokens) to 12 core tools plus two meta-tools, with the full 45-tool surface, and the full per-tool documentation, one `browser_tools` call away.** This is the first npm publication since 1.11.0, so it also **carries the [1.11.1] changes below** (the two Firefox BiDi navigation fixes) that landed on main but were never released. Tool names, parameters, and schema shapes are unchanged — a strip-descriptions deep-equal of the manifest gates the change, the same check 1.10.0 used.
+
+### Added
+
+- **Tool profiles + on-demand group activation.** The server now starts on the `core` profile (`list_pages`, `new_page`, `close_page`, `select_page`, `navigate_page`, `wait_for`, `take_snapshot`, `click`, `fill`, `type_text`, `evaluate_script`, `take_screenshot`) and holds the other 33 tools in 12 activatable groups (`src/toolGroups.ts`). `CDP_TOOL_PROFILE=full` advertises everything at startup — the exact prior behavior. Profiles are MCP-only; the CLI still exposes all 45 tools.
+- **`browser_tools` meta-tool** — `list_groups` (every group, its tools, active state), `activate`/`deactivate` (toggle one group), `set_profile` (core|full wholesale). Any change fires `notifications/tools/list_changed` so the client re-fetches `tools/list`; the server now declares `tools.listChanged: true`.
+- **`describe_tool` meta-tool** — full description and per-parameter docs for any tool by name, *including tools not currently listed* (`src/toolDocs.ts`, generated verbatim from the pre-2.0 manifest prose). Call it before using an unfamiliar tool; the live listing carries only terse summaries.
+- Environment knob: `CDP_TOOL_PROFILE` (`core` default, `full` = prior behavior).
+- The server `instructions` block now front-loads the disclosure model: core profile at startup, `browser_tools` to activate, `describe_tool` for full docs, hidden tools still callable by name.
+
+### Changed
+
+- **The manifest advertised over `tools/list` now carries terse one-line descriptions; the full prose moved to `describe_tool`.** Description text drops 61,002 → 14,077 chars; the full 45-tool payload would be ~8.5k tokens (−58% vs 1.x) and the default surface ~2.5k (−88%). Schema shapes are untouched. Hidden does not mean disabled: a hidden-but-available tool called by name still executes — only discovery is gated.
+- **MCP SDK 1.29 → 2.0.** The runtime dependency is now `@modelcontextprotocol/server@^2.0.0` (the SDK 2.0 package split), with `@modelcontextprotocol/client@^2.0.0` as a devDependency powering the in-process client tests; `scripts/build.ts` keeps the SDK external under the new package name.
+- **Tests re-pointed, guarantees preserved.** Every description assertion in `test/` now reads `TOOL_DOCS` instead of the manifest (worker-capture traps, HTML5 drag modes, lease semantics, the 500ms probe bound — all still asserted, relocated), and `test/origins.test.ts` now proves the "origin is never 'human'" vocabulary is reachable end-to-end through `describe_tool` over a real stdio MCP connection.
+- Repo hygiene: the private `.cbm-atlas`/`.cbmignore` indexing artifacts and one internal design plan doc are no longer tracked.
+
+### Fixed
+
+- Seven one-line manifest descriptions that a mechanical compression pass had corrupted with copy-paste text from unrelated tools (`fill.value`, `fill_form.fields[].value`, `emulate.mediaFeatures` item name/value, `mock_request.action`, `lighthouse_audit.categories`, `clear_mocks.all`, `list_mocks.target`) now carry their correct terse wording, derived from the preserved `TOOL_DOCS` prose.
+- The runtime version constant (`src/mcp.ts` `VERSION`) had drifted from `package.json` since 1.11.0; both now read from the same release.
+
+## [1.11.1] - 2026-08-25
+
+**Two Firefox BiDi navigation fixes: every plain `reload:true` no longer fails, and `file://` navigation gets automation-pref parity plus an actionable error when the OS still refuses.** Chrome behavior is unchanged. The tool surface is unchanged (45 tools).
+
+### Fixed
+
+- **Every plain `reload:true` on Firefox failed with `Argument "ignoreCache" is not supported yet`.** `browsingContext.reload` was sent `ignoreCache: false` unconditionally, and Firefox's BiDi server rejects the KEY regardless of value — so the default reload path, not just hard reloads, was broken on the Firefox backend. The key is now omitted from the params entirely on plain reloads, and an explicit `ignoreCache: true` fails fast with a clear backend-capability error (the same doctrine as `click`'s modifiers) instead of an opaque mid-flight protocol rejection. The `navigate_page` manifest and docs now state the Firefox limitation up front.
+- **#6 — `file://` navigation on the Firefox backend.** Two parts, with their evidentiary limits stated:
+  - Launched-Firefox profiles now carry Mozilla's automation prefs. Firefox's Remote Agent has its own recommended automation bundle, but it is gated on `remote.prefs.recommended`, which DEFAULTS TO FALSE (verified in mozilla-central's `remote/shared/RecommendedPreferences.sys.mjs`) — so a bare `--remote-debugging-port` launch ran with consumer prefs while every geckodriver/Marionette-class setup applies the bundle. `launch.ts` now seeds `user.js` into every throwaway profile with `remote.prefs.recommended: true` plus `security.fileuri.strict_origin_policy: false` and `dom.file.createInChild: true` (the latter is the pref Marionette's own `geckoinstance.py` sets). An explicit `profilePath` is deliberately NOT mutated — it belongs to its owner.
+  - `NS_ERROR_FILE_ACCESS_DENIED` now maps to an actionable error naming snap/AppArmor confinement (an Ubuntu snap Firefox cannot read host paths outside its mount namespace, and no preference fixes that) and the localhost-server workaround, instead of relaying the bare nsresult.
+  - Live-verified on macOS (Firefox 153, launch mode): top-level `file://` navigation, sibling `<script src>` loading, and same-directory `fetch()` all pass end-to-end (`test/firefox-smoke.ts`, 24/24). The Linux snap-confined case cannot be reproduced on macOS and is covered by the error mapping instead; a negative control confirmed sibling-script/fetch behavior does not discriminate the seeded prefs on Firefox 153/macOS, so those smoke checks are regression guards, not causal proof.
+
+### Changed
+
+- **`test/firefox-smoke.ts`** gains the file:// + reload section (check 7b2) with its evidentiary limits documented inline, and no longer claims to avoid `file://` categorically.
+
 ## [1.11.0] - 2026-08-18
 
 **Firefox multi-process session coordination + orphan auto-recovery, and a new `cdp install` one-command setup.** Attaching several cdp-toolkit processes to one user Firefox no longer hard-wedges on Firefox's single-BiDi-session limit, and a session orphaned by a killed client is now auto-cleared over the Marionette side channel instead of requiring a Firefox restart. Chrome behavior is unchanged. The tool surface is still 45 tools — the installer is a CLI subcommand, not a new tool.

package/README.md

@@ -1,6 +1,6 @@
 # cdp-toolkit
 
-**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. **45 tools.** Chrome is the flagship default; a second backend drives Firefox over WebDriver BiDi behind the same tool surface (see below).
+**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. **45 tools, all of them on one static, cacheable MCP listing** — or a lean 12-tool `core` listing when your client loads every schema eagerly (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).
 
 > For AI-agent developers and Claude Code / Cursor users who need **the tabs they name driven reliably**, not a Puppeteer-managed browser.
 
@@ -129,7 +129,7 @@ bun run mcp:smoke   # spawn the server + a real initialize/tools-list/tools-call
 
 - **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.
 - **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`.
-- **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, and tab-to-video screen recording. 45 single-purpose tools, no discovery overhead, and they coexist with `chrome-devtools-mcp` in a separate namespace.
+- **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, and tab-to-video screen recording. The MCP server publishes all of them on one static, cacheable `tools/list` (≈8.5k tokens, −58% vs 1.x) and serves the full per-tool prose on demand through `describe_tool`; `CDP_TOOL_PROFILE=core` trims that listing to a 12-tool everyday set (≈2.3k tokens) for clients that eagerly load every schema, and the trimmed-away tools stay callable by name. The CLI exposes all 45 regardless. They coexist with `chrome-devtools-mcp` in a separate namespace.
 - **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.
 - **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.
 - **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.
@@ -224,13 +224,77 @@ await TOOLS.navigate_page({ target: "index:0", url: "https://example.com" });
 | `CDP_STATE_DIR` | `/tmp/cdp-toolkit` | `select_page` selected-target file, in-flight trace state. |
 | `CDP_LEASE_TTL_MS` | `900000` | How long a tab lease survives without use before another agent can reclaim it. Refreshed on every checked call. |
 | `CDP_REQUIRE_LEASE` | off | Strict mode, MCP server only (inert under the CLI regardless of value). Turns leasing from optional into mandatory: a call against an unheld tab acquires a lease instead of driving it lease-free, and `list_pages`/`list_leases` close tabs an abandoned agent left behind. See "Parallel tabs" below. |
+| `CDP_TOOL_PROFILE` | `full` | MCP server only. Startup-only filter on what `tools/list` advertises, read once and fixed for the life of the process. `full` (the default, and what unset/empty means) lists every group; `core` lists just the 12 everyday tools plus `describe_tool`; or a comma-separated group list, e.g. `core,network,console` (`core` is always included). An unknown group name is a configuration error: the server prints `CDP_TOOL_PROFILE: unknown tool group 'x'. Known: full, core, input, …` and exits 1. Tools the profile leaves out stay callable by name. See "Progressive disclosure" below. |
 | `CDP_REAP_GRACE_MS` | `2700000` | Extra grace (on top of `CDP_LEASE_TTL_MS`) before an `expired` lease's tab is actually destroyed by reap; `dead-pid` tabs are reaped immediately regardless. See "Reap" below. |
 | `CDP_FIREFOX_MARIONETTE_PORT` | `2828` | Firefox backend only. The Marionette side-channel port used to force-clear Firefox's orphaned BiDi session during orphan-session recovery (a blind `WebDriver:DeleteSession`). Only effective when that Firefox was launched with `--marionette`. See "Firefox" below. |
 | `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. |
 
+## Progressive disclosure
+
+The MCP server publishes **one complete, deterministic, cacheable `tools/list`**: `describe_tool` first, then every tool the selected browser can actually run whose group the startup profile advertises, in manifest order. It is computed once at startup and frozen — byte-identical on every call, on every connection, and unchangeable by anything a client does mid-session — and on a 2026-era connection it carries cache hints (`ttlMs: 3600000`, `cacheScope: "public"`) so a client can hold it for an hour instead of re-fetching. `capabilities.tools.listChanged` is `false`: nothing will ever notify, because nothing ever changes.
+
+That shape is deliberate. The MCP **2026-07-28** revision puts lazy discovery on the *host* side — the client runs its own catalog → inspect → execute funnel across the servers it has connected — and a server cooperates by publishing a complete, deterministic, cacheable list rather than by mutating its own. The revision makes it a MUST that a server's tool set not change as a side effect of other requests on the connection. See [Build an MCP server](https://modelcontextprotocol.io/docs/2026-07-28/develop/build-server) and [Client best practices](https://modelcontextprotocol.io/docs/2026-07-28/develop/clients/client-best-practices); the latter also notes that adding or removing tool definitions mid-conversation invalidates the host's prompt cache — which a list that never changes never does. 2.0.0's `browser_tools` runtime activation toggle was exactly that anti-pattern and is **removed in 2.1**: calling it now returns `unknown tool: browser_tools`.
+
+**`describe_tool` is the inspect layer.** The listing carries terse one-liners; the full description and per-parameter docs load on demand, for *any* tool — listed or not:
+
+```json
+{"tool": "describe_tool", "arguments": {"name": "wait_for_download"}}
+{"tool": "describe_tool", "arguments": {}}
+```
+
+With no `name` it returns the grouped catalog of everything this server can run. The whole 45-tool surface costs 1,141 characters:
+
+```
+cdp-toolkit 2.1.0 · browser=chrome · 45 tools available, 46 in tools/list (CDP_TOOL_PROFILE=full)
+[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
+[listed] input (7): hover, drag, scroll, dispatch_mouse, press_key, fill_form, upload_file
+[listed] cookies (3): list_cookies, set_cookie, delete_cookies
+[listed] network (2): list_network_requests, get_network_request
+[listed] console (2): list_console_messages, get_console_message
+[listed] mocking (3): mock_request, list_mocks, clear_mocks
+[listed] emulation (2): emulate, resize_page
+[listed] performance (6): performance_start_trace, performance_stop_trace, performance_analyze_insight, performance_trace, take_heapsnapshot, lighthouse_audit
+[listed] recording (2): start_screen_recording, stop_screen_recording
+[listed] leases (3): claim_page, release_page, list_leases
+[listed] permissions (1): grant_permissions
+[listed] dialogs (1): handle_dialog
+[listed] downloads (1): wait_for_download
+Unlisted tools are callable by name; describe_tool {name} documents any of them.
+```
+
+Under a narrower profile the groups it leaves out read `[hidden]` instead of `[listed]`, and the header's second count drops accordingly.
+
+**`CDP_TOOL_PROFILE` is the only filter, and it is startup-only** — set once by whoever configures the server, then fixed for the life of the process. Measured over raw stdio (bytes = compact JSON of the `tools` array, tokens ≈ bytes ÷ 4):
+
+| `CDP_TOOL_PROFILE` | entries in `tools/list` | bytes | ≈ tokens |
+|---|---|---|---|
+| unset / `full` — the default | 46 | 33,886 | ≈8,471 |
+| `core` | 13 | 9,066 | ≈2,266 |
+| `core,network,console` | 17 | 11,893 | ≈2,973 |
+| `full` under `CDP_BROWSER=firefox` | 35 | 26,533 | ≈6,633 |
+
+For comparison, 1.x advertised 45 tools with full prose at roughly 20,200 tokens. So the default listing is **−58% vs 1.x**, and `core` is **−89%**.
+
+The default flipped from `core` (2.0.0) to `full` in 2.1 for three reasons: the standard puts discovery on the host, and a host that defers schemas — Claude Code lists MCP tool *names* and loads schemas on demand — pays little for a complete list; consumers that hold per-tool allowlists or per-tool interception keyed on the tool *name* for non-core tools (the console and network readers, `performance_analyze_insight`) were silently broken by a `core` default, because those tools were simply absent from `tools/list`; and a list that never changes never invalidates the host's prompt cache. Keep `CDP_TOOL_PROFILE=core` if your client eagerly loads every schema — that is where the ≈2.3k-token surface is worth the round trips.
+
+Three rules worth knowing:
+
+- **Unlisted does not mean blocked.** Only discovery is filtered. `tools/call` checks backend availability, not group membership, so an agent that names an unlisted-but-available tool still executes it; only a tool the selected browser cannot run at all is refused by name.
+- **`describe_tool` works for any tool by name, unlisted ones included** — the full description and per-parameter docs behind the terse one-liner `tools/list` carries.
+- **Profiles and `describe_tool` are MCP-only.** They are MCP-server concepts: `cdp describe_tool` fails with `unknown tool 'describe_tool'`, and the CLI keeps exposing all 45 tools no matter how `CDP_TOOL_PROFILE` is set.
+
+### MCP protocol eras
+
+The server serves **both** eras off the same stdio transport, and the era is pinned per connection by how the client opens:
+
+- A modern client opens with **`server/discover`** and gets `protocolVersion` `2026-07-28`, `resultType: "complete"`, the `_meta['io.modelcontextprotocol/serverInfo']` envelope, and the `ttlMs`/`cacheScope` cache hints on both `server/discover` and `tools/list`.
+- A 2025-era client opens with **`initialize`** and gets `protocolVersion` `2025-11-25`, exactly as before — this upgrade is invisible to it.
+
+Measured 2026-09-01: Claude Code 2.1.258 and Codex CLI 0.147.0 both connect and both pin the **legacy** era — their binaries carry the 2026-07-28 client strings, but neither opens with `server/discover` by default, and the MCP SDK's own `Client` behaves the same unless it opts in. So serving both eras is load-bearing, not courtesy, and today the `ttlMs`/`cacheScope` hints reach only clients that ask for the modern era. The static listing pays off on either one — no mid-session tool churn, and no prompt-cache invalidation.
+
 ## Firefox (WebDriver BiDi)
 
-cdp-toolkit ships a second backend, Firefox over [WebDriver BiDi](https://w3c.github.io/webdriver-bidi/), behind the same 45-tool surface. Chrome stays the default and its behavior is unchanged, opt in explicitly to reach Firefox:
+cdp-toolkit ships a second backend, Firefox over [WebDriver BiDi](https://w3c.github.io/webdriver-bidi/), behind the same tool surface. Chrome stays the default and its behavior is unchanged, opt in explicitly to reach Firefox:
 
 ```bash
 cdp --browser firefox take_snapshot                 # CLI: explicit flag
@@ -304,7 +368,7 @@ This coordinates and recovers **around** Firefox's one-session limit; it does no
 
 **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.
 
-**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. Under Firefox, four tool groups are absent because Firefox 153's BiDi implementation has no equivalent domain:
+**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* its group is in the startup profile — backend availability first, `CDP_TOOL_PROFILE` second (see [Progressive disclosure](#progressive-disclosure)). Under Firefox, six capability areas are absent because Firefox 153's BiDi implementation has no equivalent domain:
 
 - `performance_start_trace`, `performance_stop_trace`, `performance_analyze_insight`, `performance_trace` (needs `trace.performance`)
 - `take_heapsnapshot` (needs `heap.snapshot`)
@@ -313,7 +377,7 @@ This coordinates and recovers **around** Firefox's one-session limit; it does no
 - `dispatch_mouse` (needs `input.raw`): the raw move/down/up primitive is a direct `Input.dispatchMouseEvent` wrapper with no BiDi analogue.
 - `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.
 
-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, 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: 34 of the 45 tools. 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 agents under Firefox share and serialize on that single session (coordinated by the cross-process session lease above), not the independent concurrent sessions Chrome's unlimited CDP connections allow — see "Parallel tabs" below.
+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, 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: 34 of the 45 tools. Under `CDP_BROWSER=firefox` the MCP server's default (`full`) listing is therefore 35 entries — those 34 plus `describe_tool` — and a narrower `CDP_TOOL_PROFILE` trims it further, the profile filter applying 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 agents under Firefox share and serialize on that single session (coordinated by the cross-process session lease above), not the independent concurrent sessions Chrome's unlimited CDP connections allow — see "Parallel tabs" below.
 
 **Honest capability gaps, not oversold parity:**
 
@@ -328,6 +392,8 @@ Everything else, including `mock_request`/`list_mocks`/`clear_mocks` (Firefox's
 
 ## The tools (29 parity + 16 superset = 45)
 
+This table is the **full-profile view** — all 45 tools, which is what `cdp --list` and the MCP server's default listing (`CDP_TOOL_PROFILE=full`) both show. They are partitioned into 13 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` (7: hover, drag, scroll, dispatch_mouse, press_key, fill_form, upload_file), `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). `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).
+
 The 29 parity tools are 1:1 with `chrome-devtools-mcp`; the 16 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`, and `grant_permissions`) are toolkit additions. Each row notes the underlying CDP method(s) and the precise parity gaps.
 
 | MCP name | CDP method(s) | Parity notes / gaps |
@@ -372,7 +438,7 @@ The 29 parity tools are 1:1 with `chrome-devtools-mcp`; the 16 superset tools (`
 | `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`). |
 | `list_mocks` *(superset)* | `Runtime.evaluate` (liveness probe) | Lists active mock sessions with rules + hit counts; prunes sessions whose tab closed. |
 | `clear_mocks` *(superset)* | `Fetch.disable` | Tears down the resolved target's mock session (or all with `all:true`). |
-| `claim_page` *(superset)* | `Target.createTarget` + lease file | Opens a fresh tab and claims it (no `target`/`targetId`), or takes over a tab that is already open (`target`, any selector, or the exact-id `targetId`) and returns an opaque lease token plus `opened` (true only when this call created the tab). Never steals a tab another live process holds. Also returns `humanActiveMs` (ms since input this server did not dispatch; `null` means no data, never "no human") and, on a takeover of a tab a human used within the last 30s, a `contention` warning — the claim is never refused for it. MCP only; the CLI refuses it. |
+| `claim_page` *(superset)* | `Target.createTarget` + lease file | Opens a fresh tab and claims it (no `target`/`targetId`), or takes over a tab that is already open (`target`, any selector, or the exact-id `targetId`) and returns an opaque lease token plus `opened` (true only when this call created the tab). Never steals a tab another live process holds. Also returns `humanActiveMs` (ms since input this server did not dispatch; `null` means no data, never "no human") and, on a takeover of a tab a human used within the last 30s, a `contention` warning — the claim is never refused for it. MCP only; the CLI refuses it. The `describe_tool` meta-tool is likewise MCP-only. |
 | `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`. |
 | `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. |
 | `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. Chrome-only (`browser.downloads`). |
@@ -530,8 +596,11 @@ src/
   types.ts           # Target, TargetSelector, Uid, CDP envelopes
   index.ts           # TOOLS registry (45) + re-exported client primitives
   cli.ts             # the Bun CLI
-  mcp.ts             # stdio MCP server (exposes TOOLS via @modelcontextprotocol/sdk)
+  mcp.ts             # stdio MCP server, dual-era (serveStdio): static cacheable tools/list
+  version.ts         # the VERSION constant, single source of truth with package.json
   manifest.ts        # JSON Schemas advertised by the MCP server (one per tool)
+  toolGroups.ts      # tool-to-group map + CDP_TOOL_PROFILE resolution (startup-only filter)
+  toolDocs.ts        # full per-tool prose served on demand by describe_tool
   leases.ts          # lease records, staleness, reclamation, assertLeaseOk, CDP_REQUIRE_LEASE
   leases-tools.ts    # claim_page / release_page / list_leases
   origins.ts         # tab creation ledger: who OPENED a tab, outliving its lease