chrome-devtools-mcp 0.8.1 → 0.9.0

package/build/src/McpResponse.js

@@ -1,4 +1,4 @@
-import { formatConsoleEvent } from './formatters/consoleFormatter.js';
+import { formatConsoleEventShort, formatConsoleEventVerbose, } from './formatters/consoleFormatter.js';
 import { getFormattedHeaderValue, getFormattedResponseBody, getFormattedRequestBody, getShortDescriptionForRequest, getStatusFromRequest, } from './formatters/networkFormatter.js';
 import { formatA11ySnapshot } from './formatters/snapshotFormatter.js';
 import { handleDialog } from './tools/pages.js';
@@ -6,17 +6,19 @@ import { paginate } from './utils/pagination.js';
 export class McpResponse {
     #includePages = false;
     #includeSnapshot = false;
-    #attachedNetworkRequestData;
-    #includeConsoleData = false;
+    #includeVerboseSnapshot = false;
+    #attachedNetworkRequestId;
+    #attachedConsoleMessageId;
     #textResponseLines = [];
-    #formattedConsoleData;
     #images = [];
     #networkRequestsOptions;
+    #consoleDataOptions;
     setIncludePages(value) {
         this.#includePages = value;
     }
-    setIncludeSnapshot(value) {
+    setIncludeSnapshot(value, verbose = false) {
         this.#includeSnapshot = value;
+        this.#includeVerboseSnapshot = verbose;
     }
     setIncludeNetworkRequests(value, options) {
         if (!value) {
@@ -32,16 +34,32 @@ export class McpResponse {
                 }
                 : undefined,
             resourceTypes: options?.resourceTypes,
+            includePreservedRequests: options?.includePreservedRequests,
         };
     }
-    setIncludeConsoleData(value) {
-        this.#includeConsoleData = value;
-    }
-    attachNetworkRequest(url) {
-        this.#attachedNetworkRequestData = {
-            networkRequestUrl: url,
+    setIncludeConsoleData(value, options) {
+        if (!value) {
+            this.#consoleDataOptions = undefined;
+            return;
+        }
+        this.#consoleDataOptions = {
+            include: value,
+            pagination: options?.pageSize || options?.pageIdx
+                ? {
+                    pageSize: options.pageSize,
+                    pageIdx: options.pageIdx,
+                }
+                : undefined,
+            types: options?.types,
+            includePreservedMessages: options?.includePreservedMessages,
         };
     }
+    attachNetworkRequest(reqid) {
+        this.#attachedNetworkRequestId = reqid;
+    }
+    attachConsoleMessage(msgid) {
+        this.#attachedConsoleMessageId = msgid;
+    }
     get includePages() {
         return this.#includePages;
     }
@@ -49,14 +67,20 @@ export class McpResponse {
         return this.#networkRequestsOptions?.include ?? false;
     }
     get includeConsoleData() {
-        return this.#includeConsoleData;
+        return this.#consoleDataOptions?.include ?? false;
     }
-    get attachedNetworkRequestUrl() {
-        return this.#attachedNetworkRequestData?.networkRequestUrl;
+    get attachedNetworkRequestId() {
+        return this.#attachedNetworkRequestId;
     }
     get networkRequestsPageIdx() {
         return this.#networkRequestsOptions?.pagination?.pageIdx;
     }
+    get consoleMessagesPageIdx() {
+        return this.#consoleDataOptions?.pagination?.pageIdx;
+    }
+    get consoleMessagesTypes() {
+        return this.#consoleDataOptions?.types;
+    }
     appendResponseLine(value) {
         this.#textResponseLines.push(value);
     }
@@ -72,34 +96,99 @@ export class McpResponse {
     get includeSnapshot() {
         return this.#includeSnapshot;
     }
+    get includeVersboseSnapshot() {
+        return this.#includeVerboseSnapshot;
+    }
     async handle(toolName, context) {
         if (this.#includePages) {
             await context.createPagesSnapshot();
         }
         if (this.#includeSnapshot) {
-            await context.createTextSnapshot();
+            await context.createTextSnapshot(this.#includeVerboseSnapshot);
         }
-        let formattedConsoleMessages;
-        if (this.#attachedNetworkRequestData?.networkRequestUrl) {
-            const request = context.getNetworkRequestByUrl(this.#attachedNetworkRequestData.networkRequestUrl);
-            this.#attachedNetworkRequestData.requestBody =
-                await getFormattedRequestBody(request);
+        const bodies = {};
+        if (this.#attachedNetworkRequestId) {
+            const request = context.getNetworkRequestById(this.#attachedNetworkRequestId);
+            bodies.requestBody = await getFormattedRequestBody(request);
             const response = request.response();
             if (response) {
-                this.#attachedNetworkRequestData.responseBody =
-                    await getFormattedResponseBody(response);
+                bodies.responseBody = await getFormattedResponseBody(response);
             }
         }
-        if (this.#includeConsoleData) {
-            const consoleMessages = context.getConsoleData();
-            if (consoleMessages) {
-                formattedConsoleMessages = await Promise.all(consoleMessages.map(message => formatConsoleEvent(message)));
-                this.#formattedConsoleData = formattedConsoleMessages;
+        let consoleData;
+        if (this.#attachedConsoleMessageId) {
+            const message = context.getConsoleMessageById(this.#attachedConsoleMessageId);
+            const consoleMessageStableId = this.#attachedConsoleMessageId;
+            if ('args' in message) {
+                const consoleMessage = message;
+                consoleData = {
+                    consoleMessageStableId,
+                    type: consoleMessage.type(),
+                    message: consoleMessage.text(),
+                    args: await Promise.all(consoleMessage.args().map(async (arg) => {
+                        const stringArg = await arg.jsonValue().catch(() => {
+                            // Ignore errors.
+                        });
+                        return typeof stringArg === 'object'
+                            ? JSON.stringify(stringArg)
+                            : String(stringArg);
+                    })),
+                };
+            }
+            else {
+                consoleData = {
+                    consoleMessageStableId,
+                    type: 'error',
+                    message: message.message,
+                    args: [],
+                };
             }
         }
-        return this.format(toolName, context);
+        let consoleListData;
+        if (this.#consoleDataOptions?.include) {
+            let messages = context.getConsoleData(this.#consoleDataOptions.includePreservedMessages);
+            if (this.#consoleDataOptions.types?.length) {
+                const normalizedTypes = new Set(this.#consoleDataOptions.types);
+                messages = messages.filter(message => {
+                    if ('type' in message) {
+                        return normalizedTypes.has(message.type());
+                    }
+                    return normalizedTypes.has('error');
+                });
+            }
+            consoleListData = await Promise.all(messages.map(async (item) => {
+                const consoleMessageStableId = context.getConsoleMessageStableId(item);
+                if ('args' in item) {
+                    const consoleMessage = item;
+                    return {
+                        consoleMessageStableId,
+                        type: consoleMessage.type(),
+                        message: consoleMessage.text(),
+                        args: await Promise.all(consoleMessage.args().map(async (arg) => {
+                            const stringArg = await arg.jsonValue().catch(() => {
+                                // Ignore errors.
+                            });
+                            return typeof stringArg === 'object'
+                                ? JSON.stringify(stringArg)
+                                : String(stringArg);
+                        })),
+                    };
+                }
+                return {
+                    consoleMessageStableId,
+                    type: 'error',
+                    message: item.message,
+                    args: [],
+                };
+            }));
+        }
+        return this.format(toolName, context, {
+            bodies,
+            consoleData,
+            consoleListData,
+        });
     }
-    format(toolName, context) {
+    format(toolName, context, data) {
         const response = [`# ${toolName} response`];
         for (const line of this.#textResponseLines) {
             response.push(line);
@@ -141,9 +230,10 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 response.push(formattedSnapshot);
             }
         }
-        response.push(...this.#getIncludeNetworkRequestsData(context));
+        response.push(...this.#formatNetworkRequestData(context, data.bodies));
+        response.push(...this.#formatConsoleData(data.consoleData));
         if (this.#networkRequestsOptions?.include) {
-            let requests = context.getNetworkRequests();
+            let requests = context.getNetworkRequests(this.#networkRequestsOptions?.includePreservedRequests);
             // Apply resource type filtering if specified
             if (this.#networkRequestsOptions.resourceTypes?.length) {
                 const normalizedTypes = new Set(this.#networkRequestsOptions.resourceTypes);
@@ -157,17 +247,20 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 const data = this.#dataWithPagination(requests, this.#networkRequestsOptions.pagination);
                 response.push(...data.info);
                 for (const request of data.items) {
-                    response.push(getShortDescriptionForRequest(request));
+                    response.push(getShortDescriptionForRequest(request, context.getNetworkRequestStableId(request)));
                 }
             }
             else {
                 response.push('No requests found.');
             }
         }
-        if (this.#includeConsoleData && this.#formattedConsoleData) {
+        if (this.#consoleDataOptions?.include) {
+            const messages = data.consoleListData ?? [];
             response.push('## Console messages');
-            if (this.#formattedConsoleData.length) {
-                response.push(...this.#formattedConsoleData);
+            if (messages.length) {
+                const data = this.#dataWithPagination(messages, this.#consoleDataOptions.pagination);
+                response.push(...data.info);
+                response.push(...data.items.map(message => formatConsoleEventShort(message)));
             }
             else {
                 response.push('<no console messages found>');
@@ -206,22 +299,30 @@ Call ${handleDialog.name} to handle it before continuing.`);
             items: paginationResult.items,
         };
     }
-    #getIncludeNetworkRequestsData(context) {
+    #formatConsoleData(data) {
+        const response = [];
+        if (!data) {
+            return response;
+        }
+        response.push(formatConsoleEventVerbose(data));
+        return response;
+    }
+    #formatNetworkRequestData(context, data) {
         const response = [];
-        const url = this.#attachedNetworkRequestData?.networkRequestUrl;
-        if (!url) {
+        const id = this.#attachedNetworkRequestId;
+        if (!id) {
             return response;
         }
-        const httpRequest = context.getNetworkRequestByUrl(url);
+        const httpRequest = context.getNetworkRequestById(id);
         response.push(`## Request ${httpRequest.url()}`);
         response.push(`Status:  ${getStatusFromRequest(httpRequest)}`);
         response.push(`### Request Headers`);
         for (const line of getFormattedHeaderValue(httpRequest.headers())) {
             response.push(line);
         }
-        if (this.#attachedNetworkRequestData?.requestBody) {
+        if (data.requestBody) {
             response.push(`### Request Body`);
-            response.push(this.#attachedNetworkRequestData.requestBody);
+            response.push(data.requestBody);
         }
         const httpResponse = httpRequest.response();
         if (httpResponse) {
@@ -230,9 +331,9 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 response.push(line);
             }
         }
-        if (this.#attachedNetworkRequestData?.responseBody) {
+        if (data.responseBody) {
             response.push(`### Response Body`);
-            response.push(this.#attachedNetworkRequestData.responseBody);
+            response.push(data.responseBody);
         }
         const httpFailure = httpRequest.failure();
         if (httpFailure) {
@@ -244,7 +345,7 @@ Call ${handleDialog.name} to handle it before continuing.`);
             response.push(`### Redirect chain`);
             let indent = 0;
             for (const request of redirectChain.reverse()) {
-                response.push(`${'  '.repeat(indent)}${getShortDescriptionForRequest(request)}`);
+                response.push(`${'  '.repeat(indent)}${getShortDescriptionForRequest(request, context.getNetworkRequestStableId(request))}`);
                 indent++;
             }
         }

package/build/src/PageCollector.js

@@ -3,18 +3,30 @@
  * 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;
     /**
-     * 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) {
         this.#browser = browser;
-        this.#initializer = initializer;
+        this.#listenersInitializer = listeners;
     }
     async init() {
         const pages = await this.#browser.pages();
@@ -28,6 +40,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 +55,95 @@ 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');
+        }
+        for (const navigation of navigations) {
+            for (const collected of navigation) {
+                if (collected[stableIdSymbol] === stableId) {
+                    return collected;
+                }
+            }
+        }
+        throw new Error('Request not found for selected page');
     }
 }
 export class NetworkCollector extends PageCollector {
-    cleanup(page) {
-        const requests = this.storage.get(page) ?? [];
-        if (!requests) {
+    constructor(browser, listeners = collect => {
+        return {
+            request: req => {
+                collect(req);
+            },
+        };
+    }) {
+        super(browser, listeners);
+    }
+    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 +152,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,7 +6,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import puppeteer from 'puppeteer-core';
+import { puppeteer } from './third_party/index.js';
 let browser;
 function makeTargetFilter(devtools) {
     const ignoredPrefixes = new Set([
@@ -33,12 +33,24 @@ export async function ensureBrowserConnected(options) {
     if (browser?.connected) {
         return browser;
     }
-    browser = await puppeteer.connect({
+    const connectOptions = {
         targetFilter: makeTargetFilter(options.devtools),
-        browserURL: options.browserURL,
         defaultViewport: null,
         handleDevToolsAsPage: options.devtools,
-    });
+    };
+    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');
+    }
+    browser = await puppeteer.connect(connectOptions);
     return browser;
 }
 export async function launch(options) {

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',
@@ -83,6 +127,21 @@ export const cliOptions = {
         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 exlcude tools related to emulation.',
+    },
+    categoryPerformance: {
+        type: 'boolean',
+        default: true,
+        describe: 'Set to false to exlcude tools related to performance.',
+    },
+    categoryNetwork: {
+        type: 'boolean',
+        default: true,
+        describe: 'Set to false to exlcude tools related to network.',
+    },
 };
 export function parseArguments(version, argv = process.argv) {
     const yargsInstance = yargs(hideBin(argv))
@@ -91,7 +150,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 +161,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 +185,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()))