chrome-devtools-mcp 0.0.1 → 0.1.0

package/build/src/index.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { SetLevelRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { McpResponse } from './McpResponse.js';
+import { McpContext } from './McpContext.js';
+import { logger, saveLogsToFile } from './logger.js';
+import { resolveBrowser } from './browser.js';
+import * as emulationTools from './tools/emulation.js';
+import * as consoleTools from './tools/console.js';
+import * as inputTools from './tools/input.js';
+import * as networkTools from './tools/network.js';
+import * as pagesTools from './tools/pages.js';
+import * as performanceTools from './tools/performance.js';
+import * as screenshotTools from './tools/screenshot.js';
+import * as scriptTools from './tools/script.js';
+import * as snapshotTools from './tools/snapshot.js';
+import path from 'node:path';
+import fs from 'node:fs';
+import assert from 'node:assert';
+import { Mutex } from './Mutex.js';
+export const cliOptions = {
+    browserUrl: {
+        type: 'string',
+        description: 'Connect to a running Chrome instance using port forwarding. For more details see: https://developer.chrome.com/docs/devtools/remote-debugging/local-server.',
+        alias: 'u',
+        coerce: (url) => {
+            new URL(url);
+            return url;
+        },
+    },
+    headless: {
+        type: 'boolean',
+        description: 'Whether to run in headless (no UI) mode.',
+        default: false,
+    },
+    executablePath: {
+        type: 'string',
+        description: 'Path to custom Chrome executable.',
+        conflicts: 'browserUrl',
+        alias: 'e',
+    },
+    isolated: {
+        type: 'boolean',
+        description: 'If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed.',
+        default: false,
+    },
+    customDevtools: {
+        type: 'string',
+        description: 'Path to custom DevTools.',
+        hidden: true,
+        conflicts: 'browserUrl',
+        alias: 'd',
+    },
+    channel: {
+        type: 'string',
+        description: 'Specify a different Chrome channel that should be used.',
+        choices: ['stable', 'canary', 'beta', 'dev'],
+        conflicts: ['browserUrl', 'executablePath'],
+        default: 'stable',
+    },
+    logFile: {
+        type: 'string',
+        describe: 'Save the logs to file.',
+        hidden: true,
+    },
+};
+const yargsInstance = yargs(hideBin(process.argv))
+    .scriptName('npx chrome-devtools-mcp@latest')
+    .options(cliOptions)
+    .check(args => {
+    // We can't set default in the options else
+    // Yargs will complain
+    if (!args.channel && !args.browserUrl) {
+        args.channel = 'stable';
+    }
+    return true;
+})
+    .example([
+    [
+        '$0 --browserUrl http://127.0.0.1:9222',
+        'Connect to an existing browser instance',
+    ],
+    ['$0 --channel beta', 'Use Chrome Beta installed on this system'],
+    ['$0 --channel canary', 'Use Chrome Canary installed on this system'],
+    ['$0 --channel dev', 'Use Chrome Dev installed on this system'],
+    ['$0 --channel stable', 'Use stable Chrome installed on this system'],
+    ['$0 --logFile /tmp/log.txt', 'Save logs to a file'],
+    ['$0 --help', 'Print CLI options'],
+]);
+export const args = yargsInstance
+    .wrap(Math.min(120, yargsInstance.terminalWidth()))
+    .help()
+    .parseSync();
+if (args.logFile) {
+    saveLogsToFile(args.logFile);
+}
+function readPackageJson() {
+    const currentDir = import.meta.dirname;
+    const packageJsonPath = path.join(currentDir, '..', '..', 'package.json');
+    if (!fs.existsSync(packageJsonPath)) {
+        return {};
+    }
+    try {
+        const json = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+        assert.strict(json['name'], 'chrome-devtools-mcp');
+        return json;
+    }
+    catch {
+        return {};
+    }
+}
+const version = readPackageJson().version ?? 'unknown';
+logger(`Starting Chrome DevTools MCP Server v${version}`);
+const server = new McpServer({
+    name: 'chrome_devtools',
+    title: 'Chrome DevTools MCP server',
+    version,
+}, { capabilities: { logging: {} } });
+server.server.setRequestHandler(SetLevelRequestSchema, () => {
+    return {};
+});
+let context;
+async function getContext() {
+    const browser = await resolveBrowser({
+        browserUrl: args.browserUrl,
+        headless: args.headless,
+        executablePath: args.executablePath,
+        customDevTools: args.customDevtools,
+        channel: args.channel,
+        isolated: args.isolated,
+    });
+    if (!context) {
+        context = await McpContext.from(browser, logger);
+    }
+    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 want to share with MCP clients.`);
+};
+const toolMutex = new Mutex();
+function registerTool(tool) {
+    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();
+            const response = new McpResponse();
+            await tool.handler({
+                params,
+            }, response, context);
+            try {
+                const content = await response.handle(tool.name, context);
+                return {
+                    content,
+                };
+            }
+            catch (error) {
+                const errorText = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: errorText,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        finally {
+            guard.dispose();
+        }
+    });
+}
+const tools = [
+    ...Object.values(consoleTools),
+    ...Object.values(emulationTools),
+    ...Object.values(inputTools),
+    ...Object.values(networkTools),
+    ...Object.values(pagesTools),
+    ...Object.values(performanceTools),
+    ...Object.values(screenshotTools),
+    ...Object.values(scriptTools),
+    ...Object.values(snapshotTools),
+];
+for (const tool of tools) {
+    registerTool(tool);
+}
+const transport = new StdioServerTransport();
+await server.connect(transport);
+logger('Chrome DevTools MCP Server connected');
+logDisclaimers();

package/build/src/logger.js

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fs from 'node:fs';
+import debug from 'debug';
+const mcpDebugNamespace = 'mcp:log';
+const namespacesToEnable = [
+    mcpDebugNamespace,
+    ...(process.env['DEBUG'] ? [process.env['DEBUG']] : []),
+];
+export function saveLogsToFile(fileName) {
+    // Enable overrides everything so we need to add them
+    debug.enable(namespacesToEnable.join(','));
+    const logFile = fs.createWriteStream(fileName, { flags: 'a' });
+    debug.log = function (...chunks) {
+        logFile.write(`${chunks.join(' ')}\n`);
+    };
+    logFile.on('error', function (error) {
+        console.log(`Error when opening/writing to log file: ${error.message}`);
+        logFile.end();
+        process.exit(1);
+    });
+}
+export const logger = debug(mcpDebugNamespace);

package/build/src/tools/ToolDefinition.js

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export function defineTool(definition) {
+    return definition;
+}

package/build/src/tools/categories.js

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export var ToolCategories;
+(function (ToolCategories) {
+    ToolCategories["INPUT_AUTOMATION"] = "Input automation";
+    ToolCategories["NAVIGATION_AUTOMATION"] = "Navigation automation";
+    ToolCategories["EMULATION"] = "Emulation";
+    ToolCategories["PERFORMANCE"] = "Performance";
+    ToolCategories["NETWORK"] = "Network";
+    ToolCategories["DEBUGGING"] = "Debugging";
+})(ToolCategories || (ToolCategories = {}));

package/build/src/tools/console.js

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+export const consoleTool = defineTool({
+    name: 'list_console_messages',
+    description: 'List all console messages for the currently selected page',
+    annotations: {
+        category: ToolCategories.DEBUGGING,
+        readOnlyHint: true,
+    },
+    schema: {},
+    handler: async (_request, response) => {
+        response.setIncludeConsoleData(true);
+    },
+});

package/build/src/tools/emulation.js

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import z from 'zod';
+import { defineTool } from './ToolDefinition.js';
+import { PredefinedNetworkConditions } from 'puppeteer-core';
+import { ToolCategories } from './categories.js';
+const throttlingOptions = [
+    'No emulation',
+    ...Object.keys(PredefinedNetworkConditions),
+];
+export const emulateNetwork = defineTool({
+    name: 'emulate_network',
+    description: `Emulates network conditions such as throttling on the selected page.`,
+    annotations: {
+        category: ToolCategories.EMULATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        throttlingOption: z
+            .enum(throttlingOptions)
+            .describe(`The network throttling option to emulate. Available throttling options are: ${throttlingOptions.join(', ')}. Set to "No emulation" to disable.`),
+    },
+    handler: async (request, _response, context) => {
+        const page = context.getSelectedPage();
+        const conditions = request.params.throttlingOption;
+        if (conditions === 'No emulation') {
+            await page.emulateNetworkConditions(null);
+            context.setNetworkConditions(null);
+            return;
+        }
+        if (conditions in PredefinedNetworkConditions) {
+            const networkCondition = PredefinedNetworkConditions[conditions];
+            await page.emulateNetworkConditions(networkCondition);
+            context.setNetworkConditions(conditions);
+        }
+    },
+});
+export const emulateCpu = defineTool({
+    name: 'emulate_cpu',
+    description: `Emulates CPU throttling by slowing down the selected page's execution.`,
+    annotations: {
+        category: ToolCategories.EMULATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        throttlingRate: z
+            .number()
+            .min(1)
+            .max(20)
+            .describe('The CPU throttling rate representing the slowdown factor 1-20x. Set the rate to 1 to disable throttling'),
+    },
+    handler: async (request, _response, context) => {
+        const page = context.getSelectedPage();
+        const { throttlingRate } = request.params;
+        await page.emulateCPUThrottling(throttlingRate);
+        context.setCpuThrottlingRate(throttlingRate);
+    },
+});

