cdp-mcp 0.1.0

package/dist/tools/session.js

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import CDP from "chrome-remote-interface";
+import { launchChrome, attachChrome, closeSession, switchTarget } from "../session/browser.js";
+import { getSession, requireSession } from "../session/state.js";
+import { registerJsonTool } from "./_register.js";
+export function registerSessionTools(server) {
+    registerJsonTool(server, "launch_chrome", "Launch a new Chrome instance with remote debugging and attach. Returns the active target.", {
+        url: z.string().optional().describe("Initial URL to load (default: about:blank)"),
+        headless: z.boolean().optional().describe("Run headless"),
+        user_data_dir: z.string().optional().describe("Profile dir"),
+        args: z.array(z.string()).optional().describe("Extra chrome flags"),
+        chrome_path: z
+            .string()
+            .optional()
+            .describe("Optional explicit path to a Chrome/Chromium binary. Omit by default — chrome-launcher auto-detects (on Linux it searches PATH for google-chrome-stable, google-chrome, chromium-browser, chromium). Pass this only if a previous call failed because chrome-launcher could not find a binary."),
+        sandbox: z
+            .boolean()
+            .optional()
+            .describe("Enable Chromium's sandbox. Default false — we add --no-sandbox. On Ubuntu 23.10+ AppArmor restricts the unprivileged user namespace Chromium's sandbox depends on, so unsandboxed launch is the working default for automation. Pass true only on a host with a working sandbox path (AppArmor userns allowance or SUID chrome_sandbox helper)."),
+    }, async (input) => {
+        return await launchChrome({
+            url: input.url,
+            headless: input.headless,
+            userDataDir: input.user_data_dir,
+            args: input.args,
+            chromePath: input.chrome_path,
+            sandbox: input.sandbox,
+        });
+    });
+    registerJsonTool(server, "attach_chrome", "Attach to an already-running Chrome started with --remote-debugging-port. Picks the first matching page.", {
+        port: z.number().int().positive().optional().describe("Default 9222"),
+        host: z.string().optional(),
+        target_filter: z
+            .object({
+            type: z.string().optional(),
+            url_includes: z.string().optional(),
+        })
+            .optional(),
+    }, async (input) => {
+        return await attachChrome({
+            port: input.port,
+            host: input.host,
+            targetFilter: input.target_filter
+                ? {
+                    ...(input.target_filter.type ? { type: input.target_filter.type } : {}),
+                    ...(input.target_filter.url_includes ? { urlIncludes: input.target_filter.url_includes } : {}),
+                }
+                : undefined,
+        });
+    });
+    registerJsonTool(server, "close_session", "Close the active CDP session. Kills the browser if we launched it; leaves it alone if we attached.", undefined, async () => {
+        if (!getSession())
+            return "no active session";
+        await closeSession();
+        return "closed";
+    });
+    registerJsonTool(server, "list_targets", "List all debuggable targets on the current browser (pages, workers, iframes).", undefined, async () => {
+        const s = requireSession();
+        const targets = await CDP.List({ port: s.chromePort });
+        return targets.map((t) => ({
+            id: t.id,
+            type: t.type,
+            url: t.url,
+            title: t.title,
+            active: t.id === s.currentTargetId,
+        }));
+    });
+    registerJsonTool(server, "select_target", "Switch the active page target. Closes the current CDP socket and opens a new one.", { id: z.string().describe("Target ID from list_targets") }, async (input) => {
+        const s = requireSession();
+        if (s.currentTargetId === input.id)
+            return { id: input.id, status: "already-active" };
+        const r = await switchTarget(input.id);
+        return { id: r.targetId, url: r.url, status: "switched" };
+    });
+}
+//# sourceMappingURL=session.js.map

package/dist/tools/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/tools/session.ts"],"names":[],"mappings":"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"}

