cdp-toolkit 1.0.0

package/src/mcp.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env bun
+/**
+ * cdp-toolkit MCP server (stdio).
+ *
+ * Exposes the toolkit's raw-CDP tools to any MCP client (Claude Code, etc.) over
+ * the standard stdio transport. It does NOT connect to Chrome at startup — each
+ * tool call lazily opens a single-target CDP connection (with its own timeout),
+ * so the server loads cleanly even when Chrome isn't running; individual calls
+ * then fail with a clear error if the browser is unreachable.
+ *
+ * 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.
+ *
+ * stdout is the JSON-RPC channel — all diagnostics go to stderr only.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { TOOLS, TOOL_NAMES, BASE } from "./index.ts";
+import { MANIFEST } from "./manifest.ts";
+
+const VERSION = "1.0.0";
+
+/** Loose dispatch view of the strongly-typed TOOLS registry. */
+const dispatch = TOOLS as Record<string, (args: unknown) => Promise<unknown>>;
+
+/** Warn (to stderr) about any registry/manifest drift, but don't fail startup. */
+function auditCoverage(): void {
+  const manifestNames = new Set(MANIFEST.map((s) => s.name));
+  const registryNames = new Set<string>(TOOL_NAMES);
+  const missingSchema = [...registryNames].filter((n) => !manifestNames.has(n));
+  const orphanSchema = [...manifestNames].filter((n) => !registryNames.has(n));
+  if (missingSchema.length) console.error(`[cdp-toolkit] WARN: tools without a manifest schema: ${missingSchema.join(", ")}`);
+  if (orphanSchema.length) console.error(`[cdp-toolkit] WARN: manifest schemas with no registered tool: ${orphanSchema.join(", ")}`);
+}
+
+const server = new Server({ name: "cdp-toolkit", version: VERSION }, { capabilities: { tools: {} } });
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: MANIFEST.map((s) => ({ name: s.name, description: s.description, inputSchema: s.inputSchema })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name } = request.params;
+  const args = (request.params.arguments ?? {}) as unknown;
+  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 };
+  }
+});
+
+auditCoverage();
+await server.connect(new StdioServerTransport());
+console.error(`[cdp-toolkit] MCP server v${VERSION} ready — ${MANIFEST.length} tools, CDP_BASE=${BASE}`);

package/src/tools/console.ts

