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

package/build/src/collectors/ServiceWorkerCollector.js

@@ -0,0 +1,171 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { UncaughtError } from './PageCollector.js';
+import { createIdGenerator, stableIdSymbol } from '../utils/id.js';
+const CHROME_EXTENSION_PREFIX = 'chrome-extension://';
+export class ServiceWorkerSubscriber {
+    #target;
+    #callback;
+    #session;
+    #worker;
+    constructor(target, callback) {
+        this.#target = target;
+        this.#callback = callback;
+    }
+    async subscribe() {
+        this.#session = await this.#target.createCDPSession();
+        await this.#session.send('Runtime.enable');
+        this.#session.on('Runtime.exceptionThrown', this.#onExceptionThrown);
+        this.#worker = (await this.#target.worker()) ?? undefined;
+        if (this.#worker) {
+            this.#worker.on('console', this.#onConsole);
+        }
+    }
+    async unsubscribe() {
+        if (this.#worker) {
+            this.#worker.off('console', this.#onConsole);
+        }
+        await this.#session?.detach();
+    }
+    #onConsole = (message) => {
+        this.#callback(message);
+    };
+    #onExceptionThrown = (event) => {
+        const url = this.#target.url();
+        const extensionId = extractExtensionId(url);
+        if (extensionId) {
+            this.#callback(new UncaughtError(event.exceptionDetails, extensionId));
+        }
+    };
+}
+export class ServiceWorkerConsoleCollector {
+    #storage = new Map();
+    #maxLogs;
+    #browser;
+    #serviceWorkerSubscribers = new Map();
+    #idGenerator = createIdGenerator();
+    constructor(browser, maxLogs = 1000) {
+        this.#browser = browser;
+        this.#maxLogs = maxLogs;
+    }
+    async init(workers) {
+        if (!this.#browser) {
+            return;
+        }
+        this.#browser.on('targetcreated', this.#onTargetCreated);
+        this.#browser.on('targetdestroyed', this.#onTargetDestroyed);
+        for (const worker of workers) {
+            void this.#onTargetCreated(worker.target);
+        }
+    }
+    dispose() {
+        if (!this.#browser) {
+            return;
+        }
+        this.#browser.off('targetcreated', this.#onTargetCreated);
+        this.#browser.off('targetdestroyed', this.#onTargetDestroyed);
+        for (const subscriber of this.#serviceWorkerSubscribers.values()) {
+            subscriber.unsubscribe().catch(err => {
+                if (err instanceof Error &&
+                    !err.message.includes('Target closed') &&
+                    !err.message.includes('Session closed')) {
+                    // Swallow error as we are tearing down the system
+                }
+            });
+        }
+        this.#serviceWorkerSubscribers.clear();
+    }
+    #onTargetCreated = async (target) => {
+        if (this.#serviceWorkerSubscribers.has(target)) {
+            return;
+        }
+        const origin = target.url();
+        if (target.type() === 'service_worker' && isExtensionOrigin(origin)) {
+            const extensionId = extractExtensionId(origin);
+            if (!extensionId) {
+                return;
+            }
+            const subscriber = new ServiceWorkerSubscriber(target, item => {
+                this.addLog(extensionId, item);
+            });
+            try {
+                await subscriber.subscribe();
+            }
+            catch (err) {
+                if (err instanceof Error &&
+                    !err.message.includes('Target closed') &&
+                    !err.message.includes('Session closed')) {
+                    throw err;
+                }
+            }
+            this.#serviceWorkerSubscribers.set(target, subscriber);
+        }
+    };
+    #onTargetDestroyed = async (target) => {
+        const subscriber = this.#serviceWorkerSubscribers.get(target);
+        if (subscriber) {
+            try {
+                await subscriber.unsubscribe();
+            }
+            catch (err) {
+                if (err instanceof Error &&
+                    !err.message.includes('Target closed') &&
+                    !err.message.includes('Session closed')) {
+                    throw err;
+                }
+            }
+            this.#serviceWorkerSubscribers.delete(target);
+        }
+    };
+    addLog(extensionId, log) {
+        const logs = this.#storage.get(extensionId) ?? [];
+        const withId = log;
+        withId[stableIdSymbol] = this.#idGenerator();
+        logs.push(withId);
+        if (logs.length > this.#maxLogs) {
+            logs.shift();
+        }
+        this.#storage.set(extensionId, logs);
+    }
+    getData(extensionId) {
+        return this.#storage.get(extensionId) ?? [];
+    }
+    getById(extensionId, stableId) {
+        const logs = this.#storage.get(extensionId);
+        if (!logs) {
+            throw new Error('No logs found for selected extension');
+        }
+        const item = logs.find(item => item[stableIdSymbol] === stableId);
+        if (item) {
+            return item;
+        }
+        throw new Error('Log not found for selected extension');
+    }
+    find(extensionId, filter) {
+        const logs = this.#storage.get(extensionId);
+        if (!logs) {
+            return;
+        }
+        return logs.find(filter);
+    }
+    clearLogs(extensionId) {
+        this.#storage.delete(extensionId);
+    }
+}
+function extractExtensionId(origin) {
+    if (!origin || !isExtensionOrigin(origin)) {
+        return null;
+    }
+    const pathPart = origin.substring(CHROME_EXTENSION_PREFIX.length);
+    const slashIndex = pathPart.indexOf('/');
+    // if there's no / it means that pathPart is now the extensionId, otherwise
+    // we take everything until the first /
+    return slashIndex === -1 ? pathPart : pathPart.substring(0, slashIndex);
+}
+function isExtensionOrigin(origin) {
+    return origin.startsWith(CHROME_EXTENSION_PREFIX);
+}
+//# sourceMappingURL=ServiceWorkerCollector.js.map

