cdp-toolkit 1.0.0

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "cdp-toolkit",
+  "version": "1.0.0",
+  "description": "A lightweight chrome-devtools-mcp alternative: a single-target Chrome DevTools Protocol MCP server + CLI that drives one tab over a direct WebSocket with a bounded timeout on every call, so a stuck page can't wedge your agent or force a /mcp restart. 33 tools including built-in network mocking. No Puppeteer, no all-target fan-out.",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "Stephen Blatt",
+    "url": "https://github.com/sblattj"
+  },
+  "homepage": "https://github.com/sblattj/cdp-toolkit#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sblattj/cdp-toolkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sblattj/cdp-toolkit/issues"
+  },
+  "engines": {
+    "bun": ">=1.1.0",
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "chrome-devtools-mcp",
+    "chrome-devtools-mcp-alternative",
+    "chrome-devtools-protocol",
+    "cdp",
+    "browser-automation",
+    "web-automation",
+    "headless-chrome",
+    "chrome-automation",
+    "network-mocking",
+    "api-mocking",
+    "claude-code",
+    "claude",
+    "cursor",
+    "windsurf",
+    "ai-agent",
+    "llm-tools",
+    "puppeteer-alternative",
+    "devtools",
+    "bun"
+  ],
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "cdp-toolkit": "./dist/mcp.js",
+    "cdp": "./dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "CONTRACT.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun run scripts/build.ts",
+    "prepublishOnly": "bun run build",
+    "cdp": "bun run ./src/cli.ts",
+    "mcp": "bun run ./src/mcp.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "smoke": "bun run ./test/smoke.ts",
+    "mock:smoke": "bun run ./test/mock-smoke.ts",
+    "mcp:smoke": "bun run ./test/mcp-smoke.ts"
+  },
+  "devDependencies": {
+    "@types/node": "22.10.10",
+    "typescript": "5.7.3"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,145 @@
+#!/usr/bin/env bun
+/**
+ * cdp-toolkit CLI.
+ *
+ *   bun run src/cli.ts <tool> [--target <sel>] [--json '<obj>'] [--<key> <value> ...]
+ *   bun run src/cli.ts --list
+ *
+ * Argv parsing rules (see CONTRACT.md "Integration"):
+ *   - First positional token is the tool name (a key of TOOLS).
+ *   - `--json '<obj>'` parses a JSON object and merges it into the args object.
+ *   - `--target <sel>` sets `args.target` (a TargetSelector string).
+ *   - Any other `--key value` pair becomes `args.key`, with the value coerced:
+ *       "true"/"false" -> boolean, a numeric string -> number, else the raw
+ *       string. A bare `--flag` with no following value (or followed by another
+ *       --flag) is treated as boolean true.
+ *   - Explicit `--key` pairs OVERRIDE keys merged from `--json` (last writer
+ *     wins; --json is applied first, then the individual flags).
+ *
+ * Output:
+ *   - success -> JSON.stringify(result, null, 2) to stdout, exit 0.
+ *   - throw   -> JSON.stringify({ error: message }) to stderr, exit 1.
+ *   - no tool -> usage message to stderr, exit 1.
+ *   - --list  -> all tool names (one per line) to stdout, exit 0.
+ */
+import { TOOLS, TOOL_NAMES, type ToolName } from "./index.ts";
+
+const USAGE = `cdp-toolkit — raw single-target CDP, 29-tool chrome-devtools-mcp parity.
+
+Usage:
+  bun run src/cli.ts <tool> [--target <sel>] [--json '<obj>'] [--<key> <value> ...]
+  bun run src/cli.ts --list
+
+Examples:
+  bun run src/cli.ts list_pages
+  bun run src/cli.ts navigate_page --target index:0 --url https://example.com
+  bun run src/cli.ts click --target index:0 --uid 42
+  bun run src/cli.ts evaluate_script --json '{"expression":"1+2"}'
+  bun run src/cli.ts take_screenshot --target url:example --fullPage true
+
+Target selector grammar: active | index:N | url:<substr> | title:<substr> | <targetId>
+Run with --list to print every available tool name.`;
+
+/** Coerce a raw CLI string into boolean / number / string. */
+function coerce(raw: string): boolean | number | string {
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  // Numbers: only when the trimmed string round-trips through Number cleanly.
+  if (raw.trim() !== "" && !Number.isNaN(Number(raw)) && /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/.test(raw.trim())) {
+    return Number(raw);
+  }
+  return raw;
+}
+
+interface ParsedArgs {
+  tool?: string;
+  list: boolean;
+  args: Record<string, unknown>;
+}
+
+/** Parse process argv (already sliced to drop the runtime + script). */
+function parseArgv(argv: string[]): ParsedArgs {
+  const out: ParsedArgs = { list: false, args: {} };
+  // Collect flag pairs separately so --json can be merged BEFORE individual
+  // flags override it, regardless of token order.
+  let jsonObj: Record<string, unknown> | undefined;
+  const flagPairs: Array<[string, unknown]> = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i]!;
+    if (token === "--list") {
+      out.list = true;
+      continue;
+    }
+    if (token.startsWith("--")) {
+      const key = token.slice(2);
+      const next = argv[i + 1];
+      // A value follows unless we're at the end or the next token is another flag.
+      const hasValue = next !== undefined && !next.startsWith("--");
+      const rawValue = hasValue ? next! : "true";
+      if (hasValue) i++;
+
+      if (key === "json") {
+        const parsed = JSON.parse(rawValue) as unknown;
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+          throw new Error("--json must be a JSON object");
+        }
+        jsonObj = parsed as Record<string, unknown>;
+        continue;
+      }
+      if (key === "target") {
+        flagPairs.push(["target", rawValue]);
+        continue;
+      }
+      flagPairs.push([key, hasValue ? coerce(rawValue) : true]);
+      continue;
+    }
+    // First non-flag positional is the tool name; ignore any extras.
+    if (out.tool === undefined) out.tool = token;
+  }
+
+  // --json first, then explicit flags win.
+  if (jsonObj) Object.assign(out.args, jsonObj);
+  for (const [k, v] of flagPairs) out.args[k] = v;
+  return out;
+}
+
+function isToolName(name: string): name is ToolName {
+  return Object.prototype.hasOwnProperty.call(TOOLS, name);
+}
+
+async function main(): Promise<number> {
+  const parsed = parseArgv(process.argv.slice(2));
+
+  if (parsed.list) {
+    process.stdout.write(`${TOOL_NAMES.join("\n")}\n`);
+    return 0;
+  }
+
+  if (!parsed.tool) {
+    process.stderr.write(`${USAGE}\n`);
+    return 1;
+  }
+
+  if (!isToolName(parsed.tool)) {
+    process.stderr.write(
+      `${JSON.stringify({ error: `unknown tool '${parsed.tool}'. Run --list to see all ${TOOL_NAMES.length} tools.` })}\n`,
+    );
+    return 1;
+  }
+
+  const fn = TOOLS[parsed.tool];
+  // The registry's value type is the union of all tool signatures; each tool
+  // validates its own args at runtime, so we hand the parsed object through.
+  const result = await (fn as (args: unknown) => Promise<unknown>)(parsed.args);
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return 0;
+}
+
+main()
+  .then((code) => process.exit(code))
+  .catch((err: unknown) => {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`${JSON.stringify({ error: message })}\n`);
+    process.exit(1);
+  });

