chrome-devtools-mcp 0.17.2 → 0.18.0

package/build/src/tools/script.js

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2025 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';
+export const evaluateScript = defineTool({
+    name: 'evaluate_script',
+    description: `Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON,
+so returned values have to be JSON-serializable.`,
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        readOnlyHint: false,
+    },
+    schema: {
+        function: zod.string().describe(`A JavaScript function declaration to be executed by the tool in the currently selected page.
+Example without arguments: \`() => {
+  return document.title
+}\` or \`async () => {
+  return await fetch("example.com")
+}\`.
+Example with arguments: \`(el) => {
+  return el.innerText;
+}\`
+`),
+        args: zod
+            .array(zod.object({
+            uid: zod
+                .string()
+                .describe('The uid of an element on the page from the page content snapshot'),
+        }))
+            .optional()
+            .describe(`An optional list of arguments to pass to the function.`),
+    },
+    handler: async (request, response, context) => {
+        const args = [];
+        try {
+            const frames = new Set();
+            for (const el of request.params.args ?? []) {
+                const handle = await context.getElementByUid(el.uid);
+                frames.add(handle.frame);
+                args.push(handle);
+            }
+            let pageOrFrame;
+            // We can't evaluate the element handle across frames
+            if (frames.size > 1) {
+                throw new Error("Elements from different frames can't be evaluated together.");
+            }
+            else {
+                pageOrFrame = [...frames.values()][0] ?? context.getSelectedPage();
+            }
+            const fn = await pageOrFrame.evaluateHandle(`(${request.params.function})`);
+            args.unshift(fn);
+            await context.waitForEventsAfterAction(async () => {
+                const result = await pageOrFrame.evaluate(async (fn, ...args) => {
+                    // @ts-expect-error no types.
+                    return JSON.stringify(await fn(...args));
+                }, ...args);
+                response.appendResponseLine('Script ran on page and returned:');
+                response.appendResponseLine('```json');
+                response.appendResponseLine(`${result}`);
+                response.appendResponseLine('```');
+            });
+        }
+        finally {
+            void Promise.allSettled(args.map(arg => arg.dispose()));
+        }
+    },
+});

package/build/src/tools/slim/tools.js