package/build/src/config/browser-options.js

@@ -0,0 +1,125 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export const browserOptions = {
+    autoConnect: {
+        type: 'boolean',
+        description: 'If specified, automatically connects to a browser (Chrome 144+) running locally from the user data directory identified by the channel param (default channel is stable). Requires the remote debugging server to be started in the Chrome instance via chrome://inspect/#remote-debugging.',
+        conflicts: ['isolated', 'executablePath'],
+        default: false,
+        coerce: (value) => {
+            if (!value) {
+                return;
+            }
+            return value;
+        },
+    },
+    browserUrl: {
+        type: 'string',
+        description: 'Connect to a running, debuggable Chrome instance (e.g. `http://127.0.0.1:9222`). For more details see: https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/advanced-usage.md#connecting-to-a-running-chrome-instance.',
+        alias: 'u',
+        conflicts: ['wsEndpoint'],
+        coerce: (url) => {
+            if (!url) {
+                return;
+            }
+            try {
+                new URL(url);
+            }
+            catch {
+                throw new Error(`Provided browserUrl ${url} is not valid URL.`);
+            }
+            return url;
+        },
+    },
+    wsEndpoint: {
+        type: 'string',
+        description: 'WebSocket endpoint to connect to a running Chrome instance (e.g., ws://127.0.0.1:9222/devtools/browser/<id>). Alternative to --browserUrl.',
+        alias: 'w',
+        conflicts: ['browserUrl'],
+        coerce: (url) => {
+            if (!url) {
+                return;
+            }
+            try {
+                const parsed = new URL(url);
+                if (parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:') {
+                    throw new Error(`Provided wsEndpoint ${url} must use ws:// or wss:// protocol.`);
+                }
+                return url;
+            }
+            catch (error) {
+                if (error.message.includes('ws://')) {
+                    throw error;
+                }
+                throw new Error(`Provided wsEndpoint ${url} is not valid URL.`);
+            }
+        },
+    },
+    wsHeaders: {
+        type: 'string',
+        description: 'Custom headers for WebSocket connection in JSON format (e.g., \'{"Authorization":"Bearer token"}\'). Only works with --wsEndpoint.',
+        implies: 'wsEndpoint',
+        coerce: (val) => {
+            if (!val) {
+                return;
+            }
+            try {
+                const parsed = JSON.parse(val);
+                if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+                    throw new Error('Headers must be a JSON object');
+                }
+                return parsed;
+            }
+            catch (error) {
+                throw new Error(`Invalid JSON for wsHeaders: ${error.message}`);
+            }
+        },
+    },
+    headless: {
+        type: 'boolean',
+        description: 'Whether to run in headless (no UI) mode.',
+        default: false,
+    },
+    executablePath: {
+        type: 'string',
+        description: 'Path to custom Chrome executable.',
+        conflicts: ['browserUrl', 'wsEndpoint'],
+        alias: 'e',
+    },
+    isolated: {
+        type: 'boolean',
+        description: 'Creates a temporary user-data-dir (under the OS temp directory) that is automatically cleaned up after the browser is closed. Defaults to true; pass --no-isolated for the persistent $HOME/.cache/chrome-devtools-mcp profile, or --user-data-dir for a specific path.',
+    },
+    userDataDir: {
+        type: 'string',
+        description: 'Path to the user data directory for Chrome. Default is $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE',
+        conflicts: ['browserUrl', 'wsEndpoint', 'isolated'],
+    },
+    channel: {
+        type: 'string',
+        description: 'Specify a different Chrome channel that should be used. The default is the stable channel version.',
+        choices: ['canary', 'dev', 'beta', 'stable'],
+        conflicts: ['browserUrl', 'wsEndpoint', 'executablePath'],
+    },
+    proxyServer: {
+        type: 'string',
+        description: `Proxy server configuration for Chrome passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details.`,
+    },
+    chromeArg: {
+        type: 'array',
+        string: true,
+        describe: 'Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',
+    },
+    ignoreDefaultChromeArg: {
+        type: 'array',
+        string: true,
+        describe: 'Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',
+    },
+};
+export function getBrowserOptions() {
+    return browserOptions;
+}
+//# sourceMappingURL=browser-options.js.map