package/dist/tools/source.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { requireSession } from "../session/state.js";
+import { mapOriginalToGenerated } from "../sourcemap/store.js";
+import { registerJsonTool } from "./_register.js";
+export function registerSourceTools(server) {
+    registerJsonTool(server, "list_scripts", "List scripts the browser has parsed in the active page, with source-map status.", {
+        mapped_only: z.boolean().optional().describe("Default true: only return scripts whose map loaded"),
+        url_includes: z.string().optional(),
+        limit: z.number().int().positive().optional(),
+    }, async (input) => {
+        const s = requireSession();
+        const mappedOnly = input.mapped_only ?? true;
+        let scripts = s.scripts.all().filter((sc) => !!sc.url);
+        if (mappedOnly)
+            scripts = scripts.filter((sc) => !!sc.consumer);
+        if (input.url_includes)
+            scripts = scripts.filter((sc) => sc.url.includes(input.url_includes));
+        if (input.limit)
+            scripts = scripts.slice(0, input.limit);
+        return scripts.map((sc) => ({
+            script_id: sc.scriptId,
+            // session_id disambiguates root vs worker/iframe entries with
+            // colliding scriptIds (CDP scriptIds are per-Debugger-agent). null
+            // = root; survives JSON serialization, unlike undefined.
+            session_id: sc.sessionId ?? null,
+            url: sc.url,
+            source_map_url: sc.sourceMapURL,
+            has_map: !!sc.consumer,
+            load_error: sc.loadError,
+            original_sources: sc.sources?.slice(0, 30),
+            original_source_count: sc.sources?.length ?? 0,
+        }));
+    });
+    registerJsonTool(server, "get_script_source", "Fetch the raw generated (JS) source text for a script by CDP script ID. Pass `session_id` from list_scripts to fetch a worker/iframe script — CDP scriptIds are per-Debugger-agent, so omitting session_id always routes to root.", {
+        script_id: z.string(),
+        session_id: z.string().nullable().optional().describe("From list_scripts. null or omitted = root."),
+    }, async (input) => {
+        const s = requireSession();
+        // null is the explicit "root" sentinel from the projection; CDP wants undefined.
+        const sid = input.session_id ?? undefined;
+        const result = await s.client.send("Debugger.getScriptSource", { scriptId: input.script_id }, sid);
+        return { script_id: input.script_id, session_id: sid ?? null, source: result.scriptSource };
+    });
+    registerJsonTool(server, "resolve_source_position", "Translate a TS source coord into the JS (generated) coords CDP would use. Useful for diagnosing why a breakpoint didn't bind.", {
+        file: z.string(),
+        line: z.number().int().positive().describe("1-based"),
+        column: z.number().int().nonnegative().optional(),
+    }, async (input) => {
+        const s = requireSession();
+        const candidates = mapOriginalToGenerated(s.scripts, input.file, input.line, input.column ?? 0);
+        return {
+            query: { file: input.file, line: input.line, column: input.column ?? 0 },
+            candidates: candidates.map((c) => ({
+                script_id: c.scriptId,
+                session_id: c.sessionId ?? null,
+                script_url: c.scriptUrl,
+                line: c.lineNumber + 1, // public is 1-based
+                column: c.columnNumber,
+            })),
+        };
+    });
+}
+//# sourceMappingURL=source.js.map

package/dist/tools/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../../src/tools/source.ts"],"names":[],"mappings":"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"}

package/dist/util/browser-resolve.js

