Skip to content

Chrome DevTools for coding agents

9.1 KB
Raw Blame
#!/usr/bin/env node

/**
 * @license
 * Copyright 2026 Google LLC
 * SPDX-License-Identifier: Apache-2.0
 */

import process from 'node:process';

import type {Options, PositionalOptions} from 'yargs';

import {
  startDaemon,
  stopDaemon,
  sendCommand,
  handleResponse,
  verifyDaemonVersion,
} from '../daemon/client.js';
import type {DaemonStatusResult} from '../daemon/types.js';
import {
  isDaemonRunning,
  serializeArgs,
  assertValidSessionId,
} from '../daemon/utils.js';
import {logDisclaimers} from '../utils/disclaimers.js';
import {hideBin, yargs} from '../third_party/cli.js';
import type {CallToolResult} from '../third_party/index.js';
import {checkForUpdates} from '../utils/check-for-updates.js';
import {VERSION} from '../version.js';

import {
  buildCommand,
  getCommandArgSpec,
  shieldLiteralArgs,
} from '../config/cli-commands.js';
import {commands} from '../config/cli-options.js';
import {getCliOptions} from '../config/mcp-options.js';

import {ConfigParser} from '../config/ConfigParser.js';

process.title = 'chrome-devtools';

await checkForUpdates(
  'Run `npm install -g chrome-devtools-mcp@latest` and `chrome-devtools start` to update and restart the daemon.',
);

const DEFAULT_CLI_ARGS = ['--viaCli'];

async function start(
  args: string[],
  sessionId: string,
  stopExisting = false,
): Promise<void> {
  const combinedArgs = [...DEFAULT_CLI_ARGS, ...args];
  // Validates the arguments and the config file before starting the daemon.
  const parsedArgs = new ConfigParser(VERSION, [
    process.execPath,
    process.argv[1],
    ...combinedArgs,
  ]).parse();
  if (stopExisting && isDaemonRunning(sessionId)) {
    await stopDaemon(sessionId);
  }
  await startDaemon(combinedArgs, sessionId);
  logDisclaimers(parsedArgs);
}

const {argv: cliArgs, restore: restoreLiteralArg} = shieldLiteralArgs(
  hideBin(process.argv),
  commandName => {
    const commandDef = commands[commandName];
    return commandDef ? getCommandArgSpec(commandDef.args) : undefined;
  },
);

const y = yargs(cliArgs)
  .locale('en') // Force English to ensure error string matching works in .fail, all custom messages we output are in English anyways
  .scriptName('chrome-devtools')
  .showHelpOnFail(true)
  .usage('chrome-devtools <command> [...args] --flags')
  .usage(
    `Run 'chrome-devtools <command> --help' for help on the specific command.`,
  )
  .option('sessionId', {
    type: 'string',
    description: 'Session ID for daemon scoping',
    default: process.env.CD4A_INTERNAL_DAEMON_SESSION_ID || '',
    hidden: true,
    coerce: (sessionId: string) => {
      assertValidSessionId(sessionId);
      return sessionId;
    },
  })
  .demandCommand()
  .version(VERSION)
  .strict()
  .help(true)
  .wrap(120)
  .fail((msg, err) => {
    if (msg) {
      console.error('Error:', msg);
      if (
        msg.includes('Not enough non-option arguments') ||
        msg.includes('Unknown argument') ||
        msg.includes('Unknown arguments')
      ) {
        console.error('\n=========================================');
        console.error('💡 TIP FOR AI AGENT / DEVELOPER:');
        console.error('In the `chrome-devtools` CLI:');
        console.error(
          '1. Required parameters MUST be passed as positional arguments (without flags).',
        );
        console.error(
          '   - INCORRECT: chrome-devtools click --pageId 1 --uid "1_2"',
        );
        console.error('   - CORRECT:   chrome-devtools click 1 "1_2"');
        console.error(
          '   - CORRECT:   chrome-devtools evaluate_script "() => document.title" --pageId 1',
        );
        console.error(
          '2. Optional parameters are passed as double-dash options/flags (e.g. --dblClick true), except optional positional parameters shown in command help.',
        );
        console.error(
          '3. Make sure to escape quotes properly for your shell environment.',
        );
        console.error(
          'Run `chrome-devtools <command> --help` to see exact positional and optional parameters.',
        );
        console.error('=========================================');
      }
    } else if (err) {
      console.error(err);
    }
    process.exit(1);
  });