@@ -0,0 +1,81 @@
+/**
+ * @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';
+export const screenshot = defineTool({
+    name: 'screenshot',
+    description: `Takes a screenshot`,
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        // Not read-only due to filePath param.
+        readOnlyHint: false,
+    },
+    schema: {},
+    handler: async (request, response, context) => {
+        const page = context.getSelectedPage();
+        const screenshot = await page.screenshot({
+            type: 'png',
+            optimizeForSpeed: true,
+        });
+        const { filename } = await context.saveTemporaryFile(screenshot, `image/png`);
+        response.appendResponseLine(filename);
+    },
+});
+export const navigate = defineTool({
+    name: 'navigate',
+    description: `Loads a URL`,
+    annotations: {
+        category: ToolCategory.NAVIGATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        url: zod.string().describe('URL to navigate to'),
+    },
+    handler: async (request, response, context) => {
+        const page = context.getSelectedPage();
+        const options = {
+            timeout: 30_000,
+        };
+        const dialogHandler = (dialog) => {
+            if (dialog.type() === 'beforeunload') {
+                response.appendResponseLine(`Accepted a beforeunload dialog.`);
+                void dialog.accept();
+                // We are not going to report the dialog like regular dialogs.
+                context.clearDialog();
+            }
+        };
+        page.on('dialog', dialogHandler);
+        try {
+            await page.goto(request.params.url, options);
+            response.appendResponseLine(`Navigated to ${page.url()}.`);
+        }
+        finally {
+            page.off('dialog', dialogHandler);
+        }
+    },
+});
+export const evaluate = defineTool({
+    name: 'evaluate',
+    description: `Evaluates a JavaScript script`,
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        readOnlyHint: false,
+    },
+    schema: {
+        script: zod.string().describe(`JS script to run on the page`),
+    },
+    handler: async (request, response, context) => {
+        const page = context.getSelectedPage();
+        try {
+            const result = await page.evaluate(request.params.script);
+            response.appendResponseLine(JSON.stringify(result));
+        }
+        catch (err) {
+            response.appendResponseLine(String(err.message));
+        }
+    },
+});

package/build/src/tools/snapshot.js

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
+import { defineTool, timeoutSchema } from './ToolDefinition.js';
+export const takeSnapshot = defineTool({
+    name: 'take_snapshot',
+    description: `Take a text snapshot of the currently selected page based on the a11y tree. The snapshot lists page elements along with a unique
+identifier (uid). Always use the latest snapshot. Prefer taking a snapshot over taking a screenshot. The snapshot indicates the element selected
+in the DevTools Elements panel (if any).`,
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        // Not read-only due to filePath param.
+        readOnlyHint: false,
+    },
+    schema: {
+        verbose: zod
+            .boolean()
+            .optional()
+            .describe('Whether to include all possible information available in the full a11y tree. Default is false.'),
+        filePath: zod
+            .string()
+            .optional()
+            .describe('The absolute path, or a path relative to the current working directory, to save the snapshot to instead of attaching it to the response.'),
+    },
+    handler: async (request, response) => {
+        response.includeSnapshot({
+            verbose: request.params.verbose ?? false,
+            filePath: request.params.filePath,
+        });
+    },
+});
+export const waitFor = defineTool({
+    name: 'wait_for',
+    description: `Wait for the specified text to appear on the selected page.`,
+    annotations: {
+        category: ToolCategory.NAVIGATION,
+        readOnlyHint: true,
+    },
+    schema: {
+        text: zod
+            .array(zod.string())
+            .min(1)
+            .describe('Non-empty list of texts. Resolves when any value appears on the page.'),
+        ...timeoutSchema,
+    },
+    handler: async (request, response, context) => {
+        await context.waitForTextOnPage(request.params.text, request.params.timeout);
+        response.appendResponseLine(`Element matching one of ${JSON.stringify(request.params.text)} found.`);
+        response.includeSnapshot();
+    },
+});

package/build/src/tools/tools.js

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as consoleTools from './console.js';
+import * as emulationTools from './emulation.js';
+import * as extensionTools from './extensions.js';
+import * as inputTools from './input.js';
+import * as memoryTools from './memory.js';
+import * as networkTools from './network.js';
+import * as pagesTools from './pages.js';
+import * as performanceTools from './performance.js';
+import * as screencastTools from './screencast.js';
+import * as screenshotTools from './screenshot.js';
+import * as scriptTools from './script.js';
+import * as slimTools from './slim/tools.js';
+import * as snapshotTools from './snapshot.js';
+export const createTools = (args) => {
+    const rawTools = args.slim
+        ? Object.values(slimTools)
+        : [
+            ...Object.values(consoleTools),
+            ...Object.values(emulationTools),
+            ...Object.values(extensionTools),
+            ...Object.values(inputTools),
+            ...Object.values(memoryTools),
+            ...Object.values(networkTools),
+            ...Object.values(pagesTools),
+            ...Object.values(performanceTools),
+            ...Object.values(screencastTools),
+            ...Object.values(screenshotTools),
+            ...Object.values(scriptTools),
+            ...Object.values(snapshotTools),
+        ];
+    const tools = [];
+    for (const tool of rawTools) {
+        if (typeof tool === 'function') {
+            // @ts-expect-error none of the tools for now implement the function type tool has type "never"
+            tools.push(tool(args));
+        }
+        else {
+            tools.push(tool);
+        }
+    }
+    tools.sort((a, b) => {
+        return a.name.localeCompare(b.name);
+    });
+    return tools;
+};

package/build/src/trace-processing/parse.js

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { logger } from '../logger.js';
+import { DevTools } from '../third_party/index.js';
+const engine = DevTools.TraceEngine.TraceModel.Model.createWithAllHandlers();
+export function traceResultIsSuccess(x) {
+    return 'parsedTrace' in x;
+}
+export async function parseRawTraceBuffer(buffer) {
+    engine.resetProcessor();
+    if (!buffer) {
+        return {
+            error: 'No buffer was provided.',
+        };
+    }
+    const asString = new TextDecoder().decode(buffer);
+    if (!asString) {
+        return {
+            error: 'Decoding the trace buffer returned an empty string.',
+        };
+    }
+    try {
+        const data = JSON.parse(asString);
+        const events = Array.isArray(data) ? data : data.traceEvents;
+        await engine.parse(events);
+        const parsedTrace = engine.parsedTrace();
+        if (!parsedTrace) {
+            return {
+                error: 'No parsed trace was returned from the trace engine.',
+            };
+        }
+        const insights = parsedTrace?.insights ?? null;
+        return {
+            parsedTrace,
+            insights,
+        };
+    }
+    catch (e) {
+        const errorText = e instanceof Error ? e.message : JSON.stringify(e);
+        logger(`Unexpected error parsing trace: ${errorText}`);
+        return {
+            error: errorText,
+        };
+    }
+}
+const extraFormatDescriptions = `Information on performance traces may contain main thread activity represented as call frames and network requests.
+
+${DevTools.PerformanceTraceFormatter.callFrameDataFormatDescription}
+
+${DevTools.PerformanceTraceFormatter.networkDataFormatDescription}`;
+export function getTraceSummary(result) {
+    const focus = DevTools.AgentFocus.fromParsedTrace(result.parsedTrace);
+    const formatter = new DevTools.PerformanceTraceFormatter(focus);
+    const summaryText = formatter.formatTraceSummary();
+    return `## Summary of Performance trace findings:
+${summaryText}
+
+## Details on call tree & network request formats:
+${extraFormatDescriptions}`;
+}
+export function getInsightOutput(result, insightSetId, insightName) {
+    if (!result.insights) {
+        return {
+            error: 'No Performance insights are available for this trace.',
+        };
+    }
+    const insightSet = result.insights.get(insightSetId);
+    if (!insightSet) {
+        return {
+            error: 'No Performance Insights for the given insight set id. Only use ids given in the "Available insight sets" list.',
+        };
+    }
+    const matchingInsight = insightName in insightSet.model ? insightSet.model[insightName] : null;
+    if (!matchingInsight) {
+        return {
+            error: `No Insight with the name ${insightName} found. Double check the name you provided is accurate and try again.`,
+        };
+    }
+    const formatter = new DevTools.PerformanceInsightFormatter(DevTools.AgentFocus.fromParsedTrace(result.parsedTrace), matchingInsight);
+    return { output: formatter.formatInsight() };
+}

package/build/src/utils/ExtensionRegistry.js

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

package/build/src/utils/keyboard.js

@@ -0,0 +1,296 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// See the KeyInput type for the list of supported keys.
+const validKeys = new Set([
+    '0',
+    '1',
+    '2',
+    '3',
+    '4',
+    '5',
+    '6',
+    '7',
+    '8',
+    '9',
+    'Power',
+    'Eject',
+    'Abort',
+    'Help',
+    'Backspace',
+    'Tab',
+    'Numpad5',
+    'NumpadEnter',
+    'Enter',
+    '\r',
+    '\n',
+    'ShiftLeft',
+    'ShiftRight',
+    'ControlLeft',
+    'ControlRight',
+    'AltLeft',
+    'AltRight',
+    'Pause',
+    'CapsLock',
+    'Escape',
+    'Convert',
+    'NonConvert',
+    'Space',
+    'Numpad9',
+    'PageUp',
+    'Numpad3',
+    'PageDown',
+    'End',
+    'Numpad1',
+    'Home',
+    'Numpad7',
+    'ArrowLeft',
+    'Numpad4',
+    'Numpad8',
+    'ArrowUp',
+    'ArrowRight',
+    'Numpad6',
+    'Numpad2',
+    'ArrowDown',
+    'Select',
+    'Open',
+    'PrintScreen',
+    'Insert',
+    'Numpad0',
+    'Delete',
+    'NumpadDecimal',
+    'Digit0',
+    'Digit1',
+    'Digit2',
+    'Digit3',
+    'Digit4',
+    'Digit5',
+    'Digit6',
+    'Digit7',
+    'Digit8',
+    'Digit9',
+    'KeyA',
+    'KeyB',
+    'KeyC',
+    'KeyD',
+    'KeyE',
+    'KeyF',
+    'KeyG',
+    'KeyH',
+    'KeyI',
+    'KeyJ',
+    'KeyK',
+    'KeyL',
+    'KeyM',
+    'KeyN',
+    'KeyO',
+    'KeyP',
+    'KeyQ',
+    'KeyR',
+    'KeyS',
+    'KeyT',
+    'KeyU',
+    'KeyV',
+    'KeyW',
+    'KeyX',
+    'KeyY',
+    'KeyZ',
+    'MetaLeft',
+    'MetaRight',
+    'ContextMenu',
+    'NumpadMultiply',
+    'NumpadAdd',
+    'NumpadSubtract',
+    'NumpadDivide',
+    'F1',
+    'F2',
+    'F3',
+    'F4',
+    'F5',
+    'F6',
+    'F7',
+    'F8',
+    'F9',
+    'F10',
+    'F11',
+    'F12',
+    'F13',
+    'F14',
+    'F15',
+    'F16',
+    'F17',
+    'F18',
+    'F19',
+    'F20',
+    'F21',
+    'F22',
+    'F23',
+    'F24',
+    'NumLock',
+    'ScrollLock',
+    'AudioVolumeMute',
+    'AudioVolumeDown',
+    'AudioVolumeUp',
+    'MediaTrackNext',
+    'MediaTrackPrevious',
+    'MediaStop',
+    'MediaPlayPause',
+    'Semicolon',
+    'Equal',
+    'NumpadEqual',
+    'Comma',
+    'Minus',
+    'Period',
+    'Slash',
+    'Backquote',
+    'BracketLeft',
+    'Backslash',
+    'BracketRight',
+    'Quote',
+    'AltGraph',
+    'Props',
+    'Cancel',
+    'Clear',
+    'Shift',
+    'Control',
+    'Alt',
+    'Accept',
+    'ModeChange',
+    ' ',
+    'Print',
+    'Execute',
+    '\u0000',
+    'a',
+    'b',
+    'c',
+    'd',
+    'e',
+    'f',
+    'g',
+    'h',
+    'i',
+    'j',
+    'k',
+    'l',
+    'm',
+    'n',
+    'o',
+    'p',
+    'q',
+    'r',
+    's',
+    't',
+    'u',
+    'v',
+    'w',
+    'x',
+    'y',
+    'z',
+    'Meta',
+    '*',
+    '+',
+    '-',
+    '/',
+    ';',
+    '=',
+    ',',
+    '.',
+    '`',
+    '[',
+    '\\',
+    ']',
+    "'",
+    'Attn',
+    'CrSel',
+    'ExSel',
+    'EraseEof',
+    'Play',
+    'ZoomOut',
+    ')',
+    '!',
+    '@',
+    '#',
+    '$',
+    '%',
+    '^',
+    '&',
+    '(',
+    'A',
+    'B',
+    'C',
+    'D',
+    'E',
+    'F',
+    'G',
+    'H',
+    'I',
+    'J',
+    'K',
+    'L',
+    'M',
+    'N',
+    'O',
+    'P',
+    'Q',
+    'R',
+    'S',
+    'T',
+    'U',
+    'V',
+    'W',
+    'X',
+    'Y',
+    'Z',
+    ':',
+    '<',
+    '_',
+    '>',
+    '?',
+    '~',
+    '{',
+    '|',
+    '}',
+    '"',
+    'SoftLeft',
+    'SoftRight',
+    'Camera',
+    'Call',
+    'EndCall',
+    'VolumeDown',
+    'VolumeUp',
+]);
+function throwIfInvalidKey(key) {
+    if (validKeys.has(key)) {
+        return key;
+    }
+    throw new Error(`${key} is invalid. Valid keys are: ${Array.from(validKeys.values()).join(',')}.`);
+}
+/**
+ * Returns the primary key, followed by modifiers in original order.
+ */
+export function parseKey(keyInput) {
+    let key = '';
+    const result = [];
+    for (const ch of keyInput) {
+        // Handle cases like Shift++.
+        if (ch === '+' && key) {
+            result.push(throwIfInvalidKey(key));
+            key = '';
+        }
+        else {
+            key += ch;
+        }
+    }
+    if (key) {
+        result.push(throwIfInvalidKey(key));
+    }
+    if (result.length === 0) {
+        throw new Error(`Key ${keyInput} could not be parsed.`);
+    }
+    if (new Set(result).size !== result.length) {
+        throw new Error(`Key ${keyInput} contains duplicate keys.`);
+    }
+    return [result.at(-1), ...result.slice(0, -1)];
+}