@mcp-b/chrome-devtools-mcp 0.12.0-beta.0

package/build/src/main.js

@@ -0,0 +1,130 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import './polyfill.js';
+import { ensureBrowserConnected, ensureBrowserLaunched } from './browser.js';
+import { parseArguments } from './cli.js';
+import { loadIssueDescriptions } from './issue-descriptions.js';
+import { logger, saveLogsToFile } from './logger.js';
+import { McpContext } from './McpContext.js';
+import { McpResponse } from './McpResponse.js';
+import { Mutex } from './Mutex.js';
+import { McpServer, StdioServerTransport, SetLevelRequestSchema, } from './third_party/index.js';
+import { ToolCategory } from './tools/categories.js';
+import { tools } from './tools/tools.js';
+// If moved update release-please config
+// x-release-please-start-version
+const VERSION = '0.11.0';
+// x-release-please-end
+export const args = parseArguments(VERSION);
+const logFile = args.logFile ? saveLogsToFile(args.logFile) : undefined;
+logger(`Starting Chrome DevTools MCP Server v${VERSION}`);
+const server = new McpServer({
+    name: 'chrome_devtools',
+    title: 'Chrome DevTools MCP server',
+    version: VERSION,
+}, { capabilities: { logging: {} } });
+server.server.setRequestHandler(SetLevelRequestSchema, () => {
+    return {};
+});
+let context;
+async function getContext() {
+    const extraArgs = (args.chromeArg ?? []).map(String);
+    if (args.proxyServer) {
+        extraArgs.push(`--proxy-server=${args.proxyServer}`);
+    }
+    const devtools = args.experimentalDevtools ?? false;
+    const browser = args.browserUrl || args.wsEndpoint
+        ? await ensureBrowserConnected({
+            browserURL: args.browserUrl,
+            wsEndpoint: args.wsEndpoint,
+            wsHeaders: args.wsHeaders,
+            devtools,
+        })
+        : await ensureBrowserLaunched({
+            headless: args.headless,
+            executablePath: args.executablePath,
+            channel: args.channel,
+            isolated: args.isolated ?? false,
+            userDataDir: args.userDataDir,
+            logFile,
+            viewport: args.viewport,
+            args: extraArgs,
+            acceptInsecureCerts: args.acceptInsecureCerts,
+            devtools,
+        });
+    if (context?.browser !== browser) {
+        context = await McpContext.from(browser, logger, {
+            experimentalDevToolsDebugging: devtools,
+            experimentalIncludeAllPages: args.experimentalIncludeAllPages,
+        });
+    }
+    return context;
+}
+const logDisclaimers = () => {
+    console.error(`chrome-devtools-mcp exposes content of the browser instance to the MCP clients allowing them to inspect,
+debug, and modify any data in the browser or DevTools.
+Avoid sharing sensitive or personal information that you do not want to share with MCP clients.`);
+};
+const toolMutex = new Mutex();
+function registerTool(tool) {
+    if (tool.annotations.category === ToolCategory.EMULATION &&
+        args.categoryEmulation === false) {
+        return;
+    }
+    if (tool.annotations.category === ToolCategory.PERFORMANCE &&
+        args.categoryPerformance === false) {
+        return;
+    }
+    if (tool.annotations.category === ToolCategory.NETWORK &&
+        args.categoryNetwork === false) {
+        return;
+    }
+    server.registerTool(tool.name, {
+        description: tool.description,
+        inputSchema: tool.schema,
+        annotations: tool.annotations,
+    }, async (params) => {
+        const guard = await toolMutex.acquire();
+        try {
+            logger(`${tool.name} request: ${JSON.stringify(params, null, '  ')}`);
+            const context = await getContext();
+            logger(`${tool.name} context: resolved`);
+            await context.detectOpenDevToolsWindows();
+            const response = new McpResponse();
+            await tool.handler({
+                params,
+            }, response, context);
+            const content = await response.handle(tool.name, context);
+            return {
+                content,
+            };
+        }
+        catch (err) {
+            logger(`${tool.name} error:`, err, err?.stack);
+            const errorText = err && 'message' in err ? err.message : String(err);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: errorText,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        finally {
+            guard.dispose();
+        }
+    });
+}
+for (const tool of tools) {
+    registerTool(tool);
+}
+await loadIssueDescriptions();
+const transport = new StdioServerTransport();
+await server.connect(transport);
+logger('Chrome DevTools MCP Server connected');
+logDisclaimers();

package/build/src/polyfill.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2025 Google Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// polyfills are now bundled with all other dependencies
+import './third_party/index.js';

package/build/src/third_party/index.js

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import 'core-js/modules/es.promise.with-resolvers.js';
+import 'core-js/proposals/iterator-helpers.js';
+export { default as yargs } from 'yargs';
+export { hideBin } from 'yargs/helpers';
+export { default as debug } from 'debug';
+export { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+export { SetLevelRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+export { z as zod } from 'zod';
+export { Locator, PredefinedNetworkConditions, CDPSessionEvent, } from 'puppeteer-core';
+export { default as puppeteer } from 'puppeteer-core';

package/build/src/tools/ToolDefinition.js

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod } from '../third_party/index.js';
+export function defineTool(definition) {
+    return definition;
+}
+export const CLOSE_PAGE_ERROR = 'The last open page cannot be closed. It is fine to keep it open.';
+export const timeoutSchema = {
+    timeout: zod
+        .number()
+        .int()
+        .optional()
+        .describe(`Maximum wait time in milliseconds. If set to 0, the default timeout will be used.`)
+        .transform(value => {
+        return value && value <= 0 ? undefined : value;
+    }),
+};

package/build/src/tools/categories.js

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export var ToolCategory;
+(function (ToolCategory) {
+    ToolCategory["INPUT"] = "input";
+    ToolCategory["NAVIGATION"] = "navigation";
+    ToolCategory["EMULATION"] = "emulation";
+    ToolCategory["PERFORMANCE"] = "performance";
+    ToolCategory["NETWORK"] = "network";
+    ToolCategory["DEBUGGING"] = "debugging";
+    ToolCategory["WEBMCP"] = "webmcp";
+})(ToolCategory || (ToolCategory = {}));
+export const labels = {
+    [ToolCategory.INPUT]: 'Input automation',
+    [ToolCategory.NAVIGATION]: 'Navigation automation',
+    [ToolCategory.EMULATION]: 'Emulation',
+    [ToolCategory.PERFORMANCE]: 'Performance',
+    [ToolCategory.NETWORK]: 'Network',
+    [ToolCategory.DEBUGGING]: 'Debugging',
+    [ToolCategory.WEBMCP]: 'Website MCP Tools',
+};

package/build/src/tools/console.js

@@ -0,0 +1,85 @@
+/**
+ * @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';
+const FILTERABLE_MESSAGE_TYPES = [
+    'log',
+    'debug',
+    'info',
+    'error',
+    'warn',
+    'dir',
+    'dirxml',
+    'table',
+    'trace',
+    'clear',
+    'startGroup',
+    'startGroupCollapsed',
+    'endGroup',
+    'assert',
+    'profile',
+    'profileEnd',
+    'count',
+    'timeEnd',
+    'verbose',
+    'issue',
+];
+export const listConsoleMessages = defineTool({
+    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,
+        });
+    },
+});
+export const getConsoleMessage = defineTool({
+    name: 'get_console_message',
+    description: `Gets a console message by its ID. You can get all messages by calling ${listConsoleMessages.name}.`,
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        readOnlyHint: true,
+    },
+    schema: {
+        msgid: zod
+            .number()
+            .describe('The msgid of a console message on the page from the listed console messages'),
+    },
+    handler: async (request, response) => {
+        response.attachConsoleMessage(request.params.msgid);
+    },
+});

package/build/src/tools/emulation.js

@@ -0,0 +1,87 @@
+/**
+ * @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';
+const throttlingOptions = [
+    'No emulation',
+    'Offline',
+    ...Object.keys(PredefinedNetworkConditions),
+];
+export const emulate = defineTool({
+    name: 'emulate',
+    description: `Emulates various features on the selected page.`,
+    annotations: {
+        category: ToolCategory.EMULATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        networkConditions: zod
+            .enum(throttlingOptions)
+            .optional()
+            .describe(`Throttle network. Set to "No emulation" to disable. If omitted, conditions remain unchanged.`),
+        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.'),
+        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()
+            .optional()
+            .describe('Geolocation to emulate. Set to null to clear the geolocation override.'),
+    },
+    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);
+            }
+        }
+    },
+});

package/build/src/tools/input.js

@@ -0,0 +1,268 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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({
+    name: 'click',
+    description: `Clicks on the provided element`,
+    annotations: {
+        category: ToolCategory.INPUT,
+        readOnlyHint: false,
+    },
+    schema: {
+        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.'),
+    },
+    handler: async (request, response, context) => {
+        const uid = request.params.uid;
+        const handle = await context.getElementByUid(uid);
+        try {
+            await context.waitForEventsAfterAction(async () => {
+                await handle.asLocator().click({
+                    count: request.params.dblClick ? 2 : 1,
+                });
+            });
+            response.appendResponseLine(request.params.dblClick
+                ? `Successfully double clicked on the element`
+                : `Successfully clicked on the element`);
+            response.includeSnapshot();
+        }
+        finally {
+            void handle.dispose();
+        }
+    },
+});
+export const hover = defineTool({
+    name: 'hover',
+    description: `Hover over the provided element`,
+    annotations: {
+        category: ToolCategory.INPUT,
+        readOnlyHint: false,
+    },
+    schema: {
+        uid: zod
+            .string()
+            .describe('The uid of an element on the page from the page content snapshot'),
+    },
+    handler: async (request, response, context) => {
+        const uid = request.params.uid;
+        const handle = await context.getElementByUid(uid);
+        try {
+            await context.waitForEventsAfterAction(async () => {
+                await handle.asLocator().hover();
+            });
+            response.appendResponseLine(`Successfully hovered over the element`);
+            response.includeSnapshot();
+        }
+        finally {
+            void handle.dispose();
+        }
+    },
+});
+// The AXNode for an option doesn't contain its `value`. We set text content of the option as value.
+// If the form is a combobox, we need to find the correct option by its text value.
+// To do that, loop through the children while checking which child's text matches the requested value (requested value is actually the text content).
+// When the correct option is found, use the element handle to get the real value.
+async function selectOption(handle, aXNode, value) {
+    let optionFound = false;
+    for (const child of aXNode.children) {
+        if (child.role === 'option' && child.name === value && child.value) {
+            optionFound = true;
+            const childHandle = await child.elementHandle();
+            if (childHandle) {
+                try {
+                    const childValueHandle = await childHandle.getProperty('value');
+                    try {
+                        const childValue = await childValueHandle.jsonValue();
+                        if (childValue) {
+                            await handle.asLocator().fill(childValue.toString());
+                        }
+                    }
+                    finally {
+                        void childValueHandle.dispose();
+                    }
+                    break;
+                }
+                finally {
+                    void childHandle.dispose();
+                }
+            }
+        }
+    }
+    if (!optionFound) {
+        throw new Error(`Could not find option with text "${value}"`);
+    }
+}
+async function fillFormElement(uid, value, context) {
+    const handle = await context.getElementByUid(uid);
+    try {
+        const aXNode = context.getAXNodeByUid(uid);
+        if (aXNode && aXNode.role === 'combobox') {
+            await selectOption(handle, aXNode, value);
+        }
+        else {
+            await handle.asLocator().fill(value);
+        }
+    }
+    finally {
+        void handle.dispose();
+    }
+}
+export const fill = defineTool({
+    name: 'fill',
+    description: `Type text into a input, text area or select an option from a <select> element.`,
+    annotations: {
+        category: ToolCategory.INPUT,
+        readOnlyHint: false,
+    },
+    schema: {
+        uid: zod
+            .string()
+            .describe('The uid of an element on the page from the page content snapshot'),
+        value: zod.string().describe('The value to fill in'),
+    },
+    handler: async (request, response, context) => {
+        await context.waitForEventsAfterAction(async () => {
+            await fillFormElement(request.params.uid, request.params.value, context);
+        });
+        response.appendResponseLine(`Successfully filled out the element`);
+        response.includeSnapshot();
+    },
+});
+export const drag = defineTool({
+    name: 'drag',
+    description: `Drag an element onto another element`,
+    annotations: {
+        category: ToolCategory.INPUT,
+        readOnlyHint: false,
+    },
+    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'),
+    },
+    handler: async (request, response, context) => {
+        const fromHandle = await context.getElementByUid(request.params.from_uid);
+        const toHandle = await context.getElementByUid(request.params.to_uid);
+        try {
+            await context.waitForEventsAfterAction(async () => {
+                await fromHandle.drag(toHandle);
+                await new Promise(resolve => setTimeout(resolve, 50));
+                await toHandle.drop(fromHandle);
+            });
+            response.appendResponseLine(`Successfully dragged an element`);
+            response.includeSnapshot();
+        }
+        finally {
+            void fromHandle.dispose();
+            void toHandle.dispose();
+        }
+    },
+});
+export const fillForm = defineTool({
+    name: 'fill_form',
+    description: `Fill out multiple form elements at once`,
+    annotations: {
+        category: ToolCategory.INPUT,
+        readOnlyHint: false,
+    },
+    schema: {
+        elements: zod
+            .array(zod.object({
+            uid: zod.string().describe('The uid of the element to fill out'),
+            value: zod.string().describe('Value for the element'),
+        }))
+            .describe('Elements from snapshot to fill out.'),
+    },
+    handler: async (request, response, context) => {
+        for (const element of request.params.elements) {
+            await context.waitForEventsAfterAction(async () => {
+                await fillFormElement(element.uid, element.value, context);
+            });
+        }
+        response.appendResponseLine(`Successfully filled out the form`);
+        response.includeSnapshot();
+    },
+});
+export const uploadFile = defineTool({
+    name: 'upload_file',
+    description: 'Upload a file through a provided element.',
+    annotations: {
+        category: ToolCategory.INPUT,
+        readOnlyHint: false,
+    },
+    schema: {
+        uid: zod
+            .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'),
+    },
+    handler: async (request, response, context) => {
+        const { uid, filePath } = request.params;
+        const handle = (await context.getElementByUid(uid));
+        try {
+            try {
+                await handle.uploadFile(filePath);
+            }
+            catch {
+                // Some sites use a proxy element to trigger file upload instead of
+                // 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 }),
+                        handle.asLocator().click(),
+                    ]);
+                    await fileChooser.accept([filePath]);
+                }
+                catch {
+                    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();
+            response.appendResponseLine(`File uploaded from ${filePath}.`);
+        }
+        finally {
+            void handle.dispose();
+        }
+    },
+});
+export const pressKey = defineTool({
+    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: {
+        category: ToolCategory.INPUT,
+        readOnlyHint: false,
+    },
+    schema: {
+        key: zod
+            .string()
+            .describe('A key or a combination (e.g., "Enter", "Control+A", "Control++", "Control+Shift+R"). Modifiers: Control, Shift, Alt, Meta'),
+    },
+    handler: async (request, response, context) => {
+        const page = context.getSelectedPage();
+        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.keyboard.press(key);
+            for (const modifier of modifiers.toReversed()) {
+                await page.keyboard.up(modifier);
+            }
+        });
+        response.appendResponseLine(`Successfully pressed key: ${request.params.key}`);
+        response.includeSnapshot();
+    },
+});