@@ -0,0 +1,199 @@
+/**
+ * console.ts — read console output captured by the recorder.
+ *
+ *   list_console_messages -> listConsoleMessages
+ *   get_console_message   -> getConsoleMessage
+ *
+ * READ vs CAPTURE model (see recorder.ts header):
+ *   - default ({ reload: false }): read the target's shared "latest" buffer
+ *     (rec-<targetId>.jsonl) and return its parsed console entries. If no capture
+ *     has run for this target, returns an empty list.
+ *   - { reload: true }: run a captureWindow (records BOTH console+network into a
+ *     unique per-capture file), Page.reload, capture for `durationMs` (default
+ *     2500ms), stop, then read+return the console entries from that capture. The
+ *     both-domains capture means a network reload never wipes console history.
+ */
+import { readFile } from "node:fs/promises";
+import { CdpError, resolveTarget } from "../client.ts";
+import type { TargetSelector } from "../types.ts";
+import { recFile, captureWindow } from "./recorder.ts";
+import type { RecLine } from "./recorder.ts";
+
+const DEFAULT_CAPTURE_MS = 2500;
+
+/** A normalized console entry returned to callers. */
+export interface ConsoleEntry {
+  index: number;
+  /** Origin domain: "console" (Runtime.consoleAPICalled), "exception" (Runtime.exceptionThrown), "log" (Log.entryAdded). */
+  source: "console" | "exception" | "log";
+  /** Severity level: log/info/warn/error/debug/verbose. */
+  level: string;
+  /** Best-effort flattened text of the message. */
+  text: string;
+  /** Page URL associated with the message, if present. */
+  url?: string;
+  /** Source line number, if present. */
+  lineNumber?: number;
+  /** Wall-clock capture time (ms since epoch). */
+  ts: number;
+}
+
+export interface ListConsoleMessagesArgs {
+  target?: TargetSelector;
+  /** Record fresh by reloading the page and capturing for a window. */
+  reload?: boolean;
+  /** Capture window for reload mode (ms). Default 2500. */
+  durationMs?: number;
+}
+
+export interface GetConsoleMessageArgs {
+  target?: TargetSelector;
+  /** Zero-based index into the parsed console entries. Default 0. */
+  index?: number;
+}
+
+/** Stringify a single CDP RemoteObject arg into readable text. */
+function remoteObjectToText(arg: Record<string, unknown> | undefined): string {
+  if (!arg) return "";
+  if (arg.value !== undefined && arg.value !== null) return String(arg.value);
+  if (typeof arg.description === "string") return arg.description;
+  if (typeof arg.unserializableValue === "string") return arg.unserializableValue;
+  if (arg.type === "undefined") return "undefined";
+  if (arg.type === "object" && arg.subtype === "null") return "null";
+  if (typeof arg.type === "string") return `[${arg.type}]`;
+  return "";
+}
+
+/** Map a persisted JSONL line into a normalized ConsoleEntry. */
+function lineToEntry(line: RecLine, index: number): ConsoleEntry | null {
+  const p = line.params;
+  if (line.method === "Runtime.consoleAPICalled") {
+    const args = Array.isArray(p.args) ? (p.args as Array<Record<string, unknown>>) : [];
+    return {
+      index,
+      source: "console",
+      level: typeof p.type === "string" ? p.type : "log",
+      text: args.map(remoteObjectToText).join(" "),
+      url: undefined,
+      ts: line.ts,
+    };
+  }
+  if (line.method === "Runtime.exceptionThrown") {
+    const detail = (p.exceptionDetails ?? {}) as Record<string, unknown>;
+    const exception = (detail.exception ?? {}) as Record<string, unknown>;
+    const text =
+      remoteObjectToText(exception) ||
+      (typeof detail.text === "string" ? detail.text : "uncaught exception");
+    return {
+      index,
+      source: "exception",
+      level: "error",
+      text,
+      url: typeof detail.url === "string" ? detail.url : undefined,
+      lineNumber: typeof detail.lineNumber === "number" ? detail.lineNumber : undefined,
+      ts: line.ts,
+    };
+  }
+  if (line.method === "Log.entryAdded") {
+    const entry = (p.entry ?? {}) as Record<string, unknown>;
+    return {
+      index,
+      source: "log",
+      level: typeof entry.level === "string" ? entry.level : "info",
+      text: typeof entry.text === "string" ? entry.text : "",
+      url: typeof entry.url === "string" ? entry.url : undefined,
+      lineNumber: typeof entry.lineNumber === "number" ? entry.lineNumber : undefined,
+      ts: line.ts,
+    };
+  }
+  return null;
+}
+
+/** Parse a JSONL buffer file into console entries (skips network lines). */
+async function readConsoleEntries(file: string): Promise<ConsoleEntry[]> {
+  let raw: string;
+  try {
+    raw = await readFile(file, "utf8");
+  } catch {
+    return []; // no buffer yet
+  }
+  const out: ConsoleEntry[] = [];
+  for (const rawLine of raw.split("\n")) {
+    const trimmed = rawLine.trim();
+    if (!trimmed) continue;
+    let line: RecLine;
+    try {
+      line = JSON.parse(trimmed) as RecLine;
+    } catch {
+      continue;
+    }
+    if (line.kind !== "console") continue;
+    const entry = lineToEntry(line, out.length);
+    if (entry) out.push(entry);
+  }
+  return out;
+}
+
+/**
+ * list_console_messages — return console output for the target. With
+ * `reload:true`, records a fresh capture window by reloading the page.
+ */
+export async function listConsoleMessages(args: ListConsoleMessagesArgs = {}): Promise<{
+  target: { id: string; url: string; title: string };
+  count: number;
+  messages: ConsoleEntry[];
+  droppedWrites?: number;
+}> {
+  if (args.reload) {
+    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS);
+    await cap.stop();
+    const messages = await readConsoleEntries(cap.file);
+    return {
+      target: cap.resolved,
+      count: messages.length,
+      messages,
+      droppedWrites: cap.droppedWrites(),
+    };
+  }
+
+  const target = await resolveTarget(args.target);
+  const messages = await readConsoleEntries(recFile(target.id));
+  return {
+    target: { id: target.id, url: target.url, title: target.title },
+    count: messages.length,
+    messages,
+  };
+}
+
+/**
+ * get_console_message — return a single console entry by index from the
+ * existing buffer for the target. Throws if the index is out of range.
+ */
+export async function getConsoleMessage(args: GetConsoleMessageArgs = {}): Promise<ConsoleEntry> {
+  const target = await resolveTarget(args.target);
+  const messages = await readConsoleEntries(recFile(target.id));
+  const index = args.index ?? 0;
+  const entry = messages[index];
+  if (!entry) {
+    throw new CdpError(
+      `no console message at index ${index} (have ${messages.length}); run list_console_messages or list with reload:true first`,
+    );
+  }
+  return entry;
+}
+
+/*
+ * CDP methods / domains used (via recorder.ts + this module):
+ *   Page.enable           (reload mode)
+ *   Page.reload           (reload mode)
+ *   Runtime.enable / Runtime.consoleAPICalled / Runtime.exceptionThrown (recorder)
+ *   Log.enable / Log.entryAdded                                          (recorder)
+ *
+ * Parity gaps vs chrome-devtools-mcp:
+ *   - RemoteObject args are flattened to text best-effort; deep object inspection
+ *     (expandable previews) the DevTools UI shows is not reconstructed.
+ *   - Stack traces from exceptions are summarized to the top message + url/line,
+ *     not the full frame list.
+ *   - Without reload:true the result reflects whatever a prior recorder buffered;
+ *     the MCP keeps a live in-process buffer for its managed page.
+ */

