chrome-devtools-mcp 0.18.1 → 0.20.0

package/build/src/tools/ToolDefinition.js

@@ -5,9 +5,33 @@
  */
 import { zod } from '../third_party/index.js';
 export function defineTool(definition) {
+    if (typeof definition === 'function') {
+        const factory = definition;
+        return (args) => {
+            return factory(args);
+        };
+    }
     return definition;
 }
+export function definePageTool(definition) {
+    if (typeof definition === 'function') {
+        return (args) => {
+            const tool = definition(args);
+            return {
+                ...tool,
+                pageScoped: true,
+            };
+        };
+    }
+    return {
+        ...definition,
+        pageScoped: true,
+    };
+}
 export const CLOSE_PAGE_ERROR = 'The last open page cannot be closed. It is fine to keep it open.';
+export const pageIdSchema = {
+    pageId: zod.number().optional().describe('Targets a specific page by ID.'),
+};
 export const timeoutSchema = {
     timeout: zod
         .number()
@@ -18,3 +42,31 @@ export const timeoutSchema = {
         return value && value <= 0 ? undefined : value;
     }),
 };
+export function viewportTransform(arg) {
+    if (!arg) {
+        return undefined;
+    }
+    const [dimensions, ...tags] = arg.split(',');
+    const isMobile = tags.includes('mobile');
+    const hasTouch = tags.includes('touch');
+    const isLandscape = tags.includes('landscape');
+    const [width, height, dpr] = dimensions.split('x').map(Number);
+    return {
+        width,
+        height,
+        deviceScaleFactor: dpr,
+        isMobile: isMobile,
+        isLandscape: isLandscape,
+        hasTouch: hasTouch,
+    };
+}
+export function geolocationTransform(arg) {
+    if (!arg) {
+        return undefined;
+    }
+    const [latitude, longitude] = arg.split('x').map(Number);
+    return {
+        latitude,
+        longitude,
+    };
+}

package/build/src/tools/console.js

@@ -5,7 +5,7 @@
  */
 import { zod } from '../third_party/index.js';
 import { ToolCategory } from './categories.js';
