chrome-devtools-mcp 0.8.1 → 0.10.0

package/build/src/PageCollector.js

@@ -3,21 +3,35 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+function createIdGenerator() {
+    let i = 1;
+    return () => {
+        if (i === Number.MAX_SAFE_INTEGER) {
+            i = 0;
+        }
+        return i++;
+    };
+}
+export const stableIdSymbol = Symbol('stableIdSymbol');
 export class PageCollector {
     #browser;
-    #initializer;
+    #listenersInitializer;
+    #listeners = new WeakMap();
+    #maxNavigationSaved = 3;
+    #includeAllPages;
     /**
-     * The Array in this map should only be set once
-     * As we use the reference to it.
-     * Use methods that manipulate the array in place.
+     * This maps a Page to a list of navigations with a sub-list
+     * of all collected resources.
+     * The newer navigations come first.
      */
     storage = new WeakMap();
-    constructor(browser, initializer) {
+    constructor(browser, listeners, includeAllPages) {
         this.#browser = browser;
-        this.#initializer = initializer;
+        this.#listenersInitializer = listeners;
+        this.#includeAllPages = includeAllPages;
     }
     async init() {
-        const pages = await this.#browser.pages();
+        const pages = await this.#browser.pages(this.#includeAllPages);
         for (const page of pages) {
             this.#initializePage(page);
         }
@@ -28,6 +42,13 @@ export class PageCollector {
             }
             this.#initializePage(page);
         });
+        this.#browser.on('targetdestroyed', async (target) => {
+            const page = await target.page();
+            if (!page) {
+                return;
+            }
+            this.#cleanupPageDestroyed(page);
+        });
     }
     addPage(page) {
         this.#initializePage(page);
@@ -36,36 +57,105 @@ export class PageCollector {
         if (this.storage.has(page)) {
             return;
         }
-        const stored = [];
-        this.storage.set(page, stored);
-        page.on('framenavigated', frame => {
-            // Only reset the storage on main frame navigation
+        const idGenerator = createIdGenerator();
+        const storedLists = [[]];
+        this.storage.set(page, storedLists);
+        const listeners = this.#listenersInitializer(value => {
+            const withId = value;
+            withId[stableIdSymbol] = idGenerator();
+            const navigations = this.storage.get(page) ?? [[]];
+            navigations[0].push(withId);
+        });
+        listeners['framenavigated'] = (frame) => {
+            // Only split the storage on main frame navigation
             if (frame !== page.mainFrame()) {
                 return;
             }
-            this.cleanup(page);
-        });
-        this.#initializer(page, value => {
-            stored.push(value);
-        });
+            this.splitAfterNavigation(page);
+        };
+        for (const [name, listener] of Object.entries(listeners)) {
+            page.on(name, listener);
+        }
+        this.#listeners.set(page, listeners);
     }