y.command(
  'start',
  'Start or restart chrome-devtools-mcp',
  y =>
    y
      .options(getCliOptions())
      .example(
        '$0 start --browserUrl http://localhost:9222',
        'Start the server connecting to an existing browser',
      )
      .strict(),
  async argv => {
    const args = serializeArgs(getCliOptions(), argv);
    await start(args, argv.sessionId, /* stopExisting= */ true);
    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',
  y => y,
  async argv => {
    if (isDaemonRunning(argv.sessionId)) {
      console.log('chrome-devtools-mcp daemon is running.');
      const response = await sendCommand(
        {
          method: 'status',
        },
        argv.sessionId,
      );
      if (response.success) {
        const data: DaemonStatusResult = 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)}`);
        if (data.version !== VERSION) {
          console.warn(
            `Warning: Daemon server version (${data.version}) does not match CLI version (${VERSION}). Run 'chrome-devtools start' to update and restart the daemon.`,
          );
        }
      } 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',
  y => y,
  async argv => {
    const sessionId = argv.sessionId as string;
    if (!isDaemonRunning(sessionId)) {
      process.exit(0);
    }
    await stopDaemon(sessionId);
    process.exit(0);
  },
);

for (const [commandName, commandDef] of Object.entries(commands)) {
  const args = commandDef.args;
  const {command, usage} = buildCommand(commandName, args);

  y.command(
    command,
    commandDef.description,
    y => {
      y.usage(usage);
      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.positional) {
          const options: PositionalOptions = {
            describe: opt.description,
            type: type as PositionalOptions['type'],
          };
          if (opt.default !== undefined) {
            options.default = opt.default;
          }
          if (opt.enum) {
            options.choices = opt.enum as Array<string | number>;
          }
          y.positional(argName, options);
        } else {
          const options: Options = {
            describe: opt.description,
            type: type as Options['type'],
          };
          if (opt.default !== undefined) {
            // Document the default in --help without populating argv, so the
            // daemon applies its current tool schema and config defaults.
            options.defaultDescription = JSON.stringify(opt.default);
          }
          if (opt.enum) {
            options.choices = opt.enum as Array<string | number>;
          }
          y.option(argName, options);
        }
      }
    },
    async argv => {
      const sessionId = argv.sessionId as string;
      try {
        const daemonRunning = isDaemonRunning(sessionId);
        const versionWarningPromise = daemonRunning
          ? verifyDaemonVersion(sessionId, VERSION)
          : Promise.resolve(undefined);

        if (!daemonRunning) {
          await start([], sessionId);
        }

        const commandArgs: Record<string, unknown> = {};
        for (const argName of Object.keys(args)) {
          if (argName in argv) {
            commandArgs[argName] = restoreLiteralArg(argv[argName]);
          }
        }

        const response = await sendCommand(
          {
            method: 'invoke_tool',
            tool: commandName,
            args: commandArgs,
          },
          sessionId,
        );

        if (response.success) {
          console.log(
            await handleResponse(
              JSON.parse(response.result) as unknown as CallToolResult,
              argv['output-format'] as 'json' | 'md',
            ),
          );
        } else {
          console.error('Error:', response.error);
        }

        const versionWarning = await versionWarningPromise;
        if (versionWarning) {
          console.warn(versionWarning);
        }

        if (!response.success) {
          process.exit(1);
        }
      } catch (error) {
        console.error('Failed to execute command:', error);
        process.exit(1);
      }
    },
  );
}

await y.parse();