cdp-toolkit 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@ 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.

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 — 12 of them on the MCP server's default listing**, the rest revealed by one `browser_tools` call (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).
+**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. The MCP server lists a lean 12-tool core by default and activates the rest per group via `browser_tools`, so the discovery payload stays small; the CLI exposes all 45. 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,32 +224,73 @@ 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` | `core` | MCP server only. Startup tool profile: `core` lists the 12 everyday tools plus the `browser_tools`/`describe_tool` meta-tools; `full` lists everything at startup (exact 1.x behavior). Groups toggle at runtime via `browser_tools` either way. See "Progressive disclosure" 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
 
-By default the MCP server starts on the `core` profile: 12 everyday tools (`list_pages`, `new_page`, `close_page`, `select_page`, `navigate_page`, `wait_for`, `take_snapshot`, `click`, `fill`, `type_text`, `evaluate_script`, `take_screenshot`) plus two always-listed meta-tools, `browser_tools` and `describe_tool`. The other 33 tools stay hidden inside 12 activatable groups (`input`, `cookies`, `network`, `console`, `mocking`, `emulation`, `performance`, `recording`, `leases`, `permissions`, `dialogs`, `downloads`) until one `browser_tools` call reveals them. `CDP_TOOL_PROFILE=full` in the server's env restores 1.x behavior: everything advertised at startup.
+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.
 
-The default listing costs under 2.5k tokens and the full profile about 8.5k, down from about 20.2k in 1.x (−88% and −58%). Tool names, parameters, and schema shapes are unchanged; only what a client sees at discovery time moves.
+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`.
 
-`browser_tools` drives the disclosure; `describe_tool` serves the full docs:
+**`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": "browser_tools", "arguments": {"action": "list_groups"}}
-{"tool": "browser_tools", "arguments": {"action": "activate", "group": "mocking"}}
 {"tool": "describe_tool", "arguments": {"name": "wait_for_download"}}
+{"tool": "describe_tool", "arguments": {}}
 ```
 
-Every `activate`/`deactivate`/`set_profile` that changes the listing fires `notifications/tools/list_changed` (the server declares `listChanged: true`), so a compliant client re-fetches `tools/list` and sees the new surface. Clients that cache their tool list should honor that notification rather than keep serving the stale one.
+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:
 
-- **Hidden does not mean blocked.** Only discovery is gated. `tools/call` checks backend availability, not group membership, so an agent that names a hidden-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, hidden ones included** — the full description and per-parameter docs behind the terse one-liner `tools/list` now carries.
-- **Meta-tools are MCP-only.** Profiles are an MCP-server concept: `cdp browser_tools` fails with `unknown tool`, and the CLI keeps exposing all 45 tools no matter how `CDP_TOOL_PROFILE` is set.
+- **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)
 
@@ -327,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. 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 active — backend availability first, profile second (see [Progressive disclosure](#progressive-disclosure)). Under Firefox, six capability areas 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`)
@@ -336,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. Under the MCP server's default profile only the core subset of those is listed until their groups are activated — 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 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:**
 
@@ -351,7 +392,7 @@ 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 `CDP_TOOL_PROFILE=full` show. On the MCP server's default `core` profile only 12 of them are listed at startup; the rest sit in 12 activatable groups: `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). See [Progressive disclosure](#progressive-disclosure).
+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.
 
@@ -397,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. The `browser_tools`/`describe_tool` meta-tools are likewise MCP-only. |
+| `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`). |
@@ -555,9 +596,10 @@ 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/server)
+  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 + core/full profiles (progressive disclosure)
+  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

package/dist/mcp.js

@@ -5201,7 +5201,7 @@ var TOOL_NAMES = Object.keys(TOOLS);
 
 // src/mcp.ts
 import { Server } from "@modelcontextprotocol/server";