@@ -0,0 +1,263 @@
+// Shared Chromium/Chrome resolver used by BOTH the L3 e2e suite
+// (test/e2e/setup/browser-path.ts re-exports from here) AND the L4 eval
+// harness (evals/harness/runner.ts imports resolveBrowser() and feeds
+// the result into the spawned MCP server via CHROME_PATH). Single
+// resolution path so both layers cannot test against different
+// protocol versions — the intent already documented in
+// docs/test-eval-plan.md §L3 *Production code change required for
+// chromePath* and §L3 *CI matrix* ("the same helper is reused by the
+// eval harness").
+//
+// Resolution order (fail-fast — never silently fall back to chrome-
+// launcher's auto-detection, because that's how the wrong browser ends
+// up running and tests pass against the wrong protocol revision):
+//   1. CDP_TEST_BROWSER_PATH env — explicit override, used by CI after
+//      `npx playwright install --with-deps chromium`. Wins everything.
+//   2. `which chromium` (Linux/macOS) / `where chromium.exe` (Windows) —
+//      local dev path. Catches both /snap/bin/chromium and the apt
+//      /usr/bin/chromium symlink.
+//   3. Playwright bundled cache — ~/.cache/ms-playwright/chromium-*/
+//      chrome-linux/chrome (Linux), ~/Library/Caches/ms-playwright/...
+//      (macOS), %LOCALAPPDATA%\ms-playwright\... (Windows). Handy after
+//      a fresh `npx playwright install`.
+//   4. CDP_TEST_BROWSER=chrome — chrome-launcher's default detection.
+//   5. Fail with an actionable install hint.
+import { execSync } from "node:child_process";
+import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+export function getBrowserChoice() {
+    const env = process.env.CDP_TEST_BROWSER?.toLowerCase();
+    if (env === "chrome")
+        return "chrome";
+    if (env === "chromium" || env === undefined || env === "")
+        return "chromium";
+    throw new Error(`CDP_TEST_BROWSER must be 'chromium' or 'chrome' (got '${env}'). Default is 'chromium'.`);
+}
+export function resolveBrowser(choice = getBrowserChoice()) {
+    // Step 1 — explicit override wins.
+    const override = process.env.CDP_TEST_BROWSER_PATH;
+    if (override) {
+        if (!existsSync(override)) {
+            throw new Error(`CDP_TEST_BROWSER_PATH='${override}' does not exist. Unset it or install the binary.`);
+        }
+        return {
+            binaryPath: override,
+            choice,
+            snapConfined: override.startsWith("/snap/"),
+            source: "CDP_TEST_BROWSER_PATH",
+        };
+    }
+    // Step 2 — system-installed chromium (Linux/macOS via `which`, Windows via
+    // `where`). Skip when choice is 'chrome' — Chrome detection is delegated to
+    // chrome-launcher's defaults in step 4.
+    //
+    // On darwin we additionally skip the deprecated Homebrew cask `chromium`
+    // wrapper at /opt/homebrew/bin/chromium (and any path whose realpath
+    // resolves into /opt/homebrew/Caskroom/chromium/). That wrapper points
+    // at an unsigned .app Gatekeeper rejects as "damaged" — it launches
+    // successfully but the debug port never opens, so chrome-launcher's
+    // startup-port poll ECONNREFUSEs. The same gap is precisely what the
+    // §macOS arm64 entry in docs/known-chromium-gaps.md documents; skipping
+    // it here is what makes that entry's "resolveBrowser picks it up
+    // automatically" claim actually true for users who tried the cask first
+    // before reading the doc. Cask deprecation removal is scheduled
+    // 2026-09-01; once removed this skip becomes a no-op.
+    if (choice === "chromium") {
+        const sys = findOnPath("chromium") ?? findOnPath("chromium-browser");
+        if (sys && !isBrewCaskChromium(sys)) {
+            return {
+                binaryPath: sys,
+                choice,
+                snapConfined: sys.startsWith("/snap/"),
+                source: "which-chromium",
+            };
+        }
+    }
+    // Step 3 — Playwright's bundled cache. Used in CI after
+    // `npx playwright install`; also useful locally when the system chromium
+    // isn't installed.
+    const pw = findPlaywrightChromium();
+    if (pw && choice === "chromium") {
+        return {
+            binaryPath: pw,
+            choice,
+            snapConfined: false,
+            source: "playwright-cache",
+        };
+    }
+    // Step 4 — Chrome stable, only when explicitly requested. We don't return a
+    // path here; the caller forwards `undefined` to chrome-launcher, which runs
+    // its own detection. This is intentionally NOT used as a silent fallback
+    // for chromium because the protocol revision can diverge.
+    if (choice === "chrome") {
+        // chrome-launcher uses its own which() — we just signal it should take
+        // over by returning the marker path "chrome-launcher-default". Both
+        // callers strip this back to undefined before forwarding the path: L3
+        // global setup at test/e2e/setup/global.ts skips `chromePath` entirely,
+        // and the L4 runner at evals/harness/runner.ts omits CHROME_PATH from
+        // the subprocess env via isChromeLauncherDefault().
+        return {
+            binaryPath: "chrome-launcher-default",
+            choice,
+            snapConfined: false,
+            source: "chrome-launcher-default",
+        };
+    }
+    // Step 5 — actionable failure.
+    const isArm = process.arch === "arm64";
+    const installHint = isArm
+        ? "sudo apt-get install chromium-browser  # OR: npx playwright install chromium"
+        : "sudo snap install chromium  OR  sudo apt-get install chromium-browser  OR  npx playwright install chromium";
+    throw new Error(`Could not resolve a Chromium binary for the e2e suite.\n` +
+        `Tried (in order): CDP_TEST_BROWSER_PATH env, which chromium, Playwright cache.\n` +
+        `Install Chromium (${installHint}) or set CDP_TEST_BROWSER_PATH explicitly.`);
+}
+// Detect the deprecated Homebrew cask `chromium` wrapper on darwin. Returns
+// true for both the well-known /opt/homebrew/bin/chromium path and any path
+// whose realpath resolves into /opt/homebrew/Caskroom/chromium/ (covers
+// future brew layout shifts where the wrapper lives elsewhere but the
+// Caskroom prefix stays put). Never true off darwin.
+function isBrewCaskChromium(binaryPath) {
+    if (platform() !== "darwin")
+        return false;
+    if (binaryPath === "/opt/homebrew/bin/chromium")
+        return true;
+    try {
+        const resolved = realpathSync(binaryPath);
+        return resolved.startsWith("/opt/homebrew/Caskroom/chromium/");
+    }
+    catch {
+        return false;
+    }
+}
+function findOnPath(cmd) {
+    try {
+        const which = platform() === "win32" ? "where" : "which";
+        const out = execSync(`${which} ${cmd}`, { stdio: ["ignore", "pipe", "ignore"] })
+            .toString()
+            .split(/\r?\n/)
+            .find((line) => line.trim().length > 0);
+        if (!out)
+            return null;
+        const path = out.trim();
+        return existsSync(path) ? path : null;
+    }
+    catch {
+        return null;
+    }
+}
+function findPlaywrightChromium() {
+    const candidates = playwrightCacheDirs();
+    for (const dir of candidates) {
+        if (!existsSync(dir))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        // Filter to chromium-* / chromium-headless-shell-* — pick the highest-
+        // numbered revision (newest install).
+        const chromiums = entries
+            .filter((e) => e.startsWith("chromium-") && !e.startsWith("chromium-headless-shell-"))
+            .map((e) => ({ name: e, full: join(dir, e) }))
+            .filter((e) => {
+            try {
+                return statSync(e.full).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        })
+            .sort((a, b) => b.name.localeCompare(a.name));
+        for (const c of chromiums) {
+            const exe = pickPlaywrightExe(c.full);
+            if (exe)
+                return exe;
+        }
+    }
+    return null;
+}
+function playwrightCacheDirs() {
+    const home = homedir();
+    const plat = platform();
+    if (plat === "linux")
+        return [join(home, ".cache", "ms-playwright")];
+    if (plat === "darwin")
+        return [join(home, "Library", "Caches", "ms-playwright")];
+    if (plat === "win32") {
+        const local = process.env.LOCALAPPDATA ?? join(home, "AppData", "Local");
+        return [join(local, "ms-playwright")];
+    }
+    return [join(home, ".cache", "ms-playwright")];
+}
+function pickPlaywrightExe(chromiumDir) {
+    // Layout, per Playwright's install layout:
+    //   Linux:   chromium-<rev>/chrome-linux/chrome
+    //   macOS:   chromium-<rev>/chrome-mac/Chromium.app/Contents/MacOS/Chromium
+    //   Windows: chromium-<rev>/chrome-win/chrome.exe
+    const plat = platform();
+    // Playwright's layout varies by version/arch (Chrome-for-Testing renamed
+    // some folders ~Playwright 1.40+):
+    //   Linux x86_64:  chromium-<rev>/chrome-linux/chrome     (older)
+    //                  chromium-<rev>/chrome-linux64/chrome   (CfT, newer)
+    //   Linux ARM64:   chromium-<rev>/chrome-linux/chrome     (ARM64 unchanged)
+    //                  chromium-<rev>/chrome-linux-arm64/chrome (rare variant)
+    //   macOS x86_64:  chromium-<rev>/chrome-mac/Chromium.app/...                       (older)
+    //                  chromium-<rev>/chrome-mac-x64/Google Chrome for Testing.app/...  (CfT, newer)
+    //   macOS arm64:   chromium-<rev>/chrome-mac-arm/Chromium.app/...                   (older)
+    //                  chromium-<rev>/chrome-mac-arm64/Google Chrome for Testing.app/...(CfT, newer)
+    //   Windows:       chromium-<rev>/chrome-win/chrome.exe   (older)
+    //                  chromium-<rev>/chrome-win64/chrome.exe (newer)
+    // Codex blocker review on PR #11 flagged the missing chrome-linux64
+    // candidate — modern Playwright on ubuntu-latest landed in CfT layout
+    // and the resolver step exited 1 before the test runner started.
+    // The mac-arm64 CfT candidates were added while validating
+    // set_breakpoint idempotency on darwin-arm64, where Playwright
+    // v1223+ installs to chrome-mac-arm64/Google Chrome
+    // for Testing.app/Contents/MacOS/Google Chrome for Testing.
+    const candidates = plat === "win32"
+        ? [
+            join(chromiumDir, "chrome-win64", "chrome.exe"),
+            join(chromiumDir, "chrome-win", "chrome.exe"),
+        ]
+        : plat === "darwin"
+            ? [
+                // CfT-renamed layouts first (Playwright 1.40+ / chromium revisions
+                // ~v1200+). `existsSync` makes the order forgiving — try newer
+                // first so we don't accidentally pick an older sibling layout
+                // when both happen to be present.
+                join(chromiumDir, "chrome-mac-arm64", "Google Chrome for Testing.app", "Contents", "MacOS", "Google Chrome for Testing"),
+                join(chromiumDir, "chrome-mac-x64", "Google Chrome for Testing.app", "Contents", "MacOS", "Google Chrome for Testing"),
+                // Older Chromium.app-branded layouts.
+                join(chromiumDir, "chrome-mac", "Chromium.app", "Contents", "MacOS", "Chromium"),
+                join(chromiumDir, "chrome-mac-arm", "Chromium.app", "Contents", "MacOS", "Chromium"),
+            ]
+            : [
+                join(chromiumDir, "chrome-linux", "chrome"),
+                join(chromiumDir, "chrome-linux64", "chrome"),
+                join(chromiumDir, "chrome-linux-arm64", "chrome"),
+            ];
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    return null;
+}
+/** True when the given binary is the snap-marker returned by step 4. */
+export function isChromeLauncherDefault(b) {
+    return b.source === "chrome-launcher-default";
+}
+/** Determine the user-data-dir for snap-confined Chromium. Snap confinement
+ *  rejects /tmp/... paths; only ~/snap/<app>/current/ is writable. */
+export function snapUserDataDir(binaryPath) {
+    // Parse the snap app name out of the binary path. /snap/bin/chromium ->
+    // 'chromium'; /snap/firefox/current/firefox -> 'firefox'.
+    const match = binaryPath.match(/\/snap\/(?:bin\/)?([^/]+)/);
+    const app = match?.[1] ?? "chromium";
+    return join(homedir(), "snap", app, "current", "cdp-mcp-test-profile");
+}
+//# sourceMappingURL=browser-resolve.js.map

package/dist/util/browser-resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-resolve.js","sourceRoot":"","sources":["../../src/util/browser-resolve.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,wEAAwE;AACxE,sEAAsE;AACtE,kEAAkE;AAClE,+DAA+D;AAC/D,uDAAuD;AACvD,kEAAkE;AAClE,qEAAqE;AACrE,kBAAkB;AAClB,EAAE;AACF,oEAAoE;AACpE,uEAAuE;AACvE,kEAAkE;AAClE,uEAAuE;AACvE,uEAAuE;AACvE,yEAAyE;AACzE,mEAAmE;AACnE,kCAAkC;AAClC,qEAAqE;AACrE,uEAAuE;AACvE,wEAAwE;AACxE,yCAAyC;AACzC,sEAAsE;AACtE,6CAA6C;AAE7C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAoBjC,MAAM,UAAU,gBAAgB;IAC9B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,WAAW,EAAE,CAAC;IACxD,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IACtC,IAAI,GAAG,KAAK,UAAU,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,UAAU,CAAC;IAC7E,MAAM,IAAI,KAAK,CACb,yDAAyD,GAAG,4BAA4B,CACzF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,SAAwB,gBAAgB,EAAE;IACvE,mCAAmC;IACnC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;IACnD,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,0BAA0B,QAAQ,mDAAmD,CACtF,CAAC;QACJ,CAAC;QACD,OAAO;YACL,UAAU,EAAE,QAAQ;YACpB,MAAM;YACN,YAAY,EAAE,QAAQ,CAAC,UAAU,CAAC,QAAQ,CAAC;YAC3C,MAAM,EAAE,uBAAuB;SAChC,CAAC;IACJ,CAAC;IAED,2EAA2E;IAC3E,4EAA4E;IAC5E,wCAAwC;IACxC,EAAE;IACF,yEAAyE;IACzE,qEAAqE;IACrE,uEAAuE;IACvE,oEAAoE;IACpE,oEAAoE;IACpE,qEAAqE;IACrE,wEAAwE;IACxE,iEAAiE;IACjE,wEAAwE;IACxE,gEAAgE;IAChE,sDAAsD;IACtD,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,UAAU,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,kBAAkB,CAAC,CAAC;QACrE,IAAI,GAAG,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;YACpC,OAAO;gBACL,UAAU,EAAE,GAAG;gBACf,MAAM;gBACN,YAAY,EAAE,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC;gBACtC,MAAM,EAAE,gBAAgB;aACzB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,wDAAwD;IACxD,yEAAyE;IACzE,mBAAmB;IACnB,MAAM,EAAE,GAAG,sBAAsB,EAAE,CAAC;IACpC,IAAI,EAAE,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;QAChC,OAAO;YACL,UAAU,EAAE,EAAE;YACd,MAAM;YACN,YAAY,EAAE,KAAK;YACnB,MAAM,EAAE,kBAAkB;SAC3B,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,4EAA4E;IAC5E,yEAAyE;IACzE,0DAA0D;IAC1D,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QACxB,uEAAuE;QACvE,oEAAoE;QACpE,sEAAsE;QACtE,wEAAwE;QACxE,sEAAsE;QACtE,oDAAoD;QACpD,OAAO;YACL,UAAU,EAAE,yBAAyB;YACrC,MAAM;YACN,YAAY,EAAE,KAAK;YACnB,MAAM,EAAE,yBAAyB;SAClC,CAAC;IACJ,CAAC;IAED,+BAA+B;IAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC;IACvC,MAAM,WAAW,GAAG,KAAK;QACvB,CAAC,CAAC,8EAA8E;QAChF,CAAC,CAAC,4GAA4G,CAAC;IACjH,MAAM,IAAI,KAAK,CACb,0DAA0D;QACxD,kFAAkF;QAClF,qBAAqB,WAAW,4CAA4C,CAC/E,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,4EAA4E;AAC5E,wEAAwE;AACxE,sEAAsE;AACtE,qDAAqD;AACrD,SAAS,kBAAkB,CAAC,UAAkB;IAC5C,IAAI,QAAQ,EAAE,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC1C,IAAI,UAAU,KAAK,4BAA4B;QAAE,OAAO,IAAI,CAAC;IAC7D,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC;QAC1C,OAAO,QAAQ,CAAC,UAAU,CAAC,kCAAkC,CAAC,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,GAAW;IAC7B,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,QAAQ,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;QACzD,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,KAAK,IAAI,GAAG,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC;aAC7E,QAAQ,EAAE;aACV,KAAK,CAAC,OAAO,CAAC;aACd,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC1C,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC;QACtB,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;QACxB,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,sBAAsB;IAC7B,MAAM,UAAU,GAAG,mBAAmB,EAAE,CAAC;IACzC,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QAC/B,IAAI,OAAiB,CAAC;QACtB,IAAI,CAAC;YACH,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,uEAAuE;QACvE,sCAAsC;QACtC,MAAM,SAAS,GAAG,OAAO;aACtB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,0BAA0B,CAAC,CAAC;aACrF,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;aAC7C,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;YACZ,IAAI,CAAC;gBACH,OAAO,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;YACxC,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC,CAAC;aACD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAChD,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;YAC1B,MAAM,GAAG,GAAG,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YACtC,IAAI,GAAG;gBAAE,OAAO,GAAG,CAAC;QACtB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,mBAAmB;IAC1B,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAC;IACxB,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC;IACrE,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC;IACjF,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACrB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;QACzE,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,iBAAiB,CAAC,WAAmB;IAC5C,2CAA2C;IAC3C,gDAAgD;IAChD,4EAA4E;IAC5E,kDAAkD;IAClD,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAC;IACxB,yEAAyE;IACzE,mCAAmC;IACnC,kEAAkE;IAClE,uEAAuE;IACvE,4EAA4E;IAC5E,2EAA2E;IAC3E,4FAA4F;IAC5F,iGAAiG;IACjG,4FAA4F;IAC5F,iGAAiG;IACjG,kEAAkE;IAClE,kEAAkE;IAClE,oEAAoE;IACpE,sEAAsE;IACtE,iEAAiE;IACjE,2DAA2D;IAC3D,+DAA+D;IAC/D,oDAAoD;IACpD,4DAA4D;IAC5D,MAAM,UAAU,GACd,IAAI,KAAK,OAAO;QACd,CAAC,CAAC;YACE,IAAI,CAAC,WAAW,EAAE,cAAc,EAAE,YAAY,CAAC;YAC/C,IAAI,CAAC,WAAW,EAAE,YAAY,EAAE,YAAY,CAAC;SAC9C;QACH,CAAC,CAAC,IAAI,KAAK,QAAQ;YACjB,CAAC,CAAC;gBACE,mEAAmE;gBACnE,+DAA+D;gBAC/D,8DAA8D;gBAC9D,kCAAkC;gBAClC,IAAI,CACF,WAAW,EACX,kBAAkB,EAClB,+BAA+B,EAC/B,UAAU,EACV,OAAO,EACP,2BAA2B,CAC5B;gBACD,IAAI,CACF,WAAW,EACX,gBAAgB,EAChB,+BAA+B,EAC/B,UAAU,EACV,OAAO,EACP,2BAA2B,CAC5B;gBACD,sCAAsC;gBACtC,IAAI,CACF,WAAW,EACX,YAAY,EACZ,cAAc,EACd,UAAU,EACV,OAAO,EACP,UAAU,CACX;gBACD,IAAI,CACF,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,OAAO,EACP,UAAU,CACX;aACF;YACH,CAAC,CAAC;gBACE,IAAI,CAAC,WAAW,EAAE,cAAc,EAAE,QAAQ,CAAC;gBAC3C,IAAI,CAAC,WAAW,EAAE,gBAAgB,EAAE,QAAQ,CAAC;gBAC7C,IAAI,CAAC,WAAW,EAAE,oBAAoB,EAAE,QAAQ,CAAC;aAClD,CAAC;IACV,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,UAAU,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,uBAAuB,CAAC,CAAkB;IACxD,OAAO,CAAC,CAAC,MAAM,KAAK,yBAAyB,CAAC;AAChD,CAAC;AAED;sEACsE;AACtE,MAAM,UAAU,eAAe,CAAC,UAAkB;IAChD,wEAAwE;IACxE,0DAA0D;IAC1D,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC5D,MAAM,GAAG,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC;IACrC,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,sBAAsB,CAAC,CAAC;AACzE,CAAC"}

package/dist/util/errors.js

@@ -0,0 +1,12 @@
+export class ToolError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ToolError";
+    }
+}
+export const noSession = () => new ToolError("no_session", "No browser session. Call launch_chrome or attach_chrome first.");
+export const notPaused = () => new ToolError("not_paused", "Operation requires the debugger to be paused. Set a breakpoint and call wait_for_pause.");
+export const alreadySession = () => new ToolError("already_session", "A session is already active. Call close_session before opening a new one.");
+//# sourceMappingURL=errors.js.map

