cdp-toolkit 3.0.3 → 3.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +28 -0
- package/CONTRACT.md +2 -2
- package/README.md +122 -1
- package/dist/bidi/mux-daemon.js +675 -130
- package/dist/cli.js +1432 -635
- package/dist/index.js +1110 -116
- package/dist/mcp.js +1474 -658
- package/package.json +3 -1
- package/src/bidi/snapshot.ts +123 -113
- package/src/cdp/driver.ts +55 -41
- package/src/cdp/endpoint.ts +200 -0
- package/src/cdp/session.ts +246 -0
- package/src/cli.ts +17 -4
- package/src/client.ts +140 -16
- package/src/endpoints.ts +428 -0
- package/src/leases-tools.ts +6 -3
- package/src/leases.ts +28 -4
- package/src/manifest.ts +54 -42
- package/src/mcp.ts +52 -8
- package/src/origins.ts +5 -2
- package/src/policy.ts +163 -0
- package/src/reap.ts +14 -0
- package/src/shared-tools.ts +164 -25
- package/src/toolDocs.ts +41 -38
- package/src/tools/browser-session.ts +26 -12
- package/src/tools/dispatch-mouse.ts +2 -1
- package/src/tools/evaluate.ts +3 -3
- package/src/tools/focus-emulation.ts +5 -3
- package/src/tools/lighthouse.ts +4 -2
- package/src/tools/navigation.ts +3 -3
- package/src/tools/network_mock.ts +2 -2
- package/src/tools/performance.ts +5 -5
- package/src/tools/recorder.ts +3 -3
- package/src/tools/screencast.ts +46 -6
- package/src/tools/snapshot.ts +2 -2
- package/src/version.ts +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,34 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [3.2.0] - 2026-11-10
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- Action results now say what they touched, not just where. `click`, `hover`, `fill`, `type_text` and `upload_file` return an `element` field with a snapshot-style `role "name"` string (`{"clicked":true,"element":"button \"Save\"","x":85,"y":95}`), so a transcript shows "clicked button Save" instead of a bare uid. `fill_form` returns `elements` (one per field, `null` where none could be read) and `drag` returns `element` for the source plus `target_element` when `to` is an element. The description is read in the page before the action (a click can navigate or unmount its node; `fill` reports the field's label, not the new value), is bounded to 2s, and is omitted rather than thrown on failure, so it can never break or mask the action's own result or error. Additive: no existing field changed. (`src/shared-tools.ts`, `test/describe-element.test.ts`)
|
|
15
|
+
- The role and accessible-name heuristics behind the Firefox snapshot walker are now one shared in-page source (`ACCNAME_HELPERS_SOURCE`, `src/bidi/snapshot.ts`) used by both the walker and the new describe step; the walker's generated function is byte-identical modulo whitespace. Caveat: on Chrome the snapshot comes from the native accessibility tree while `element` uses this DOM heuristic, so the two agree for buttons, links, tabs and labelled inputs but can differ on exotic accname cases.
|
|
16
|
+
- **Browser-WebSocket transport: attach to a Chrome that serves no `/json`.** A Chrome that had debugging turned on at runtime, through the toggle on `chrome://inspect/#remote-debugging`, serves only the browser-level socket — measured on Chrome 153, `/devtools/browser/<uuid>` returns 101 while `/devtools/page/<targetId>` returns 403 and `/json/version`+`/json/list` both return 404. That is the transport a user gets when they attach to the browser they were already using rather than relaunching it, and the toolkit could not reach it at all. Discovery now falls back to `Target.getTargets` over that one socket, and each call reaches its page through a flat `Target.attachToTarget` session on it. **The HTTP path is byte-for-byte unchanged**: `listTargets` issues its original `GET /json/list` first and unconditionally, and only a request that did not answer reaches the fallback — no added round-trip, no added failure mode, and the transport is cached after the first listing. The switch happens only when detection confirms the endpoint serves no `/json`: on a Chrome that does, a single failed `/json/list` (a restart, a timeout) is reported and the next call tries HTTP again, and `/json/version` is still asked on every call, so a restarted Chrome's new browser uuid is picked up. A cached browser-socket URL that stops answering is detected again once, which picks up a restarted Chrome's new `DevToolsActivePort`. The one-target-per-call guarantee holds: `Target.getTargets` is metadata-only and attaches to nothing, so a browser with hundreds of tabs costs one round trip rather than one attach per tab. Nothing is auto-discovered — a runtime-toggled Chrome raises a modal consent prompt for each new client, so the browser is named explicitly with `CDP_BROWSER_WS` (the socket URL) or `CDP_USER_DATA_DIR` (the profile whose `DevToolsActivePort` holds it), and the default profile is never scanned. (`src/cdp/endpoint.ts`, `src/cdp/session.ts`, `src/client.ts`, `src/cdp/driver.ts`)
|
|
17
|
+
- **`bun run browser-ws:smoke` and `bun run browser-ws:wedge`.** Both spawn their own disposable headless Chrome and front it with a proxy that removes exactly what the runtime-toggle mode removes (`test/browser-ws-only-proxy.ts`), because that mode cannot be requested with a flag and puts a consent dialog in front of every client. The smoke drives discovery and per-tab work against a confirmed `/json/version=404 /json/list=404 page-ws=403` endpoint, with every phase capped at the real 60s MCP tool timeout: at `TABS=200` it listed 201 pages (410 targets across 6 types) in 0.08s, evaluated in 0.09s, snapshotted in 0.03s, and drove 5 consecutive tabs in 0.03s. The wedge proves the timeout bound survives socket sharing, which `bench:wedge` cannot — that benchmark gives every page its own socket, where a hung renderer can only block the one socket dialed into it, while this transport puts every page on ONE socket. Observed in CI on headless Chrome 156 against a 5s bound: the blackholed tab rejected at 5.00s while a witness tab answered in 3ms, `list_pages` in 4ms and a freshly opened tab in 13ms, all on the same socket. (An earlier "under 1ms" figure was an artifact: the wedge read the clock before awaiting the call, so every success measured about 0ms.) Both scripts now run in CI, in their own job. (`test/browser-ws-smoke.ts`, `test/browser-ws-wedge.ts`)
|
|
18
|
+
- With named endpoints, transport detection runs per endpoint. `CDP_BROWSER_WS` and `CDP_USER_DATA_DIR` each name one browser, so they apply to the default endpoint only. (`src/cdp/endpoint.ts`)
|
|
19
|
+
|
|
20
|
+
### Fixed
|
|
21
|
+
|
|
22
|
+
- `stop_screen_recording` failed on new ffmpeg (9.0.1 on Homebrew) with `Unrecognized option 'vsync'`, because `-vsync` is gone there. The encoder probe now also reads `ffmpeg -version` and uses `-fps_mode vfr` on ffmpeg 5.1 and later (and git snapshots), keeping `-vsync vfr` for 4.4 and 5.0. If `-version` fails or prints no readable version, the probe reads the option list from `-h full` instead, and if that fails too it picks `-fps_mode`, never the removed `-vsync`. Verified on ffmpeg 9.0.1: a 4 s two-frame ledger encoded to 4.04 s with `-fps_mode`; the old argv exited 8. (`src/tools/screencast.ts` `supportsFpsMode`, `test/screencast.test.ts`)
|
|
23
|
+
- Tests could reach the developer's own browser on the default DevTools port. A stub that fails `/json/list` on purpose sent the browser-ws fallback to the real `/json/version`, and the transport learned there stayed cached for the rest of the run, so later stubbed listing tests read live tabs. A `bun test` preload (`test/helpers/no-live-browser.ts`, wired in `bunfig.toml`) now refuses any fetch or WebSocket to the default endpoint's port and clears the transport caches before each test.
|
|
24
|
+
|
|
25
|
+
## [3.1.0] - 2026-11-10
|
|
26
|
+
|
|
27
|
+
### Added
|
|
28
|
+
|
|
29
|
+
- Named endpoints (#15): one server drives several DevTools ports, e.g. a browser and an Electron or WebView2 app such as the Microsoft Teams desktop app. Configure them with `CDP_ENDPOINTS="browser=http://127.0.0.1:9222,teams=http://127.0.0.1:9333?mode=read"` or a JSON file named by `CDP_ENDPOINTS_FILE`. Pick one per call with a `endpoint:<name>/<selector>` target prefix or an `endpoint` argument. A `chrome@<name>:` lease token also selects its own endpoint, and if the token and a prefix disagree the call is an error. Leases and origins are namespaced per endpoint. `list_pages {allEndpoints:true}` lists every endpoint, and a down one shows as `down:true`. An endpoint that is down at startup works once it comes up, with no restart. This supersedes item 5 of #12. (`src/endpoints.ts`, `src/mcp.ts`, `src/cli.ts`, `src/leases.ts`)
|
|
30
|
+
- Read-only endpoints (`?mode=read`, or `"readOnly": true` in the file): only read tools run there (snapshot, screenshot, lists, `evaluate_script`, waits). A mutating tool, or a read tool with an argument that changes the page (`reload`, `renderWidth`/`renderHeight`, a body fetch that re-requests), is refused before any CDP message goes out, with error code `read_only_endpoint`. `call_tool` can't get around this, because the inner tool is checked again. Strict-lease reaping never closes tabs on a read-only endpoint. (`src/policy.ts`, `src/reap.ts`)
|
|
31
|
+
- `tools/list` now carries `annotations.readOnlyHint` on every tool.
|
|
32
|
+
- Existing single-`CDP_BASE` setups behave as before: same lease and origin filenames, same `chrome:` tokens, and no endpoint fields in output.
|
|
33
|
+
|
|
34
|
+
### Fixed
|
|
35
|
+
|
|
36
|
+
- A tool whose result was `undefined` (e.g. `evaluate_script` on `void 0`) sent a reply with no text, and the MCP SDK rejected it with JSON-RPC -32602. It now answers `null`. The CLI prints `null` too.
|
|
37
|
+
|
|
10
38
|
## [3.0.3] - 2026-10-29
|
|
11
39
|
|
|
12
40
|
### Fixed
|
package/CONTRACT.md
CHANGED
|
@@ -12,7 +12,7 @@ writing a module.
|
|
|
12
12
|
3. **TypeScript strict.** `tsc --noEmit` must pass with `strict`, `noUncheckedIndexedAccess`, `verbatimModuleSyntax`. Import types with `import type`. Use `.ts` extensions in imports (e.g. `import { withPage } from "../client.ts"`).
|
|
13
13
|
4. **One module per assigned bundle.** Write only the files you are assigned. Never edit `client.ts`, `types.ts`, or another agent's file.
|
|
14
14
|
5. **Tool fn naming = camelCase of the MCP tool name.** `take_snapshot` → `export async function takeSnapshot(...)`. `list_network_requests` → `listNetworkRequests`. The integration step maps mechanically, so the names must be exact.
|
|
15
|
-
6. **Never re-resolve a target outside a choke point.** There are exactly three functions that turn a `TargetSelector` into a concrete tab, and all three call `assertLeaseOk`: `resolveTarget` (`src/client.ts`, Chrome), `resolveContext` (`src/bidi/driver.ts`, Firefox), and `resolvePage` (`src/shared-tools.ts`, used by `close_page`, `select_page`, and `release_page`'s `target` argument). A new tool must go through one of them. If you add a fourth resolution path, it must call `assertLeaseOk` too, or every tool on that path silently loses lease protection. Do NOT add a lease check to an individual tool: that puts the burden on every future contributor to remember it, and one forgotten tool defeats the feature for that tool. A lease conflict throws `LeaseConflictError` rather than being modelled as a capability gap under ADR-001. That departure is deliberate and reviewed: a runtime ownership collision between two agents is not a missing backend capability, so it cannot be discovered at `tools/list` time and must surface at call time. If you touch any of those three choke points, or the error handling above them, re-run `bun run lease:smoke` (`test/lease-smoke.ts`): `bun test` cannot reach this, because a lease is keyed on the claiming pid and only a second live OS process can collide with the first. That harness spawns one, drives a real browser, and asserts the refusal keeps its type, its `targetId` and its `holder` and actually blocks the side effect. It is safe against a browser with real tabs open: one throwaway tab, addressed and closed by its own id, with a runtime-captured baseline diffed at the end.
|
|
15
|
+
6. **Never re-resolve a target outside a choke point.** There are exactly three functions that turn a `TargetSelector` into a concrete tab, and all three call `assertLeaseOk`: `resolveTarget` (`src/client.ts`, Chrome), `resolveContext` (`src/bidi/driver.ts`, Firefox), and `resolvePage` (`src/shared-tools.ts`, used by `close_page`, `select_page`, and `release_page`'s `target` argument). A new tool must go through one of them. If you add a fourth resolution path, it must call `assertLeaseOk` too, or every tool on that path silently loses lease protection. Do NOT add a lease check to an individual tool: that puts the burden on every future contributor to remember it, and one forgotten tool defeats the feature for that tool. A lease conflict throws `LeaseConflictError` rather than being modelled as a capability gap under ADR-001. That departure is deliberate and reviewed: a runtime ownership collision between two agents is not a missing backend capability, so it cannot be discovered at `tools/list` time and must surface at call time. The named-endpoint prefix (`endpoint:<name>/`, issue #15) is NOT a fourth grammar arm in these pickers: `runTool` (`src/mcp.ts`) and the CLI dispatch strip it ONCE, before any of them run, and set the endpoint scope (`withEndpointScope`, `src/endpoints.ts`) that `listTargets`/`browserWsUrl` and the lease key (`chromeLeaseBackend`) read. Never parse it inside a picker. If you touch any of those three choke points, or the error handling above them, re-run `bun run lease:smoke` (`test/lease-smoke.ts`): `bun test` cannot reach this, because a lease is keyed on the claiming pid and only a second live OS process can collide with the first. That harness spawns one, drives a real browser, and asserts the refusal keeps its type, its `targetId` and its `holder` and actually blocks the side effect. It is safe against a browser with real tabs open: one throwaway tab, addressed and closed by its own id, with a runtime-captured baseline diffed at the end.
|
|
16
16
|
|
|
17
17
|
**Under `CDP_REQUIRE_LEASE` the gate does not only check, it can ACQUIRE.** `assertLeaseOk` calls `claimLease` itself when the resolved tab is unheld and strict mode is on (see `requireLease()` and the `auto` tier in `src/leases.ts`). A fourth resolution path that skipped the choke point used to lose only enforcement; under strict mode it also loses acquisition, so a tab reached that way is silently never protected even after the flag is on. `lease:smoke`'s strict-mode phase (`CDP_REQUIRE_LEASE=1`, run as a second live process) is what actually exercises this; `bun test` cannot, since acquisition is keyed on the calling pid the same way enforcement is.
|
|
18
18
|
|
|
@@ -27,7 +27,7 @@ writing a module.
|
|
|
27
27
|
## Core client API (from `src/client.ts`)
|
|
28
28
|
|
|
29
29
|
```ts
|
|
30
|
-
const BASE: string; // http://127.0.0.1:9222 (env CDP_BASE)
|
|
30
|
+
const BASE: string; // the DEFAULT endpoint's base, fixed at import: http://127.0.0.1:9222 (env CDP_BASE). Requests resolve per call via currentEndpoint() (src/endpoints.ts)
|
|
31
31
|
const DEFAULT_TIMEOUT_MS: number; // 15000 (env CDP_TIMEOUT_MS)
|
|
32
32
|
class CdpError extends Error {}
|
|
33
33
|
|
package/README.md
CHANGED
|
@@ -235,8 +235,12 @@ await TOOLS.navigate_page({ target: "index:0", url: "https://example.com" });
|
|
|
235
235
|
|
|
236
236
|
| Env var | Default | Purpose |
|
|
237
237
|
|---|---|---|
|
|
238
|
-
| `CDP_BASE` | `http://127.0.0.1:9222` | DevTools HTTP origin (drives discovery + the lighthouse `--port`). |
|
|
238
|
+
| `CDP_BASE` | `http://127.0.0.1:9222` | DevTools HTTP origin (drives discovery + the lighthouse `--port`). The endpoint named `default` when named endpoints are configured. |
|
|
239
|
+
| `CDP_ENDPOINTS` | unset | Chrome only. Extra named endpoints, `name=url` comma-separated, e.g. `browser=http://127.0.0.1:9222,teams=http://127.0.0.1:9333?mode=read`. See "Named endpoints" below. |
|
|
240
|
+
| `CDP_ENDPOINTS_FILE` | unset | Chrome only. Path to a JSON file defining named endpoints (same meaning as `CDP_ENDPOINTS`, merged with it). See "Named endpoints" below. |
|
|
239
241
|
| `CDP_TIMEOUT_MS` | `15000` | Per-command timeout. |
|
|
242
|
+
| `CDP_BROWSER_WS` | unset | The `ws://…/devtools/browser/<uuid>` URL, for a Chrome that serves no `/json`. Only consulted after an HTTP listing has already failed. See "Attaching to a Chrome that serves no `/json`" below. |
|
|
243
|
+
| `CDP_USER_DATA_DIR` | unset | Profile directory to read `DevToolsActivePort` from, to find that browser socket without naming its uuid. Opt-in on purpose: nothing is scanned unless you name it. |
|
|
240
244
|
| `CDP_ARTIFACT_DIR` | `/tmp/cdp-toolkit` | Screenshots, traces, heap snapshots, lighthouse reports, recorder buffers. |
|
|
241
245
|
| `CDP_STATE_DIR` | `/tmp/cdp-toolkit` | `select_page` selected-target file, in-flight trace state. |
|
|
242
246
|
| `CDP_EXTRACT_BASE_URL` | `http://127.0.0.1:8090/v1` | `extract_page` only. Base URL of the OpenAI-compatible extraction endpoint (the server appends `/chat/completions`). The default is loopback llm-ferry, so page content never leaves the machine; overriding it sends page content wherever the operator points. |
|
|
@@ -336,6 +340,42 @@ The server serves **both** eras off the same stdio transport, and the era is pin
|
|
|
336
340
|
|
|
337
341
|
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.
|
|
338
342
|
|
|
343
|
+
## Attaching to a Chrome that serves no `/json`
|
|
344
|
+
|
|
345
|
+
Chrome has two ways in, and until recently every build served both: (A) the HTTP discovery endpoints `/json/version` and `/json/list`, plus a per-target socket at `/devtools/page/<targetId>`; and (B) one browser-level socket at `/devtools/browser/<uuid>`, over which `Target.getTargets` lists and `Target.attachToTarget` reaches a page.
|
|
346
|
+
|
|
347
|
+
A Chrome started with `--remote-debugging-port` serves both, and nothing below is reached on one. A Chrome that had debugging turned on **at runtime**, through the toggle on `chrome://inspect/#remote-debugging`, serves only (B) — measured on Chrome 153:
|
|
348
|
+
|
|
349
|
+
| Request | `--remote-debugging-port` Chrome | runtime-toggled Chrome |
|
|
350
|
+
|---|---|---|
|
|
351
|
+
| `ws://127.0.0.1:<port>/devtools/browser/<uuid>` | 101 | **101** |
|
|
352
|
+
| `ws://127.0.0.1:<port>/devtools/page/<targetId>` | 101 | **403** |
|
|
353
|
+
| `http://127.0.0.1:<port>/json/version`, `/json/list` | 200 | **404** |
|
|
354
|
+
|
|
355
|
+
That is the transport a user gets when they attach to the browser they were *already using* rather than relaunching it — a logged-in profile with their real tabs — so it is worth supporting rather than working around. cdp-toolkit reaches it with `Target.getTargets` for discovery and one flat `Target.attachToTarget` session per call for the work, over a single refcounted browser socket.
|
|
356
|
+
|
|
357
|
+
**The HTTP path is untouched.** `list_pages` issues its original `GET /json/list` first and unconditionally; only a request that did *not* answer reaches the fallback. On a Chrome that serves (A) the code path is the one that shipped, with no added round-trip and no added failure mode. The transport is then cached, so the 404 is paid once per process.
|
|
358
|
+
|
|
359
|
+
**Nothing is auto-discovered — you name the browser.** Connecting to a DevTools endpoint is not a neutral act: a runtime-toggled Chrome raises a modal *"Allow remote debugging?"* prompt on the user's screen for each new client, and that prompt grants full access to a logged-in session. So cdp-toolkit never scans the default profile looking for a browser socket. Point it at one explicitly:
|
|
360
|
+
|
|
361
|
+
```bash
|
|
362
|
+
# the browser socket directly (its uuid is minted fresh on every Chrome start)
|
|
363
|
+
CDP_BROWSER_WS=ws://127.0.0.1:9222/devtools/browser/<uuid> cdp list_pages
|
|
364
|
+
|
|
365
|
+
# or name the profile, and the uuid is read from its DevToolsActivePort file
|
|
366
|
+
CDP_USER_DATA_DIR="$HOME/Library/Application Support/Google/Chrome" cdp list_pages
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
**The one-target-per-call guarantee still holds.** Discovery is one `Target.getTargets` — metadata only, it attaches to nothing — so a browser with hundreds of tabs costs one round trip, not one attach per tab. Each call then attaches to the one target it named and detaches on close. Every command still carries `CDP_TIMEOUT_MS`, per command id rather than per socket, so a wedged tab rejects at the bound and the shared socket stays clear for everyone else. `bun run browser-ws:wedge` proves exactly that: it blackholes one tab, then measures a witness tab, `list_pages`, and a freshly opened tab on the same socket.
|
|
370
|
+
|
|
371
|
+
```bash
|
|
372
|
+
bun run browser-ws:smoke # drives discovery + per-tab work on a browser-ws-only endpoint
|
|
373
|
+
TABS=200 bun run browser-ws:smoke
|
|
374
|
+
bun run browser-ws:wedge # one stuck tab must not wedge the shared socket
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
Both spawn their own disposable headless Chrome and front it with a proxy that removes exactly what the runtime-toggle mode removes (`test/browser-ws-only-proxy.ts`), because the real mode cannot be requested with a flag and puts a consent dialog in front of every client. They never look for a Chrome you are already running.
|
|
378
|
+
|
|
339
379
|
## Structured page extraction (`extract_page`)
|
|
340
380
|
|
|
341
381
|
`extract_page` turns a page into **schema-conformant JSON** instead of prose: it grabs the target page's HTML, cleans it (scripts, styles, hidden elements and other non-content noise stripped), and sends it to an OpenAI-compatible `/chat/completions` endpoint along with your JSON Schema, returning JSON that matches the schema — fields you name, not a paragraph you have to parse. A `selector` scopes extraction to one subtree (piercing open shadow roots), so you can extract the article or the table rather than the whole page.
|
|
@@ -661,6 +701,87 @@ So every tab this toolkit creates is written to a creation ledger, and `list_pag
|
|
|
661
701
|
- No protection from humans. The lease is enforced against cdp-toolkit's own tool calls. It cannot stop someone clicking into the tab.
|
|
662
702
|
- Not for the CLI. A CLI invocation is one process per call, so a lease it claimed would be reclaimable immediately by the dead-pid rule. `claim_page` is refused there. CLI calls can still present a token minted by the MCP server with `--lease`. Strict mode (`CDP_REQUIRE_LEASE`) is likewise MCP-only and for the same underlying reason, doubled: an auto-acquired lease would be reclaimable on arrival, worse than no lease at all, and reap would then be free to read that instantly-dead-pid record as an abandoned tab and close it on the next listing.
|
|
663
703
|
|
|
704
|
+
## Named endpoints: several browsers or apps from one server
|
|
705
|
+
|
|
706
|
+
One server can drive more than one DevTools port: your browser on `9222` and, say, the Microsoft Teams desktop app (WebView2, launched with `WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=9333`) or an Electron app. Chrome backend only.
|
|
707
|
+
|
|
708
|
+
```bash
|
|
709
|
+
CDP_ENDPOINTS="browser=http://127.0.0.1:9222,teams=http://127.0.0.1:9333?mode=read"
|
|
710
|
+
# or
|
|
711
|
+
CDP_ENDPOINTS_FILE=~/.config/cdp-endpoints.json
|
|
712
|
+
```
|
|
713
|
+
|
|
714
|
+
```json
|
|
715
|
+
{ "default": "browser",
|
|
716
|
+
"endpoints": {
|
|
717
|
+
"browser": { "base": "http://127.0.0.1:9222" },
|
|
718
|
+
"teams": { "base": "http://127.0.0.1:9333", "readOnly": true } } }
|
|
719
|
+
```
|
|
720
|
+
|
|
721
|
+
- **Selecting one:** prefix any target selector with `endpoint:<name>/`, e.g. `endpoint:teams/title:Chat` or `endpoint:teams/<targetId>`. `endpoint:teams` alone means that endpoint's active page. No prefix means the default endpoint. Tools without a `target` (`new_page`, `list_pages`) take an `endpoint` argument instead; giving both, naming different endpoints, is an error.
|
|
722
|
+
- **Discovery:** `list_pages { endpoint: "teams" }` lists one endpoint; `list_pages { allEndpoints: true }` lists all of them, tags each page row with `endpoint`, and adds an `endpoints` array where an unreachable endpoint shows as `{ endpoint, down: true, error }` instead of failing the call. Every row from a non-default endpoint carries `endpoint`.
|
|
723
|
+
- **App endpoints** often list an empty host page first (the Teams app's first `page` target has 3 accessibility nodes); the real window is the page whose title names it, so use `title:`.
|
|
724
|
+
- **The default endpoint** is the file's `"default"` key if set, else the endpoint named `default`. `CDP_BASE` is the endpoint named `default`; with neither it is `http://127.0.0.1:9222`. With only `CDP_BASE` (or nothing) set, behavior is exactly what it was before named endpoints.
|
|
725
|
+
- **Precedence:** `CDP_ENDPOINTS` and the file are merged, not shadowed: a name defined in both must be defined identically, or startup fails naming it. Listing order is env string, then file.
|
|
726
|
+
- **Errors:** a bad URL, duplicate name, unknown `mode` (only `read` / `write`), unknown key, or an unreadable or invalid file is a startup error for the MCP server (it prints the problem and exits 1) and a first-use error for the CLI. Names are letters, digits and `_`.
|
|
727
|
+
- **Late starters:** endpoints are tried on every call, never at startup, so an app launched after the server is reachable as soon as it is up.
|
|
728
|
+
- **Leases and origins** are kept per endpoint: the default endpoint's files keep their names (`lease-chrome-<id>.json`), a named one gets `lease-chrome@<name>-<id>.json`, and reap only ever compares an endpoint's leases against that endpoint's own live targets. An endpoint whose base equals the default's shares the default's lease space (two names, one browser).
|
|
729
|
+
- **Lease tokens carry their endpoint.** A token minted on a named endpoint starts `chrome@<name>:`, so `release_page { lease }` (or any call that passes only a `lease`) acts on that endpoint with no prefix needed. A prefix or `endpoint` argument that names a different endpoint than the token is an error.
|
|
730
|
+
|
|
731
|
+
### Read-only endpoints
|
|
732
|
+
|
|
733
|
+
Mark an endpoint read-only with `?mode=read` in `CDP_ENDPOINTS`, or `"readOnly": true` (or `"mode": "read"`) in the file. On a read-only endpoint, every tool that can change page or browser state is refused **before any HTTP request or CDP message is sent**, with an error naming the tool and the endpoint:
|
|
734
|
+
|
|
735
|
+
```
|
|
736
|
+
Error: 'click' is not allowed on endpoint 'teams': the endpoint is read-only (tools that change state are refused before any CDP message is sent)
|
|
737
|
+
```
|
|
738
|
+
|
|
739
|
+
The classes live in `src/policy.ts`, and a test fails if a new tool is added without being classified. A tool that is in neither class is refused (default-deny).
|
|
740
|
+
|
|
741
|
+
| Class | Tools |
|
|
742
|
+
|---|---|
|
|
743
|
+
| **Read** (allowed) | `list_pages`, `list_leases`, `take_snapshot`, `take_screenshot`, `wait_for`, `evaluate_script`, `extract_page`, `list_cookies`, `list_console_messages`, `get_console_message`, `list_network_requests`, `get_network_request`, `performance_analyze_insight`, `take_heapsnapshot`, `list_mocks` |
|
|
744
|
+
| **Mutating** (refused) | everything else: clicks, typing, fill, drag, scroll, hover, navigation, new/close/select page, emulation and resize, dialogs, cookie writes, uploads, downloads, permissions, mocks, traces, recording, Lighthouse, `claim_page` / `release_page` |
|
|
745
|
+
|
|
746
|
+
- **Argument escalation.** Some read tools change state with certain arguments, and those calls are refused too: `take_screenshot` with `renderWidth`/`renderHeight` (applies a device-metrics override), `list_console_messages` / `list_network_requests` with `reload: true`, and `get_network_request` with `includeBody` plus `url` (drives a reload capture).
|
|
747
|
+
- **`evaluate_script` is allowed.** This is a deliberate choice: the script can do anything, and the agent is responsible for running only reads on a read-only endpoint. Use it to read app state that the accessibility tree misses.
|
|
748
|
+
- **No reap.** Under `CDP_REQUIRE_LEASE`, `list_pages` and `list_leases` normally close abandoned agent tabs. On a read-only endpoint that reap is skipped entirely, so those reads never close a tab there.
|
|
749
|
+
- **`call_tool` is checked too.** `call_tool { name: "click", arguments: { target: "endpoint:teams/..." } }` is refused exactly like a direct `click`.
|
|
750
|
+
- **`tools/list` hints.** Every listed tool carries `annotations.readOnlyHint`, `true` exactly for the read class, so a client can tell which tools a read-only endpoint will accept.
|
|
751
|
+
- The CLI enforces the same policy: a refused call prints `{"error": ...}` and exits 1.
|
|
752
|
+
|
|
753
|
+
### Example: the Microsoft Teams desktop app, read-only
|
|
754
|
+
|
|
755
|
+
The macOS Teams app is built on Edge WebView2 and opens a DevTools port when launched with an extra browser argument. Quit Teams fully first, then:
|
|
756
|
+
|
|
757
|
+
```bash
|
|
758
|
+
open -a "Microsoft Teams" --env WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=9333
|
|
759
|
+
curl -s http://127.0.0.1:9333/json/version # reports an Edg/ browser
|
|
760
|
+
```
|
|
761
|
+
|
|
762
|
+
Configure it next to your browser, read-only:
|
|
763
|
+
|
|
764
|
+
```bash
|
|
765
|
+
CDP_ENDPOINTS="teams=http://127.0.0.1:9333?mode=read" # CDP_BASE (or 9222) stays the default
|
|
766
|
+
```
|
|
767
|
+
|
|
768
|
+
```json
|
|
769
|
+
{ "mcpServers": { "cdp-toolkit": {
|
|
770
|
+
"command": "npx", "args": ["-y", "cdp-toolkit"],
|
|
771
|
+
"env": { "CDP_ENDPOINTS": "teams=http://127.0.0.1:9333?mode=read" } } } }
|
|
772
|
+
```
|
|
773
|
+
|
|
774
|
+
Then read the open chat. The app's first page is an empty host page, so select the chat window by title:
|
|
775
|
+
|
|
776
|
+
```
|
|
777
|
+
list_pages { endpoint: "teams" }
|
|
778
|
+
take_snapshot { target: "endpoint:teams/title:Chat" }
|
|
779
|
+
take_screenshot { target: "endpoint:teams/title:Chat" }
|
|
780
|
+
click { target: "endpoint:teams/title:Chat", uid: "..." } # refused: read-only
|
|
781
|
+
```
|
|
782
|
+
|
|
783
|
+
If Teams is not running when the server starts, `teams` just shows as down in `list_pages { allEndpoints: true }` until you launch it; no restart needed.
|
|
784
|
+
|
|
664
785
|
## How it's built
|
|
665
786
|
|
|
666
787
|
```
|