package/src/client.ts

@@ -0,0 +1,255 @@
+/**
+ * Core raw-CDP client. Zero runtime dependencies — uses Node's global
+ * WebSocket (Node >= 22; verified on Node 25.9). Every tool module is built on
+ * the primitives exported here. See CONTRACT.md.
+ */
+import type { CdpResponse, Target, TargetSelector } from "./types.ts";
+
+/** Base HTTP origin of the DevTools endpoint. Override with CDP_BASE. */
+export const BASE = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
+
+/** Default per-command timeout (ms). Override with CDP_TIMEOUT_MS. */
+export const DEFAULT_TIMEOUT_MS = Number(process.env.CDP_TIMEOUT_MS ?? 15_000);
+
+export class CdpError extends Error {
+  constructor(
+    message: string,
+    readonly code?: number,
+    readonly data?: unknown,
+  ) {
+    super(message);
+    this.name = "CdpError";
+  }
+}
+
+type EventHandler = (params: Record<string, unknown>, sessionId?: string) => void;
+
+/**
+ * A single CDP WebSocket connection (to either the browser endpoint or a page
+ * target endpoint). Correlates id->response, fans out events to subscribers,
+ * and enforces a per-command timeout so a wedged renderer can never hang a
+ * caller indefinitely (the exact failure mode that breaks the MCP layer).
+ */
+export class CdpConnection {
+  private ws?: WebSocket;
+  private nextId = 0;
+  private readonly pending = new Map<
+    number,
+    { resolve: (r: CdpResponse) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }
+  >();
+  private readonly listeners = new Map<string, Set<EventHandler>>();
+  private closed = false;
+
+  constructor(
+    readonly wsUrl: string,
+    private readonly opts: { timeoutMs?: number } = {},
+  ) {}
+
+  connect(): Promise<this> {
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(this.wsUrl);
+      this.ws = ws;
+      const openTimer = setTimeout(() => reject(new CdpError(`connect timeout: ${this.wsUrl}`)), this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+      ws.onopen = () => {
+        clearTimeout(openTimer);
+        resolve(this);
+      };
+      ws.onerror = (e: Event) => {
+        clearTimeout(openTimer);
+        const msg = (e as ErrorEvent)?.message ?? "websocket error";
+        if (this.pending.size === 0) reject(new CdpError(msg));
+        this.rejectAll(new CdpError(msg));
+      };
+      ws.onclose = () => {
+        this.closed = true;
+        this.rejectAll(new CdpError("connection closed"));
+      };
+      ws.onmessage = (ev: MessageEvent) => this.onMessage(String(ev.data));
+    });
+  }
+
+  private onMessage(raw: string): void {
+    let msg: CdpResponse & { method?: string; params?: Record<string, unknown>; sessionId?: string };
+    try {
+      msg = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (typeof msg.id === "number" && this.pending.has(msg.id)) {
+      const p = this.pending.get(msg.id)!;
+      clearTimeout(p.timer);
+      this.pending.delete(msg.id);
+      p.resolve(msg);
+      return;
+    }
+    if (msg.method) {
+      const set = this.listeners.get(msg.method);
+      if (set) for (const h of set) h(msg.params ?? {}, msg.sessionId);
+      const star = this.listeners.get("*");
+      if (star) for (const h of star) h({ method: msg.method, ...(msg.params ?? {}) }, msg.sessionId);
+    }
+  }
+
+  private rejectAll(err: Error): void {
+    for (const [, p] of this.pending) {
+      clearTimeout(p.timer);
+      p.reject(err);
+    }
+    this.pending.clear();
+  }
+
+  /** Send a CDP command and await its result. Rejects on CDP error or timeout. */
+  send<T = Record<string, unknown>>(
+    method: string,
+    params: Record<string, unknown> = {},
+    opts: { timeoutMs?: number; sessionId?: string } = {},
+  ): Promise<T> {
+    if (this.closed || !this.ws) return Promise.reject(new CdpError("connection not open"));
+    const id = ++this.nextId;
+    const timeoutMs = opts.timeoutMs ?? this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const payload: Record<string, unknown> = { id, method, params };
+    if (opts.sessionId) payload.sessionId = opts.sessionId;
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new CdpError(`'${method}' timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      this.pending.set(id, {
+        resolve: (r) => {
+          if (r.error) reject(new CdpError(`${method}: ${r.error.message}`, r.error.code, r.error.data));
+          else resolve((r.result ?? {}) as T);
+        },
+        reject,
+        timer,
+      });
+      this.ws!.send(JSON.stringify(payload));
+    });
+  }
+
+  /** Subscribe to a CDP event method (or "*" for all). Returns an unsubscribe fn. */
+  on(method: string, handler: EventHandler): () => void {
+    let set = this.listeners.get(method);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(method, set);
+    }
+    set.add(handler);
+    return () => set!.delete(handler);
+  }
+
+  /**
+   * Resolve when an event matching `method` (and optional predicate) fires, or
+   * reject on timeout. Useful for navigation/dialog/load synchronization.
+   */
+  waitFor<P = Record<string, unknown>>(
+    method: string,
+    predicate?: (params: P) => boolean,
+    timeoutMs = this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+  ): Promise<P> {
+    return new Promise<P>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        off();
+        reject(new CdpError(`waitFor('${method}') timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      const off = this.on(method, (params) => {
+        if (!predicate || predicate(params as P)) {
+          clearTimeout(timer);
+          off();
+          resolve(params as P);
+        }
+      });
+    });
+  }
+
+  close(): void {
+    this.closed = true;
+    this.rejectAll(new CdpError("closed by caller"));
+    try {
+      this.ws?.close();
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/* ----------------------------- endpoint discovery ----------------------------- */
+
+async function httpJson<T>(path: string): Promise<T> {
+  const res = await fetch(`${BASE}${path}`);
+  if (!res.ok) throw new CdpError(`${path} -> HTTP ${res.status}`);
+  return (await res.json()) as T;
+}
+
+/** All targets (GET /json/list). */
+export function listTargets(): Promise<Target[]> {
+  return httpJson<Target[]>("/json/list");
+}
+
+/** Browser-level WebSocket URL (GET /json/version) — for Target.* / Browser.*. */
+export async function browserWsUrl(): Promise<string> {
+  const v = await httpJson<{ webSocketDebuggerUrl: string }>("/json/version");
+  return v.webSocketDebuggerUrl;
+}
+
+/** Resolve a TargetSelector to a concrete page target. See types.ts for grammar. */
+export async function resolveTarget(selector: TargetSelector): Promise<Target> {
+  const targets = await listTargets();
+  const pages = targets.filter((t) => t.type === "page");
+  if (!selector || selector === "active") {
+    if (!pages.length) throw new CdpError("no page targets open");
+    return pages[0]!;
+  }
+  if (selector.startsWith("index:")) {
+    const i = Number(selector.slice(6));
+    if (!pages[i]) throw new CdpError(`no page target at index ${i} (have ${pages.length})`);
+    return pages[i]!;
+  }
+  if (selector.startsWith("url:")) {
+    const needle = selector.slice(4);
+    const hit = pages.find((t) => t.url.includes(needle));
+    if (!hit) throw new CdpError(`no page url containing '${needle}'`);
+    return hit;
+  }
+  if (selector.startsWith("title:")) {
+    const needle = selector.slice(6);
+    const hit = pages.find((t) => t.title.includes(needle));
+    if (!hit) throw new CdpError(`no page title containing '${needle}'`);
+    return hit;
+  }
+  // bare id
+  const byId = targets.find((t) => t.id === selector);
+  if (!byId) throw new CdpError(`no target with id '${selector}'`);
+  return byId;
+}
+
+/** Open a connection to the browser endpoint (Target.* / Browser.* domains). */
+export async function openBrowser(opts: { timeoutMs?: number } = {}): Promise<CdpConnection> {
+  return new CdpConnection(await browserWsUrl(), opts).connect();
+}
+
+/** Open a connection to a page target. Returns the connection and the target. */
+export async function openPage(
+  selector: TargetSelector,
+  opts: { timeoutMs?: number } = {},
+): Promise<{ conn: CdpConnection; target: Target }> {
+  const target = await resolveTarget(selector);
+  const conn = await new CdpConnection(target.webSocketDebuggerUrl, opts).connect();
+  return { conn, target };
+}
+
+/**
+ * Convenience: open a page, run `fn`, and always close the connection.
+ * The standard wrapper for stateless one-shot tools.
+ */
+export async function withPage<T>(
+  selector: TargetSelector,
+  fn: (conn: CdpConnection, target: Target) => Promise<T>,
+  opts: { timeoutMs?: number } = {},
+): Promise<T> {
+  const { conn, target } = await openPage(selector, opts);
+  try {
+    return await fn(conn, target);
+  } finally {
+    conn.close();
+  }
+}

package/src/index.ts

@@ -0,0 +1,128 @@
+/**
+ * cdp-toolkit public surface.
+ *
+ * Two exports:
+ *   1. `TOOLS` — the registry mapping every chrome-devtools-mcp tool name
+ *      (snake_case string, all 29) to its raw-CDP implementation function. The
+ *      CLI and any embedder dispatch through this single table.
+ *   2. The client primitives, re-exported so consumers can build their own
+ *      flows on the same connection/timeout machinery the tools use.
+ *
+ * Every tool fn takes a single typed args object and returns a JSON-serializable
+ * value (or throws). See CONTRACT.md for the design rules each module follows.
+ */
+
+// --- pages (browser endpoint: Target.*) ---
+import { listPages, newPage, closePage, selectPage } from "./tools/pages.ts";
+// --- navigation ---
+import { navigatePage, waitForText } from "./tools/navigation.ts";
+// --- evaluate ---
+import { evaluateScript } from "./tools/evaluate.ts";
+// --- snapshot (a11y tree + shared resolveUid helper) ---
+import { takeSnapshot } from "./tools/snapshot.ts";
+// --- input / interaction ---
+import { click, hover, drag, fill, fillForm, typeText, pressKey, uploadFile } from "./tools/input.ts";
+// --- screenshot + emulation ---
+import { takeScreenshot } from "./tools/screenshot.ts";
+import { emulate, resizePage } from "./tools/emulation.ts";
+// --- dialogs ---
+import { handleDialog } from "./tools/dialogs.ts";
+// --- console + network (read the recorder buffer) ---
+import { listConsoleMessages, getConsoleMessage } from "./tools/console.ts";
+import { listNetworkRequests, getNetworkRequest } from "./tools/network.ts";
+// --- performance ---
+import {
+  performanceStartTrace,
+  performanceStopTrace,
+  performanceAnalyzeInsight,
+  performanceTrace,
+} from "./tools/performance.ts";
+// --- heap ---
+import { takeHeapsnapshot } from "./tools/heap.ts";
+// --- lighthouse (the sole non-CDP tool) ---
+import { lighthouseAudit } from "./tools/lighthouse.ts";
+// --- network mocking (Fetch domain) — toolkit addition beyond the 29 parity tools ---
+import { mockRequest, listMocks, clearMocks } from "./tools/network_mock.ts";
+
+/** A toolkit tool: a single typed-args function returning JSON-serializable data. */
+export type ToolFn = (args: never) => Promise<unknown>;
+
+/**
+ * The complete chrome-devtools-mcp parity surface: all 29 MCP tools keyed by
+ * their canonical MCP (snake_case) name, plus one convenience superset tool
+ * (`performance_trace`, a robust single-call trace — the start/stop pair cannot
+ * span two stateless CLI processes), plus a 3-tool network-mocking group
+ * (mock_request/list_mocks/clear_mocks — a persistent per-target fake backend).
+ * 33 entries total. Listed explicitly so the mapping is auditable at a glance and
+ * the CLI can `--list` it.
+ */
+export const TOOLS = {
+  // pages (4)
+  list_pages: listPages,
+  new_page: newPage,
+  close_page: closePage,
+  select_page: selectPage,
+  // navigation (2)
+  navigate_page: navigatePage,
+  wait_for: waitForText,
+  // evaluate (1)
+  evaluate_script: evaluateScript,
+  // snapshot (1)
+  take_snapshot: takeSnapshot,
+  // interaction (8)
+  click: click,
+  hover: hover,
+  drag: drag,
+  fill: fill,
+  fill_form: fillForm,
+  type_text: typeText,
+  press_key: pressKey,
+  upload_file: uploadFile,
+  // screenshot + emulation (3)
+  take_screenshot: takeScreenshot,
+  emulate: emulate,
+  resize_page: resizePage,
+  // dialogs (1)
+  handle_dialog: handleDialog,
+  // console + network (4)
+  list_console_messages: listConsoleMessages,
+  get_console_message: getConsoleMessage,
+  list_network_requests: listNetworkRequests,
+  get_network_request: getNetworkRequest,
+  // performance (3 MCP + 1 convenience one-shot)
+  performance_start_trace: performanceStartTrace,
+  performance_stop_trace: performanceStopTrace,
+  performance_analyze_insight: performanceAnalyzeInsight,
+  performance_trace: performanceTrace,
+  // heap (1)
+  take_heapsnapshot: takeHeapsnapshot,
+  // lighthouse (1) — the only non-CDP tool
+  lighthouse_audit: lighthouseAudit,
+  // network mocking (3) — persistent per-target fake backend (toolkit addition, Fetch domain)
+  mock_request: mockRequest,
+  list_mocks: listMocks,
+  clear_mocks: clearMocks,
+} satisfies Record<string, (args: never) => Promise<unknown>>;
+
+/** Canonical MCP tool name accepted by the registry. */
+export type ToolName = keyof typeof TOOLS;
+
+/** All tool names (handy for `--list` and validation). */
+export const TOOL_NAMES = Object.keys(TOOLS) as ToolName[];
+
+/* ----------------------------- client primitives ----------------------------- */
+
+export {
+  BASE,
+  DEFAULT_TIMEOUT_MS,
+  CdpError,
+  CdpConnection,
+  listTargets,
+  browserWsUrl,
+  resolveTarget,
+  openBrowser,
+  openPage,
+  withPage,
+} from "./client.ts";
+
+export type { Target, TargetSelector, Uid, CdpResponse, CdpEvent, ToolResult } from "./types.ts";