-import { defineTool } from './ToolDefinition.js';
+import { definePageTool } from './ToolDefinition.js';
 const FILTERABLE_MESSAGE_TYPES = [
     'log',
     'debug',
@@ -28,7 +28,7 @@ const FILTERABLE_MESSAGE_TYPES = [
     'verbose',
     'issue',
 ];
-export const listConsoleMessages = defineTool({
+export const listConsoleMessages = definePageTool({
     name: 'list_console_messages',
     description: 'List all console messages for the currently selected page since the last navigation.',
     annotations: {
@@ -67,7 +67,7 @@ export const listConsoleMessages = defineTool({
         });
     },
 });
-export const getConsoleMessage = defineTool({
+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}.`,
     annotations: {

package/build/src/tools/emulation.js

@@ -6,13 +6,12 @@
  */
 import { zod, PredefinedNetworkConditions } from '../third_party/index.js';
 import { ToolCategory } from './categories.js';
-import { defineTool } from './ToolDefinition.js';
+import { definePageTool, geolocationTransform, viewportTransform, } from './ToolDefinition.js';
 const throttlingOptions = [
-    'No emulation',
     'Offline',
     ...Object.keys(PredefinedNetworkConditions),
 ];
-export const emulate = defineTool({
+export const emulate = definePageTool({
     name: 'emulate',
     description: `Emulates various features on the selected page.`,
     annotations: {
@@ -23,65 +22,34 @@ export const emulate = defineTool({
         networkConditions: zod
             .enum(throttlingOptions)
             .optional()
-            .describe(`Throttle network. Set to "No emulation" to disable. If omitted, conditions remain unchanged.`),
+            .describe(`Throttle network. Omit to disable throttling.`),
         cpuThrottlingRate: zod
             .number()
             .min(1)
             .max(20)
             .optional()
-            .describe('Represents the CPU slowdown factor. Set the rate to 1 to disable throttling. If omitted, throttling remains unchanged.'),
+            .describe('Represents the CPU slowdown factor. Omit or set the rate to 1 to disable throttling'),
         geolocation: zod
-            .object({
-            latitude: zod
-                .number()
-                .min(-90)
-                .max(90)
-                .describe('Latitude between -90 and 90.'),
-            longitude: zod
-                .number()
-                .min(-180)
-                .max(180)
-                .describe('Longitude between -180 and 180.'),
-        })
-            .nullable()
+            .string()
             .optional()
-            .describe('Geolocation to emulate. Set to null to clear the geolocation override.'),
+            .transform(geolocationTransform)
+            .describe('Geolocation (`<latitude>x<longitude>`) to emulate. Latitude between -90 and 90. Longitude between -180 and 180. Omit clear the geolocation override.'),
         userAgent: zod
             .string()
-            .nullable()
             .optional()
-            .describe('User agent to emulate. Set to null to clear the user agent override.'),
+            .describe('User agent to emulate. Set to empty string 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()
+            .string()
             .optional()
-            .describe('Viewport to emulate. Set to null to reset to the default viewport.'),
+            .transform(viewportTransform)
+            .describe(`Emulate device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to emulate mobile devices. 'landscape' to emulate landscape mode.`),
     },
     handler: async (request, _response, context) => {
-        await context.emulate(request.params);
+        const page = request.page;
+        await context.emulate(request.params, page.pptrPage);
     },
 });

package/build/src/tools/extensions.js

@@ -77,3 +77,20 @@ export const reloadExtension = defineTool({
         response.appendResponseLine('Extension reloaded.');
     },
 });
+export const triggerExtensionAction = defineTool({
+    name: 'trigger_extension_action',
+    description: 'Triggers an action in a Chrome extension.',
+    annotations: {
+        category: ToolCategory.EXTENSIONS,
+        readOnlyHint: false,
+        conditions: [EXTENSIONS_CONDITION],
+    },
+    schema: {
+        id: zod.string().describe('ID of the extension.'),
+    },
+    handler: async (request, response, context) => {
+        const { id } = request.params;
+        await context.triggerExtensionAction(id);
+        response.appendResponseLine(`Extension action triggered. Id: ${id}`);
+    },
+});

package/build/src/tools/input.js

@@ -7,7 +7,7 @@ import { logger } from '../logger.js';
 import { zod } from '../third_party/index.js';
 import { parseKey } from '../utils/keyboard.js';
 import { ToolCategory } from './categories.js';
-import { defineTool } from './ToolDefinition.js';
+import { definePageTool } from './ToolDefinition.js';
 const dblClickSchema = zod
     .boolean()
     .optional()
@@ -26,7 +26,7 @@ function handleActionError(error, uid) {
         cause: error,
     });
 }
-export const click = defineTool({
+export const click = definePageTool({
     name: 'click',
     description: `Clicks on the provided element`,
     annotations: {
@@ -42,7 +42,7 @@ export const click = defineTool({
     },
     handler: async (request, response, context) => {
         const uid = request.params.uid;
-        const handle = await context.getElementByUid(uid);
+        const handle = await request.page.getElementByUid(uid);
         try {
             await context.waitForEventsAfterAction(async () => {
                 await handle.asLocator().click({
@@ -64,7 +64,7 @@ export const click = defineTool({
         }
     },
 });
-export const clickAt = defineTool({
+export const clickAt = definePageTool({
     name: 'click_at',
     description: `Clicks at the provided coordinates`,
     annotations: {
@@ -79,9 +79,9 @@ export const clickAt = defineTool({
         includeSnapshot: includeSnapshotSchema,
     },
     handler: async (request, response, context) => {
-        const page = context.getSelectedPage();
+        const page = request.page;
         await context.waitForEventsAfterAction(async () => {
-            await page.mouse.click(request.params.x, request.params.y, {
+            await page.pptrPage.mouse.click(request.params.x, request.params.y, {
                 clickCount: request.params.dblClick ? 2 : 1,
             });
         });
@@ -93,7 +93,7 @@ export const clickAt = defineTool({
         }
     },
 });
-export const hover = defineTool({
+export const hover = definePageTool({
     name: 'hover',
     description: `Hover over the provided element`,
     annotations: {
@@ -108,7 +108,7 @@ export const hover = defineTool({
     },
     handler: async (request, response, context) => {
         const uid = request.params.uid;
-        const handle = await context.getElementByUid(uid);
+        const handle = await request.page.getElementByUid(uid);
         try {
             await context.waitForEventsAfterAction(async () => {
                 await handle.asLocator().hover();
@@ -163,8 +163,8 @@ async function selectOption(handle, aXNode, value) {
 function hasOptionChildren(aXNode) {
     return aXNode.children.some(child => child.role === 'option');
 }
-async function fillFormElement(uid, value, context) {
-    const handle = await context.getElementByUid(uid);
+async function fillFormElement(uid, value, context, page) {
+    const handle = await page.getElementByUid(uid);
     try {
         const aXNode = context.getAXNodeByUid(uid);
         // We assume that combobox needs to be handled as select if it has
@@ -175,8 +175,7 @@ async function fillFormElement(uid, value, context) {
         else {
             // Increase timeout for longer input values.
             const timeoutPerChar = 10; // ms
-            const fillTimeout = context.getSelectedPage().getDefaultTimeout() +
-                value.length * timeoutPerChar;
+            const fillTimeout = page.pptrPage.getDefaultTimeout() + value.length * timeoutPerChar;
             await handle.asLocator().setTimeout(fillTimeout).fill(value);
         }
     }
@@ -187,7 +186,7 @@ async function fillFormElement(uid, value, context) {
         void handle.dispose();
     }
 }
-export const fill = defineTool({
+export const fill = definePageTool({
     name: 'fill',
     description: `Type text into a input, text area or select an option from a <select> element.`,
     annotations: {
@@ -202,8 +201,9 @@ export const fill = defineTool({
         includeSnapshot: includeSnapshotSchema,
     },
     handler: async (request, response, context) => {
+        const page = request.page;
         await context.waitForEventsAfterAction(async () => {
-            await fillFormElement(request.params.uid, request.params.value, context);
+            await fillFormElement(request.params.uid, request.params.value, context, page);
         });
         response.appendResponseLine(`Successfully filled out the element`);
         if (request.params.includeSnapshot) {
@@ -211,7 +211,7 @@ export const fill = defineTool({
         }
     },
 });
-export const typeText = defineTool({
+export const typeText = definePageTool({
     name: 'type_text',
     description: `Type text using keyboard into a previously focused input`,
     annotations: {
@@ -223,17 +223,17 @@ export const typeText = defineTool({
         submitKey: submitKeySchema,
     },
     handler: async (request, response, context) => {
+        const page = request.page;
         await context.waitForEventsAfterAction(async () => {
-            const page = context.getSelectedPage();
-            await page.keyboard.type(request.params.text);
+            await page.pptrPage.keyboard.type(request.params.text);
             if (request.params.submitKey) {
-                await page.keyboard.press(request.params.submitKey);
+                await page.pptrPage.keyboard.press(request.params.submitKey);
             }
         });
         response.appendResponseLine(`Typed text "${request.params.text}${request.params.submitKey ? ` + ${request.params.submitKey}` : ''}"`);
     },
 });
-export const drag = defineTool({
+export const drag = definePageTool({
     name: 'drag',
     description: `Drag an element onto another element`,
     annotations: {
@@ -246,8 +246,8 @@ export const drag = defineTool({
         includeSnapshot: includeSnapshotSchema,
     },
     handler: async (request, response, context) => {
-        const fromHandle = await context.getElementByUid(request.params.from_uid);
-        const toHandle = await context.getElementByUid(request.params.to_uid);
+        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 fromHandle.drag(toHandle);
@@ -265,7 +265,7 @@ export const drag = defineTool({
         }
     },
 });
-export const fillForm = defineTool({
+export const fillForm = definePageTool({
     name: 'fill_form',
     description: `Fill out multiple form elements at once`,
     annotations: {
@@ -282,9 +282,10 @@ export const fillForm = defineTool({
         includeSnapshot: includeSnapshotSchema,
     },
     handler: async (request, response, context) => {
+        const page = request.page;
         for (const element of request.params.elements) {
             await context.waitForEventsAfterAction(async () => {
-                await fillFormElement(element.uid, element.value, context);
+                await fillFormElement(element.uid, element.value, context, page);
             });
         }
         response.appendResponseLine(`Successfully filled out the form`);
@@ -293,7 +294,7 @@ export const fillForm = defineTool({
         }
     },
 });
-export const uploadFile = defineTool({
+export const uploadFile = definePageTool({
     name: 'upload_file',
     description: 'Upload a file through a provided element.',
     annotations: {
@@ -307,9 +308,9 @@ export const uploadFile = defineTool({
         filePath: zod.string().describe('The local path of the file to upload'),
         includeSnapshot: includeSnapshotSchema,
     },
-    handler: async (request, response, context) => {
+    handler: async (request, response) => {
         const { uid, filePath } = request.params;
-        const handle = (await context.getElementByUid(uid));
+        const handle = (await request.page.getElementByUid(uid));
         try {
             try {
                 await handle.uploadFile(filePath);
@@ -319,9 +320,8 @@ export const uploadFile = defineTool({
                 // a type=file element. In this case, we want to default to
                 // Page.waitForFileChooser() and upload the file this way.
                 try {
-                    const page = context.getSelectedPage();
                     const [fileChooser] = await Promise.all([
-                        page.waitForFileChooser({ timeout: 3000 }),
+                        request.page.pptrPage.waitForFileChooser({ timeout: 3000 }),
                         handle.asLocator().click(),
                     ]);
                     await fileChooser.accept([filePath]);
@@ -340,7 +340,7 @@ export const uploadFile = defineTool({
         }
     },
 });
-export const pressKey = defineTool({
+export const pressKey = definePageTool({
     name: 'press_key',
     description: `Press a key or key combination. Use this when other input methods like fill() cannot be used (e.g., keyboard shortcuts, navigation keys, or special key combinations).`,
     annotations: {
@@ -354,16 +354,16 @@ export const pressKey = defineTool({
         includeSnapshot: includeSnapshotSchema,
     },
     handler: async (request, response, context) => {
-        const page = context.getSelectedPage();
+        const page = request.page;
         const tokens = parseKey(request.params.key);
         const [key, ...modifiers] = tokens;
         await context.waitForEventsAfterAction(async () => {
             for (const modifier of modifiers) {
-                await page.keyboard.down(modifier);
+                await page.pptrPage.keyboard.down(modifier);
             }
-            await page.keyboard.press(key);
+            await page.pptrPage.keyboard.press(key);
             for (const modifier of modifiers.toReversed()) {
-                await page.keyboard.up(modifier);
+                await page.pptrPage.keyboard.up(modifier);
             }
         });
         response.appendResponseLine(`Successfully pressed key: ${request.params.key}`);

package/build/src/tools/lighthouse.js

@@ -0,0 +1,123 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import path from 'node:path';
+import { snapshot, navigation, generateReport, zod, } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
+import { startTrace } from './performance.js';
+import { definePageTool } from './ToolDefinition.js';
+export const lighthouseAudit = definePageTool({
+    name: 'lighthouse_audit',
+    description: `Get Lighthouse score and reports for accessibility, SEO and best practices. This excludes performance. For performance audits, run ${startTrace.name}`,
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        readOnlyHint: true,
+    },
+    schema: {
+        mode: zod
+            .enum(['navigation', 'snapshot'])
+            .default('navigation')
+            .describe('"navigation" reloads & audits. "snapshot" analyzes current state.'),
+        device: zod
+            .enum(['desktop', 'mobile'])
+            .default('desktop')
+            .describe('Device to emulate.'),
+        outputDirPath: zod
+            .string()
+            .optional()
+            .describe('Directory for reports. If omitted, uses temporary files.'),
+    },
+    handler: async (request, response, context) => {
+        const page = request.page;
+        const categories = ['accessibility', 'seo', 'best-practices'];
+        const formats = ['json', 'html'];
+        const { mode = 'navigation', device = 'desktop', outputDirPath, } = request.params;
+        const flags = {
+            onlyCategories: categories,
+            output: formats,
+            // Default 30 second timeout for page load.
+            maxWaitForLoad: 30_000,
+        };
+        if (device === 'desktop') {
+            flags.formFactor = 'desktop';
+            flags.screenEmulation = {
+                mobile: false,
+                width: 1350,
+                height: 940,
+                deviceScaleFactor: 1,
+                disabled: false,
+            };
+        }
+        else {
+            flags.formFactor = 'mobile';
+            flags.screenEmulation = {
+                mobile: true,
+                width: 412,
+                height: 823,
+                deviceScaleFactor: 1.75,
+                disabled: false,
+            };
+        }
+        let result;
+        try {
+            if (mode === 'navigation') {
+                result = await navigation(page.pptrPage, page.pptrPage.url(), {
+                    flags,
+                });
+            }
+            else {
+                result = await snapshot(page.pptrPage, {
+                    flags,
+                });
+            }
+            if (!result) {
+                throw new Error('Lighthouse audit failed.');
+            }
+        }
+        finally {
+            await context.restoreEmulation(page);
+        }
+        const lhr = result.lhr;
+        const reportPaths = [];
+        const encoder = new TextEncoder();
+        for (const format of formats) {
+            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);
+                reportPaths.push(filename);
+            }
+            else {
+                const { filepath } = await context.saveTemporaryFile(data, `report.${format}`);
+                reportPaths.push(filepath);
+            }
+        }
+        const categoryScores = Object.values(lhr.categories).map(c => ({
+            id: c.id,
+            title: c.title,
+            score: c.score,
+        }));
+        const failedAudits = Object.values(lhr.audits).filter(a => a.score !== null && a.score < 1).length;
+        const passedAudits = Object.values(lhr.audits).filter(a => a.score === 1).length;
+        const output = {
+            summary: {
+                mode,
+                device,
+                url: lhr.mainDocumentUrl,
+                scores: categoryScores,
+                audits: {
+                    failed: failedAudits,
+                    passed: passedAudits,
+                },
+                timing: {
+                    total: lhr.timing.total,
+                },
+            },
+            reports: reportPaths,
+        };
+        response.attachLighthouseResult(output);
+    },
+});

package/build/src/tools/memory.js

@@ -5,8 +5,8 @@
  */
 import { zod } from '../third_party/index.js';
 import { ToolCategory } from './categories.js';
-import { defineTool } from './ToolDefinition.js';
-export const takeMemorySnapshot = defineTool({
+import { definePageTool } from './ToolDefinition.js';
+export const takeMemorySnapshot = definePageTool({
     name: 'take_memory_snapshot',
     description: `Capture a memory heapsnapshot of the currently selected page to memory leak debugging`,
     annotations: {
@@ -18,9 +18,9 @@ export const takeMemorySnapshot = defineTool({
             .string()
             .describe('A path to a .heapsnapshot file to save the heapsnapshot to.'),
     },
-    handler: async (request, response, context) => {
-        const page = context.getSelectedPage();
-        await page.captureHeapSnapshot({
+    handler: async (request, response, _context) => {
+        const page = request.page;
+        await page.pptrPage.captureHeapSnapshot({
             path: request.params.filePath,
         });
         response.appendResponseLine(`Heap snapshot saved to ${request.params.filePath}`);

package/build/src/tools/network.js

@@ -5,7 +5,7 @@
  */
 import { zod } from '../third_party/index.js';
 import { ToolCategory } from './categories.js';
-import { defineTool } from './ToolDefinition.js';
+import { definePageTool } from './ToolDefinition.js';
 const FILTERABLE_RESOURCE_TYPES = [
     'document',
     'stylesheet',
@@ -27,7 +27,7 @@ const FILTERABLE_RESOURCE_TYPES = [
     'fedcm',
     'other',
 ];
-export const listNetworkRequests = defineTool({
+export const listNetworkRequests = definePageTool({
     name: 'list_network_requests',
     description: `List all requests for the currently selected page since the last navigation.`,
     annotations: {
@@ -58,10 +58,10 @@ export const listNetworkRequests = defineTool({
             .describe('Set to true to return the preserved requests over the last 3 navigations.'),
     },
     handler: async (request, response, context) => {
-        const data = await context.getDevToolsData();
+        const data = await context.getDevToolsData(request.page);
         response.attachDevToolsData(data);
         const reqid = data?.cdpRequestId
-            ? context.resolveCdpRequestId(data.cdpRequestId)
+            ? context.resolveCdpRequestId(request.page, data.cdpRequestId)
             : undefined;
         response.setIncludeNetworkRequests(true, {
             pageSize: request.params.pageSize,
@@ -72,7 +72,7 @@ export const listNetworkRequests = defineTool({
         });
     },
 });
-export const getNetworkRequest = defineTool({
+export const getNetworkRequest = definePageTool({
     name: 'get_network_request',
     description: `Gets a network request by an optional reqid, if omitted returns the currently selected request in the DevTools Network panel.`,
     annotations: {
@@ -101,10 +101,10 @@ export const getNetworkRequest = defineTool({
             });
         }
         else {
-            const data = await context.getDevToolsData();
+            const data = await context.getDevToolsData(request.page);
             response.attachDevToolsData(data);
             const reqid = data?.cdpRequestId
-                ? context.resolveCdpRequestId(data.cdpRequestId)
+                ? context.resolveCdpRequestId(request.page, data.cdpRequestId)
                 : undefined;
             if (reqid) {
                 response.attachNetworkRequest(reqid, {