cdp-toolkit 3.0.2 → 3.1.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 +25 -0
- package/CONTRACT.md +2 -2
- package/README.md +85 -2
- package/dist/bidi/mux-daemon.js +316 -10
- package/dist/cli.js +615 -94
- package/dist/index.js +440 -41
- package/dist/mcp.js +667 -133
- package/package.json +1 -1
- package/src/cdp/driver.ts +71 -11
- package/src/cli.ts +17 -4
- package/src/client.ts +22 -6
- package/src/endpoints.ts +428 -0
- package/src/install/browser.ts +9 -3
- package/src/install/wizard.ts +8 -8
- 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 +72 -4
- package/src/toolDocs.ts +39 -36
- package/src/tools/browser-session.ts +26 -12
- package/src/tools/dispatch-mouse.ts +2 -1
- package/src/tools/focus-emulation.ts +5 -3
- package/src/tools/lighthouse.ts +4 -2
- package/src/version.ts +1 -1
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cdp-toolkit",
|
|
3
|
-
"version": "3.0
|
|
3
|
+
"version": "3.1.0",
|
|
4
4
|
"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. 48 tools (only 5 core tools listed by default, plus search_tools/call_tool to reach the rest) 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.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
package/src/cdp/driver.ts
CHANGED
|
@@ -7,7 +7,8 @@
|
|
|
7
7
|
*/
|
|
8
8
|
import { CdpConnection, CdpError, listTargets, openBrowser, openPage, resolveTarget } from "../client.ts";
|
|
9
9
|
import type { Target, TargetSelector } from "../types.ts";
|
|
10
|
-
import { LeaseConflictError } from "../leases.ts";
|
|
10
|
+
import { chromeLeaseBackend, LeaseConflictError } from "../leases.ts";
|
|
11
|
+
import { currentEndpoint } from "../endpoints.ts";
|
|
11
12
|
import { BEACON_READ_EXPRESSION, BEACON_SOURCE, BeaconSessions, RENDERER_PROBE_EXPRESSION, RENDERER_PROBE_TIMEOUT_MS, sendInput } from "../activity.ts";
|
|
12
13
|
import { resolveUid } from "../tools/snapshot.ts";
|
|
13
14
|
import { resolveWorkerSelector } from "./workers.ts";
|
|
@@ -703,7 +704,7 @@ class CdpPageDriver implements PageDriver {
|
|
|
703
704
|
* one.
|
|
704
705
|
*/
|
|
705
706
|
private async dispatchInput<T = Record<string, unknown>>(method: string, params: Record<string, unknown> = {}): Promise<T> {
|
|
706
|
-
return sendInput<T>(this.conn,
|
|
707
|
+
return sendInput<T>(this.conn, chromeLeaseBackend(), this.info.id, method, params);
|
|
707
708
|
}
|
|
708
709
|
/** Same as ensureDomain but tolerates the enable call itself failing (matches a legacy
|
|
709
710
|
* `.catch(() => undefined)` site); a failed enable is NOT re-attempted on the next call. */
|
|
@@ -1597,6 +1598,14 @@ class CdpPageDriver implements PageDriver {
|
|
|
1597
1598
|
*/
|
|
1598
1599
|
const beaconSessions = new BeaconSessions<CdpConnection>((conn) => conn.close());
|
|
1599
1600
|
|
|
1601
|
+
/** Beacon sessions are keyed by endpoint plus target id: a target id only means
|
|
1602
|
+
* something inside one browser, and named endpoints are separate browsers. The
|
|
1603
|
+
* default endpoint keeps the bare id. */
|
|
1604
|
+
function beaconKey(targetId: string): string {
|
|
1605
|
+
const backend = chromeLeaseBackend(currentEndpoint());
|
|
1606
|
+
return backend === "chrome" ? targetId : `${backend}\u0000${targetId}`;
|
|
1607
|
+
}
|
|
1608
|
+
|
|
1600
1609
|
/** The page endpoint for a target id, or undefined if the browser no longer has it. */
|
|
1601
1610
|
async function targetWsUrl(targetId: string): Promise<string | undefined> {
|
|
1602
1611
|
const hit = (await listTargets()).find((t) => t.id === targetId);
|
|
@@ -1691,6 +1700,56 @@ function noSuchTarget(e: unknown): never {
|
|
|
1691
1700
|
if (typeof (e as { code?: unknown } | null | undefined)?.code === "string") throw e;
|
|
1692
1701
|
throw driverError("no-such-target", e instanceof CdpError ? e.message : String(e));
|
|
1693
1702
|
}
|
|
1703
|
+
/** Upper bound on waiting for a new tab to settle; see createSettledTarget. */
|
|
1704
|
+
export const NEW_TARGET_SETTLE_MS = 2000;
|
|
1705
|
+
|
|
1706
|
+
/**
|
|
1707
|
+
* Create a tab and return only once the browser has finished adopting it.
|
|
1708
|
+
*
|
|
1709
|
+
* Vivaldi wedges a tab that anything attaches to in the first few milliseconds
|
|
1710
|
+
* after Target.createTarget: the tab keeps an empty URL, its renderer never
|
|
1711
|
+
* answers again (Page.enable, Runtime.evaluate and runIfWaitingForDebugger all
|
|
1712
|
+
* time out), and only a manual reload recovers it. new_page{claim:true} hit this
|
|
1713
|
+
* every time, because the activity beacon attaches straight after creation.
|
|
1714
|
+
* Measured on Vivaldi 8.2 (Chromium 152): an attach at ~0ms wedged 5/5 tabs
|
|
1715
|
+
* (https and about:blank alike, page socket or flattened session alike); an
|
|
1716
|
+
* attach after the tab's first Target.targetInfoChanged loaded 5/5.
|
|
1717
|
+
*
|
|
1718
|
+
* So: discover targets, create, and wait for that first targetInfoChanged for
|
|
1719
|
+
* this id, capped at NEW_TARGET_SETTLE_MS. The listener is registered BEFORE
|
|
1720
|
+
* createTarget because the event can beat the command's response. A browser
|
|
1721
|
+
* that never sends the event costs at most the cap, never a failure.
|
|
1722
|
+
*/
|
|
1723
|
+
export async function createSettledTarget(
|
|
1724
|
+
conn: Pick<CdpConnection, "send" | "on">,
|
|
1725
|
+
url: string,
|
|
1726
|
+
settleMs = NEW_TARGET_SETTLE_MS,
|
|
1727
|
+
): Promise<string> {
|
|
1728
|
+
const changed = new Set<string>();
|
|
1729
|
+
let id = "";
|
|
1730
|
+
let wake: (() => void) | undefined;
|
|
1731
|
+
const off = conn.on("Target.targetInfoChanged", (params) => {
|
|
1732
|
+
const t = (params as { targetInfo?: { targetId?: string } }).targetInfo?.targetId;
|
|
1733
|
+
if (!t) return;
|
|
1734
|
+
changed.add(t);
|
|
1735
|
+
if (t === id) wake?.();
|
|
1736
|
+
});
|
|
1737
|
+
try {
|
|
1738
|
+
await conn.send("Target.setDiscoverTargets", { discover: true }).catch(() => undefined);
|
|
1739
|
+
const { targetId } = await conn.send<{ targetId: string }>("Target.createTarget", { url });
|
|
1740
|
+
if (!targetId) throw driverError("page-error", "Target.createTarget returned no targetId");
|
|
1741
|
+
id = targetId;
|
|
1742
|
+
if (!changed.has(targetId)) {
|
|
1743
|
+
await new Promise<void>((resolve) => {
|
|
1744
|
+
const timer = setTimeout(resolve, settleMs);
|
|
1745
|
+
wake = () => { clearTimeout(timer); resolve(); };
|
|
1746
|
+
});
|
|
1747
|
+
}
|
|
1748
|
+
return targetId;
|
|
1749
|
+
} finally {
|
|
1750
|
+
off();
|
|
1751
|
+
}
|
|
1752
|
+
}
|
|
1694
1753
|
class CdpBrowserDriver implements BrowserDriver {
|
|
1695
1754
|
readonly scheme = "cdp";
|
|
1696
1755
|
readonly lifetime: LifetimeModel = "per-call";
|
|
@@ -1706,8 +1765,7 @@ class CdpBrowserDriver implements BrowserDriver {
|
|
|
1706
1765
|
}
|
|
1707
1766
|
async newPage(url?: string): Promise<PageInfo> {
|
|
1708
1767
|
return withBrowserConn(async (conn) => {
|
|
1709
|
-
const
|
|
1710
|
-
if (!targetId) throw driverError("page-error", "Target.createTarget returned no targetId");
|
|
1768
|
+
const targetId = await createSettledTarget(conn, url ?? "about:blank");
|
|
1711
1769
|
return { id: targetId, url: url ?? "about:blank", title: "" };
|
|
1712
1770
|
});
|
|
1713
1771
|
}
|
|
@@ -1720,7 +1778,7 @@ class CdpBrowserDriver implements BrowserDriver {
|
|
|
1720
1778
|
// Opportunistic, not load-bearing: the beacon socket dies with the tab
|
|
1721
1779
|
// anyway, and readBeaconOver's dead-connection branch would drop it on the
|
|
1722
1780
|
// next read. Dropping it here just avoids holding a corpse until then.
|
|
1723
|
-
if (res.success !== false) beaconSessions.drop(id);
|
|
1781
|
+
if (res.success !== false) beaconSessions.drop(beaconKey(id));
|
|
1724
1782
|
return { success: res.success ?? true };
|
|
1725
1783
|
});
|
|
1726
1784
|
}
|
|
@@ -1772,7 +1830,8 @@ class CdpBrowserDriver implements BrowserDriver {
|
|
|
1772
1830
|
* into a document that already has it adds no second set of listeners.
|
|
1773
1831
|
*/
|
|
1774
1832
|
async installActivityBeacon(targetId: string): Promise<boolean> {
|
|
1775
|
-
const
|
|
1833
|
+
const key = beaconKey(targetId);
|
|
1834
|
+
const held = beaconSessions.get(key);
|
|
1776
1835
|
if (held) {
|
|
1777
1836
|
const rearmed = await held
|
|
1778
1837
|
.send("Runtime.evaluate", { expression: BEACON_SOURCE, returnByValue: true })
|
|
@@ -1781,7 +1840,7 @@ class CdpBrowserDriver implements BrowserDriver {
|
|
|
1781
1840
|
if (rearmed) return true;
|
|
1782
1841
|
// The socket is gone (tab closed, browser restarted): fall through and
|
|
1783
1842
|
// build a fresh one rather than reporting a beacon that is not there.
|
|
1784
|
-
beaconSessions.drop(
|
|
1843
|
+
beaconSessions.drop(key);
|
|
1785
1844
|
}
|
|
1786
1845
|
const wsUrl = await targetWsUrl(targetId).catch(() => undefined);
|
|
1787
1846
|
if (!wsUrl) return false;
|
|
@@ -1795,7 +1854,7 @@ class CdpBrowserDriver implements BrowserDriver {
|
|
|
1795
1854
|
conn.close();
|
|
1796
1855
|
return false;
|
|
1797
1856
|
}
|
|
1798
|
-
beaconSessions.set(
|
|
1857
|
+
beaconSessions.set(key, conn);
|
|
1799
1858
|
return true;
|
|
1800
1859
|
}
|
|
1801
1860
|
|
|
@@ -1810,11 +1869,12 @@ class CdpBrowserDriver implements BrowserDriver {
|
|
|
1810
1869
|
* CLI, which holds nothing.
|
|
1811
1870
|
*/
|
|
1812
1871
|
async readActivityBeacon(targetId: string): Promise<number | null> {
|
|
1813
|
-
const
|
|
1872
|
+
const key = beaconKey(targetId);
|
|
1873
|
+
const held = beaconSessions.get(key);
|
|
1814
1874
|
if (held) {
|
|
1815
1875
|
const value = await readBeaconOver(held);
|
|
1816
1876
|
if (value !== undefined) return value;
|
|
1817
|
-
beaconSessions.drop(
|
|
1877
|
+
beaconSessions.drop(key);
|
|
1818
1878
|
}
|
|
1819
1879
|
const wsUrl = await targetWsUrl(targetId).catch(() => undefined);
|
|
1820
1880
|
if (!wsUrl) return null;
|
|
@@ -1842,7 +1902,7 @@ class CdpBrowserDriver implements BrowserDriver {
|
|
|
1842
1902
|
* would let one wedged tab cost the listing two timeouts instead of one.
|
|
1843
1903
|
*/
|
|
1844
1904
|
async probeRenderer(targetId: string, timeoutMs: number = RENDERER_PROBE_TIMEOUT_MS): Promise<{ responsive: boolean; beaconTs: number | null }> {
|
|
1845
|
-
const held = beaconSessions.get(targetId);
|
|
1905
|
+
const held = beaconSessions.get(beaconKey(targetId));
|
|
1846
1906
|
if (held) return probeOver(held, timeoutMs);
|
|
1847
1907
|
const wsUrl = await targetWsUrl(targetId).catch(() => undefined);
|
|
1848
1908
|
if (!wsUrl) return { responsive: false, beaconTs: null };
|
package/src/cli.ts
CHANGED
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
* wins; --json is applied first, then the individual flags).
|
|
20
20
|
*
|
|
21
21
|
* Output:
|
|
22
|
-
* - success -> JSON.stringify(result, null, 2) to stdout, exit 0.
|
|
22
|
+
* - success -> JSON.stringify(result ?? null, null, 2) to stdout, exit 0.
|
|
23
23
|
* - throw -> JSON.stringify({ error: message }) to stderr, exit 1.
|
|
24
24
|
* - no tool -> usage message to stderr, exit 1.
|
|
25
25
|
* - --list -> all tool names (one per line) to stdout, exit 0.
|
|
@@ -29,7 +29,9 @@ import { resolveBackend, stripBrowserFlag, stripConnectFlag, startFirefoxSession
|
|
|
29
29
|
import { toolAvailability } from "./capabilities.ts";
|
|
30
30
|
import { FIREFOX_TOOLS } from "./firefox-tools.ts";
|
|
31
31
|
import { leaseFromArgs, withLeaseScope } from "./leases.ts";
|
|
32
|
+
import { ENDPOINTS_FIREFOX_MESSAGE, stripEndpointArgs, usesEndpointArgs, withEndpointScope } from "./endpoints.ts";
|
|
32
33
|
import { MANIFEST } from "./manifest.ts";
|
|
34
|
+
import { assertAllowed } from "./policy.ts";
|
|
33
35
|
import { runInstaller } from "./install/wizard.ts";
|
|
34
36
|
import { realpathSync } from "node:fs";
|
|
35
37
|
import { fileURLToPath } from "node:url";
|
|
@@ -344,16 +346,27 @@ async function main(): Promise<number> {
|
|
|
344
346
|
return withLeaseScope(leaseFromArgs(parsed.args), async () => {
|
|
345
347
|
if (browser === "chrome") {
|
|
346
348
|
const fn = TOOLS[tool];
|
|
349
|
+
// Same endpoint scope as mcp.ts's runTool: the endpoint:<name>/ prefix (or
|
|
350
|
+
// --endpoint) is resolved and stripped once, here. A bad name or a malformed
|
|
351
|
+
// CDP_ENDPOINTS throws to main's catch, which prints {"error": ...} and exits 1.
|
|
352
|
+
const { endpoint, args: toolArgs } = stripEndpointArgs(parsed.args);
|
|
353
|
+
// Read-only endpoint policy, before the tool runs (same check as mcp.ts's runTool).
|
|
354
|
+
// A PolicyError throws to main's catch: {"error": "'click' is not allowed on endpoint ..."}, exit 1.
|
|
355
|
+
assertAllowed(tool, endpoint, toolArgs);
|
|
347
356
|
// The registry's value type is the union of all tool signatures; each tool
|
|
348
357
|
// validates its own args at runtime, so we hand the parsed object through.
|
|
349
|
-
const result = await (fn as (args: unknown) => Promise<unknown>)(
|
|
350
|
-
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
|
|
358
|
+
const result = await withEndpointScope(endpoint, () => (fn as (args: unknown) => Promise<unknown>)(toolArgs));
|
|
359
|
+
process.stdout.write(`${JSON.stringify(result ?? null, null, 2)}\n`);
|
|
351
360
|
return 0;
|
|
352
361
|
}
|
|
353
362
|
|
|
354
363
|
// Firefox: one process per invocation. Launch (or, with --connect/CDP_FIREFOX_ENDPOINT,
|
|
355
364
|
// attach), run exactly one tool call, always dispose, even if the tool call itself throws —
|
|
356
365
|
// in launch mode that reaps the spawned process; in attach mode it only ends the BiDi session.
|
|
366
|
+
if (usesEndpointArgs(parsed.args)) {
|
|
367
|
+
process.stderr.write(`${JSON.stringify({ error: ENDPOINTS_FIREFOX_MESSAGE })}\n`);
|
|
368
|
+
return 1;
|
|
369
|
+
}
|
|
357
370
|
const neutralFn = FIREFOX_TOOLS[tool];
|
|
358
371
|
if (!neutralFn) {
|
|
359
372
|
process.stderr.write(`${JSON.stringify({ error: `tool '${tool}' has no Firefox implementation wired` })}\n`);
|
|
@@ -362,7 +375,7 @@ async function main(): Promise<number> {
|
|
|
362
375
|
const session = await startFirefoxSession({ endpoint });
|
|
363
376
|
try {
|
|
364
377
|
const result = await neutralFn(session.driver, parsed.args as never);
|
|
365
|
-
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
|
|
378
|
+
process.stdout.write(`${JSON.stringify(result ?? null, null, 2)}\n`);
|
|
366
379
|
return 0;
|
|
367
380
|
} finally {
|
|
368
381
|
await session.dispose();
|
package/src/client.ts
CHANGED
|
@@ -4,8 +4,9 @@
|
|
|
4
4
|
* the primitives exported here. See CONTRACT.md.
|
|
5
5
|
*/
|
|
6
6
|
import type { CdpResponse, Target, TargetSelector } from "./types.ts";
|
|
7
|
-
import { assertLeaseOk } from "./leases.ts";
|
|
7
|
+
import { assertLeaseOk, chromeLeaseBackend } from "./leases.ts";
|
|
8
8
|
import { resolveLiveLabel } from "./origins.ts";
|
|
9
|
+
import { currentEndpoint, defaultEndpoint, DEFAULT_CDP_BASE } from "./endpoints.ts";
|
|
9
10
|
import {
|
|
10
11
|
isWorkerSelector,
|
|
11
12
|
isWorkerTargetType,
|
|
@@ -24,8 +25,21 @@ import {
|
|
|
24
25
|
FRAME_EMPTY_NEEDLE_MESSAGE,
|
|
25
26
|
} from "./frames.ts";
|
|
26
27
|
|
|
27
|
-
/**
|
|
28
|
-
|
|
28
|
+
/**
|
|
29
|
+
* Base HTTP origin of the DEFAULT DevTools endpoint, fixed at import (CDP_BASE, else
|
|
30
|
+
* http://127.0.0.1:9222, or the default named by CDP_ENDPOINTS / CDP_ENDPOINTS_FILE).
|
|
31
|
+
* Kept for library callers; nothing in this package reads it to build a URL any more:
|
|
32
|
+
* every request resolves its base per call through currentEndpoint() (src/endpoints.ts).
|
|
33
|
+
* A malformed endpoint config must not crash the import, so this falls back to the old
|
|
34
|
+
* expression and the config error surfaces on first use (or at MCP/CLI startup).
|
|
35
|
+
*/
|
|
36
|
+
export const BASE: string = (() => {
|
|
37
|
+
try {
|
|
38
|
+
return defaultEndpoint().base;
|
|
39
|
+
} catch {
|
|
40
|
+
return process.env.CDP_BASE ?? DEFAULT_CDP_BASE;
|
|
41
|
+
}
|
|
42
|
+
})();
|
|
29
43
|
|
|
30
44
|
/** Default per-command timeout (ms). Override with CDP_TIMEOUT_MS. */
|
|
31
45
|
export const DEFAULT_TIMEOUT_MS = Number(process.env.CDP_TIMEOUT_MS ?? 15_000);
|
|
@@ -194,7 +208,9 @@ export class CdpConnection {
|
|
|
194
208
|
/* ----------------------------- endpoint discovery ----------------------------- */
|
|
195
209
|
|
|
196
210
|
async function httpJson<T>(path: string): Promise<T> {
|
|
197
|
-
|
|
211
|
+
// Resolved PER CALL, never cached: the endpoint comes from the dispatch scope, and an
|
|
212
|
+
// endpoint that was down a moment ago is simply tried again.
|
|
213
|
+
const res = await fetch(`${currentEndpoint().base}${path}`);
|
|
198
214
|
if (!res.ok) throw new CdpError(`${path} -> HTTP ${res.status}`);
|
|
199
215
|
return (await res.json()) as T;
|
|
200
216
|
}
|
|
@@ -237,7 +253,7 @@ export async function resolveTarget(selector: TargetSelector, opts: { lease?: st
|
|
|
237
253
|
// target we just resolved. Passing it would only suggest a check is happening
|
|
238
254
|
// that is not. target-gone earns its keep on claim, and on a list_leases
|
|
239
255
|
// reap, where a record's id may genuinely be absent from the browser.
|
|
240
|
-
await assertLeaseOk(
|
|
256
|
+
await assertLeaseOk(chromeLeaseBackend(), hit.id, { lease: opts.lease, url: hit.url, title: hit.title });
|
|
241
257
|
return hit;
|
|
242
258
|
}
|
|
243
259
|
|
|
@@ -266,7 +282,7 @@ async function pickTarget(targets: Target[], selector: TargetSelector): Promise<
|
|
|
266
282
|
}
|
|
267
283
|
if (selector.startsWith("label:")) {
|
|
268
284
|
const label = selector.slice(6);
|
|
269
|
-
const { matchIds, knownLabels } = await resolveLiveLabel(
|
|
285
|
+
const { matchIds, knownLabels } = await resolveLiveLabel(chromeLeaseBackend(), label, pages.map((t) => t.id));
|
|
270
286
|
if (matchIds.length > 1) {
|
|
271
287
|
throw new CdpError(`label 'label:${label}' matches more than one live target: ${matchIds.join(", ")}. Resolve by target id instead.`);
|
|
272
288
|
}
|