chrome-devtools-mcp 0.21.0 → 0.22.0

package/build/src/tools/categories.js

@@ -13,6 +13,7 @@ export var ToolCategory;
     ToolCategory["DEBUGGING"] = "debugging";
     ToolCategory["EXTENSIONS"] = "extensions";
     ToolCategory["IN_PAGE"] = "in-page";
+    ToolCategory["MEMORY"] = "memory";
 })(ToolCategory || (ToolCategory = {}));
 export const labels = {
     [ToolCategory.INPUT]: 'Input automation',
@@ -23,4 +24,6 @@ export const labels = {
     [ToolCategory.DEBUGGING]: 'Debugging',
     [ToolCategory.EXTENSIONS]: 'Extensions',
     [ToolCategory.IN_PAGE]: 'In-page tools',
+    [ToolCategory.MEMORY]: 'Memory',
 };
+export const OFF_BY_DEFAULT_CATEGORIES = [ToolCategory.EXTENSIONS];

package/build/src/tools/console.js

@@ -28,48 +28,51 @@ const FILTERABLE_MESSAGE_TYPES = [
     'verbose',
     'issue',
 ];
-export const listConsoleMessages = definePageTool({
-    name: 'list_console_messages',
-    description: 'List all console messages for the currently selected page since the last navigation.',
-    annotations: {
-        category: ToolCategory.DEBUGGING,
-        readOnlyHint: true,
-    },
-    schema: {
-        pageSize: zod
-            .number()
-            .int()
-            .positive()
-            .optional()
-            .describe('Maximum number of messages to return. When omitted, returns all requests.'),
-        pageIdx: zod
-            .number()
-            .int()
-            .min(0)
-            .optional()
-            .describe('Page number to return (0-based). When omitted, returns the first page.'),
-        types: zod
-            .array(zod.enum(FILTERABLE_MESSAGE_TYPES))
-            .optional()
-            .describe('Filter messages to only return messages of the specified resource types. When omitted or empty, returns all messages.'),
-        includePreservedMessages: zod
-            .boolean()
-            .default(false)
-            .optional()
-            .describe('Set to true to return the preserved messages over the last 3 navigations.'),
-    },
-    handler: async (request, response) => {
-        response.setIncludeConsoleData(true, {
-            pageSize: request.params.pageSize,
-            pageIdx: request.params.pageIdx,
-            types: request.params.types,
-            includePreservedMessages: request.params.includePreservedMessages,
-        });
-    },
+const LIST_CONSOLE_MESSAGES_TOOL_NAME = 'list_console_messages';
+export const listConsoleMessages = definePageTool(cliArgs => {
+    return {
+        name: LIST_CONSOLE_MESSAGES_TOOL_NAME,
+        description: `List all console messages for the currently selected page since the last navigation.${cliArgs?.categoryExtensions ? ' This includes console messages originating from extensions content scripts.' : ''}`,
+        annotations: {
+            category: ToolCategory.DEBUGGING,
+            readOnlyHint: true,
+        },
+        schema: {
+            pageSize: zod
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe('Maximum number of messages to return. When omitted, returns all messages.'),
+            pageIdx: zod
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe('Page number to return (0-based). When omitted, returns the first page.'),
+            types: zod
+                .array(zod.enum(FILTERABLE_MESSAGE_TYPES))
+                .optional()
+                .describe('Filter messages to only return messages of the specified resource types. When omitted or empty, returns all messages.'),
+            includePreservedMessages: zod
+                .boolean()
+                .default(false)
+                .optional()
+                .describe('Set to true to return the preserved messages over the last 3 navigations.'),
+        },
+        handler: async (request, response) => {
+            response.setIncludeConsoleData(true, {
+                pageSize: request.params.pageSize,
+                pageIdx: request.params.pageIdx,
+                types: request.params.types,
+                includePreservedMessages: request.params.includePreservedMessages,
+            });
+        },
+    };
 });
 export const getConsoleMessage = definePageTool({
     name: 'get_console_message',
-    description: `Gets a console message by its ID. You can get all messages by calling ${listConsoleMessages.name}.`,
+    description: `Gets a console message by its ID. You can get all messages by calling ${LIST_CONSOLE_MESSAGES_TOOL_NAME}.`,
     annotations: {
         category: ToolCategory.DEBUGGING,
         readOnlyHint: true,

package/build/src/tools/emulation.js

@@ -33,7 +33,7 @@ export const emulate = definePageTool({
             .string()
             .optional()
             .transform(geolocationTransform)
-            .describe('Geolocation (`<latitude>x<longitude>`) to emulate. Latitude between -90 and 90. Longitude between -180 and 180. Omit clear the geolocation override.'),
+            .describe('Geolocation (`<latitude>x<longitude>`) to emulate. Latitude between -90 and 90. Longitude between -180 and 180. Omit to clear the geolocation override.'),
         userAgent: zod
             .string()
             .optional()

package/build/src/tools/extensions.js

@@ -6,14 +6,12 @@
 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
@@ -32,7 +30,6 @@ export const uninstallExtension = defineTool({
     annotations: {
         category: ToolCategory.EXTENSIONS,
         readOnlyHint: false,
-        conditions: [EXTENSIONS_CONDITION],
     },
     schema: {
         id: zod.string().describe('ID of the extension to uninstall.'),
@@ -45,11 +42,10 @@ export const uninstallExtension = defineTool({
 });
 export const listExtensions = defineTool({
     name: 'list_extensions',
-    description: 'Lists all extensions via this server, including their name, ID, version, and enabled status.',
+    description: 'Lists all the Chrome extensions installed in the browser. This includes their name, ID, version, and enabled status.',
     annotations: {
         category: ToolCategory.EXTENSIONS,
         readOnlyHint: true,
-        conditions: [EXTENSIONS_CONDITION],
     },
     schema: {},
     handler: async (_request, response, _context) => {
@@ -62,14 +58,13 @@ export const reloadExtension = defineTool({
     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);
+        const extension = await context.getExtension(id);
         if (!extension) {
             throw new Error(`Extension with ID ${id} not found.`);
         }
@@ -79,18 +74,17 @@ export const reloadExtension = defineTool({
 });
 export const triggerExtensionAction = defineTool({
     name: 'trigger_extension_action',
-    description: 'Triggers an action in a Chrome extension.',
+    description: 'Triggers the default action of an extension by its ID.',
     annotations: {
         category: ToolCategory.EXTENSIONS,
         readOnlyHint: false,
-        conditions: [EXTENSIONS_CONDITION],
     },
     schema: {
-        id: zod.string().describe('ID of the extension.'),
+        id: zod.string().describe('ID of the extension to trigger the action for.'),
     },
     handler: async (request, response, context) => {
         const { id } = request.params;
         await context.triggerExtensionAction(id);
-        response.appendResponseLine(`Extension action triggered. Id: ${id}`);
+        response.appendResponseLine(`Extension action triggered for ID ${id}`);
     },
 });

package/build/src/tools/inPage.js

@@ -3,7 +3,7 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { zod, ajv } from '../third_party/index.js';
+import { zod, ajv, } from '../third_party/index.js';
 import { ToolCategory } from './categories.js';
 import { definePageTool } from './ToolDefinition.js';
 export const listInPageTools = definePageTool({
@@ -40,8 +40,7 @@ export const executeInPageTool = definePageTool({
             .optional()
             .describe('The JSON-stringified parameters to pass to the tool'),
     },
-    handler: async (request, response, context) => {
-        const page = context.getSelectedMcpPage();
+    handler: async (request, response) => {
         const toolName = request.params.toolName;
         let params = {};
         if (request.params.params) {
@@ -59,7 +58,20 @@ export const executeInPageTool = definePageTool({
                 throw new Error(`Failed to parse params as JSON: ${errorMessage}`);
             }
         }
-        const toolGroup = context.getInPageTools();
+        // Creates array of ElementHandles from the UIDs in the params.
+        // We do not replace the uids with the ElementsHandles yet, because
+        // the `evaluate` function only turns them into DOM elements if they
+        // are passed as non-nested arguments.
+        const handles = [];
+        for (const value of Object.values(params)) {
+            if (value instanceof Object &&
+                'uid' in value &&
+                typeof value.uid === 'string' &&
+                Object.keys(value).length === 1) {
+                handles.push(await request.page.getElementByUid(value.uid));
+            }
+        }
+        const toolGroup = request.page.getInPageTools();
         const tool = toolGroup?.tools.find(t => t.name === toolName);
         if (!tool) {
             throw new Error(`Tool ${toolName} not found`);
@@ -70,7 +82,16 @@ export const executeInPageTool = definePageTool({
         if (!valid) {
             throw new Error(`Invalid parameters for tool ${toolName}: ${ajvInstance.errorsText(validate.errors)}`);
         }
-        const result = await page.pptrPage.evaluate(async (name, args) => {
+        const result = await request.page.pptrPage.evaluate(async (name, args, ...elements) => {
+            // Replace the UIDs with DOM elements.
+            for (const [key, value] of Object.entries(args)) {
+                if (value instanceof Object &&
+                    'uid' in value &&
+                    typeof value.uid === 'string' &&
+                    Object.keys(value).length === 1) {
+                    args[key] = elements.shift();
+                }
+            }
             if (!window.__dtmcp?.executeTool) {
                 throw new Error('No tools found on the page');
             }
@@ -78,7 +99,7 @@ export const executeInPageTool = definePageTool({
             return {
                 result: toolResult,
             };
-        }, toolName, params);
+        }, toolName, params, ...handles);
         response.appendResponseLine(JSON.stringify(result, null, 2));
     },
 });

package/build/src/tools/input.js

@@ -40,11 +40,11 @@ export const click = definePageTool({
         dblClick: dblClickSchema,
         includeSnapshot: includeSnapshotSchema,
     },
-    handler: async (request, response, context) => {
+    handler: async (request, response) => {
         const uid = request.params.uid;
         const handle = await request.page.getElementByUid(uid);
         try {
-            await context.waitForEventsAfterAction(async () => {
+            await request.page.waitForEventsAfterAction(async () => {
                 await handle.asLocator().click({
                     count: request.params.dblClick ? 2 : 1,
                 });
@@ -78,9 +78,9 @@ export const clickAt = definePageTool({
         dblClick: dblClickSchema,
         includeSnapshot: includeSnapshotSchema,
     },
-    handler: async (request, response, context) => {
+    handler: async (request, response) => {
         const page = request.page;
-        await context.waitForEventsAfterAction(async () => {
+        await page.waitForEventsAfterAction(async () => {
             await page.pptrPage.mouse.click(request.params.x, request.params.y, {
                 clickCount: request.params.dblClick ? 2 : 1,
             });
@@ -106,11 +106,11 @@ export const hover = definePageTool({
             .describe('The uid of an element on the page from the page content snapshot'),
         includeSnapshot: includeSnapshotSchema,
     },
-    handler: async (request, response, context) => {
+    handler: async (request, response) => {
         const uid = request.params.uid;
         const handle = await request.page.getElementByUid(uid);
         try {
-            await context.waitForEventsAfterAction(async () => {
+            await request.page.waitForEventsAfterAction(async () => {
                 await handle.asLocator().hover();
             });
             response.appendResponseLine(`Successfully hovered over the element`);
@@ -186,10 +186,9 @@ async function fillFormElement(uid, value, context, page) {
         void handle.dispose();
     }
 }
-// here
 export const fill = definePageTool({
     name: 'fill',
-    description: `Type text into a input, text area or select an option from a <select> element.`,
+    description: `Type text into an input, text area or select an option from a <select> element.`,
     annotations: {
         category: ToolCategory.INPUT,
         readOnlyHint: false,
@@ -203,7 +202,7 @@ export const fill = definePageTool({
     },
     handler: async (request, response, context) => {
         const page = request.page;
-        await context.waitForEventsAfterAction(async () => {
+        await page.waitForEventsAfterAction(async () => {
             await fillFormElement(request.params.uid, request.params.value, context, page);
         });
         response.appendResponseLine(`Successfully filled out the element`);
@@ -223,9 +222,9 @@ export const typeText = definePageTool({
         text: zod.string().describe('The text to type'),
         submitKey: submitKeySchema,
     },
-    handler: async (request, response, context) => {
+    handler: async (request, response) => {
         const page = request.page;
-        await context.waitForEventsAfterAction(async () => {
+        await page.waitForEventsAfterAction(async () => {
             await page.pptrPage.keyboard.type(request.params.text);
             if (request.params.submitKey) {
                 await page.pptrPage.keyboard.press(request.params.submitKey);
@@ -246,11 +245,11 @@ export const drag = definePageTool({
         to_uid: zod.string().describe('The uid of the element to drop into'),
         includeSnapshot: includeSnapshotSchema,
     },
-    handler: async (request, response, context) => {
+    handler: async (request, response) => {
         const fromHandle = await request.page.getElementByUid(request.params.from_uid);
         const toHandle = await request.page.getElementByUid(request.params.to_uid);
         try {
-            await context.waitForEventsAfterAction(async () => {
+            await request.page.waitForEventsAfterAction(async () => {
                 await fromHandle.drag(toHandle);
                 await new Promise(resolve => setTimeout(resolve, 50));
                 await toHandle.drop(fromHandle);
@@ -287,7 +286,7 @@ export const fillForm = definePageTool({
     handler: async (request, response, context) => {
         const page = request.page;
         for (const element of request.params.elements) {
-            await context.waitForEventsAfterAction(async () => {
+            await page.waitForEventsAfterAction(async () => {
                 await fillFormElement(element.uid, element.value, context, page);
             });
         }
@@ -356,11 +355,11 @@ export const pressKey = definePageTool({
             .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) => {
+    handler: async (request, response) => {
         const page = request.page;
         const tokens = parseKey(request.params.key);
         const [key, ...modifiers] = tokens;
-        await context.waitForEventsAfterAction(async () => {
+        await page.waitForEventsAfterAction(async () => {
             for (const modifier of modifiers) {
                 await page.pptrPage.keyboard.down(modifier);
             }

package/build/src/tools/lighthouse.js

@@ -86,8 +86,8 @@ export const lighthouseAudit = definePageTool({
             const report = generateReport(lhr, format);
             const data = encoder.encode(report);
             if (outputDirPath) {
-                const reportPath = path.join(outputDirPath, `report.${format}`);
-                const { filename } = await context.saveFile(data, reportPath);
+                const reportPath = path.join(outputDirPath, `report`);
+                const { filename } = await context.saveFile(data, reportPath, `.${format}`);
                 reportPaths.push(filename);
             }
             else {

package/build/src/tools/memory.js

@@ -4,13 +4,14 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { zod } from '../third_party/index.js';
+import { ensureExtension } from '../utils/files.js';
 import { ToolCategory } from './categories.js';
-import { definePageTool } from './ToolDefinition.js';
+import { definePageTool, defineTool } from './ToolDefinition.js';
 export const takeMemorySnapshot = definePageTool({
     name: 'take_memory_snapshot',
     description: `Capture a heap snapshot of the currently selected page. Use to analyze the memory distribution of JavaScript objects and debug memory leaks.`,
     annotations: {
-        category: ToolCategory.PERFORMANCE,
+        category: ToolCategory.MEMORY,
         readOnlyHint: false,
     },
     schema: {
@@ -21,8 +22,52 @@ export const takeMemorySnapshot = definePageTool({
     handler: async (request, response, _context) => {
         const page = request.page;
         await page.pptrPage.captureHeapSnapshot({
-            path: request.params.filePath,
+            path: ensureExtension(request.params.filePath, '.heapsnapshot'),
         });
         response.appendResponseLine(`Heap snapshot saved to ${request.params.filePath}`);
     },
 });
+export const exploreMemorySnapshot = defineTool({
+    name: 'load_memory_snapshot',
+    description: 'Loads a memory heapsnapshot and returns snapshot summary stats.',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: true,
+        conditions: ['experimentalMemory'],
+    },
+    schema: {
+        filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+    },
+    handler: async (request, response, context) => {
+        const stats = await context.getHeapSnapshotStats(request.params.filePath);
+        const staticData = await context.getHeapSnapshotStaticData(request.params.filePath);
+        response.setHeapSnapshotStats(stats, staticData);
+    },
+});
+export const getMemorySnapshotDetails = defineTool({
+    name: 'get_memory_snapshot_details',
+    description: 'Loads a memory heapsnapshot and returns all available information including statistics, static data, and aggregated node information. Supports pagination for aggregates.',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: true,
+        conditions: ['experimentalMemory'],
+    },
+    schema: {
+        filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+        pageIdx: zod
+            .number()
+            .optional()
+            .describe('The page index for pagination of aggregates.'),
+        pageSize: zod
+            .number()
+            .optional()
+            .describe('The page size for pagination of aggregates.'),
+    },
+    handler: async (request, response, context) => {
+        const aggregates = await context.getHeapSnapshotAggregates(request.params.filePath);
+        response.setHeapSnapshotAggregates(aggregates, {
+            pageIdx: request.params.pageIdx,
+            pageSize: request.params.pageSize,
+        });
+    },
+});

package/build/src/tools/network.js

@@ -87,11 +87,11 @@ export const getNetworkRequest = definePageTool({
         requestFilePath: zod
             .string()
             .optional()
-            .describe('The absolute or relative path to save the request body to. If omitted, the body is returned inline.'),
+            .describe('The absolute or relative path to a .network-request file 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.'),
+            .describe('The absolute or relative path to a .network-response file to save the response body to. If omitted, the body is returned inline.'),
     },
     handler: async (request, response, context) => {
         if (request.params.reqid) {

package/build/src/tools/pages.js

@@ -10,7 +10,7 @@ import { CLOSE_PAGE_ERROR, definePageTool, defineTool, timeoutSchema, } from './
 export const listPages = defineTool(args => {
     return {
         name: 'list_pages',
-        description: `Get a list of pages ${args?.categoryExtensions ? 'including extension service workers' : ''} open in the browser.`,
+        description: `Get a list of pages${args?.categoryExtensions ? ' including extension service workers' : ''} open in the browser.`,
         annotations: {
             category: ToolCategory.NAVIGATION,
             readOnlyHint: true,
@@ -19,6 +19,7 @@ export const listPages = defineTool(args => {
         handler: async (_request, response) => {
             response.setIncludePages(true);
             response.setListInPageTools();
+            response.setListWebMcpTools();
         },
     };
 });
@@ -43,6 +44,7 @@ export const selectPage = defineTool({
         context.selectPage(page);
         response.setIncludePages(true);
         response.setListInPageTools();
+        response.setListWebMcpTools();
         if (request.params.bringToFront) {
             await page.pptrPage.bringToFront();
         }
@@ -99,7 +101,7 @@ export const newPage = defineTool({
     },
     handler: async (request, response, context) => {
         const page = await context.newPage(request.params.background, request.params.isolatedContext);
-        await context.waitForEventsAfterAction(async () => {
+        await page.waitForEventsAfterAction(async () => {
             await page.pptrPage.goto(request.params.url, {
                 timeout: request.params.timeout,
             });
@@ -135,7 +137,7 @@ export const navigatePage = definePageTool({
             .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) => {
+    handler: async (request, response) => {
         const page = request.page;
         const options = {
             timeout: request.params.timeout,
@@ -168,7 +170,7 @@ export const navigatePage = definePageTool({
         }
         page.pptrPage.on('dialog', dialogHandler);
         try {
-            await context.waitForEventsAfterAction(async () => {
+            await page.waitForEventsAfterAction(async () => {
                 switch (request.params.type) {
                     case 'url':
                         if (!request.params.url) {
@@ -179,7 +181,7 @@ export const navigatePage = definePageTool({
                             response.appendResponseLine(`Successfully navigated to ${request.params.url}.`);
                         }
                         catch (error) {
-                            response.appendResponseLine(`Unable to navigate in the  selected page: ${error.message}.`);
+                            response.appendResponseLine(`Unable to navigate in the selected page: ${error.message}.`);
                         }
                         break;
                     case 'back':
@@ -227,6 +229,7 @@ export const navigatePage = definePageTool({
         }
         response.setIncludePages(true);
         response.setListInPageTools();
+        response.setListWebMcpTools();
     },
 });
 export const resizePage = definePageTool({

package/build/src/tools/performance.js

@@ -142,7 +142,7 @@ async function stopTracingAndAppendOutput(page, response, context, filePath) {
                     });
                 });
             }
-            const file = await context.saveFile(dataToWrite, filePath);
+            const file = await context.saveFile(dataToWrite, filePath, filePath.endsWith('.gz') ? '.json.gz' : '.json');
             response.appendResponseLine(`The raw trace data was saved to ${file.filename}.`);
         }
         const result = await parseRawTraceBuffer(traceEventsBuffer);

package/build/src/tools/screencast.js

@@ -7,6 +7,7 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { zod } from '../third_party/index.js';
+import { ensureExtension } from '../utils/files.js';
 import { ToolCategory } from './categories.js';
 import { definePageTool } from './ToolDefinition.js';
 async function generateTempFilePath() {
@@ -33,7 +34,7 @@ export const startScreencast = definePageTool({
             return;
         }
         const filePath = request.params.path ?? (await generateTempFilePath());
-        const resolvedPath = path.resolve(filePath);
+        const resolvedPath = ensureExtension(path.resolve(filePath), '.mp4');
         const page = request.page;
         let recorder;
         try {

package/build/src/tools/screenshot.js

@@ -28,7 +28,7 @@ export const screenshot = definePageTool({
         uid: zod
             .string()
             .optional()
-            .describe('The uid of an element on the page from the page content snapshot. If omitted takes a pages screenshot.'),
+            .describe('The uid of an element on the page from the page content snapshot. If omitted, takes a page screenshot.'),
         fullPage: zod
             .boolean()
             .optional()
@@ -67,8 +67,8 @@ export const screenshot = definePageTool({
             response.appendResponseLine("Took a screenshot of the current page's viewport.");
         }
         if (request.params.filePath) {
-            const file = await context.saveFile(screenshot, request.params.filePath);
-            response.appendResponseLine(`Saved screenshot to ${file.filename}.`);
+            const result = await context.saveFile(screenshot, request.params.filePath, `.${format}`);
+            response.appendResponseLine(`Saved screenshot to ${result.filename}.`);
         }
         else if (screenshot.length >= 2_000_000) {
             const { filepath } = await context.saveTemporaryFile(screenshot, `screenshot.${request.params.format}`);