@nimbus21.ai/chrome-devtools-mcp 0.12.3 → 0.17.4

package/build/src/tools/pages.js

@@ -27,16 +27,16 @@ export const selectPage = defineTool({
         readOnlyHint: true,
     },
     schema: {
-        pageIdx: zod
+        pageId: zod
             .number()
-            .describe(`The index of the page to select. Call ${listPages.name} to get available pages.`),
+            .describe(`The ID of the page to select. Call ${listPages.name} to get available pages.`),
         bringToFront: zod
             .boolean()
             .optional()
             .describe('Whether to focus the page and bring it to the top.'),
     },
     handler: async (request, response, context) => {
-        const page = context.getPageByIdx(request.params.pageIdx);
+        const page = context.getPageById(request.params.pageId);
         context.selectPage(page);
         response.setIncludePages(true);
         if (request.params.bringToFront) {
@@ -52,13 +52,13 @@ export const closePage = defineTool({
         readOnlyHint: false,
     },
     schema: {
-        pageIdx: zod
+        pageId: zod
             .number()
-            .describe('The index of the page to close. Call list_pages to list pages.'),
+            .describe('The ID of the page to close. Call list_pages to list pages.'),
     },
     handler: async (request, response, context) => {
         try {
-            await context.closePage(request.params.pageIdx);
+            await context.closePage(request.params.pageId);
         }
         catch (err) {
             if (err.message === CLOSE_PAGE_ERROR) {
@@ -80,15 +80,19 @@ export const newPage = defineTool({
     },
     schema: {
         url: zod.string().describe('URL to load in a new page.'),
+        background: zod
+            .boolean()
+            .optional()
+            .describe('Whether to open the page in the background without bringing it to the front. Default is false (foreground).'),
         ...timeoutSchema,
     },
     handler: async (request, response, context) => {
-        const page = await context.newPage();
+        const page = await context.newPage(request.params.background);
         await context.waitForEventsAfterAction(async () => {
             await page.goto(request.params.url, {
                 timeout: request.params.timeout,
             });
-        });
+        }, { timeout: request.params.timeout });
         response.setIncludePages(true);
     },
 });
@@ -109,6 +113,14 @@ export const navigatePage = defineTool({
             .boolean()
             .optional()
             .describe('Whether to ignore cache on reload.'),
+        handleBeforeUnload: zod
+            .enum(['accept', 'decline'])
+            .optional()
+            .describe('Whether to auto accept or beforeunload dialogs triggered by this navigation. Default is accept.'),
+        initScript: zod
+            .string()
+            .optional()
+            .describe('A JavaScript script to be executed on each new document before any other scripts for the next navigation.'),
         ...timeoutSchema,
     },
     handler: async (request, response, context) => {
@@ -122,52 +134,85 @@ export const navigatePage = defineTool({
         if (!request.params.type) {
             request.params.type = 'url';
         }
-        await context.waitForEventsAfterAction(async () => {
-            switch (request.params.type) {
-                case 'url':
-                    if (!request.params.url) {
-                        throw new Error('A URL is required for navigation of type=url.');
-                    }
-                    try {
-                        await page.goto(request.params.url, options);
-                        response.appendResponseLine(`Successfully navigated to ${request.params.url}.`);
-                    }
-                    catch (error) {
-                        response.appendResponseLine(`Unable to navigate in the  selected page: ${error.message}.`);
-                    }
-                    break;
-                case 'back':
-                    try {
-                        await page.goBack(options);
-                        response.appendResponseLine(`Successfully navigated back to ${page.url()}.`);
-                    }
-                    catch (error) {
-                        response.appendResponseLine(`Unable to navigate back in the selected page: ${error.message}.`);
-                    }
-                    break;
-                case 'forward':
-                    try {
-                        await page.goForward(options);
-                        response.appendResponseLine(`Successfully navigated forward to ${page.url()}.`);
-                    }
-                    catch (error) {
-                        response.appendResponseLine(`Unable to navigate forward in the selected page: ${error.message}.`);
-                    }
-                    break;
-                case 'reload':
-                    try {
-                        await page.reload({
-                            ...options,
-                            ignoreCache: request.params.ignoreCache,
-                        });
-                        response.appendResponseLine(`Successfully reloaded the page.`);
-                    }
-                    catch (error) {
-                        response.appendResponseLine(`Unable to reload the selected page: ${error.message}.`);
-                    }
-                    break;
+        const handleBeforeUnload = request.params.handleBeforeUnload ?? 'accept';
+        const dialogHandler = (dialog) => {
+            if (dialog.type() === 'beforeunload') {
+                if (handleBeforeUnload === 'accept') {
+                    response.appendResponseLine(`Accepted a beforeunload dialog.`);
+                    void dialog.accept();
+                }
+                else {
+                    response.appendResponseLine(`Declined a beforeunload dialog.`);
+                    void dialog.dismiss();
+                }
+                // We are not going to report the dialog like regular dialogs.
+                context.clearDialog();
             }
-        });
+        };
+        let initScriptId;
+        if (request.params.initScript) {
+            const { identifier } = await page.evaluateOnNewDocument(request.params.initScript);
+            initScriptId = identifier;
+        }
+        page.on('dialog', dialogHandler);
+        try {
+            await context.waitForEventsAfterAction(async () => {
+                switch (request.params.type) {
+                    case 'url':
+                        if (!request.params.url) {
+                            throw new Error('A URL is required for navigation of type=url.');
+                        }
+                        try {
+                            await page.goto(request.params.url, options);
+                            response.appendResponseLine(`Successfully navigated to ${request.params.url}.`);
+                        }
+                        catch (error) {
+                            response.appendResponseLine(`Unable to navigate in the  selected page: ${error.message}.`);
+                        }
+                        break;
+                    case 'back':
+                        try {
+                            await page.goBack(options);
+                            response.appendResponseLine(`Successfully navigated back to ${page.url()}.`);
+                        }
+                        catch (error) {
+                            response.appendResponseLine(`Unable to navigate back in the selected page: ${error.message}.`);
+                        }
+                        break;
+                    case 'forward':
+                        try {
+                            await page.goForward(options);
+                            response.appendResponseLine(`Successfully navigated forward to ${page.url()}.`);
+                        }
+                        catch (error) {
+                            response.appendResponseLine(`Unable to navigate forward in the selected page: ${error.message}.`);
+                        }
+                        break;
+                    case 'reload':
+                        try {
+                            await page.reload({
+                                ...options,
+                                ignoreCache: request.params.ignoreCache,
+                            });
+                            response.appendResponseLine(`Successfully reloaded the page.`);
+                        }
+                        catch (error) {
+                            response.appendResponseLine(`Unable to reload the selected page: ${error.message}.`);
+                        }
+                        break;
+                }
+            }, { timeout: request.params.timeout });
+        }
+        finally {
+            page.off('dialog', dialogHandler);
+            if (initScriptId) {
+                await page
+                    .removeScriptToEvaluateOnNewDocument(initScriptId)
+                    .catch(error => {
+                    logger(`Failed to remove init script`, error);
+                });
+            }
+        }
         response.setIncludePages(true);
     },
 });
@@ -184,7 +229,22 @@ export const resizePage = defineTool({
     },
     handler: async (request, response, context) => {
         const page = context.getSelectedPage();
-        // @ts-expect-error internal API for now.
+        try {
+            const browser = page.browser();
+            const windowId = await page.windowId();
+            const bounds = await browser.getWindowBounds(windowId);
+            if (bounds.windowState === 'fullscreen') {
+                // Have to call this twice on Ubuntu when the window is in fullscreen mode.
+                await browser.setWindowBounds(windowId, { windowState: 'normal' });
+                await browser.setWindowBounds(windowId, { windowState: 'normal' });
+            }
+            else if (bounds.windowState !== 'normal') {
+                await browser.setWindowBounds(windowId, { windowState: 'normal' });
+            }
+        }
+        catch {
+            // Window APIs are not supported on all platforms
+        }
         await page.resize({
             contentWidth: request.params.width,
             contentHeight: request.params.height,
@@ -241,3 +301,23 @@ export const handleDialog = defineTool({
         response.setIncludePages(true);
     },
 });
+export const getTabId = defineTool({
+    name: 'get_tab_id',
+    description: `Get the tab ID of the page`,
+    annotations: {
+        category: ToolCategory.NAVIGATION,
+        readOnlyHint: true,
+        conditions: ['experimentalInteropTools'],
+    },
+    schema: {
+        pageId: zod
+            .number()
+            .describe(`The ID of the page to get the tab ID for. Call ${listPages.name} to get available pages.`),
+    },
+    handler: async (request, response, context) => {
+        const page = context.getPageById(request.params.pageId);
+        // @ts-expect-error _tabId is internal.
+        const tabId = page._tabId;
+        response.setTabId(tabId);
+    },
+});

package/build/src/tools/performance.js

@@ -3,25 +3,31 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import zlib from 'node:zlib';
 import { logger } from '../logger.js';
-import { zod } from '../third_party/index.js';
-import { getInsightOutput, getTraceSummary, parseRawTraceBuffer, traceResultIsSuccess, } from '../trace-processing/parse.js';
+import { zod, DevTools } from '../third_party/index.js';
+import { parseRawTraceBuffer, traceResultIsSuccess, } from '../trace-processing/parse.js';
 import { ToolCategory } from './categories.js';
 import { defineTool } from './ToolDefinition.js';
+const filePathSchema = zod
+    .string()
+    .optional()
+    .describe('The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).');
 export const startTrace = defineTool({
     name: 'performance_start_trace',
-    description: 'Starts a performance trace recording on the selected page. This can be used to look for performance problems and insights to improve the performance of the page. It will also report Core Web Vital (CWV) scores for the page.',
+    description: `Starts a performance trace recording on the selected page. This can be used to look for performance problems and insights to improve the performance of the page. It will also report Core Web Vital (CWV) scores for the page.`,
     annotations: {
         category: ToolCategory.PERFORMANCE,
-        readOnlyHint: true,
+        readOnlyHint: false,
     },
     schema: {
         reload: zod
             .boolean()
-            .describe('Determines if, once tracing has started, the page should be automatically reloaded.'),
+            .describe('Determines if, once tracing has started, the current selected page should be automatically reloaded. Navigate the page to the right URL using the navigate_page tool BEFORE starting the trace if reload or autoStop is set to true.'),
         autoStop: zod
             .boolean()
             .describe('Determines if the trace recording should be automatically stopped.'),
+        filePath: filePathSchema,
     },
     handler: async (request, response, context) => {
         if (context.isRunningPerformanceTrace()) {
@@ -68,7 +74,7 @@ export const startTrace = defineTool({
         }
         if (request.params.autoStop) {
             await new Promise(resolve => setTimeout(resolve, 5_000));
-            await stopTracingAndAppendOutput(page, response, context);
+            await stopTracingAndAppendOutput(page, response, context, request.params.filePath);
         }
         else {
             response.appendResponseLine(`The performance trace is being recorded. Use performance_stop_trace to stop it.`);
@@ -80,15 +86,17 @@ export const stopTrace = defineTool({
     description: 'Stops the active performance trace recording on the selected page.',
     annotations: {
         category: ToolCategory.PERFORMANCE,
-        readOnlyHint: true,
+        readOnlyHint: false,
+    },
+    schema: {
+        filePath: filePathSchema,
     },
-    schema: {},
-    handler: async (_request, response, context) => {
+    handler: async (request, response, context) => {
         if (!context.isRunningPerformanceTrace()) {
             return;
         }
         const page = context.getSelectedPage();
-        await stopTracingAndAppendOutput(page, response, context);
+        await stopTracingAndAppendOutput(page, response, context, request.params.filePath);
     },
 });
 export const analyzeInsight = defineTool({
@@ -112,36 +120,69 @@ export const analyzeInsight = defineTool({
             response.appendResponseLine('No recorded traces found. Record a performance trace so you have Insights to analyze.');
             return;
         }
-        const insightOutput = getInsightOutput(lastRecording, request.params.insightSetId, request.params.insightName);
-        if ('error' in insightOutput) {
-            response.appendResponseLine(insightOutput.error);
-            return;
-        }
-        response.appendResponseLine(insightOutput.output);
+        response.attachTraceInsight(lastRecording, request.params.insightSetId, request.params.insightName);
     },
 });
-async function stopTracingAndAppendOutput(page, response, context) {
+async function stopTracingAndAppendOutput(page, response, context, filePath) {
     try {
         const traceEventsBuffer = await page.tracing.stop();
+        if (filePath && traceEventsBuffer) {
+            let dataToWrite = traceEventsBuffer;
+            if (filePath.endsWith('.gz')) {
+                dataToWrite = await new Promise((resolve, reject) => {
+                    zlib.gzip(traceEventsBuffer, (error, result) => {
+                        if (error) {
+                            reject(error);
+                        }
+                        else {
+                            resolve(result);
+                        }
+                    });
+                });
+            }
+            const file = await context.saveFile(dataToWrite, filePath);
+            response.appendResponseLine(`The raw trace data was saved to ${file.filename}.`);
+        }
         const result = await parseRawTraceBuffer(traceEventsBuffer);
         response.appendResponseLine('The performance trace has been stopped.');
         if (traceResultIsSuccess(result)) {
+            if (context.isCruxEnabled()) {
+                await populateCruxData(result);
+            }
             context.storeTraceRecording(result);
-            const traceSummaryText = getTraceSummary(result);
-            response.appendResponseLine(traceSummaryText);
+            response.attachTraceSummary(result);
         }
         else {
-            response.appendResponseLine('There was an unexpected error parsing the trace:');
-            response.appendResponseLine(result.error);
+            throw new Error(`There was an unexpected error parsing the trace: ${result.error}`);
         }
     }
-    catch (e) {
-        const errorText = e instanceof Error ? e.message : JSON.stringify(e);
-        logger(`Error stopping performance trace: ${errorText}`);
-        response.appendResponseLine('An error occurred generating the response for this trace:');
-        response.appendResponseLine(errorText);
-    }
     finally {
         context.setIsRunningPerformanceTrace(false);
     }
 }
+/** We tell CrUXManager to fetch data so it's available when DevTools.PerformanceTraceFormatter is invoked */
+async function populateCruxData(result) {
+    logger('populateCruxData called');
+    const cruxManager = DevTools.CrUXManager.instance();
+    // go/jtfbx. Yes, we're aware this API key is public. ;)
+    cruxManager.setEndpointForTesting('https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=AIzaSyBn5gimNjhiEyA_euicSKko6IlD3HdgUfk');
+    const cruxSetting = DevTools.Common.Settings.Settings.instance().createSetting('field-data', {
+        enabled: true,
+    });
+    cruxSetting.set({ enabled: true });
+    // Gather URLs to fetch CrUX data for
+    const urls = [...(result.parsedTrace.insights?.values() ?? [])].map(c => c.url.toString());
+    urls.push(result.parsedTrace.data.Meta.mainFrameURL);
+    const urlSet = new Set(urls);
+    if (urlSet.size === 0) {
+        logger('No URLs found for CrUX data');
+        return;
+    }
+    logger(`Fetching CrUX data for ${urlSet.size} URLs: ${Array.from(urlSet).join(', ')}`);
+    const cruxData = await Promise.all(Array.from(urlSet).map(async (url) => {
+        const data = await cruxManager.getFieldDataForPage(url);
+        logger(`CrUX data for ${url}: ${data ? 'found' : 'not found'}`);
+        return data;
+    }));
+    result.parsedTrace.metadata.cruxFieldData = cruxData;
+}

package/build/src/tools/script.js

@@ -8,8 +8,8 @@ import { ToolCategory } from './categories.js';
 import { defineTool } from './ToolDefinition.js';
 export const evaluateScript = defineTool({
     name: 'evaluate_script',
-    description: `Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON
-so returned values have to JSON-serializable.`,
+    description: `Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON,
+so returned values have to be JSON-serializable.`,
     annotations: {
         category: ToolCategory.DEBUGGING,
         readOnlyHint: false,

package/build/src/tools/tools.js

@@ -5,6 +5,7 @@
  */
 import * as consoleTools from './console.js';
 import * as emulationTools from './emulation.js';
+import * as extensionTools from './extensions.js';
 import * as inputTools from './input.js';
 import * as networkTools from './network.js';
 import * as pagesTools from './pages.js';
@@ -15,6 +16,7 @@ import * as snapshotTools from './snapshot.js';
 const tools = [
     ...Object.values(consoleTools),
     ...Object.values(emulationTools),
+    ...Object.values(extensionTools),
     ...Object.values(inputTools),
     ...Object.values(networkTools),
     ...Object.values(pagesTools),

package/build/src/utils/ExtensionRegistry.js

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export class ExtensionRegistry {
+    #extensions = new Map();
+    async registerExtension(id, extensionPath) {
+        const manifestPath = path.join(extensionPath, 'manifest.json');
+        const manifestContent = await fs.readFile(manifestPath, 'utf-8');
+        const manifest = JSON.parse(manifestContent);
+        const name = manifest.name ?? 'Unknown';
+        const version = manifest.version ?? 'Unknown';
+        const extension = {
+            id,
+            name,
+            version,
+            isEnabled: true,
+            path: extensionPath,
+        };
+        this.#extensions.set(extension.id, extension);
+        return extension;
+    }
+    remove(id) {
+        this.#extensions.delete(id);
+    }
+    list() {
+        return Array.from(this.#extensions.values());
+    }
+    getById(id) {
+        return this.#extensions.get(id);
+    }
+}

package/build/src/utils/string.js

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Converts a given string to snake_case.
+ * This function handles camelCase, PascalCase, and acronyms, including transitions between letters and numbers.
+ * It uses Unicode-aware regular expressions (`\p{L}`, `\p{N}`, `\p{Lu}`, `\p{Ll}` with the `u` flag)
+ * to correctly process letters and numbers from various languages.
+ *
+ * @param text The input string to convert to snake_case.
+ * @returns The snake_case version of the input string.
+ */
+export function toSnakeCase(text) {
+    if (!text) {
+        return '';
+    }
+    // First, handle case-based transformations to insert underscores correctly.
+    // 1. Add underscore between a letter and a number.
+    //    e.g., "version2" -> "version_2"
+    // 2. Add underscore between an uppercase letter sequence and a following uppercase+lowercase sequence.
+    //    e.g., "APIFlags" -> "API_Flags"
+    // 3. Add underscore between a lowercase/number and an uppercase letter.
+    //    e.g., "lastName" -> "last_Name", "version_2Update" -> "version_2_Update"
+    // 4. Replace sequences of non-alphanumeric with a single underscore
+    // 5. Remove any leading or trailing underscores.
+    const result = text
+        .replace(/(\p{L})(\p{N})/gu, '$1_$2') // 1
+        .replace(/(\p{Lu}+)(\p{Lu}\p{Ll})/gu, '$1_$2') // 2
+        .replace(/(\p{Ll}|\p{N})(\p{Lu})/gu, '$1_$2') // 3
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, '_') // 4
+        .replace(/^_|_$/g, ''); // 5
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus21.ai/chrome-devtools-mcp",
-  "version": "0.12.3",
+  "version": "0.17.4",
   "description": "MCP server for Chrome DevTools with stealth mode support",
   "type": "module",
   "bin": "./build/src/index.js",
@@ -16,14 +16,14 @@
     "docs:generate": "node --experimental-strip-types scripts/generate-docs.ts",
     "start": "npm run build && node build/src/index.js",
     "start-debug": "DEBUG=mcp:* DEBUG_COLORS=false npm run build && node build/src/index.js",
-    "test:node20": "node --import ./build/tests/setup.js --test-reporter spec --test-force-exit --test build/tests",
-    "test:no-build": "node --import ./build/tests/setup.js --no-warnings=ExperimentalWarning --test-reporter spec --test-force-exit --test \"build/tests/**/*.test.js\"",
-    "test": "npm run build && npm run test:no-build",
-    "test:only": "npm run build && npm run test:only:no-build",
-    "test:only:no-build": "node --import ./build/tests/setup.js --no-warnings=ExperimentalWarning --test-reporter spec --test-force-exit --test --test-only \"build/tests/**/*.test.js\"",
-    "test:update-snapshots": "npm run build && node --import ./build/tests/setup.js --no-warnings=ExperimentalWarning --test-force-exit --test --test-update-snapshots \"build/tests/**/*.test.js\"",
-    "prepare": "node scripts/prepare.js",
-    "verify-server-json-version": "node build/scripts/verify-server-json-version.js"
+    "test": "npm run build && node scripts/test.mjs",
+    "test:no-build": "node scripts/test.mjs",
+    "test:only": "npm run build && node scripts/test.mjs --test-only",
+    "test:update-snapshots": "npm run build && node scripts/test.mjs --test-update-snapshots",
+    "prepare": "node --experimental-strip-types scripts/prepare.ts",
+    "verify-server-json-version": "node --experimental-strip-types scripts/verify-server-json-version.ts",
+    "eval": "npm run build && CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS=true node --experimental-strip-types scripts/eval_gemini.ts",
+    "count-tokens": "node --experimental-strip-types scripts/count_tokens.ts"
   },
   "files": [
     "build/src",
@@ -46,7 +46,8 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.35.0",
-    "@modelcontextprotocol/sdk": "1.24.3",
+    "@google/genai": "^1.37.0",
+    "@modelcontextprotocol/sdk": "1.26.0",
     "@rollup/plugin-commonjs": "^29.0.0",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
@@ -58,20 +59,20 @@
     "@types/yargs": "^17.0.33",
     "@typescript-eslint/eslint-plugin": "^8.43.0",
     "@typescript-eslint/parser": "^8.43.0",
-    "chrome-devtools-frontend": "1.0.1555430",
-    "core-js": "3.47.0",
+    "chrome-devtools-frontend": "1.0.1583146",
+    "core-js": "3.48.0",
     "debug": "4.4.3",
     "eslint": "^9.35.0",
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
-    "globals": "^16.4.0",
+    "globals": "^17.0.0",
     "prettier": "^3.6.2",
-    "puppeteer": "24.33.0",
-    "rollup": "4.53.3",
+    "puppeteer": "24.37.4",
+    "rollup": "4.57.1",
     "rollup-plugin-cleanup": "^3.2.1",
     "rollup-plugin-license": "^3.6.0",
     "sinon": "^21.0.0",
-    "tsx": "^4.21.0",
+    "tiktoken": "^1.0.22",
     "typescript": "^5.9.2",
     "typescript-eslint": "^8.43.0",
     "yargs": "18.0.0"