@yezack/chrome-devtools-mcp-108 0.0.0-stage → 1.10.2

package/build/src/tools/thirdPartyDeveloper.js

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod, ajv } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
+import { definePageTool } from './ToolDefinition.js';
+export const listThirdPartyDeveloperTools = definePageTool(() => ({
+    name: 'list_3p_developer_tools',
+    description: `Lists all third-party developer tools the page exposes for providing runtime information.
+Third-party developer tools can be called via the 'execute_3p_developer_tool()' MCP tool.
+Alternatively, third-party developer tools can be executed by calling 'evaluate_script' and adding the
+following command to the script:
+\`window.__dtmcp.executeTool(toolName, params)\`
+This might be helpful when the third-party developer tools return non-serializable values or when composing
+third-party developer tools with additional functionality.`,
+    annotations: {
+        category: ToolCategory.THIRD_PARTY,
+        readOnlyHint: true,
+    },
+    schema: {},
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async (_request, response) => {
+        response.setListThirdPartyDeveloperTools();
+    },
+}));
+export const executeThirdPartyDeveloperTool = definePageTool(() => ({
+    name: 'execute_3p_developer_tool',
+    description: `Executes a tool exposed by the page.`,
+    annotations: {
+        category: ToolCategory.THIRD_PARTY,
+        readOnlyHint: false,
+    },
+    schema: {
+        toolName: zod.string().describe('The name of the tool to execute'),
+        params: zod
+            .string()
+            .optional()
+            .describe('The JSON-stringified parameters to pass to the tool'),
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async (request, response) => {
+        const toolName = request.params.toolName;
+        let params = {};
+        if (request.params.params) {
+            try {
+                const parsed = JSON.parse(request.params.params);
+                if (typeof parsed === 'object' && parsed !== null) {
+                    params = parsed;
+                }
+                else {
+                    throw new Error('Parsed params is not an object');
+                }
+            }
+            catch (e) {
+                const errorMessage = e instanceof Error ? e.message : String(e);
+                throw new Error(`Failed to parse params as JSON: ${errorMessage}`);
+            }
+        }
+        const toolGroups = request.page.getThirdPartyDeveloperTools();
+        let tool;
+        if (toolGroups) {
+            for (const group of toolGroups) {
+                tool = group.tools?.find(t => t.name === toolName);
+                if (tool) {
+                    break;
+                }
+            }
+        }
+        if (!tool) {
+            throw new Error(`Tool ${toolName} not found`);
+        }
+        const ajvInstance = new ajv();
+        const validate = ajvInstance.compile(tool.inputSchema);
+        const valid = validate(params);
+        if (!valid) {
+            throw new Error(`Invalid parameters for tool ${toolName}: ${ajvInstance.errorsText(validate.errors)}`);
+        }
+        await request.page.executeThirdPartyDeveloperTool(toolName, params, response);
+    },
+}));
+//# sourceMappingURL=thirdPartyDeveloper.js.map

package/build/src/tools/tools.js

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as commentsTools from './comments.js';
+import * as consoleTools from './console.js';
+import * as cssTools from './css.js';
+import * as emulationTools from './emulation.js';
+import * as extensionTools from './extensions.js';
+import * as inputTools from './input.js';
+import * as lighthouseTools from './lighthouse.js';
+import * as memoryTools from './memory.js';
+import * as networkTools from './network.js';
+import * as pagesTools from './pages.js';
+import * as performanceTools from './performance.js';
+import * as pwaTools from './pwa.js';
+import * as screencastTools from './screencast.js';
+import * as screenshotTools from './screenshot.js';
+import * as scriptTools from './script.js';
+import * as slimTools from './slim/tools.js';
+import * as snapshotTools from './snapshot.js';
+import * as thirdPartyDeveloperTools from './thirdPartyDeveloper.js';
+import * as webmcpTools from './webmcp.js';
+export const createTools = (args) => {
+    const rawTools = args.slim
+        ? Object.values(slimTools)
+        : [
+            ...(args.devtoolsComments ? Object.values(commentsTools) : []),
+            ...Object.values(consoleTools),
+            ...Object.values(cssTools),
+            ...Object.values(emulationTools),
+            ...Object.values(extensionTools),
+            ...Object.values(inputTools),
+            ...Object.values(lighthouseTools),
+            ...Object.values(memoryTools),
+            ...Object.values(networkTools),
+            ...Object.values(pagesTools),
+            ...Object.values(performanceTools),
+            ...Object.values(pwaTools),
+            ...Object.values(screencastTools),
+            ...Object.values(screenshotTools),
+            ...Object.values(scriptTools),
+            ...Object.values(snapshotTools),
+            ...Object.values(thirdPartyDeveloperTools),
+            ...Object.values(webmcpTools),
+        ];
+    const tools = [];
+    for (const tool of rawTools) {
+        tools.push(tool(args));
+    }
+    tools.sort((a, b) => a.name.localeCompare(b.name));
+    return tools;
+};
+//# sourceMappingURL=tools.js.map

package/build/src/tools/webmcp.js

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
+import { definePageTool } from './ToolDefinition.js';
+export const listWebMcpTools = definePageTool(() => ({
+    name: 'list_webmcp_tools',
+    description: `Lists all WebMCP tools the page exposes.`,
+    annotations: {
+        category: ToolCategory.WEBMCP,
+        readOnlyHint: true,
+    },
+    schema: {},
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async (_request, response) => {
+        response.setListWebMcpTools();
+    },
+}));
+export const executeWebMcpTool = definePageTool(() => ({
+    name: 'execute_webmcp_tool',
+    description: `Executes a WebMCP tool exposed by the page.`,
+    annotations: {
+        category: ToolCategory.WEBMCP,
+        readOnlyHint: false,
+    },
+    schema: {
+        toolName: zod.string().describe('The name of the WebMCP tool to execute'),
+        input: zod
+            .string()
+            .optional()
+            .describe('The JSON-stringified parameters to pass to the WebMCP tool'),
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async (request, response) => {
+        const toolName = request.params.toolName;
+        let input = {};
+        if (request.params.input) {
+            try {
+                const parsed = JSON.parse(request.params.input);
+                if (typeof parsed === 'object' && parsed !== null) {
+                    input = parsed;
+                }
+                else {
+                    throw new Error('Parsed input is not an object');
+                }
+            }
+            catch (e) {
+                const errorMessage = e instanceof Error ? e.message : String(e);
+                throw new Error(`Failed to parse input as JSON: ${errorMessage}`);
+            }
+        }
+        const tools = request.page.pptrPage.webmcp.tools();
+        const tool = tools.find(t => t.name === toolName);
+        if (!tool) {
+            throw new Error(`Tool ${toolName} not found`);
+        }
+        const { status, output, errorText } = await tool.execute(input);
+        response.appendResponseLine(JSON.stringify({ status, output, errorText }, null, 2));
+    },
+}));
+//# sourceMappingURL=webmcp.js.map

package/build/src/types.js

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export var CD4ABridgeEvents;
+(function (CD4ABridgeEvents) {
+    CD4ABridgeEvents["COMMENT_THREADS_CHANGED"] = "CommentThreadsChanged";
+})(CD4ABridgeEvents || (CD4ABridgeEvents = {}));
+//# sourceMappingURL=types.js.map

package/build/src/utils/WaitForHelper.js

@@ -0,0 +1,316 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { logger } from './logger.js';
+export class WaitForHelper {
+    #abortController = new AbortController();
+    #page;
+    #stableDomTimeout;
+    #stableDomFor;
+    #expectNavigationIn;
+    #navigationTimeout;
+    #dialogHandled = false;
+    /** Track all dialogs as they pause the renderer. */
+    #dialogDetected = false;
+    #initialUrl;
+    constructor(page, cpuTimeoutMultiplier, networkTimeoutMultiplier) {
+        this.#stableDomTimeout = 3000 * cpuTimeoutMultiplier;
+        this.#stableDomFor = 100 * cpuTimeoutMultiplier;
+        this.#expectNavigationIn = 100 * cpuTimeoutMultiplier;
+        this.#navigationTimeout = 3000 * networkTimeoutMultiplier;
+        this.#page = page;
+        this.#initialUrl = page.url();
+    }
+    /**
+     * A wrapper that executes a action and waits for
+     * a potential navigation, after which it waits
+     * for the DOM to be stable before returning.
+     */
+    async waitForStableDom() {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            // Bound the setup evaluation against the stable-DOM timeout. Without this
+            // cap a paused renderer (e.g. an open dialog) would make evaluateHandle
+            // hang until protocolTimeout (default 180s) while the tool mutex is held.
+            const stableDomObserver = __addDisposableResource(env_1, await Promise.race([
+                this.#page.evaluateHandle(timeout => {
+                    let timeoutId;
+                    function callback() {
+                        clearTimeout(timeoutId);
+                        timeoutId = setTimeout(() => {
+                            domObserver.resolver.resolve();
+                            domObserver.observer.disconnect();
+                        }, timeout);
+                    }
+                    const domObserver = {
+                        resolver: Promise.withResolvers(),
+                        observer: new MutationObserver(callback),
+                    };
+                    // It's possible that the DOM is not gonna change so we
+                    // need to start the timeout initially.
+                    callback();
+                    domObserver.observer.observe(document.body, {
+                        childList: true,
+                        subtree: true,
+                        attributes: true,
+                    });
+                    return domObserver;
+                }, this.#stableDomFor),
+                this.timeout(this.#stableDomTimeout),
+            ]).catch(() => undefined), false);
+            if (!stableDomObserver) {
+                return;
+            }
+            this.#abortController.signal.addEventListener('abort', async () => {
+                try {
+                    await stableDomObserver.evaluate(observer => {
+                        observer.observer.disconnect();
+                        observer.resolver.resolve();
+                    });
+                }
+                catch {
+                    // Ignored cleanup errors
+                }
+            });
+            return Promise.race([
+                stableDomObserver.evaluate(async (observer) => {
+                    return await observer.resolver.promise;
+                }),
+                this.timeout(this.#stableDomTimeout).then(() => {
+                    throw new Error('Timeout');
+                }),
+            ]);
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    }
+    timeout(time) {
+        if (this.#abortController.signal.aborted) {
+            return Promise.resolve();
+        }
+        return new Promise(res => {
+            const id = setTimeout(res, time);
+            this.#abortController.signal.addEventListener('abort', () => {
+                res();
+                clearTimeout(id);
+            });
+        });
+    }
+    async waitForEventsAfterAction(action, options) {
+        if (this.#abortController.signal.aborted) {
+            throw new Error("Can't re-use a WaitForHelper");
+        }
+        const dialogHandler = (dialog) => {
+            this.#dialogDetected = true;
+            let actionToTake;
+            if (typeof options?.handleDialog === 'object') {
+                actionToTake = options.handleDialog[dialog.type()];
+            }
+            else {
+                actionToTake = options?.handleDialog;
+            }
+            if (actionToTake) {
+                this.#dialogHandled = true;
+                if (actionToTake === 'dismiss') {
+                    void dialog.dismiss();
+                }
+                else if (actionToTake === 'accept') {
+                    void dialog.accept();
+                }
+                else {
+                    void dialog.accept(actionToTake);
+                }
+            }
+            else {
+                this.#abortController.abort(new Error('Action interrupted by a dialog'));
+            }
+        };
+        this.#page.on('dialog', dialogHandler);
+        this.#abortController.signal.addEventListener('abort', () => {
+            this.#page.off('dialog', dialogHandler);
+        });
+        // A scoped AbortController used to clean up navigation probe listeners.
+        // When aborted (either after navigation detection finishes or if this.#abortController
+        // aborts), it removes CDP navigation probe listeners and automatically
+        // detaches the abort listener from this.#abortController.signal.
+        const navigationAbortController = new AbortController();
+        const navigationStartedResolvers = Promise.withResolvers();
+        const navigationListener = (event) => {
+            if (event.frameId !== this.#page.mainFrame()._id) {
+                return;
+            }
+            if (event.navigationType === 'sameDocument' ||
+                event.navigationType === 'historySameDocument') {
+                return;
+            }
+            navigationStartedResolvers.resolve(true);
+        };
+        const requestedNavigationListener = (event) => {
+            if (event.frameId === this.#page.mainFrame()._id) {
+                navigationStartedResolvers.resolve(true);
+            }
+        };
+        this.#page._client().on('Page.frameStartedNavigating', navigationListener);
+        this.#page
+            ._client()
+            .on('Page.frameRequestedNavigation', requestedNavigationListener);
+        navigationAbortController.signal.addEventListener('abort', () => {
+            this.#page
+                ._client()
+                .off('Page.frameStartedNavigating', navigationListener);
+            this.#page
+                ._client()
+                .off('Page.frameRequestedNavigation', requestedNavigationListener);
+        });
+        this.#abortController.signal.addEventListener('abort', () => {
+            navigationStartedResolvers.resolve(false);
+            navigationAbortController.abort();
+        }, { signal: navigationAbortController.signal });
+        // Puppeteer's waitForNavigation must be started before the action runs so that
+        // it captures the pre-action loader ID. If started after the action triggers navigation,
+        // it risks recording the new loader ID and hanging until timeout.
+        // If no navigation occurs, this.#abortController will cancel it in the finally block.
+        const navigationFinished = this.#page
+            .waitForNavigation({
+            timeout: 0,
+            signal: this.#abortController.signal,
+            ignoreSameDocumentNavigation: true,
+        })
+            .then(result => {
+            navigationStartedResolvers.resolve(true);
+            return result;
+        })
+            .catch(error => {
+            if (this.#abortController.signal.aborted ||
+                (error instanceof Error && error.name === 'AbortError')) {
+                return;
+            }
+            logger?.(error);
+        });
+        try {
+            await action(this.#abortController.signal);
+        }
+        catch (error) {
+            // Clear up pending promises
+            this.#abortController.abort();
+            throw error;
+        }
+        const expectNavigationIn = options?.expectNavigationIn ?? this.#expectNavigationIn;
+        const navigationStarted = await Promise.race([
+            navigationStartedResolvers.promise,
+            this.timeout(expectNavigationIn).then(() => {
+                navigationStartedResolvers.resolve(false);
+                return false;
+            }),
+        ]);
+        navigationAbortController.abort();
+        try {
+            // Only await navigation if one was actually initiated; otherwise, the
+            // pending waitForNavigation promise will be cancelled when this.#abortController aborts.
+            if (navigationStarted) {
+                await Promise.race([
+                    navigationFinished,
+                    this.timeout(options?.timeout ?? this.#navigationTimeout),
+                ]);
+            }
+            if (this.#dialogDetected) {
+                return this.#getResult();
+            }
+            // Wait for stable dom after navigation so we execute in
+            // the correct context
+            if (options?.waitForStableDom !== false) {
+                await this.waitForStableDom();
+            }
+        }
+        catch (error) {
+            logger?.(error);
+        }
+        finally {
+            this.#abortController.abort();
+        }
+        return this.#getResult();
+    }
+    #getResult() {
+        const urlAfterAction = this.#page.url();
+        return {
+            ...(urlAfterAction !== this.#initialUrl
+                ? { navigatedToUrl: urlAfterAction }
+                : {}),
+            dialogHandled: this.#dialogHandled,
+        };
+    }
+}
+export function getNetworkMultiplierFromString(condition) {
+    const puppeteerCondition = condition;
+    switch (puppeteerCondition) {
+        case 'Fast 4G':
+            return 1;
+        case 'Slow 4G':
+            return 2.5;
+        case 'Fast 3G':
+            return 5;
+        case 'Slow 3G':
+            return 10;
+    }
+    return 1;
+}
+//# sourceMappingURL=WaitForHelper.js.map

