chrome-devtools-mcp 0.13.0 → 0.15.0

package/build/src/tools/categories.js

@@ -11,6 +11,7 @@ export var ToolCategory;
     ToolCategory["PERFORMANCE"] = "performance";
     ToolCategory["NETWORK"] = "network";
     ToolCategory["DEBUGGING"] = "debugging";
+    ToolCategory["EXTENSIONS"] = "extensions";
 })(ToolCategory || (ToolCategory = {}));
 export const labels = {
     [ToolCategory.INPUT]: 'Input automation',
@@ -19,4 +20,5 @@ export const labels = {
     [ToolCategory.PERFORMANCE]: 'Performance',
     [ToolCategory.NETWORK]: 'Network',
     [ToolCategory.DEBUGGING]: 'Debugging',
+    [ToolCategory.EXTENSIONS]: 'Extensions',
 };

package/build/src/tools/emulation.js

@@ -2,6 +2,7 @@
  * @license
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
+ *
  */
 import { zod, PredefinedNetworkConditions } from '../third_party/index.js';
 import { ToolCategory } from './categories.js';
@@ -45,10 +46,44 @@ export const emulate = defineTool({
             .nullable()
             .optional()
             .describe('Geolocation to emulate. Set to null to clear the geolocation override.'),
+        userAgent: zod
+            .string()
+            .nullable()
+            .optional()
+            .describe('User agent to emulate. Set to null to clear the user agent override.'),
+        colorScheme: zod
+            .enum(['dark', 'light', 'auto'])
+            .optional()
+            .describe('Emulate the dark or the light mode. Set to "auto" to reset to the default.'),
+        viewport: zod
+            .object({
+            width: zod.number().int().min(0).describe('Page width in pixels.'),
+            height: zod.number().int().min(0).describe('Page height in pixels.'),
+            deviceScaleFactor: zod
+                .number()
+                .min(0)
+                .optional()
+                .describe('Specify device scale factor (can be thought of as dpr).'),
+            isMobile: zod
+                .boolean()
+                .optional()
+                .describe('Whether the meta viewport tag is taken into account. Defaults to false.'),
+            hasTouch: zod
+                .boolean()
+                .optional()
+                .describe('Specifies if viewport supports touch events. This should be set to true for mobile devices.'),
+            isLandscape: zod
+                .boolean()
+                .optional()
+                .describe('Specifies if viewport is in landscape mode. Defaults to false.'),
+        })
+            .nullable()
+            .optional()
+            .describe('Viewport to emulate. Set to null to reset to the default viewport.'),
     },
     handler: async (request, _response, context) => {
         const page = context.getSelectedPage();
-        const { networkConditions, cpuThrottlingRate, geolocation } = request.params;
+        const { networkConditions, cpuThrottlingRate, geolocation, userAgent, viewport, } = request.params;
         if (networkConditions) {
             if (networkConditions === 'No emulation') {
                 await page.emulateNetworkConditions(null);
@@ -83,5 +118,52 @@ export const emulate = defineTool({
                 context.setGeolocation(geolocation);
             }
         }
+        if (userAgent !== undefined) {
+            if (userAgent === null) {
+                await page.setUserAgent({
+                    userAgent: undefined,
+                });
+                context.setUserAgent(null);
+            }
+            else {
+                await page.setUserAgent({
+                    userAgent,
+                });
+                context.setUserAgent(userAgent);
+            }
+        }
+        if (request.params.colorScheme) {
+            if (request.params.colorScheme === 'auto') {
+                await page.emulateMediaFeatures([
+                    { name: 'prefers-color-scheme', value: '' },
+                ]);
+                context.setColorScheme(null);
+            }
+            else {
+                await page.emulateMediaFeatures([
+                    {
+                        name: 'prefers-color-scheme',
+                        value: request.params.colorScheme,
+                    },
+                ]);
+                context.setColorScheme(request.params.colorScheme);
+            }
+        }
+        if (viewport !== undefined) {
+            if (viewport === null) {
+                await page.setViewport(null);
+                context.setViewport(null);
+            }
+            else {
+                const defaults = {
+                    deviceScaleFactor: 1,
+                    isMobile: false,
+                    hasTouch: false,
+                    isLandscape: false,
+                };
+                await page.setViewport({ ...defaults, ...viewport });
+                context.setViewport({ ...defaults, ...viewport });
+            }
+        }
     },
 });

package/build/src/tools/extensions.js

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+const EXTENSIONS_CONDITION = 'experimentalExtensionSupport';
+export const installExtension = defineTool({
+    name: 'install_extension',
+    description: 'Installs a Chrome extension from the given path.',
+    annotations: {
+        category: ToolCategory.EXTENSIONS,
+        readOnlyHint: false,
+        conditions: [EXTENSIONS_CONDITION],
+    },
+    schema: {
+        path: zod
+            .string()
+            .describe('Absolute path to the unpacked extension folder.'),
+    },
+    handler: async (request, response, context) => {
+        const { path } = request.params;
+        const id = await context.installExtension(path);
+        response.appendResponseLine(`Extension installed. Id: ${id}`);
+    },
+});
+export const uninstallExtension = defineTool({
+    name: 'uninstall_extension',
+    description: 'Uninstalls a Chrome extension by its ID.',
+    annotations: {
+        category: ToolCategory.EXTENSIONS,
+        readOnlyHint: false,
+        conditions: [EXTENSIONS_CONDITION],
+    },
+    schema: {
+        id: zod.string().describe('ID of the extension to uninstall.'),
+    },
+    handler: async (request, response, context) => {
+        const { id } = request.params;
+        await context.uninstallExtension(id);
+        response.appendResponseLine(`Extension uninstalled. Id: ${id}`);
+    },
+});
+export const listExtensions = defineTool({
+    name: 'list_extensions',
+    description: 'Lists all extensions via this server, including their name, ID, version, and enabled status.',
+    annotations: {
+        category: ToolCategory.EXTENSIONS,
+        readOnlyHint: true,
+        conditions: [EXTENSIONS_CONDITION],
+    },
+    schema: {},
+    handler: async (_request, response, _context) => {
+        response.setListExtensions();
+    },
+});
+export const reloadExtension = defineTool({
+    name: 'reload_extension',
+    description: 'Reloads an unpacked Chrome extension by its ID.',
+    annotations: {
+        category: ToolCategory.EXTENSIONS,
+        readOnlyHint: false,
+        conditions: [EXTENSIONS_CONDITION],
+    },
+    schema: {
+        id: zod.string().describe('ID of the extension to reload.'),
+    },
+    handler: async (request, response, context) => {
+        const { id } = request.params;
+        const extension = context.getExtension(id);
+        if (!extension) {
+            throw new Error(`Extension with ID ${id} not found.`);
+        }
+        await context.installExtension(extension.path);
+        response.appendResponseLine('Extension reloaded.');
+    },
+});

package/build/src/tools/input.js

@@ -3,6 +3,7 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { logger } from '../logger.js';
 import { zod } from '../third_party/index.js';
 import { parseKey } from '../utils/keyboard.js';
 import { ToolCategory } from './categories.js';
@@ -11,6 +12,16 @@ const dblClickSchema = zod
     .boolean()
     .optional()
     .describe('Set to true for double clicks. Default is false.');
+const includeSnapshotSchema = zod
+    .boolean()
+    .optional()
+    .describe('Whether to include a snapshot in the response. Default is false.');
+function handleActionError(error, uid) {
+    logger('failed to act using a locator', error);
+    throw new Error(`Failed to interact with the element with uid ${uid}. The element did not become interactive within the configured timeout.`, {
+        cause: error,
+    });
+}
 export const click = defineTool({
     name: 'click',
     description: `Clicks on the provided element`,
@@ -23,6 +34,7 @@ export const click = defineTool({
             .string()
             .describe('The uid of an element on the page from the page content snapshot'),
         dblClick: dblClickSchema,
+        includeSnapshot: includeSnapshotSchema,
     },
     handler: async (request, response, context) => {
         const uid = request.params.uid;
@@ -36,7 +48,12 @@ export const click = defineTool({
             response.appendResponseLine(request.params.dblClick
                 ? `Successfully double clicked on the element`
                 : `Successfully clicked on the element`);
-            response.includeSnapshot();
+            if (request.params.includeSnapshot) {
+                response.includeSnapshot();
+            }
+        }
+        catch (error) {
+            handleActionError(error, uid);
         }
         finally {
             void handle.dispose();
@@ -55,6 +72,7 @@ export const clickAt = defineTool({
         x: zod.number().describe('The x coordinate'),
         y: zod.number().describe('The y coordinate'),
         dblClick: dblClickSchema,
+        includeSnapshot: includeSnapshotSchema,
     },
     handler: async (request, response, context) => {
         const page = context.getSelectedPage();
@@ -66,7 +84,9 @@ export const clickAt = defineTool({
         response.appendResponseLine(request.params.dblClick
             ? `Successfully double clicked at the coordinates`
             : `Successfully clicked at the coordinates`);
-        response.includeSnapshot();
+        if (request.params.includeSnapshot) {
+            response.includeSnapshot();
+        }
     },
 });
 export const hover = defineTool({
@@ -80,6 +100,7 @@ export const hover = defineTool({
         uid: zod
             .string()
             .describe('The uid of an element on the page from the page content snapshot'),
+        includeSnapshot: includeSnapshotSchema,
     },
     handler: async (request, response, context) => {
         const uid = request.params.uid;
@@ -89,7 +110,12 @@ export const hover = defineTool({
                 await handle.asLocator().hover();
             });
             response.appendResponseLine(`Successfully hovered over the element`);
-            response.includeSnapshot();
+            if (request.params.includeSnapshot) {
+                response.includeSnapshot();
+            }
+        }
+        catch (error) {
+            handleActionError(error, uid);
         }
         finally {
             void handle.dispose();
@@ -138,9 +164,16 @@ async function fillFormElement(uid, value, context) {
             await selectOption(handle, aXNode, value);
         }
         else {
-            await handle.asLocator().fill(value);
+            // Increase timeout for longer input values.
+            const timeoutPerChar = 10; // ms
+            const fillTimeout = context.getSelectedPage().getDefaultTimeout() +
+                value.length * timeoutPerChar;
+            await handle.asLocator().setTimeout(fillTimeout).fill(value);
         }
     }
+    catch (error) {
+        handleActionError(error, uid);
+    }
     finally {
         void handle.dispose();
     }
@@ -157,13 +190,17 @@ export const fill = defineTool({
             .string()
             .describe('The uid of an element on the page from the page content snapshot'),
         value: zod.string().describe('The value to fill in'),
+        includeSnapshot: includeSnapshotSchema,
     },
     handler: async (request, response, context) => {
         await context.waitForEventsAfterAction(async () => {
+            await context.getSelectedPage().keyboard.type(request.params.value);
             await fillFormElement(request.params.uid, request.params.value, context);
         });
         response.appendResponseLine(`Successfully filled out the element`);
-        response.includeSnapshot();
+        if (request.params.includeSnapshot) {
+            response.includeSnapshot();
+        }
     },
 });
 export const drag = defineTool({
@@ -176,6 +213,7 @@ export const drag = defineTool({
     schema: {
         from_uid: zod.string().describe('The uid of the element to drag'),
         to_uid: zod.string().describe('The uid of the element to drop into'),
+        includeSnapshot: includeSnapshotSchema,
     },
     handler: async (request, response, context) => {
         const fromHandle = await context.getElementByUid(request.params.from_uid);
@@ -187,7 +225,9 @@ export const drag = defineTool({
                 await toHandle.drop(fromHandle);
             });
             response.appendResponseLine(`Successfully dragged an element`);
-            response.includeSnapshot();
+            if (request.params.includeSnapshot) {
+                response.includeSnapshot();
+            }
         }
         finally {
             void fromHandle.dispose();
@@ -209,6 +249,7 @@ export const fillForm = defineTool({
             value: zod.string().describe('Value for the element'),
         }))
             .describe('Elements from snapshot to fill out.'),
+        includeSnapshot: includeSnapshotSchema,
     },
     handler: async (request, response, context) => {
         for (const element of request.params.elements) {
@@ -217,7 +258,9 @@ export const fillForm = defineTool({
             });
         }
         response.appendResponseLine(`Successfully filled out the form`);
-        response.includeSnapshot();
+        if (request.params.includeSnapshot) {
+            response.includeSnapshot();
+        }
     },
 });
 export const uploadFile = defineTool({
@@ -232,6 +275,7 @@ export const uploadFile = defineTool({
             .string()
             .describe('The uid of the file input element or an element that will open file chooser on the page from the page content snapshot'),
         filePath: zod.string().describe('The local path of the file to upload'),
+        includeSnapshot: includeSnapshotSchema,
     },
     handler: async (request, response, context) => {
         const { uid, filePath } = request.params;
@@ -256,7 +300,9 @@ export const uploadFile = defineTool({
                     throw new Error(`Failed to upload file. The element could not accept the file directly, and clicking it did not trigger a file chooser.`);
                 }
             }
-            response.includeSnapshot();
+            if (request.params.includeSnapshot) {
+                response.includeSnapshot();
+            }
             response.appendResponseLine(`File uploaded from ${filePath}.`);
         }
         finally {
@@ -275,6 +321,7 @@ export const pressKey = defineTool({
         key: zod
             .string()
             .describe('A key or a combination (e.g., "Enter", "Control+A", "Control++", "Control+Shift+R"). Modifiers: Control, Shift, Alt, Meta'),
+        includeSnapshot: includeSnapshotSchema,
     },
     handler: async (request, response, context) => {
         const page = context.getSelectedPage();
@@ -290,6 +337,8 @@ export const pressKey = defineTool({
             }
         });
         response.appendResponseLine(`Successfully pressed key: ${request.params.key}`);
-        response.includeSnapshot();
+        if (request.params.includeSnapshot) {
+            response.includeSnapshot();
+        }
     },
 });

package/build/src/tools/network.js

@@ -77,17 +77,28 @@ export const getNetworkRequest = defineTool({
     description: `Gets a network request by an optional reqid, if omitted returns the currently selected request in the DevTools Network panel.`,
     annotations: {
         category: ToolCategory.NETWORK,
-        readOnlyHint: true,
+        readOnlyHint: false,
     },
     schema: {
         reqid: zod
             .number()
             .optional()
             .describe('The reqid of the network request. If omitted returns the currently selected request in the DevTools Network panel.'),
+        requestFilePath: zod
+            .string()
+            .optional()
+            .describe('The absolute or relative path to save the request body to. If omitted, the body is returned inline.'),
+        responseFilePath: zod
+            .string()
+            .optional()
+            .describe('The absolute or relative path to save the response body to. If omitted, the body is returned inline.'),
     },
     handler: async (request, response, context) => {
         if (request.params.reqid) {
-            response.attachNetworkRequest(request.params.reqid);
+            response.attachNetworkRequest(request.params.reqid, {
+                requestFilePath: request.params.requestFilePath,
+                responseFilePath: request.params.responseFilePath,
+            });
         }
         else {
             const data = await context.getDevToolsData();
@@ -96,7 +107,10 @@ export const getNetworkRequest = defineTool({
                 ? context.resolveCdpRequestId(data.cdpRequestId)
                 : undefined;
             if (reqid) {
-                response.attachNetworkRequest(reqid);
+                response.attachNetworkRequest(reqid, {
+                    requestFilePath: request.params.requestFilePath,
+                    responseFilePath: request.params.responseFilePath,
+                });
             }
             else {
                 response.appendResponseLine(`Nothing is currently selected in the DevTools Network panel.`);

package/build/src/tools/pages.js

@@ -80,10 +80,14 @@ 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,
@@ -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;
+                }
+            });
+        }
+        finally {
+            page.off('dialog', dialogHandler);
+            if (initScriptId) {
+                await page
+                    .removeScriptToEvaluateOnNewDocument(initScriptId)
+                    .catch(error => {
+                    logger(`Failed to remove init script`, error);
+                });
+            }
+        }
         response.setIncludePages(true);
     },
 });

package/build/src/tools/performance.js

@@ -4,9 +4,8 @@
  * 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 { parseRawTraceBuffer, traceResultIsSuccess, } from '../trace-processing/parse.js';
 import { ToolCategory } from './categories.js';
 import { defineTool } from './ToolDefinition.js';
 const filePathSchema = zod
@@ -15,7 +14,7 @@ const filePathSchema = zod
     .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: false,
@@ -23,7 +22,7 @@ export const startTrace = defineTool({
     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.'),
@@ -120,12 +119,7 @@ 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, filePath) {
@@ -152,20 +146,12 @@ async function stopTracingAndAppendOutput(page, response, context, filePath) {
         response.appendResponseLine('The performance trace has been stopped.');
         if (traceResultIsSuccess(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);
     }