package/build/src/tools/input.js

@@ -0,0 +1,202 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import z from 'zod';
+import { defineTool } from './ToolDefinition.js';
+import { ToolCategories } from './categories.js';
+import { waitForEventsAfterAction } from '../waitForHelpers.js';
+export const click = defineTool({
+    name: 'click',
+    description: `Clicks on the provided element`,
+    annotations: {
+        category: ToolCategories.INPUT_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        uid: z
+            .number()
+            .describe('The uid of an element on the page from the page content snapshot'),
+        dblClick: z
+            .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 waitForEventsAfterAction(handle.frame.page(), 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.setIncludeSnapshot(true);
+        }
+        finally {
+            handle.dispose();
+        }
+    },
+});
+export const hover = defineTool({
+    name: 'hover',
+    description: `Hover over the provided element`,
+    annotations: {
+        category: ToolCategories.INPUT_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        uid: z
+            .number()
+            .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 waitForEventsAfterAction(handle.frame.page(), async () => {
+                await handle.asLocator().hover();
+            });
+            response.appendResponseLine(`Successfully hovered over the element`);
+            response.setIncludeSnapshot(true);
+        }
+        finally {
+            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: ToolCategories.INPUT_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        uid: z
+            .number()
+            .describe('The uid of an element on the page from the page content snapshot'),
+        value: z.string().describe('The value to fill in'),
+    },
+    handler: async (request, response, context) => {
+        const handle = await context.getElementByUid(request.params.uid);
+        try {
+            await waitForEventsAfterAction(handle.frame.page(), async () => {
+                await handle.asLocator().fill(request.params.value);
+            });
+            response.appendResponseLine(`Successfully filled out the element`);
+            response.setIncludeSnapshot(true);
+        }
+        finally {
+            handle.dispose();
+        }
+    },
+});
+export const drag = defineTool({
+    name: 'drag',
+    description: `Drag an element onto another element`,
+    annotations: {
+        category: ToolCategories.INPUT_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        from_uid: z.number().describe('The uid of the element to drag'),
+        to_uid: z.number().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 waitForEventsAfterAction(fromHandle.frame.page(), async () => {
+                await fromHandle.drag(toHandle);
+                await new Promise(resolve => setTimeout(resolve, 50));
+                await toHandle.drop(fromHandle);
+            });
+            response.appendResponseLine(`Successfully dragged an element`);
+            response.setIncludeSnapshot(true);
+        }
+        finally {
+            fromHandle.dispose();
+            toHandle.dispose();
+        }
+    },
+});
+export const fillForm = defineTool({
+    name: 'fill_form',
+    description: `Fill out multiple form elements at once`,
+    annotations: {
+        category: ToolCategories.INPUT_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        elements: z
+            .array(z.object({
+            uid: z.number().describe('The uid of the element to fill out'),
+            value: z.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) {
+            const handle = await context.getElementByUid(element.uid);
+            try {
+                await waitForEventsAfterAction(handle.frame.page(), async () => {
+                    await handle.asLocator().fill(element.value);
+                });
+            }
+            finally {
+                handle.dispose();
+            }
+        }
+        response.appendResponseLine(`Successfully filled out the form`);
+        response.setIncludeSnapshot(true);
+    },
+});
+export const uploadFile = defineTool({
+    name: 'upload_file',
+    description: 'Upload a file through a provided element.',
+    annotations: {
+        category: ToolCategories.INPUT_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        uid: z
+            .number()
+            .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: z.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 = await 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.setIncludeSnapshot(true);
+            response.appendResponseLine(`File uploaded from ${filePath}.`);
+        }
+        finally {
+            handle.dispose();
+        }
+    },
+});

package/build/src/tools/network.js

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import z from 'zod';
+import { defineTool } from './ToolDefinition.js';
+import { ToolCategories } from './categories.js';
+export const listNetworkRequests = defineTool({
+    name: 'list_network_requests',
+    description: `List all requests for the currently selected page`,
+    annotations: {
+        category: ToolCategories.NETWORK,
+        readOnlyHint: true,
+    },
+    schema: {},
+    handler: async (_request, response) => {
+        response.setIncludeNetworkRequests(true);
+    },
+});
+export const getNetworkRequest = defineTool({
+    name: 'get_network_request',
+    description: `Gets a network request by URL. You can get all requests by calling ${listNetworkRequests.name}.`,
+    annotations: {
+        category: ToolCategories.NETWORK,
+        readOnlyHint: true,
+    },
+    schema: {
+        url: z.string().describe('The URL of the request.'),
+    },
+    handler: async (request, response, _context) => {
+        response.attachNetworkRequest(request.params.url);
+        response.setIncludeNetworkRequests(true);
+    },
+});