package/src/tools/dialogs.ts

@@ -0,0 +1,236 @@
+/**
+ * dialogs.ts — JavaScript dialog handling (alert / confirm / prompt / beforeunload).
+ *
+ * Replicates chrome-devtools-mcp's `handle_dialog`. A JS dialog opened by the
+ * page (alert/confirm/prompt/beforeunload) blocks the renderer until the
+ * embedder responds via Page.handleJavaScriptDialog. Over raw CDP we:
+ *   1. Page.enable
+ *   2. subscribe to Page.javascriptDialogOpening
+ *   3. on fire, respond with Page.handleJavaScriptDialog({ accept, promptText })
+ *
+ * Two modes are supported per CONTRACT:
+ *   - "wait for next dialog then handle" (default): arm the listener and resolve
+ *     when the next dialog is handled, or time out if none appears.
+ *   - "auto-handle for N ms" ({ autoMs }): handle every dialog that opens during
+ *     a fixed window, then resolve with the list handled.
+ *
+ * Because a dialog blocks the renderer, the code that *triggers* the dialog
+ * (e.g. a Runtime.evaluate of `confirm("x")`) must NOT be awaited before the
+ * dialog is handled — otherwise it deadlocks. `handleDialogForExpression` arms
+ * the listener, fires the expression WITHOUT awaiting, waits for the dialog to
+ * be handled, then awaits the now-unblocked evaluate result.
+ */
+import type { CdpConnection } from "../client.ts";
+import { CdpError, openPage } from "../client.ts";
+import type { TargetSelector } from "../types.ts";
+
+/** Raw shape of the Page.javascriptDialogOpening event params. */
+interface JavascriptDialogOpening {
+  url: string;
+  message: string;
+  type: "alert" | "confirm" | "prompt" | "beforeunload" | string;
+  hasBrowserHandler: boolean;
+  defaultPrompt?: string;
+}
+
+/** A single handled dialog. */
+export interface HandledDialog {
+  type: string;
+  message: string;
+  url: string;
+  defaultPrompt?: string;
+  accept: boolean;
+  promptText?: string;
+  handled: true;
+}
+
+export interface HandleDialogArgs {
+  target?: TargetSelector;
+  /** Whether to accept (OK) or dismiss (Cancel) the dialog. */
+  accept: boolean;
+  /** Text to enter for a prompt() dialog when accepting. */
+  promptText?: string;
+  /** How long to wait for the next dialog (default 15000ms). */
+  timeoutMs?: number;
+  /**
+   * Auto-handle mode: keep handling every dialog that opens for this many ms,
+   * then resolve. When set, the return value is a list of handled dialogs and
+   * the function never throws on "no dialog" (an empty list is a valid result).
+   */
+  autoMs?: number;
+}
+
+/**
+ * Arm a dialog handler on a live page connection. Returns a disarm function and
+ * a promise that resolves with each dialog as it is handled (via the onHandled
+ * callback). This is the low-level primitive used by both public modes and by
+ * the expression helper.
+ */
+function armDialogHandler(
+  conn: CdpConnection,
+  accept: boolean,
+  promptText: string | undefined,
+  onHandled: (d: HandledDialog) => void,
+): () => void {
+  return conn.on("Page.javascriptDialogOpening", (params) => {
+    const ev = params as unknown as JavascriptDialogOpening;
+    void (async () => {
+      try {
+        await conn.send("Page.handleJavaScriptDialog", {
+          accept,
+          ...(promptText !== undefined ? { promptText } : {}),
+        });
+        onHandled({
+          type: ev.type,
+          message: ev.message,
+          url: ev.url,
+          ...(ev.defaultPrompt !== undefined ? { defaultPrompt: ev.defaultPrompt } : {}),
+          accept,
+          ...(promptText !== undefined ? { promptText } : {}),
+          handled: true,
+        });
+      } catch {
+        /* connection may have raced closed; the awaiter will time out */
+      }
+    })();
+  });
+}
+
+/**
+ * handle_dialog — wait for the next JS dialog on a page and respond to it.
+ *
+ * Default mode: opens a persistent connection, enables Page, arms the listener,
+ * and resolves with the first handled dialog (or throws on timeout). Auto mode
+ * ({ autoMs }): handles every dialog for the window and resolves with the list.
+ *
+ * The caller is expected to trigger the dialog out-of-band (e.g. by clicking a
+ * button on the page). To trigger-and-handle in one call, use
+ * handleDialogForExpression.
+ */
+export async function handleDialog(
+  args: HandleDialogArgs,
+): Promise<HandledDialog | { handled: HandledDialog[]; count: number }> {
+  const { target, accept, promptText, timeoutMs = 15_000, autoMs } = args;
+  const { conn } = await openPage(target);
+  try {
+    await conn.send("Page.enable");
+
+    if (autoMs !== undefined) {
+      const handled: HandledDialog[] = [];
+      const disarm = armDialogHandler(conn, accept, promptText, (d) => handled.push(d));
+      await new Promise<void>((resolve) => setTimeout(resolve, autoMs));
+      disarm();
+      return { handled, count: handled.length };
+    }
+
+    return await new Promise<HandledDialog>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        disarm();
+        reject(new CdpError(`handle_dialog: no dialog opened within ${timeoutMs}ms`));
+      }, timeoutMs);
+      const disarm = armDialogHandler(conn, accept, promptText, (d) => {
+        clearTimeout(timer);
+        disarm();
+        resolve(d);
+      });
+    });
+  } finally {
+    conn.close();
+  }
+}
+
+export interface HandleDialogForExpressionArgs {
+  target?: TargetSelector;
+  /** A JS expression that opens a dialog, e.g. `confirm("ok?")` or `prompt("name?")`. */
+  expression: string;
+  accept: boolean;
+  promptText?: string;
+  timeoutMs?: number;
+}
+
+/**
+ * Arm a dialog handler, evaluate an expression that OPENS a dialog (without
+ * awaiting it — a blocking dialog would otherwise deadlock the evaluate), wait
+ * for the dialog to be handled, then await the now-unblocked evaluate result.
+ *
+ * Returns both the handled-dialog metadata and the value the expression
+ * resolved to (e.g. `true` for an accepted confirm, the entered text for an
+ * accepted prompt, `false`/`null` for a dismissed one). This is the
+ * trigger-and-handle helper used by the live smoke test.
+ */
+export async function handleDialogForExpression(
+  args: HandleDialogForExpressionArgs,
+): Promise<{ dialog: HandledDialog; value: unknown }> {
+  const { target, expression, accept, promptText, timeoutMs = 15_000 } = args;
+  const { conn } = await openPage(target);
+  try {
+    await conn.send("Page.enable");
+    await conn.send("Runtime.enable");
+
+    let resolveDialog!: (d: HandledDialog) => void;
+    let rejectDialog!: (e: Error) => void;
+    const dialogPromise = new Promise<HandledDialog>((res, rej) => {
+      resolveDialog = res;
+      rejectDialog = rej;
+    });
+    const timer = setTimeout(
+      () => rejectDialog(new CdpError(`handle_dialog: expression opened no dialog within ${timeoutMs}ms`)),
+      timeoutMs,
+    );
+    const disarm = armDialogHandler(conn, accept, promptText, (d) => {
+      clearTimeout(timer);
+      resolveDialog(d);
+    });
+
+    // Fire the dialog-opening expression WITHOUT awaiting: a blocking dialog
+    // holds the evaluate open until we handle it. We capture the promise so we
+    // can await its (now-unblocked) value after the dialog is handled.
+    const evalPromise = conn
+      .send<{ result: { value?: unknown }; exceptionDetails?: { text?: string } }>("Runtime.evaluate", {
+        expression,
+        returnByValue: true,
+        awaitPromise: true,
+        // The evaluate itself must not time out before we handle the dialog.
+        userGesture: true,
+      })
+      .catch((e: unknown) => {
+        // Surface as an exception-shaped result so the await below can decide.
+        return { result: {}, __error: e } as { result: { value?: unknown }; __error: unknown };
+      });
+
+    const dialog = await dialogPromise;
+    disarm();
+
+    const evalResult = (await evalPromise) as {
+      result: { value?: unknown };
+      exceptionDetails?: { text?: string };
+      __error?: unknown;
+    };
+    if (evalResult.__error) throw evalResult.__error;
+    if (evalResult.exceptionDetails) {
+      throw new CdpError(`expression threw: ${evalResult.exceptionDetails.text ?? "unknown error"}`);
+    }
+
+    return { dialog, value: evalResult.result?.value };
+  } finally {
+    conn.close();
+  }
+}
+
+/* ----------------------------------------------------------------------------
+ * CDP methods / domains used:
+ *   - Page.enable
+ *   - Page.javascriptDialogOpening   (event, subscribed)
+ *   - Page.handleJavaScriptDialog    ({ accept, promptText })
+ *   - Runtime.enable                 (helper only)
+ *   - Runtime.evaluate               (helper only — fires the dialog-opening expr)
+ *
+ * Parity gaps vs chrome-devtools-mcp `handle_dialog`:
+ *   - MCP auto-handles the single pending dialog tracked by its Page object;
+ *     here the caller arms first and triggers out-of-band, OR uses the
+ *     handleDialogForExpression helper to trigger-and-handle atomically.
+ *   - MCP returns its standard page/snapshot envelope after handling; this
+ *     returns just the handled-dialog metadata (type/message/url/accept/...).
+ *   - beforeunload dialogs are handled the same way but are only emitted when a
+ *     real navigation/close is attempted; arming alone does not provoke them.
+ * -------------------------------------------------------------------------- */