-    cleanup(page) {
-        const collection = this.storage.get(page);
-        if (collection) {
-            // Keep the reference alive
-            collection.length = 0;
+    splitAfterNavigation(page) {
+        const navigations = this.storage.get(page);
+        if (!navigations) {
+            return;
         }
+        // Add the latest navigation first
+        navigations.unshift([]);
+        navigations.splice(this.#maxNavigationSaved);
     }
-    getData(page) {
-        return this.storage.get(page) ?? [];
+    #cleanupPageDestroyed(page) {
+        const listeners = this.#listeners.get(page);
+        if (listeners) {
+            for (const [name, listener] of Object.entries(listeners)) {
+                page.off(name, listener);
+            }
+        }
+        this.storage.delete(page);
+    }
+    getData(page, includePreservedData) {
+        const navigations = this.storage.get(page);
+        if (!navigations) {
+            return [];
+        }
+        if (!includePreservedData) {
+            return navigations[0];
+        }
+        const data = [];
+        for (let index = this.#maxNavigationSaved; index >= 0; index--) {
+            if (navigations[index]) {
+                data.push(...navigations[index]);
+            }
+        }
+        return data;
+    }
+    getIdForResource(resource) {
+        return resource[stableIdSymbol] ?? -1;
+    }
+    getById(page, stableId) {
+        const navigations = this.storage.get(page);
+        if (!navigations) {
+            throw new Error('No requests found for selected page');
+        }
+        const item = this.find(page, item => item[stableIdSymbol] === stableId);
+        if (item) {
+            return item;
+        }
+        throw new Error('Request not found for selected page');
+    }
+    find(page, filter) {
+        const navigations = this.storage.get(page);
+        if (!navigations) {
+            return;
+        }
+        for (const navigation of navigations) {
+            const item = navigation.find(filter);
+            if (item) {
+                return item;
+            }
+        }
+        return;
     }
 }
 export class NetworkCollector extends PageCollector {
-    cleanup(page) {
-        const requests = this.storage.get(page) ?? [];
-        if (!requests) {
+    constructor(browser, listeners = collect => {
+        return {
+            request: req => {
+                collect(req);
+            },
+        };
+    }, includeAllPages) {
+        super(browser, listeners, includeAllPages);
+    }
+    splitAfterNavigation(page) {
+        const navigations = this.storage.get(page) ?? [];
+        if (!navigations) {
             return;
         }
+        const requests = navigations[0];
         const lastRequestIdx = requests.findLastIndex(request => {
             return request.frame() === page.mainFrame()
                 ? request.isNavigationRequest()
@@ -74,6 +164,12 @@ export class NetworkCollector extends PageCollector {
         // Keep all requests since the last navigation request including that
         // navigation request itself.
         // Keep the reference
-        requests.splice(0, Math.max(lastRequestIdx, 0));
+        if (lastRequestIdx !== -1) {
+            const fromCurrentNavigation = requests.splice(lastRequestIdx);
+            navigations.unshift(fromCurrentNavigation);
+        }
+        else {
+            navigations.unshift([]);
+        }
     }
 }

package/build/src/WaitForHelper.js

@@ -1,3 +1,8 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
 import { logger } from './logger.js';
 export class WaitForHelper {
     #abortController = new AbortController();

package/build/src/browser.js

@@ -6,17 +6,15 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import puppeteer from 'puppeteer-core';
+import { logger } from './logger.js';
+import { puppeteer } from './third_party/index.js';
 let browser;
-function makeTargetFilter(devtools) {
+function makeTargetFilter() {
     const ignoredPrefixes = new Set([
         'chrome://',
         'chrome-extension://',
         'chrome-untrusted://',
     ]);
-    if (!devtools) {
-        ignoredPrefixes.add('devtools://');
-    }
     return function targetFilter(target) {
         if (target.url() === 'chrome://newtab/') {
             return true;
@@ -33,12 +31,26 @@ export async function ensureBrowserConnected(options) {
     if (browser?.connected) {
         return browser;
     }
-    browser = await puppeteer.connect({
-        targetFilter: makeTargetFilter(options.devtools),
-        browserURL: options.browserURL,
+    const connectOptions = {
+        targetFilter: makeTargetFilter(),
         defaultViewport: null,
-        handleDevToolsAsPage: options.devtools,
-    });
+        handleDevToolsAsPage: true,
+    };
+    if (options.wsEndpoint) {
+        connectOptions.browserWSEndpoint = options.wsEndpoint;
+        if (options.wsHeaders) {
+            connectOptions.headers = options.wsHeaders;
+        }
+    }
+    else if (options.browserURL) {
+        connectOptions.browserURL = options.browserURL;
+    }
+    else {
+        throw new Error('Either browserURL or wsEndpoint must be provided');
+    }
+    logger('Connecting Puppeteer to ', JSON.stringify(connectOptions));
+    browser = await puppeteer.connect(connectOptions);
+    logger('Connected Puppeteer');
     return browser;
 }
 export async function launch(options) {
@@ -73,7 +85,7 @@ export async function launch(options) {
     try {
         const browser = await puppeteer.launch({
             channel: puppeteerChannel,
-            targetFilter: makeTargetFilter(options.devtools),
+            targetFilter: makeTargetFilter(),
             executablePath,
             defaultViewport: null,
             userDataDir,
@@ -81,7 +93,7 @@ export async function launch(options) {
             headless,
             args,
             acceptInsecureCerts: options.acceptInsecureCerts,
-            handleDevToolsAsPage: options.devtools,
+            handleDevToolsAsPage: true,
         });
         if (options.logFile) {
             // FIXME: we are probably subscribing too late to catch startup logs. We

package/build/src/cli.js

@@ -3,13 +3,13 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import yargs from 'yargs';
-import { hideBin } from 'yargs/helpers';
+import { yargs, hideBin } from './third_party/index.js';
 export const cliOptions = {
     browserUrl: {
         type: 'string',
         description: 'Connect to a running Chrome instance using port forwarding. For more details see: https://developer.chrome.com/docs/devtools/remote-debugging/local-server.',
         alias: 'u',
+        conflicts: 'wsEndpoint',
         coerce: (url) => {
             if (!url) {
                 return;
@@ -23,6 +23,50 @@ export const cliOptions = {
             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.',
@@ -31,7 +75,7 @@ export const cliOptions = {
     executablePath: {
         type: 'string',
         description: 'Path to custom Chrome executable.',
-        conflicts: 'browserUrl',
+        conflicts: ['browserUrl', 'wsEndpoint'],
         alias: 'e',
     },
     isolated: {
@@ -43,7 +87,7 @@ export const cliOptions = {
         type: 'string',
         description: 'Specify a different Chrome channel that should be used. The default is the stable channel version.',
         choices: ['stable', 'canary', 'beta', 'dev'],
-        conflicts: ['browserUrl', 'executablePath'],
+        conflicts: ['browserUrl', 'wsEndpoint', 'executablePath'],
     },
     logFile: {
         type: 'string',
@@ -79,10 +123,30 @@ export const cliOptions = {
         describe: 'Whether to enable automation over DevTools targets',
         hidden: true,
     },
+    experimentalIncludeAllPages: {
+        type: 'boolean',
+        describe: 'Whether to include all kinds of pages such as webviews or background pages as pages.',
+        hidden: true,
+    },
     chromeArg: {
         type: 'array',
         describe: 'Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',
     },
+    categoryEmulation: {
+        type: 'boolean',
+        default: true,
+        describe: 'Set to false to exclude tools related to emulation.',
+    },
+    categoryPerformance: {
+        type: 'boolean',
+        default: true,
+        describe: 'Set to false to exclude tools related to performance.',
+    },
+    categoryNetwork: {
+        type: 'boolean',
+        default: true,
+        describe: 'Set to false to exclude tools related to network.',
+    },
 };
 export function parseArguments(version, argv = process.argv) {
     const yargsInstance = yargs(hideBin(argv))
@@ -91,7 +155,10 @@ export function parseArguments(version, argv = process.argv) {
         .check(args => {
         // We can't set default in the options else
         // Yargs will complain
-        if (!args.channel && !args.browserUrl && !args.executablePath) {
+        if (!args.channel &&
+            !args.browserUrl &&
+            !args.wsEndpoint &&
+            !args.executablePath) {
             args.channel = 'stable';
         }
         return true;
@@ -99,7 +166,15 @@ export function parseArguments(version, argv = process.argv) {
         .example([
         [
             '$0 --browserUrl http://127.0.0.1:9222',
-            'Connect to an existing browser instance',
+            'Connect to an existing browser instance via HTTP',
+        ],
+        [
+            '$0 --wsEndpoint ws://127.0.0.1:9222/devtools/browser/abc123',
+            'Connect to an existing browser instance via WebSocket',
+        ],
+        [
+            `$0 --wsEndpoint ws://127.0.0.1:9222/devtools/browser/abc123 --wsHeaders '{"Authorization":"Bearer token"}'`,
+            'Connect via WebSocket with custom headers',
         ],
         ['$0 --channel beta', 'Use Chrome Beta installed on this system'],
         ['$0 --channel canary', 'Use Chrome Canary installed on this system'],
@@ -115,6 +190,12 @@ export function parseArguments(version, argv = process.argv) {
             `$0 --chrome-arg='--no-sandbox' --chrome-arg='--disable-setuid-sandbox'`,
             'Launch Chrome without sandboxes. Use with caution.',
         ],
+        ['$0 --no-category-emulation', 'Disable tools in the emulation category'],
+        [
+            '$0 --no-category-performance',
+            'Disable tools in the performance category',
+        ],
+        ['$0 --no-category-network', 'Disable tools in the network category'],
     ]);
     return yargsInstance
         .wrap(Math.min(120, yargsInstance.terminalWidth()))

package/build/src/formatters/consoleFormatter.js

@@ -3,71 +3,38 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-const logLevels = {
-    log: 'Log',
-    info: 'Info',
-    warning: 'Warning',
-    error: 'Error',
-    exception: 'Exception',
-    assert: 'Assert',
-};
-export async function formatConsoleEvent(event) {
-    // Check if the event object has the .type() method, which is unique to ConsoleMessage
-    if ('type' in event) {
-        return await formatConsoleMessage(event);
-    }
-    return `Error: ${event.message}`;
+// The short format for a console message, based on a previous format.
+export function formatConsoleEventShort(msg) {
+    return `msgid=${msg.consoleMessageStableId} [${msg.type}] ${msg.message} (${msg.args?.length ?? 0} args)`;
 }
-async function formatConsoleMessage(msg) {
-    const logLevel = logLevels[msg.type()];
-    const args = msg.args();
-    if (logLevel === 'Error') {
-        let message = `${logLevel}> `;
-        if (msg.text() === 'JSHandle@error') {
-            const errorHandle = args[0];
-            message += await errorHandle
-                .evaluate(error => {
-                return error.toString();
-            })
-                .catch(() => {
-                return 'Error occurred';
-            });
-            void errorHandle.dispose().catch();
-            const formattedArgs = await formatArgs(args.slice(1));
-            if (formattedArgs) {
-                message += ` ${formattedArgs}`;
-            }
-        }
-        else {
-            message += msg.text();
-            const formattedArgs = await formatArgs(args);
-            if (formattedArgs) {
-                message += ` ${formattedArgs}`;
-            }
-            for (const frame of msg.stackTrace()) {
-                message += '\n' + formatStackFrame(frame);
-            }
-        }
-        return message;
+function getArgs(msg) {
+    const args = [...(msg.args ?? [])];
+    // If there is no text, the first argument serves as text (see formatMessage).
+    if (!msg.message) {
+        args.shift();
     }
-    const formattedArgs = await formatArgs(args);
-    const text = msg.text();
-    return `${logLevel}> ${formatStackFrame(msg.location())}: ${text} ${formattedArgs}`.trim();
+    return args;
+}
+// The verbose format for a console message, including all details.
+export function formatConsoleEventVerbose(msg) {
+    const result = [
+        `ID: ${msg.consoleMessageStableId}`,
+        `Message: ${msg.type}> ${msg.message}`,
+        formatArgs(msg),
+    ].filter(line => !!line);
+    return result.join('\n');
 }
-async function formatArgs(args) {
-    const argValues = await Promise.all(args.map(arg => arg.jsonValue().catch(() => {
-        // Ignore errors
-    })));
-    return argValues
-        .map(value => {
-        return typeof value === 'object' ? JSON.stringify(value) : String(value);
-    })
-        .join(' ');
+function formatArg(arg) {
+    return typeof arg === 'object' ? JSON.stringify(arg) : String(arg);
 }
-function formatStackFrame(stackFrame) {
-    if (!stackFrame?.url) {
-        return '<unknown>';
+function formatArgs(consoleData) {
+    const args = getArgs(consoleData);
+    if (!args.length) {
+        return '';
+    }
+    const result = ['### Arguments'];
+    for (const [key, arg] of args.entries()) {
+        result.push(`Arg #${key}: ${formatArg(arg)}`);
     }
-    const filename = stackFrame.url.replace(/^.*\//, '');
-    return `${filename}:${stackFrame.lineNumber}:${stackFrame.columnNumber}`;
+    return result.join('\n');
 }

package/build/src/formatters/networkFormatter.js

@@ -5,8 +5,9 @@
  */
 import { isUtf8 } from 'node:buffer';
 const BODY_CONTEXT_SIZE_LIMIT = 10000;
-export function getShortDescriptionForRequest(request) {
-    return `${request.url()} ${request.method()} ${getStatusFromRequest(request)}`;
+export function getShortDescriptionForRequest(request, id, selectedInDevToolsUI = false) {
+    // TODO truncate the URL
+    return `reqid=${id} ${request.method()} ${request.url()} ${getStatusFromRequest(request)}${selectedInDevToolsUI ? ` [selected in the DevTools Network panel]` : ''}`;
 }
 export function getStatusFromRequest(request) {
     const httpResponse = request.response();
@@ -47,8 +48,7 @@ export async function getFormattedResponseBody(httpResponse, sizeLimit = BODY_CO
         return `<binary data>`;
     }
     catch {
-        // buffer() call might fail with CDP exception, in this case we don't print anything in the context
-        return;
+        return `<not available anymore>`;
     }
 }
 export async function getFormattedRequestBody(httpRequest, sizeLimit = BODY_CONTEXT_SIZE_LIMIT) {
@@ -64,8 +64,7 @@ export async function getFormattedRequestBody(httpRequest, sizeLimit = BODY_CONT
             }
         }
         catch {
-            // fetchPostData() call might fail with CDP exception, in this case we don't print anything in the context
-            return;
+            return `<not available anymore>`;
         }
     }
     return;

package/build/src/formatters/snapshotFormatter.js

@@ -1,20 +1,37 @@
-export function formatA11ySnapshot(serializedAXNodeRoot, depth = 0) {
+export function formatSnapshotNode(root, snapshot, depth = 0) {
     let result = '';
-    const attributes = getAttributes(serializedAXNodeRoot);
-    const line = ' '.repeat(depth * 2) + attributes.join(' ') + '\n';
+    const attributes = getAttributes(root);
+    const line = ' '.repeat(depth * 2) +
+        attributes.join(' ') +
+        (root.id === snapshot?.selectedElementUid
+            ? ' [selected in the DevTools Elements panel]'
+            : '') +
+        '\n';
     result += line;
-    for (const child of serializedAXNodeRoot.children) {
-        result += formatA11ySnapshot(child, depth + 1);
+    for (const child of root.children) {
+        result += formatSnapshotNode(child, snapshot, depth + 1);
     }
     return result;
 }
 function getAttributes(serializedAXNodeRoot) {
-    const attributes = [
-        `uid=${serializedAXNodeRoot.id}`,
-        serializedAXNodeRoot.role,
-        `"${serializedAXNodeRoot.name || ''}"`, // Corrected: Added quotes around name
-    ];
-    const excluded = new Set(['id', 'role', 'name', 'elementHandle', 'children']);
+    const attributes = [`uid=${serializedAXNodeRoot.id}`];
+    if (serializedAXNodeRoot.role) {
+        // To match representation in DevTools.
+        attributes.push(serializedAXNodeRoot.role === 'none'
+            ? 'ignored'
+            : serializedAXNodeRoot.role);
+    }
+    if (serializedAXNodeRoot.name) {
+        attributes.push(`"${serializedAXNodeRoot.name}"`);
+    }
+    const excluded = new Set([
+        'id',
+        'role',
+        'name',
+        'elementHandle',
+        'children',
+        'backendNodeId',
+    ]);
     const booleanPropertyMap = {
         disabled: 'disableable',
         expanded: 'expandable',

package/build/src/logger.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import fs from 'node:fs';
-import debug from 'debug';
+import { debug } from './third_party/index.js';
 const mcpDebugNamespace = 'mcp:log';
 const namespacesToEnable = [
     mcpDebugNamespace,