package/dist/util/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/util/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,SAAU,SAAQ,KAAK;IACf;IAAnB,YAAmB,IAAY,EAAE,OAAe;QAC9C,KAAK,CAAC,OAAO,CAAC,CAAC;QADE,SAAI,GAAJ,IAAI,CAAQ;QAE7B,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,EAAE,CAC5B,IAAI,SAAS,CACX,YAAY,EACZ,gEAAgE,CACjE,CAAC;AAEJ,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,EAAE,CAC5B,IAAI,SAAS,CACX,YAAY,EACZ,yFAAyF,CAC1F,CAAC;AAEJ,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,EAAE,CACjC,IAAI,SAAS,CACX,iBAAiB,EACjB,2EAA2E,CAC5E,CAAC"}

package/dist/util/format.js

@@ -0,0 +1,65 @@
+const MAX_PREVIEW = 200;
+export function truncate(s, max = MAX_PREVIEW) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max) + `…(+${s.length - max} chars)`;
+}
+// Compact textual preview of a CDP RemoteObject without dereferencing further.
+export function previewRemoteObject(obj) {
+    if (obj.unserializableValue)
+        return obj.unserializableValue;
+    if (obj.type === "undefined")
+        return "undefined";
+    if (obj.subtype === "null")
+        return "null";
+    if (obj.type === "string")
+        return JSON.stringify(obj.value ?? "");
+    if (obj.type === "number" || obj.type === "boolean" || obj.type === "bigint") {
+        return String(obj.value);
+    }
+    if (obj.type === "function") {
+        return obj.description ? truncate(obj.description) : "function";
+    }
+    if (obj.preview) {
+        return truncate(previewFromPreview(obj.preview));
+    }
+    if (obj.description)
+        return truncate(obj.description);
+    return obj.className ?? obj.subtype ?? obj.type;
+}
+function previewFromPreview(p) {
+    if (p.subtype === "array") {
+        const items = (p.properties ?? [])
+            .map((pp) => previewProperty(pp))
+            .join(", ");
+        return `[${items}${p.overflow ? ", …" : ""}]`;
+    }
+    const items = (p.properties ?? [])
+        .map((pp) => `${pp.name}: ${previewProperty(pp)}`)
+        .join(", ");
+    const head = p.description && p.description !== "Object" ? `${p.description} ` : "";
+    return `${head}{${items}${p.overflow ? ", …" : ""}}`;
+}
+function previewProperty(p) {
+    if (p.type === "string")
+        return JSON.stringify(p.value ?? "");
+    if (p.value !== undefined)
+        return p.value;
+    return p.type;
+}
+export function describeRemote(obj) {
+    return {
+        type: obj.subtype ?? obj.type,
+        preview: previewRemoteObject(obj),
+        ...(obj.objectId ? { objectId: obj.objectId } : {}),
+    };
+}
+// Wrap any value into the MCP tool content envelope.
+export function toolText(text) {
+    return { content: [{ type: "text", text }] };
+}
+// Stringify a JSON result with a stable shape for the LLM to parse.
+export function toolJson(value) {
+    return toolText(JSON.stringify(value, null, 2));
+}
+//# sourceMappingURL=format.js.map