package/build/src/config/category-options.js

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ToolCategory } from '../tools/categories.js';
+const categoryOverrides = {
+    [ToolCategory.INPUT]: {
+        hidden: false,
+    },
+    [ToolCategory.NAVIGATION]: {
+        hidden: false,
+    },
+    [ToolCategory.EMULATION]: {
+        hidden: false,
+    },
+    [ToolCategory.PERFORMANCE]: {
+        hidden: false,
+    },
+    [ToolCategory.NETWORK]: {
+        hidden: false,
+    },
+    [ToolCategory.DEBUGGING]: {
+        hidden: false,
+    },
+    [ToolCategory.MEMORY]: {
+        hidden: false,
+    },
+    [ToolCategory.WEBMCP]: {
+        describe: 'Set to true to enable debugging WebMCP tools. Requires Chrome 150+ with the following flag: `--enable-features=WebMCP`',
+        offByDefault: true,
+        hidden: false,
+    },
+    [ToolCategory.EXTENSIONS]: {
+        describe: 'Set to true to include tools related to extensions. Note: This feature is currently only supported with a pipe connection. autoConnect, browserUrl, and wsEndpoint are not supported with this feature until 149 will be released.',
+        hidden: false,
+        offByDefault: true,
+    },
+    [ToolCategory.THIRD_PARTY]: {
+        describe: 'Set to true to enable third-party developer tools exposed by the inspected page itself',
+        hidden: false,
+        offByDefault: true,
+    },
+    [ToolCategory.PWA]: {
+        describe: 'Set to true to include tools for automating Progressive Web Apps (install, launch, uninstall, and OS state). This feature is only supported with a pipe connection; autoConnect, browserUrl, and wsEndpoint are not supported.',
+        conflicts: ['autoConnect', 'browserUrl', 'wsEndpoint'],
+        hidden: false,
+        offByDefault: true,
+    },
+};
+function createOption(category) {
+    const overrides = categoryOverrides[category];
+    const describe = overrides.offByDefault
+        ? `Set to true to include tools related to ${category}.`
+        : `Set to false to exclude tools related to ${category}.`;
+    return {
+        type: 'boolean',
+        describe,
+        hidden: true,
+        ...overrides,
+        ...(overrides.offByDefault ? {} : { default: true }),
+    };
+}
+export function categoryToFlagName(category) {
+    return `category${category.charAt(0).toUpperCase()}${category.slice(1)}`;
+}
+export function getCategoryOptions() {
+    const options = {};
+    for (const category of Object.values(ToolCategory)) {
+        const flagName = categoryToFlagName(category);
+        options[flagName] = createOption(category);
+    }
+    return options;
+}
+export function isCategoryOffByDefault(category) {
+    const flagName = categoryToFlagName(category);
+    const option = getCategoryOptions()[flagName];
+    return !('default' in option) || option.default !== true;
+}
+export function getOffByDefaultCategories() {
+    const result = [];
+    for (const category of Object.values(ToolCategory)) {
+        if (isCategoryOffByDefault(category)) {
+            result.push(category);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=category-options.js.map

package/build/src/config/cli-commands.js

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Builds the yargs command string and usage line for a CLI command.
+ *
+ * Optional args are rendered as `[--flag]` in the usage line only: as part of
+ * the command string yargs parses each one as a trailing positional, and a
+ * variadic positional has to be the last one.
+ */
+export function buildCommand(commandName, args) {
+    let command = commandName;
+    let flags = '';
+    for (const [name, arg] of Object.entries(args)) {
+        if (arg.required) {
+            command += arg.type === 'array' ? ` <${name}..>` : ` <${name}>`;
+        }
+        else {
+            flags += ` [--${name}]`;
+        }
+    }
+    return { command, usage: `$0 ${command}${flags}` };
+}
+//# sourceMappingURL=cli-commands.js.map