@mcp-b/chrome-devtools-mcp 2.1.0 → 2.2.0

package/build/src/{cli.js → bin/chrome-devtools-mcp-cli-options.js}

@@ -3,17 +3,18 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { yargs, hideBin } from './third_party/index.js';
+import { yargs, hideBin } from '../third_party/index.js';
 export const cliOptions = {
     autoConnect: {
         type: 'boolean',
-        description: 'If specified, automatically connects to a browser (Chrome 145+) running in the user data directory identified by the channel param. Falls back to launching a new instance if no running browser is found.',
-        default: true,
+        description: 'If specified, automatically connects to a browser (Chrome 144+) running locally from the user data directory identified by the channel param (default channel is stable). Requires the remoted debugging server to be started in the Chrome instance via chrome://inspect/#remote-debugging.',
+        conflicts: ['isolated', 'executablePath'],
+        default: false,
         coerce: (value) => {
-            if (value === false) {
-                return false;
+            if (!value) {
+                return;
             }
-            return true;
+            return value;
         },
     },
     browserUrl: {
@@ -133,20 +134,48 @@ export const cliOptions = {
         type: 'boolean',
         description: `If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.`,
     },
+    experimentalPageIdRouting: {
+        type: 'boolean',
+        describe: 'Whether to expose pageId on page-scoped tools and route requests by page ID.',
+        hidden: true,
+    },
     experimentalDevtools: {
         type: 'boolean',
         describe: 'Whether to enable automation over DevTools targets',
         hidden: true,
     },
+    experimentalVision: {
+        type: 'boolean',
+        describe: 'Whether to enable vision tools',
+        hidden: true,
+    },
+    experimentalStructuredContent: {
+        type: 'boolean',
+        describe: 'Whether to output structured formatted content.',
+        hidden: true,
+    },
     experimentalIncludeAllPages: {
         type: 'boolean',
         describe: 'Whether to include all kinds of pages such as webviews or background pages as pages.',
         hidden: true,
     },
+    experimentalInteropTools: {
+        type: 'boolean',
+        describe: 'Whether to enable interoperability tools',
+        hidden: true,
+    },
+    experimentalScreencast: {
+        type: 'boolean',
+        describe: 'Exposes experimental screencast tools (requires ffmpeg). Install ffmpeg https://www.ffmpeg.org/download.html and ensure it is available in the MCP server PATH.',
+    },
     chromeArg: {
         type: 'array',
         describe: 'Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',
     },
+    ignoreDefaultChromeArg: {
+        type: 'array',
+        describe: 'Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',
+    },
     categoryEmulation: {
         type: 'boolean',
         default: true,
@@ -162,10 +191,45 @@ export const cliOptions = {
         default: true,
         describe: 'Set to false to exclude tools related to network.',
     },
-    includeExtensionPages: {
+    categoryExtensions: {
         type: 'boolean',
-        describe: 'Include chrome-extension:// pages in page listing and tool discovery.',
         default: false,
+        hidden: true,
+        describe: 'Set to false to exclude tools related to extensions.',
+    },
+    performanceCrux: {
+        type: 'boolean',
+        default: true,
+        describe: 'Set to false to disable sending URLs from performance traces to CrUX API to get field performance data.',
+    },
+    usageStatistics: {
+        type: 'boolean',
+        default: true,
+        describe: 'Set to false to opt-out of usage statistics collection. Google collects usage data to improve the tool, handled under the Google Privacy Policy (https://policies.google.com/privacy). This is independent from Chrome browser metrics. Disabled if CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS or CI env variables are set.',
+    },
+    clearcutEndpoint: {
+        type: 'string',
+        hidden: true,
+        describe: 'Endpoint for Clearcut telemetry.',
+    },
+    clearcutForceFlushIntervalMs: {
+        type: 'number',
+        hidden: true,
+        describe: 'Force flush interval in milliseconds (for testing).',
+    },
+    clearcutIncludePidHeader: {
+        type: 'boolean',
+        hidden: true,
+        describe: 'Include watchdog PID in Clearcut request headers (for testing).',
+    },
+    slim: {
+        type: 'boolean',
+        describe: 'Exposes a "slim" set of 3 tools covering navigation, script execution and screenshots only. Useful for basic browser tasks.',
+    },
+    viaCli: {
+        type: 'boolean',
+        describe: 'Set by Chrome DevTools CLI if the MCP server is started via the CLI client (this arg exists for usage stats)',
+        hidden: true,
     },
 };
 export function parseArguments(version, argv = process.argv) {
@@ -175,11 +239,10 @@ export function parseArguments(version, argv = process.argv) {
         .check(args => {
         // We can't set default in the options else
         // Yargs will complain
-        // Note: Use explicit undefined checks since empty strings are valid falsy values
-        if (args.channel === undefined &&
-            args.browserUrl === undefined &&
-            args.wsEndpoint === undefined &&
-            args.executablePath === undefined) {
+        if (!args.channel &&
+            !args.browserUrl &&
+            !args.wsEndpoint &&
+            !args.executablePath) {
             args.channel = 'stable';
         }
         return true;
@@ -211,6 +274,10 @@ export function parseArguments(version, argv = process.argv) {
             `$0 --chrome-arg='--no-sandbox' --chrome-arg='--disable-setuid-sandbox'`,
             'Launch Chrome without sandboxes. Use with caution.',
         ],
+        [
+            `$0 --ignore-default-chrome-arg='--disable-extensions'`,
+            'Disable the default arguments provided by Puppeteer. Use with caution.',
+        ],
         ['$0 --no-category-emulation', 'Disable tools in the emulation category'],
         [
             '$0 --no-category-performance',
@@ -223,11 +290,23 @@ export function parseArguments(version, argv = process.argv) {
         ],
         [
             '$0 --auto-connect',
-            'Connect to a stable Chrome instance (Chrome 145+) running instead of launching a new instance',
+            'Connect to a stable Chrome instance (Chrome 144+) running instead of launching a new instance',
         ],
         [
             '$0 --auto-connect --channel=canary',
-            'Connect to a canary Chrome instance (Chrome 145+) running instead of launching a new instance',
+            'Connect to a canary Chrome instance (Chrome 144+) running instead of launching a new instance',
+        ],
+        [
+            '$0 --no-usage-statistics',
+            'Do not send usage statistics https://github.com/ChromeDevTools/chrome-devtools-mcp#usage-statistics.',
+        ],
+        [
+            '$0 --no-performance-crux',
+            'Disable CrUX (field data) integration in performance tools.',
+        ],
+        [
+            '$0 --slim',
+            'Only 3 tools: navigation, JavaScript execution and screenshot',
         ],
     ]);
     return yargsInstance

package/build/src/bin/chrome-devtools-mcp-main.js

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import '../polyfill.js';
+import process from 'node:process';
+import { createMcpServer, logDisclaimers } from '../index.js';
+import { logger, saveLogsToFile } from '../logger.js';
+import { computeFlagUsage } from '../telemetry/flagUtils.js';
+import { StdioServerTransport } from '../third_party/index.js';
+import { VERSION } from '../version.js';
+import { cliOptions, parseArguments } from './chrome-devtools-mcp-cli-options.js';
+export const args = parseArguments(VERSION);
+const logFile = args.logFile ? saveLogsToFile(args.logFile) : undefined;
+if (process.env['CI'] ||
+    process.env['CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS']) {
+    console.error("turning off usage statistics. process.env['CI'] || process.env['CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS'] is set.");
+    args.usageStatistics = false;
+}
+if (process.env['CHROME_DEVTOOLS_MCP_CRASH_ON_UNCAUGHT'] !== 'true') {
+    process.on('unhandledRejection', (reason, promise) => {
+        logger('Unhandled promise rejection', promise, reason);
+    });
+}
+logger(`Starting Chrome DevTools MCP Server v${VERSION}`);
+const { server, clearcutLogger } = await createMcpServer(args, {
+    logFile,
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+logger('Chrome DevTools MCP Server connected');
+logDisclaimers(args);
+void clearcutLogger?.logDailyActiveIfNeeded();
+void clearcutLogger?.logServerStart(computeFlagUsage(args, cliOptions));

package/build/src/bin/chrome-devtools-mcp.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { version } from 'node:process';
+const [major, minor] = version.substring(1).split('.').map(Number);
+if (major === 20 && minor < 19) {
+    console.error(`ERROR: \`chrome-devtools-mcp\` does not support Node ${process.version}. Please upgrade to Node 20.19.0 LTS or a newer LTS.`);
+    process.exit(1);
+}
+if (major === 22 && minor < 12) {
+    console.error(`ERROR: \`chrome-devtools-mcp\` does not support Node ${process.version}. Please upgrade to Node 22.12.0 LTS or a newer LTS.`);
+    process.exit(1);
+}
+if (major < 20) {
+    console.error(`ERROR: \`chrome-devtools-mcp\` does not support Node ${process.version}. Please upgrade to Node 20.19.0 LTS or a newer LTS.`);
+    process.exit(1);
+}
+await import('./chrome-devtools-mcp-main.js');

package/build/src/bin/chrome-devtools.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import process from 'node:process';
+import { startDaemon, stopDaemon, sendCommand, handleResponse, } from '../daemon/client.js';
+import { isDaemonRunning, serializeArgs } from '../daemon/utils.js';
+import { logDisclaimers } from '../index.js';
+import { hideBin, yargs } from '../third_party/index.js';
+import { VERSION } from '../version.js';
+import { commands } from './chrome-devtools-cli-options.js';
+import { cliOptions, parseArguments } from './chrome-devtools-mcp-cli-options.js';
+async function start(args) {
+    const combinedArgs = [...args, ...defaultArgs];
+    await startDaemon(combinedArgs);
+    logDisclaimers(parseArguments(VERSION, combinedArgs));
+}
+const defaultArgs = ['--viaCli', '--experimentalStructuredContent'];
+function normalizeCommandArgValue(commandName, argName, argType, value) {
+    if (argType !== 'object' || value === undefined) {
+        return value;
+    }
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    if (typeof value !== 'string') {
+        throw new Error(`Invalid value for ${commandName} --${argName}. Expected a JSON object string.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON for ${commandName} --${argName}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`Invalid value for ${commandName} --${argName}. Expected a JSON object.`);
+    }
+    return parsed;
+}
+const startCliOptions = {
+    ...cliOptions,
+};
+// Not supported in CLI on purpose.
+delete startCliOptions.autoConnect;
+// Missing CLI serialization.
+delete startCliOptions.viewport;
+// CLI is generated based on the default tool definitions. To enable conditional
+// tools, they needs to be enabled during CLI generation.
+delete startCliOptions.experimentalPageIdRouting;
+delete startCliOptions.experimentalVision;
+delete startCliOptions.experimentalInteropTools;
+delete startCliOptions.experimentalScreencast;
+delete startCliOptions.categoryEmulation;
+delete startCliOptions.categoryPerformance;
+delete startCliOptions.categoryNetwork;
+delete startCliOptions.categoryExtensions;
+// Always on in CLI.
+delete startCliOptions.experimentalStructuredContent;
+// Change the defaults.
+if (!('default' in cliOptions.headless)) {
+    throw new Error('headless cli option unexpectedly does not have a default');
+}
+if ('default' in cliOptions.isolated) {
+    throw new Error('headless cli option unexpectedly does not have a default');
+}
+startCliOptions.headless.default = true;
+const y = yargs(hideBin(process.argv))
+    .scriptName('chrome-devtools')
+    .showHelpOnFail(true)
+    .usage('chrome-devtools <command> [...args] --flags')
+    .usage(`Run 'chrome-devtools <command> --help' for help on the specific command.`)
+    .demandCommand()
+    .version(VERSION)
+    .strict()
+    .help(true)
+    .wrap(120);
+y.command('start', 'Start or restart chrome-devtools-mcp', y => y
+    .options(startCliOptions)
+    .example('$0 start --browserUrl http://localhost:9222', 'Start the server connecting to an existing browser')
+    .strict(), async (argv) => {
+    if (isDaemonRunning()) {
+        await stopDaemon();
+    }
+    // Defaults but we do not want to affect the yargs conflict resolution.
+    if (argv.isolated === undefined) {
+        argv.isolated = true;
+    }
+    if (argv.headless === undefined) {
+        argv.headless = true;
+    }
+    const args = serializeArgs(cliOptions, argv);
+    await start(args);
+    process.exit(0);
+}).strict(); // Re-enable strict validation for other commands; this is applied to the yargs instance itself
+y.command('status', 'Checks if chrome-devtools-mcp is running', async () => {
+    if (isDaemonRunning()) {
+        console.log('chrome-devtools-mcp daemon is running.');
+        const response = await sendCommand({
+            method: 'status',
+        });
+        if (response.success) {
+            const data = JSON.parse(response.result);
+            console.log(`pid=${data.pid} socket=${data.socketPath} start-date=${data.startDate} version=${data.version}`);
+            console.log(`args=${JSON.stringify(data.args)}`);
+        }
+        else {
+            console.error('Error:', response.error);
+            process.exit(1);
+        }
+    }
+    else {
+        console.log('chrome-devtools-mcp daemon is not running.');
+    }
+    process.exit(0);
+});
+y.command('stop', 'Stop chrome-devtools-mcp if any', async () => {
+    if (!isDaemonRunning()) {
+        process.exit(0);
+    }
+    await stopDaemon();
+    process.exit(0);
+});
+for (const [commandName, commandDef] of Object.entries(commands)) {
+    const args = commandDef.args;
+    const requiredArgNames = Object.keys(args).filter(name => args[name].required);
+    const optionalArgNames = Object.keys(args).filter(name => !args[name].required);
+    let commandStr = commandName;
+    for (const arg of requiredArgNames) {
+        commandStr += ` <${arg}>`;
+    }
+    for (const arg of optionalArgNames) {
+        commandStr += ` [--${arg}]`;
+    }
+    y.command(commandStr, commandDef.description, y => {
+        y.option('output-format', {
+            choices: ['md', 'json'],
+            default: 'md',
+        });
+        for (const [argName, opt] of Object.entries(args)) {
+            const type = opt.type === 'integer' || opt.type === 'number'
+                ? 'number'
+                : opt.type === 'boolean'
+                    ? 'boolean'
+                    : opt.type === 'array'
+                        ? 'array'
+                        : 'string';
+            if (opt.required) {
+                const options = {
+                    describe: opt.description,
+                    type: type,
+                };
+                if (opt.default !== undefined) {
+                    options.default = opt.default;
+                }
+                if (opt.enum) {
+                    options.choices = opt.enum;
+                }
+                y.positional(argName, options);
+            }
+            else {
+                const options = {
+                    describe: opt.description,
+                    type: type,
+                };
+                if (opt.default !== undefined) {
+                    options.default = opt.default;
+                }
+                if (opt.enum) {
+                    options.choices = opt.enum;
+                }
+                y.option(argName, options);
+            }
+        }
+    }, async (argv) => {
+        try {
+            if (!isDaemonRunning()) {
+                await start([]);
+            }
+            const commandArgs = {};
+            for (const [argName, argDef] of Object.entries(args)) {
+                if (argName in argv) {
+                    commandArgs[argName] = normalizeCommandArgValue(commandName, argName, argDef.type, argv[argName]);
+                }
+            }
+            const response = await sendCommand({
+                method: 'invoke_tool',
+                tool: commandName,
+                args: commandArgs,
+            });
+            if (response.success) {
+                console.log(await handleResponse(JSON.parse(response.result), argv['output-format']));
+            }
+            else {
+                console.error('Error:', response.error);
+                process.exit(1);
+            }
+        }
+        catch (error) {
+            console.error('Failed to execute command:', error);
+            process.exit(1);
+        }
+    });
+}
+await y.parse();