package/dist/util/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/util/format.ts"],"names":[],"mappings":"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"}

package/dist/util/log.js

@@ -0,0 +1,34 @@
+// Logging for an MCP stdio server.
+//
+// stdout is reserved for JSON-RPC framing — anything we write there will
+// corrupt the protocol. All logging goes to stderr.
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+function envLevel() {
+    const raw = process.env.CDP_MCP_LOG?.toLowerCase();
+    if (raw === "debug" || raw === "info" || raw === "warn" || raw === "error")
+        return raw;
+    return "info";
+}
+const threshold = LEVELS[envLevel()];
+function emit(level, msg, meta) {
+    if (LEVELS[level] < threshold)
+        return;
+    const ts = new Date().toISOString();
+    const tail = meta ? " " + safeJson(meta) : "";
+    process.stderr.write(`[${ts}] ${level.toUpperCase()} ${msg}${tail}\n`);
+}
+function safeJson(v) {
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+export const log = {
+    debug: (msg, meta) => emit("debug", msg, meta),
+    info: (msg, meta) => emit("info", msg, meta),
+    warn: (msg, meta) => emit("warn", msg, meta),
+    error: (msg, meta) => emit("error", msg, meta),
+};
+//# sourceMappingURL=log.js.map

package/dist/util/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../../src/util/log.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,EAAE;AACF,yEAAyE;AACzE,oDAAoD;AAIpD,MAAM,MAAM,GAA0B,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;AAEnF,SAAS,QAAQ;IACf,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,WAAW,EAAE,CAAC;IACnD,IAAI,GAAG,KAAK,OAAO,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,OAAO;QAAE,OAAO,GAAG,CAAC;IACvF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;AAErC,SAAS,IAAI,CAAC,KAAY,EAAE,GAAW,EAAE,IAA8B;IACrE,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,SAAS;QAAE,OAAO;IACtC,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,KAAK,CAAC,WAAW,EAAE,IAAI,GAAG,GAAG,IAAI,IAAI,CAAC,CAAC;AACzE,CAAC;AAED,SAAS,QAAQ,CAAC,CAAU;IAC1B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,GAAG,GAAG;IACjB,KAAK,EAAE,CAAC,GAAW,EAAE,IAA8B,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC;IAChF,IAAI,EAAE,CAAC,GAAW,EAAE,IAA8B,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC;IAC9E,IAAI,EAAE,CAAC,GAAW,EAAE,IAA8B,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC;IAC9E,KAAK,EAAE,CAAC,GAAW,EAAE,IAA8B,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC;CACjF,CAAC"}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "cdp-mcp",
+  "version": "0.1.0",
+  "description": "Chrome DevTools Protocol MCP server — a TypeScript-aware frontend debugger for AI agents.",
+  "license": "MIT",
+  "author": "Leonard Janke",
+  "homepage": "https://github.com/lcjanke2020/cdp-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lcjanke2020/cdp-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lcjanke2020/cdp-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "chrome-devtools-protocol",
+    "cdp",
+    "debugger",
+    "devtools",
+    "ai-agents",
+    "typescript",
+    "source-maps"
+  ],
+  "type": "module",
+  "bin": {
+    "cdp-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "pretest:e2e": "node scripts/check-chromium-skips.mjs && npm run sample:build",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "sample:build": "npm ci --prefix examples/sample-app && npm run --prefix examples/sample-app build && npm run variants:build",
+    "variants:build": "node scripts/build-variants.mjs",
+    "lint:chromium-skips": "node scripts/check-chromium-skips.mjs",
+    "smoke": "node scripts/smoke.mjs",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.evals.json",
+    "preeval": "npm run build",
+    "preeval:quick": "npm run build",
+    "eval": "tsx evals/cli.ts",
+    "eval:quick": "tsx evals/cli.ts --scenarios=compute-step --trials=1",
+    "clean": "rimraf dist",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@jridgewell/source-map": "^0.3.11",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "chrome-launcher": "^1.2.1",
+    "chrome-remote-interface": "^0.34.0",
+    "devtools-protocol": "^0.0.1628107",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.30.1",
+    "@google/genai": "^2.4.0",
+    "@types/chrome-remote-interface": "^0.33.0",
+    "@types/node": "^22.10.5",
+    "rimraf": "^6.0.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}