-import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
 
 // src/manifest.ts
 var MANIFEST = [
@@ -9317,6 +9317,26 @@ var PROFILES = {
   core: ["core"],
   full: [...TOOL_GROUPS]
 };
+function resolveProfile(spec) {
+  const all = () => ({ groups: new Set(TOOL_GROUPS), label: "full" });
+  const raw = (spec ?? "").trim();
+  if (raw === "" || raw.toLowerCase() === "full")
+    return all();
+  const tokens = raw.split(",").map((t) => t.trim().toLowerCase()).filter((t) => t !== "");
+  if (tokens.includes("full"))
+    return all();
+  const known = new Set(TOOL_GROUPS);
+  const picked = new Set(["core"]);
+  for (const token of tokens) {
+    if (!known.has(token)) {
+      throw new Error(`CDP_TOOL_PROFILE: unknown tool group '${token}'. Known: full, core, ${TOOL_GROUPS.filter((g) => g !== "core").join(", ")}`);
+    }
+    picked.add(token);
+  }
+  if (picked.size === TOOL_GROUPS.length)
+    return all();
+  return { groups: picked, label: TOOL_GROUPS.filter((g) => picked.has(g)).join(",") };
+}
 
 // src/toolDocs.ts
 var TOOL_DOCS = {
@@ -9785,8 +9805,10 @@ var TOOL_DOCS = {
   }
 };
 
+// src/version.ts
+var VERSION = "2.1.0";
+
 // src/mcp.ts
-var VERSION = "2.0.0";
 var { kind: BROWSER, endpoint: FIREFOX_ENDPOINT } = resolveBackend(process.argv.slice(2));
 var AVAILABILITY = toolAvailability(BROWSER);
 var AVAILABLE_NAMES = new Set(AVAILABILITY.available);
@@ -9804,51 +9826,50 @@ function auditCoverage() {
 }
 var INSTRUCTIONS = [
   "cdp-toolkit drives a real browser over Chrome DevTools Protocol (or Firefox WebDriver-BiDi): open and drive pages, click/fill/type, screenshot and accessibility-snapshot, read console + network, set cookies, emulate devices, run Lighthouse and performance traces, record screencasts. Conventions shared across its tools:",
-  "TOOL AVAILABILITY: the server starts on the core profile (12 everyday tools); the rest are organized into groups you can discover and activate with `browser_tools` (or start with CDP_TOOL_PROFILE=full for everything at once). `describe_tool` returns full docs for any tool by name, including hidden ones. Hidden tools are still callable by name even while unlisted.",
+  "TOOL AVAILABILITY: tools/list is complete and fixed for this process's life — cache it. Its one-liners are not the full docs: call describe_tool {name} on an unfamiliar tool, or describe_tool {} for the grouped catalog. CDP_TOOL_PROFILE=core (or a group list) lists only those groups; unlisted tools stay callable by name.",
   "TARGET SELECTOR (the `target` param, unless a tool says otherwise): 'active' (default = first page) | 'index:N' (0-based) | 'url:<substr>' | 'title:<substr>' | 'label:<name>' (exact, from the origin ledger or a live lease) | a 32-hex '<targetId>'. Four Chrome-only tools (evaluate_script, list_network_requests, get_network_request, list_console_messages) also accept 'worker:<substr>' to reach a service/shared worker — e.g. an MV3 extension's background worker (worker:<extension-id> or worker:background.js); an idle-evicted worker is started first (see each tool's `wake`).",
   "LEASES (the `lease` param): claim_page, and new_page{claim:true}, mint an opaque token. Omit it for a tab THIS process already holds. It is required for a tab held by ANOTHER process, or one claimed explicitly. Under CDP_REQUIRE_LEASE the gate auto-acquires a lease for any tab this process drives — no token is surfaced, so pass `target`, not `lease` — while an explicit claim:true still demands its token on every later call. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all.",
   "ORIGIN: list_pages and list_leases tag each tab's `origin` as 'agent' (this toolkit created it) or 'unknown' — never 'human', because the toolkit cannot prove a person opened a tab. An 'agent' tab stays findable after its creator releases the lease or dies."
 ].join(`
 
 `);
-var START_PROFILE = process.env.CDP_TOOL_PROFILE === "full" ? "full" : "core";
-var activeGroups = new Set(PROFILES[START_PROFILE]);
-var META_TOOLS = [
+var PROFILE = startupProfile();
+function startupProfile() {
+  try {
+    return resolveProfile(process.env.CDP_TOOL_PROFILE);
+  } catch (err) {
+    console.error(`[cdp-toolkit] ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}
+var LISTING = Object.freeze([
   {
-    name: "browser_tools",
-    description: "Manage which cdp-toolkit tool groups are exposed (progressive disclosure). Most tools are hidden until their group is activated; activating one reveals its tools via tools/list_changed. Use action:list_groups first to see what exists.",
+    name: "describe_tool",
+    description: "Full description and per-parameter docs for any cdp-toolkit tool by name, including tools not in tools/list (unlisted tools stay callable by name). Call it before using an unfamiliar tool: the live tools/list carries only terse one-liners. With no name it returns the grouped catalog of every tool the selected browser supports.",
     inputSchema: {
       type: "object",
       properties: {
-        action: {
+        name: {
           type: "string",
-          enum: ["list_groups", "activate", "deactivate", "set_profile"],
-          description: "list_groups: show every group, its tools, and active state; activate/deactivate: toggle one group; set_profile: switch wholesale."
-        },
-        group: { type: "string", enum: [...TOOL_GROUPS], description: "Group for activate/deactivate." },
-        profile: { type: "string", enum: ["core", "full"], description: "Profile for set_profile (core=lean, full=all groups)." }
+          description: "Tool name, e.g. take_screenshot. Omit it to get the catalog: every group, its tool names, and whether the group is in tools/list."
+        }
       },
-      required: ["action"],
       additionalProperties: false
     }
   },
-  {
-    name: "describe_tool",
-    description: "Return the full description and per-parameter docs for any cdp-toolkit tool by name — including tools not currently listed. Call this before using an unfamiliar tool; the live tools/list carries only terse summaries.",
-    inputSchema: {
-      type: "object",
-      properties: { name: { type: "string", description: "Tool name, e.g. take_screenshot." } },
-      required: ["name"],
-      additionalProperties: false
-    }
-  }
-];
-function renderGroups() {
-  const lines = [`profile start=${START_PROFILE}; active groups: ${[...activeGroups].join(", ") || "(none)"}`];
+  ...MANIFEST.filter((s) => AVAILABLE_NAMES.has(s.name) && PROFILE.groups.has(TOOL_GROUP[s.name])).map((s) => ({ name: s.name, description: s.description, inputSchema: s.inputSchema }))
+]);
+function renderCatalog() {
+  const lines = [
+    `cdp-toolkit ${VERSION} · browser=${BROWSER} · ${AVAILABILITY.available.length} tools available, ${LISTING.length} in tools/list (CDP_TOOL_PROFILE=${PROFILE.label})`
+  ];
   for (const g of TOOL_GROUPS) {
     const shown = GROUP_TOOLS[g].filter((n) => AVAILABLE_NAMES.has(n));
-    lines.push(`${activeGroups.has(g) ? "[on] " : "[off]"} ${g} (${shown.length}): ${shown.join(", ")}`);
+    if (!shown.length)
+      continue;
+    lines.push(`${PROFILE.groups.has(g) ? "[listed]" : "[hidden]"} ${g} (${shown.length}): ${shown.join(", ")}`);
   }
+  lines.push("Unlisted tools are callable by name; describe_tool {name} documents any of them.");
   return lines.join(`
 `);
 }
@@ -9867,93 +9888,67 @@ ${doc.description}
 Parameters:
 ${body}`;
 }
-var server = new Server({ name: "cdp-toolkit", version: VERSION }, { capabilities: { tools: { listChanged: true } }, instructions: INSTRUCTIONS });
-server.setRequestHandler("tools/list", async () => ({
-  tools: [
-    ...META_TOOLS,
-    ...MANIFEST.filter((s) => AVAILABLE_NAMES.has(s.name) && activeGroups.has(TOOL_GROUP[s.name] ?? "")).map((s) => ({ name: s.name, description: s.description, inputSchema: s.inputSchema }))
-  ]
-}));
-server.setRequestHandler("tools/call", async (request) => {
-  const { name } = request.params;
-  const args = request.params.arguments ?? {};
-  if (name === "describe_tool") {
-    const toolName = typeof args.name === "string" ? args.name : "";
-    const known = Boolean(TOOL_DOCS[toolName]);
-    return { content: [{ type: "text", text: renderToolDoc(toolName) }], isError: !known };
-  }
-  if (name === "browser_tools") {
-    const a = args;
-    const action = typeof a.action === "string" ? a.action : "";
-    const before = [...activeGroups].sort().join(",");
-    if (action === "list_groups") {
-      return { content: [{ type: "text", text: renderGroups() }] };
-    }
-    if (action === "activate" || action === "deactivate") {
-      const group = typeof a.group === "string" ? a.group : "";
-      if (!TOOL_GROUPS.includes(group)) {
-        return { content: [{ type: "text", text: `unknown group: ${group}. Known: ${TOOL_GROUPS.join(", ")}` }], isError: true };
+var LIST_CACHE_HINT = { ttlMs: 3600000, cacheScope: "public" };
+function buildServer() {
+  const server = new Server({ name: "cdp-toolkit", version: VERSION }, {
+    capabilities: { tools: { listChanged: false } },
+    instructions: INSTRUCTIONS,
+    cacheHints: { "tools/list": LIST_CACHE_HINT, "server/discover": LIST_CACHE_HINT }
+  });
+  server.setRequestHandler("tools/list", async () => ({ tools: LISTING }));
+  server.setRequestHandler("tools/call", async (request) => {
+    const { name } = request.params;
+    const args = request.params.arguments ?? {};
+    if (name === "describe_tool") {
+      const requested = args.name;
+      if (typeof requested !== "string" || requested === "") {
+        return { content: [{ type: "text", text: renderCatalog() }] };
       }
-      if (action === "activate")
-        activeGroups.add(group);
-      else
-        activeGroups.delete(group);
-    } else if (action === "set_profile") {
-      const profile = a.profile === "full" ? "full" : a.profile === "core" ? "core" : "";
-      if (!profile)
-        return { content: [{ type: "text", text: `unknown profile: ${String(a.profile)}. Known: core, full` }], isError: true };
-      activeGroups.clear();
-      for (const g of PROFILES[profile])
-        activeGroups.add(g);
-    } else {
-      return { content: [{ type: "text", text: `unknown action: ${action}. Use list_groups | activate | deactivate | set_profile.` }], isError: true };
+      const known = Boolean(TOOL_DOCS[requested]);
+      return { content: [{ type: "text", text: renderToolDoc(requested) }], isError: !known };
+    }
+    if (!AVAILABLE_NAMES.has(name)) {
+      const gap = AVAILABILITY.unavailable.find((u) => u.name === name);
+      return {
+        content: [{ type: "text", text: `unknown tool: ${name}${gap ? ` (not available under --browser ${BROWSER}, needs: ${gap.missing.join(", ")})` : ""}` }],
+        isError: true
+      };
     }
-    if ([...activeGroups].sort().join(",") !== before) {
-      try {
-        await server.sendToolListChanged();
-      } catch (err) {
-        console.error(`[cdp-toolkit] WARN: sendToolListChanged failed: ${err instanceof Error ? err.message : String(err)}`);
+    return withLeaseScope(leaseFromArgs(args), async () => {
+      if (BROWSER === "chrome") {
+        const fn = dispatch[name];
+        if (!fn)
+          return { content: [{ type: "text", text: `unknown tool: ${name}` }], isError: true };
+        try {
+          const result = await fn(args);
+          return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+        }
       }
-    }
-    return { content: [{ type: "text", text: renderGroups() }] };
-  }
-  if (!AVAILABLE_NAMES.has(name)) {
-    const gap = AVAILABILITY.unavailable.find((u) => u.name === name);
-    return {
-      content: [{ type: "text", text: `unknown tool: ${name}${gap ? ` (not available under --browser ${BROWSER}, needs: ${gap.missing.join(", ")})` : ""}` }],
-      isError: true
-    };
-  }
-  return withLeaseScope(leaseFromArgs(args), async () => {
-    if (BROWSER === "chrome") {
-      const fn = dispatch[name];
-      if (!fn)
+      const neutralFn = neutralDispatch[name];
+      if (!neutralFn)
         return { content: [{ type: "text", text: `unknown tool: ${name}` }], isError: true };
       try {
-        const result = await fn(args);
+        const session2 = await getOrCreateFirefoxSession({ endpoint: FIREFOX_ENDPOINT });
+        const result = await neutralFn(session2.driver, args);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
       }
-    }
-    const neutralFn = neutralDispatch[name];
-    if (!neutralFn)
-      return { content: [{ type: "text", text: `unknown tool: ${name}` }], isError: true };
-    try {
-      const session2 = await getOrCreateFirefoxSession({ endpoint: FIREFOX_ENDPOINT });
-      const result = await neutralFn(session2.driver, args);
-      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
-    }
+    });
   });
-});
+  return server;
+}
 auditCoverage();
 markLongLivedProcess();
-await server.connect(new StdioServerTransport);
-console.error(`[cdp-toolkit] MCP server v${VERSION} ready, browser=${BROWSER}${FIREFOX_ENDPOINT ? ` (attach ${FIREFOX_ENDPOINT})` : ""}, ${AVAILABILITY.available.length} tools, CDP_BASE=${BASE}`);
+var handle = serveStdio(({ era }) => {
+  console.error(`[cdp-toolkit] connection pinned to the ${era} protocol era`);
+  return buildServer();
+}, { onerror: (err) => console.error(`[cdp-toolkit] stdio: ${err.message}`) });
+console.error(`[cdp-toolkit] MCP server v${VERSION} ready, browser=${BROWSER}${FIREFOX_ENDPOINT ? ` (attach ${FIREFOX_ENDPOINT})` : ""}, ${AVAILABILITY.available.length} tools available, ${LISTING.length} listed (CDP_TOOL_PROFILE=${PROFILE.label}), CDP_BASE=${BASE}`);
 var shuttingDown = false;
 async function shutdown() {
   if (shuttingDown)
@@ -9961,6 +9956,9 @@ async function shutdown() {
   shuttingDown = true;
   await disposeFirefoxSession();
   await disposeBrowserSession();
+  await handle.close().catch(() => {
+    return;
+  });
   process.exit(0);
 }
 process.on("SIGINT", () => void shutdown());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-toolkit",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "A lightweight chrome-devtools-mcp alternative: an MCP server + CLI that drives the tabs you name, one target per call over one direct WebSocket, with a bounded timeout on every call, so a stuck page can't wedge your agent or force a /mcp restart. Chrome over CDP and Firefox over WebDriver BiDi, with tools a backend can't run absent from tools/list rather than throwing mid-task. 45 tools including built-in network mocking, a cookie group, tab leases with human-activity detection, real HTML5 drag-and-drop, raw mouse/scroll dispatch, downloads, permission grants, and tab-to-video screen recording so several agents can drive one browser without stealing each other's tabs or a human's. No Puppeteer, no all-target fan-out.",
   "type": "module",
   "license": "MIT",

package/src/mcp.ts

@@ -10,6 +10,9 @@
  *
  * Launch: `bunx -y cdp-toolkit`  (or `bun run src/mcp.ts` from a checkout)
  * Config:  CDP_BASE (default http://127.0.0.1:9222), CDP_TIMEOUT_MS, CDP_ARTIFACT_DIR,
+ *          CDP_TOOL_PROFILE (`full` — the default — advertises every group; `core` advertises
+ *          just the 12 everyday tools; or a comma-separated group list, e.g. `core,network`.
+ *          Startup-only filter on what tools/list shows; unlisted tools stay callable by name),
  *          CDP_FIREFOX_ENDPOINT (attach to a user-launched Firefox instead of spawning one;
  *          see backend.ts's ATTACH mode).
  *
@@ -17,7 +20,7 @@
  */
 import { Server } from "@modelcontextprotocol/server";
 import type { Tool } from "@modelcontextprotocol/server";
-import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { TOOLS, TOOL_NAMES, BASE } from "./index.ts";
 import { MANIFEST } from "./manifest.ts";
 import { resolveBackend, getOrCreateFirefoxSession, disposeFirefoxSession } from "./backend.ts";
@@ -25,10 +28,9 @@ import { disposeBrowserSession } from "./tools/browser-session.ts";
 import { toolAvailability } from "./capabilities.ts";
 import { FIREFOX_TOOLS } from "./firefox-tools.ts";
 import { leaseFromArgs, markLongLivedProcess, withLeaseScope } from "./leases.ts";
-import { TOOL_GROUP, TOOL_GROUPS, GROUP_TOOLS, PROFILES, type ProfileName } from "./toolGroups.ts";
+import { resolveProfile, TOOL_GROUP, TOOL_GROUPS, GROUP_TOOLS } from "./toolGroups.ts";
 import { TOOL_DOCS } from "./toolDocs.ts";
-
-const VERSION = "2.0.0";
+import { VERSION } from "./version.ts";
 
 // Backend + (Firefox only) attach endpoint are read once at startup (MCP has no per-call notion
 // of backend): --browser flag / CDP_BROWSER env, else "chrome" (zero behavior change for existing
@@ -52,70 +54,85 @@ function auditCoverage(): void {
   if (orphanSchema.length) console.error(`[cdp-toolkit] WARN: manifest schemas with no registered tool: ${orphanSchema.join(", ")}`);
 }
 
-// Server `instructions` (MCP initialize result): the cross-cutting conventions that
-// used to be re-stated inside every tool's schema — the target-selector grammar, the
-// lease-token model, the MV3 worker/wake arm, the origin vocabulary. Stating them ONCE
-// here (loaded a single time at init) is what let the per-tool descriptions and the
+// Server `instructions` (returned by server/discover on 2026-era connections, and by
+// initialize on 2025-era ones): the cross-cutting conventions that used to be re-stated
+// inside every tool's schema — the target-selector grammar, the lease-token model, the
+// MV3 worker/wake arm, the origin vocabulary — plus how to read the (fixed, cacheable)
+// tool listing. Stating them ONCE here is what let the per-tool descriptions and the
 // 42-way-duplicated `lease` param collapse to short pointers, cutting the tools/list
 // payload without losing a single behavior. Kept under Claude Code's 2KB instructions
 // cap and front-loaded (grammar + leases before origin) so nothing critical is clipped.
 const INSTRUCTIONS = [
   "cdp-toolkit drives a real browser over Chrome DevTools Protocol (or Firefox WebDriver-BiDi): open and drive pages, click/fill/type, screenshot and accessibility-snapshot, read console + network, set cookies, emulate devices, run Lighthouse and performance traces, record screencasts. Conventions shared across its tools:",
-  "TOOL AVAILABILITY: the server starts on the core profile (12 everyday tools); the rest are organized into groups you can discover and activate with `browser_tools` (or start with CDP_TOOL_PROFILE=full for everything at once). `describe_tool` returns full docs for any tool by name, including hidden ones. Hidden tools are still callable by name even while unlisted.",
+  "TOOL AVAILABILITY: tools/list is complete and fixed for this process's life — cache it. Its one-liners are not the full docs: call describe_tool {name} on an unfamiliar tool, or describe_tool {} for the grouped catalog. CDP_TOOL_PROFILE=core (or a group list) lists only those groups; unlisted tools stay callable by name.",
   "TARGET SELECTOR (the `target` param, unless a tool says otherwise): 'active' (default = first page) | 'index:N' (0-based) | 'url:<substr>' | 'title:<substr>' | 'label:<name>' (exact, from the origin ledger or a live lease) | a 32-hex '<targetId>'. Four Chrome-only tools (evaluate_script, list_network_requests, get_network_request, list_console_messages) also accept 'worker:<substr>' to reach a service/shared worker — e.g. an MV3 extension's background worker (worker:<extension-id> or worker:background.js); an idle-evicted worker is started first (see each tool's `wake`).",
   "LEASES (the `lease` param): claim_page, and new_page{claim:true}, mint an opaque token. Omit it for a tab THIS process already holds. It is required for a tab held by ANOTHER process, or one claimed explicitly. Under CDP_REQUIRE_LEASE the gate auto-acquires a lease for any tab this process drives — no token is surfaced, so pass `target`, not `lease` — while an explicit claim:true still demands its token on every later call. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all.",
   "ORIGIN: list_pages and list_leases tag each tab's `origin` as 'agent' (this toolkit created it) or 'unknown' — never 'human', because the toolkit cannot prove a person opened a tab. An 'agent' tab stays findable after its creator releases the lease or dies.",
 ].join("\n\n");
 
-// Progressive disclosure: start with a lean profile (default "core") and reveal
-// further tool groups on demand via the browser_tools meta-tool, which fires
-// notifications/tools/list_changed so the client re-fetches tools/list. This keeps
-// the baseline tools/list payload — and thus the context tokens the toolkit costs —
-// a fraction of the full 45-tool surface until a group is actually needed. Set
-// CDP_TOOL_PROFILE=full to advertise everything at startup (prior behavior).
-const START_PROFILE: ProfileName = process.env.CDP_TOOL_PROFILE === "full" ? "full" : "core";
-const activeGroups = new Set<string>(PROFILES[START_PROFILE]);
+// Progressive disclosure, 2.1 model: the tool listing is STATIC — computed once here and
+// returned byte-identical to every tools/list on every connection, so a client may cache
+// it (the 2026-07-28 revision requires the tool set not to change as a side effect of
+// other requests, which is exactly what the 2.0 browser_tools toggle did). Discovery is
+// the HOST's job per the MCP client best-practices: the client picks which of the listed
+// tools to put in front of the model. `describe_tool` is the inspect layer — one call
+// returns the full prose for any tool, listed or not — and CDP_TOOL_PROFILE is the only
+// filter, applied once at startup by whoever configures the server. A tool that the
+// profile hides is still callable by name; hiding only trims the listing's token cost.
+const PROFILE = startupProfile();
 
-/** Always-listed meta-tools that drive disclosure; never part of a group. */
-const META_TOOLS: ReadonlyArray<{ name: string; description: string; inputSchema: Tool["inputSchema"] }> = [
+/** Read CDP_TOOL_PROFILE once; an unknown group name is a configuration error, not a warning. */
+function startupProfile() {
+  try {
+    return resolveProfile(process.env.CDP_TOOL_PROFILE);
+  } catch (err) {
+    console.error(`[cdp-toolkit] ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * The one and only tools/list payload, in manifest order (a stable order is a spec
+ * SHOULD, and it keeps the response byte-identical across calls so caching is real):
+ * describe_tool first, then every manifest tool the selected backend can run whose
+ * group the profile advertises. Descriptions here are the compressed one-liners —
+ * full prose is served on demand by describe_tool.
+ *
+ * Frozen at runtime (the handler hands the SAME array to every caller); the cast back to
+ * a mutable Tool[] is only because ListToolsResult declares `tools` mutable.
+ */
+const LISTING: Tool[] = Object.freeze([
   {
-    name: "browser_tools",
+    name: "describe_tool",
     description:
-      "Manage which cdp-toolkit tool groups are exposed (progressive disclosure). Most tools are hidden until their group is activated; activating one reveals its tools via tools/list_changed. Use action:list_groups first to see what exists.",
+      "Full description and per-parameter docs for any cdp-toolkit tool by name, including tools not in tools/list (unlisted tools stay callable by name). Call it before using an unfamiliar tool: the live tools/list carries only terse one-liners. With no name it returns the grouped catalog of every tool the selected browser supports.",
     inputSchema: {
       type: "object",
       properties: {
-        action: {
+        name: {
           type: "string",
-          enum: ["list_groups", "activate", "deactivate", "set_profile"],
-          description: "list_groups: show every group, its tools, and active state; activate/deactivate: toggle one group; set_profile: switch wholesale.",
+          description: "Tool name, e.g. take_screenshot. Omit it to get the catalog: every group, its tool names, and whether the group is in tools/list.",
         },
-        group: { type: "string", enum: [...TOOL_GROUPS], description: "Group for activate/deactivate." },
-        profile: { type: "string", enum: ["core", "full"], description: "Profile for set_profile (core=lean, full=all groups)." },
       },
-      required: ["action"],
-      additionalProperties: false,
-    } as Tool["inputSchema"],
-  },
-  {
-    name: "describe_tool",
-    description: "Return the full description and per-parameter docs for any cdp-toolkit tool by name — including tools not currently listed. Call this before using an unfamiliar tool; the live tools/list carries only terse summaries.",
-    inputSchema: {
-      type: "object",
-      properties: { name: { type: "string", description: "Tool name, e.g. take_screenshot." } },
-      required: ["name"],
       additionalProperties: false,
     } as Tool["inputSchema"],
   },
-];
+  ...MANIFEST
+    .filter((s) => AVAILABLE_NAMES.has(s.name) && PROFILE.groups.has(TOOL_GROUP[s.name]!))
+    .map((s) => ({ name: s.name, description: s.description, inputSchema: s.inputSchema as Tool["inputSchema"] })),
+] satisfies Tool[]) as Tool[];
 
-/** Human-readable dump of every group, its tools, and whether it's currently active. */
-function renderGroups(): string {
-  const lines = [`profile start=${START_PROFILE}; active groups: ${[...activeGroups].join(", ") || "(none)"}`];
+/** describe_tool with no name: every group the backend supports, and whether it is listed. */
+function renderCatalog(): string {
+  const lines = [
+    `cdp-toolkit ${VERSION} · browser=${BROWSER} · ${AVAILABILITY.available.length} tools available, ${LISTING.length} in tools/list (CDP_TOOL_PROFILE=${PROFILE.label})`,
+  ];
   for (const g of TOOL_GROUPS) {
     const shown = GROUP_TOOLS[g].filter((n) => AVAILABLE_NAMES.has(n));
-    lines.push(`${activeGroups.has(g) ? "[on] " : "[off]"} ${g} (${shown.length}): ${shown.join(", ")}`);
+    if (!shown.length) continue;
+    lines.push(`${PROFILE.groups.has(g) ? "[listed]" : "[hidden]"} ${g} (${shown.length}): ${shown.join(", ")}`);
   }
+  lines.push("Unlisted tools are callable by name; describe_tool {name} documents any of them.");
   return lines.join("\n");
 }
 
@@ -129,114 +146,114 @@ function renderToolDoc(toolName: string): string {
   return `${toolName}${group ? ` [group: ${group}]` : ""}\n\n${doc.description}\n\nParameters:\n${body}`;
 }
 
-const server = new Server({ name: "cdp-toolkit", version: VERSION }, { capabilities: { tools: { listChanged: true } }, instructions: INSTRUCTIONS });
-
-server.setRequestHandler('tools/list', async () => ({
-  // Two-axis disclosure: (1) the always-present meta-tools; (2) manifest tools the
-  // selected backend can run AND whose group is currently active. Descriptions/schemas
-  // here are the compressed form — full prose is served on demand by describe_tool.
-  tools: [
-    ...META_TOOLS,
-    ...MANIFEST
-      .filter((s) => AVAILABLE_NAMES.has(s.name) && activeGroups.has(TOOL_GROUP[s.name] ?? ""))
-      .map((s) => ({ name: s.name, description: s.description, inputSchema: s.inputSchema as Tool["inputSchema"] })),
-  ],
-}));
+// The listing never changes, and it is identical for every caller (a stdio server has no
+// per-caller auth), so it is `public` with a 1h TTL rather than the SDK's conservative
+// { ttlMs: 0, cacheScope: 'private' } default. A restart under a different CDP_TOOL_PROFILE
+// or --browser is a different server configuration, not a mid-life change to this one.
+const LIST_CACHE_HINT = { ttlMs: 3_600_000, cacheScope: "public" } as const;
 
-server.setRequestHandler('tools/call', async (request) => {
-  const { name } = request.params;
-  const args = (request.params.arguments ?? {}) as unknown;
+/**
+ * Build one server instance. serveStdio calls this per connection — and possibly twice
+ * per process (a server/discover probe instance that is discarded if the client falls
+ * back to initialize) — so it must be PURE: no I/O, no shared mutable state.
+ *
+ * We stay on the low-level `Server` rather than `McpServer` deliberately, despite the
+ * deprecation note. McpServer.registerTool 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 (src/manifest.ts). McpServer also cannot express
+ * "hidden tools remain callable by name", which is the whole point of CDP_TOOL_PROFILE.
+ */
+function buildServer(): Server {
+  const server = new Server(
+    { name: "cdp-toolkit", version: VERSION },
+    {
+      // The list is fixed for the life of the process; nothing will ever notify.
+      capabilities: { tools: { listChanged: false } },
+      instructions: INSTRUCTIONS,
+      cacheHints: { "tools/list": LIST_CACHE_HINT, "server/discover": LIST_CACHE_HINT },
+    },
+  );
 
-  // Meta-tools are handled at the MCP layer (they mutate what tools/list advertises)
-  // and never enter the browser dispatch or a lease scope.
-  if (name === "describe_tool") {
-    const toolName = typeof (args as { name?: unknown }).name === "string" ? (args as { name: string }).name : "";
-    const known = Boolean(TOOL_DOCS[toolName]);
-    return { content: [{ type: "text" as const, text: renderToolDoc(toolName) }], isError: !known };
-  }
+  server.setRequestHandler('tools/list', async () => ({ tools: LISTING }));
 
-  if (name === "browser_tools") {
-    const a = args as { action?: unknown; group?: unknown; profile?: unknown };
-    const action = typeof a.action === "string" ? a.action : "";
-    const before = [...activeGroups].sort().join(",");
+  server.setRequestHandler('tools/call', async (request) => {
+    const { name } = request.params;
+    const args = (request.params.arguments ?? {}) as unknown;
 
-    if (action === "list_groups") {
-      return { content: [{ type: "text" as const, text: renderGroups() }] };
-    }
-    if (action === "activate" || action === "deactivate") {
-      const group = typeof a.group === "string" ? a.group : "";
-      if (!(TOOL_GROUPS as readonly string[]).includes(group)) {
-        return { content: [{ type: "text" as const, text: `unknown group: ${group}. Known: ${TOOL_GROUPS.join(", ")}` }], isError: true };
+    // describe_tool is handled at the MCP layer (it reads only static docs) and never
+    // enters the browser dispatch or a lease scope. With a name it documents one tool —
+    // listed or not; with no name it returns the grouped catalog.
+    if (name === "describe_tool") {
+      const requested = (args as { name?: unknown }).name;
+      if (typeof requested !== "string" || requested === "") {
+        return { content: [{ type: "text" as const, text: renderCatalog() }] };
       }
-      if (action === "activate") activeGroups.add(group);
-      else activeGroups.delete(group);
-    } else if (action === "set_profile") {
-      const profile = a.profile === "full" ? "full" : a.profile === "core" ? "core" : "";
-      if (!profile) return { content: [{ type: "text" as const, text: `unknown profile: ${String(a.profile)}. Known: core, full` }], isError: true };
-      activeGroups.clear();
-      for (const g of PROFILES[profile]) activeGroups.add(g);
-    } else {
-      return { content: [{ type: "text" as const, text: `unknown action: ${action}. Use list_groups | activate | deactivate | set_profile.` }], isError: true };
+      const known = Boolean(TOOL_DOCS[requested]);
+      return { content: [{ type: "text" as const, text: renderToolDoc(requested) }], isError: !known };
     }
 
-    if ([...activeGroups].sort().join(",") !== before) {
-      try {
-        await server.sendToolListChanged();
-      } catch (err) {
-        console.error(`[cdp-toolkit] WARN: sendToolListChanged failed: ${err instanceof Error ? err.message : String(err)}`);
-      }
+    if (!AVAILABLE_NAMES.has(name)) {
+      const gap = AVAILABILITY.unavailable.find((u) => u.name === name);
+      return {
+        content: [{ type: "text" as const, text: `unknown tool: ${name}${gap ? ` (not available under --browser ${BROWSER}, needs: ${gap.missing.join(", ")})` : ""}` }],
+        isError: true,
+      };
     }
-    return { content: [{ type: "text" as const, text: renderGroups() }] };
-  }
 
-  if (!AVAILABLE_NAMES.has(name)) {
-    const gap = AVAILABILITY.unavailable.find((u) => u.name === name);
-    return {
-      content: [{ type: "text" as const, text: `unknown tool: ${name}${gap ? ` (not available under --browser ${BROWSER}, needs: ${gap.missing.join(", ")})` : ""}` }],
-      isError: true,
-    };
-  }
+    // ONE lease scope per dispatch, wrapping BOTH backend branches. This is the
+    // reason no tool takes a lease parameter: the token rides the async context
+    // down to whichever resolution path the tool eventually reaches, so a tool
+    // added tomorrow is covered with no action from whoever writes it. Reading
+    // 'lease' off args here is the only place the MCP layer knows the key exists.
+    return withLeaseScope(leaseFromArgs(args), async () => {
+      if (BROWSER === "chrome") {
+        const fn = dispatch[name];
+        if (!fn) return { content: [{ type: "text" as const, text: `unknown tool: ${name}` }], isError: true };
+        try {
+          const result = await fn(args);
+          return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          return { content: [{ type: "text" as const, text: `Error: ${message}` }], isError: true };
+        }
+      }
 
-  // ONE lease scope per dispatch, wrapping BOTH backend branches. This is the
-  // reason no tool takes a lease parameter: the token rides the async context
-  // down to whichever resolution path the tool eventually reaches, so a tool
-  // added tomorrow is covered with no action from whoever writes it. Reading
-  // 'lease' off args here is the only place the MCP layer knows the key exists.
-  return withLeaseScope(leaseFromArgs(args), async () => {
-    if (BROWSER === "chrome") {
-      const fn = dispatch[name];
-      if (!fn) return { content: [{ type: "text" as const, text: `unknown tool: ${name}` }], isError: true };
+      // Firefox: one BiDi session memoized for the life of this server process (lifetime "session",
+      // ADR-001); launched lazily on the first Firefox tool call, torn down on shutdown below.
+      const neutralFn = neutralDispatch[name];
+      if (!neutralFn) return { content: [{ type: "text" as const, text: `unknown tool: ${name}` }], isError: true };
       try {
-        const result = await fn(args);
+        const session = await getOrCreateFirefoxSession({ endpoint: FIREFOX_ENDPOINT });
+        const result = await neutralFn(session.driver, args);
         return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         return { content: [{ type: "text" as const, text: `Error: ${message}` }], isError: true };
       }
-    }
-
-    // Firefox: one BiDi session memoized for the life of this server process (lifetime "session",
-    // ADR-001); launched lazily on the first Firefox tool call, torn down on shutdown below.
-    const neutralFn = neutralDispatch[name];
-    if (!neutralFn) return { content: [{ type: "text" as const, text: `unknown tool: ${name}` }], isError: true };
-    try {
-      const session = await getOrCreateFirefoxSession({ endpoint: FIREFOX_ENDPOINT });
-      const result = await neutralFn(session.driver, args);
-      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      return { content: [{ type: "text" as const, text: `Error: ${message}` }], isError: true };
-    }
+    });
   });
-});
+
+  return server;
+}
 
 auditCoverage();
 // This process is the long-lived MCP server, which is what makes strict mode
 // (CDP_REQUIRE_LEASE) safe to honor here and unsafe in cli.ts. See requireLease.
 markLongLivedProcess();
-await server.connect(new StdioServerTransport());
+
+// serveStdio owns the era decision for the connection: a modern opening (server/discover
+// with the per-request _meta envelope) pins a 2026-07-28 instance, a 2025-era `initialize`
+// pins a legacy one. legacy:'serve' (the default) is deliberate — 2025-era clients keep the
+// initialize handshake they expect, so this upgrade is invisible to them.
+const handle = serveStdio(
+  ({ era }) => {
+    console.error(`[cdp-toolkit] connection pinned to the ${era} protocol era`);
+    return buildServer();
+  },
+  { onerror: (err) => console.error(`[cdp-toolkit] stdio: ${err.message}`) },
+);
 console.error(
-  `[cdp-toolkit] MCP server v${VERSION} ready, browser=${BROWSER}${FIREFOX_ENDPOINT ? ` (attach ${FIREFOX_ENDPOINT})` : ""}, ${AVAILABILITY.available.length} tools, CDP_BASE=${BASE}`,
+  `[cdp-toolkit] MCP server v${VERSION} ready, browser=${BROWSER}${FIREFOX_ENDPOINT ? ` (attach ${FIREFOX_ENDPOINT})` : ""}, ${AVAILABILITY.available.length} tools available, ${LISTING.length} listed (CDP_TOOL_PROFILE=${PROFILE.label}), CDP_BASE=${BASE}`,
 );
 
 // LAUNCH-mode Firefox owns a real OS process (see bidi/launch.ts): it must be reaped on every
@@ -255,6 +272,9 @@ async function shutdown(): Promise<void> {
   // Track P3). Unlike Firefox it owns no OS process, so process.exit would collect it anyway; it is
   // closed explicitly so shutdown does not depend on that, and is a no-op when neither tool ran.
   await disposeBrowserSession();
+  // Close the stdio connection (pinned instance + transport) last, so a tool call still
+  // in flight over it cannot outlive the browser resources it was driving.
+  await handle.close().catch(() => undefined);
   process.exit(0);
 }
 process.on("SIGINT", () => void shutdown());

package/src/toolGroups.ts

@@ -47,3 +47,35 @@ export const PROFILES = {
 } as const;
 
 export type ProfileName = keyof typeof PROFILES;
+
+/**
+ * Resolve CDP_TOOL_PROFILE into the set of groups whose tools tools/list advertises.
+ *
+ * The profile is a STARTUP filter, read once: the listing it selects is fixed for the
+ * life of the process (2.1 dropped the runtime `browser_tools` toggle, so the tool set
+ * can never change as a side effect of another request — a spec MUST). Accepted
+ * spellings: unset/empty or "full" (everything), "core" (the lean everyday set), or a
+ * comma-separated list of group names. `core` is always included, so a list can never
+ * strand the basics.
+ */
+export function resolveProfile(spec: string | undefined): { groups: ReadonlySet<ToolGroup>; label: string } {
+  const all = (): { groups: ReadonlySet<ToolGroup>; label: string } => ({ groups: new Set(TOOL_GROUPS), label: "full" });
+  const raw = (spec ?? "").trim();
+  if (raw === "" || raw.toLowerCase() === "full") return all();
+
+  const tokens = raw.split(",").map((t) => t.trim().toLowerCase()).filter((t) => t !== "");
+  if (tokens.includes("full")) return all();
+
+  const known = new Set<string>(TOOL_GROUPS);
+  const picked = new Set<ToolGroup>(["core"]);
+  for (const token of tokens) {
+    if (!known.has(token)) {
+      throw new Error(`CDP_TOOL_PROFILE: unknown tool group '${token}'. Known: full, core, ${TOOL_GROUPS.filter((g) => g !== "core").join(", ")}`);
+    }
+    picked.add(token as ToolGroup);
+  }
+  if (picked.size === TOOL_GROUPS.length) return all();
+  // Canonical label: TOOL_GROUPS order, not the order the caller typed, so the ready
+  // line and the catalog header read the same for every equivalent spelling.
+  return { groups: picked, label: TOOL_GROUPS.filter((g) => picked.has(g)).join(",") };
+}

package/src/version.ts

@@ -0,0 +1,9 @@
+/**
+ * Single source of truth for the package version string.
+ *
+ * mcp.ts reports it in the MCP `serverInfo` (and thus in the 2026-07-28
+ * `_meta['io.modelcontextprotocol/serverInfo']` envelope) and on its stderr
+ * ready line; keeping it in its own module means a release bump touches one
+ * line here plus package.json, not a const buried in the server.
+ */
+export const VERSION = "2.1.0";