package/build/src/utils/bytes.js

@@ -0,0 +1,105 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod } from '../third_party/index.js';
+const BYTE_UNITS = {
+    b: 1,
+    byte: 1,
+    bytes: 1,
+    k: 1000,
+    kb: 1000,
+    kib: 1024,
+    m: 1000 * 1000,
+    mb: 1000 * 1000,
+    mib: 1024 * 1024,
+    g: 1000 * 1000 * 1000,
+    gb: 1000 * 1000 * 1000,
+    gib: 1024 * 1024 * 1024,
+    t: 1000 * 1000 * 1000 * 1000,
+    tb: 1000 * 1000 * 1000 * 1000,
+    tib: 1024 * 1024 * 1024 * 1024,
+};
+/**
+ * Parses a byte size string (e.g. "1M", "1MB", "500KB", "1.5GB", "1024") into bytes.
+ */
+export function parseByteSize(value) {
+    const trimmed = value.trim();
+    if (trimmed === '') {
+        throw new Error(`Invalid byte size: "${value}"`);
+    }
+    const match = trimmed.match(/^(\d+(?:\.\d+)?)\s*([a-zA-Z]+)?$/);
+    if (!match) {
+        throw new Error(`Invalid byte size format: "${value}". Expected a number or format like "1024", "1M", "1MB", "1G", "1GB".`);
+    }
+    const numMatch = match[1];
+    if (numMatch === undefined) {
+        throw new Error(`Invalid byte size: "${value}"`);
+    }
+    const num = Number(numMatch);
+    if (!Number.isFinite(num) || num < 0) {
+        throw new Error(`Invalid byte size: "${value}"`);
+    }
+    const unitMatch = match[2];
+    if (unitMatch === undefined) {
+        return Math.round(num);
+    }
+    const unit = unitMatch.toLowerCase();
+    const multiplier = BYTE_UNITS[unit];
+    if (multiplier === undefined) {
+        throw new Error(`Unknown unit "${unitMatch}" in "${value}". Supported units: B, KB, KiB, MB, MiB, GB, GiB, TB, TiB.`);
+    }
+    const bytes = Math.round(num * multiplier);
+    if (!Number.isFinite(bytes)) {
+        throw new Error(`Invalid byte size: "${value}"`);
+    }
+    return bytes;
+}
+/**
+ * Parses an inclusive byte-size range (e.g. "1MB", "1MB-2MB", "-1MB", "1MB-").
+ */
+export function parseByteSizeRange(value) {
+    const trimmed = value.trim();
+    if (!trimmed.includes('-')) {
+        return { min: parseByteSize(trimmed), max: undefined };
+    }
+    const parts = trimmed.split('-');
+    if (parts.length !== 2) {
+        throw new Error(`Invalid byte size range: "${value}". Expected a size or range like "1MB", "1MB-2MB", "-1MB", or "1MB-".`);
+    }
+    const minValue = parts[0];
+    const maxValue = parts[1];
+    if (minValue === undefined || maxValue === undefined) {
+        throw new Error(`Invalid byte size range: "${value}"`);
+    }
+    const minText = minValue.trim();
+    const maxText = maxValue.trim();
+    if (minText === '' && maxText === '') {
+        throw new Error(`Invalid byte size range: "${value}". At least one bound is required.`);
+    }
+    const min = minText === '' ? 0 : parseByteSize(minText);
+    const max = maxText === '' ? undefined : parseByteSize(maxText);
+    if (max !== undefined && min > max) {
+        throw new Error(`Invalid byte size range: "${value}". The lower bound must not exceed the upper bound.`);
+    }
+    return { min, max };
+}
+export function byteSizeRangeSchema(description) {
+    return zod
+        .string()
+        .transform((value, context) => {
+        try {
+            return parseByteSizeRange(value);
+        }
+        catch (error) {
+            context.addIssue({
+                code: zod.ZodIssueCode.custom,
+                message: error instanceof Error ? error.message : 'Invalid byte size range',
+            });
+            return zod.NEVER;
+        }
+    })
+        .describe(description);
+}
+//# sourceMappingURL=bytes.js.map