@mcp-b/chrome-devtools-mcp 2.0.13 → 2.2.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/categories.js

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

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

@@ -2,16 +2,16 @@
  * @license
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
+ *
  */
 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: {
@@ -22,66 +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()
+            .optional()
+            .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
+            .string()
+            .optional()
+            .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) => {
-        const page = context.getSelectedPage();
-        const { networkConditions, cpuThrottlingRate, geolocation } = request.params;
-        if (networkConditions) {
-            if (networkConditions === 'No emulation') {
-                await page.emulateNetworkConditions(null);
-                context.setNetworkConditions(null);
-            }
-            else if (networkConditions === 'Offline') {
-                await page.emulateNetworkConditions({
-                    offline: true,
-                    download: 0,
-                    upload: 0,
-                    latency: 0,
-                });
-                context.setNetworkConditions('Offline');
-            }
-            else if (networkConditions in PredefinedNetworkConditions) {
-                const networkCondition = PredefinedNetworkConditions[networkConditions];
-                await page.emulateNetworkConditions(networkCondition);
-                context.setNetworkConditions(networkConditions);
-            }
-        }
-        if (cpuThrottlingRate) {
-            await page.emulateCPUThrottling(cpuThrottlingRate);
-            context.setCpuThrottlingRate(cpuThrottlingRate);
-        }
-        if (geolocation !== undefined) {
-            if (geolocation === null) {
-                await page.setGeolocation({ latitude: 0, longitude: 0 });
-                context.setGeolocation(null);
-            }
-            else {
-                await page.setGeolocation(geolocation);
-                context.setGeolocation(geolocation);
-            }
-        }
+        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

@@ -3,13 +3,32 @@
  * 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';
-import { defineTool } from './ToolDefinition.js';
-export const click = defineTool({
+import { definePageTool } from './ToolDefinition.js';
+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.');
+const submitKeySchema = zod
+    .string()
+    .optional()
+    .describe('Optional key to press after typing. E.g., "Enter", "Tab", "Escape"');
+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 = definePageTool({
     name: 'click',
-    description: `Clicks on the provided element. IMPORTANT: Always call take_snapshot first to get a fresh uid - UIDs expire when the page changes.`,
+    description: `Clicks on the provided element`,
     annotations: {
         category: ToolCategory.INPUT,
         readOnlyHint: false,
@@ -18,14 +37,12 @@ export const click = defineTool({
         uid: zod
             .string()
             .describe('The uid of an element on the page from the page content snapshot'),
-        dblClick: zod
-            .boolean()
-            .optional()
-            .describe('Set to true for double clicks. Default is false.'),
+        dblClick: dblClickSchema,
+        includeSnapshot: includeSnapshotSchema,
     },
     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({
@@ -35,14 +52,48 @@ 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();
         }
     },
 });
-export const hover = defineTool({
+export const clickAt = definePageTool({
+    name: 'click_at',
+    description: `Clicks at the provided coordinates`,
+    annotations: {
+        category: ToolCategory.INPUT,
+        readOnlyHint: false,
+        conditions: ['computerVision'],
+    },
+    schema: {
+        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 = request.page;
+        await context.waitForEventsAfterAction(async () => {
+            await page.pptrPage.mouse.click(request.params.x, request.params.y, {
+                clickCount: request.params.dblClick ? 2 : 1,
+            });
+        });
+        response.appendResponseLine(request.params.dblClick
+            ? `Successfully double clicked at the coordinates`
+            : `Successfully clicked at the coordinates`);
+        if (request.params.includeSnapshot) {
+            response.includeSnapshot();
+        }
+    },
+});
+export const hover = definePageTool({
     name: 'hover',
     description: `Hover over the provided element`,
     annotations: {
@@ -53,16 +104,22 @@ 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;
-        const handle = await context.getElementByUid(uid);
+        const handle = await request.page.getElementByUid(uid);
         try {
             await context.waitForEventsAfterAction(async () => {
                 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();
@@ -106,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
@@ -116,14 +173,20 @@ 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 = page.pptrPage.getDefaultTimeout() + value.length * timeoutPerChar;
+            await handle.asLocator().setTimeout(fillTimeout).fill(value);
         }
     }
+    catch (error) {
+        handleActionError(error, uid);
+    }
     finally {
         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: {
@@ -135,16 +198,42 @@ 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) => {
+        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`);
-        response.includeSnapshot();
+        if (request.params.includeSnapshot) {
+            response.includeSnapshot();
+        }
+    },
+});
+export const typeText = definePageTool({
+    name: 'type_text',
+    description: `Type text using keyboard into a previously focused input`,
+    annotations: {
+        category: ToolCategory.INPUT,
+        readOnlyHint: false,
+    },
+    schema: {
+        text: zod.string().describe('The text to type'),
+        submitKey: submitKeySchema,
+    },
+    handler: async (request, response, context) => {
+        const page = request.page;
+        await context.waitForEventsAfterAction(async () => {
+            await page.pptrPage.keyboard.type(request.params.text);
+            if (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: {
@@ -154,10 +243,11 @@ 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);
-        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);
@@ -165,7 +255,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();
@@ -173,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: {
@@ -187,18 +279,22 @@ 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) => {
+        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`);
-        response.includeSnapshot();
+        if (request.params.includeSnapshot) {
+            response.includeSnapshot();
+        }
     },
 });
-export const uploadFile = defineTool({
+export const uploadFile = definePageTool({
     name: 'upload_file',
     description: 'Upload a file through a provided element.',
     annotations: {
@@ -210,10 +306,11 @@ 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) => {
+    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);
@@ -223,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]);
@@ -234,7 +330,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 {
@@ -242,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: {
@@ -253,21 +351,24 @@ 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();
+        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}`);
-        response.includeSnapshot();
+        if (request.params.includeSnapshot) {
+            response.includeSnapshot();
+        }
     },
 });