Chrome DevTools for coding agents
refactor: extract browser options (#2654)
Nikolay Vitkova918b7b4086b
diff --git a/docs/configuration.md b/docs/configuration.mdindex 6b911086..3132f642 100644--- a/docs/configuration.md+++ b/docs/configuration.md@@ -80,6 +80,21 @@ The Chrome DevTools MCP server supports the following configuration option:- **Choices:** `canary`, `dev`, `beta`, `stable`- **Default:** `false`+- **`--proxyServer`/ `--proxy-server`**+ Proxy server configuration for Chrome passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details.+ - **Type:** string+ - **Default:** `false`++- **`--chromeArg`/ `--chrome-arg`**+ Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.+ - **Type:** array+ - **Default:** `false`++- **`--ignoreDefaultChromeArg`/ `--ignore-default-chrome-arg`**+ Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.+ - **Type:** array+ - **Default:** `false`+- **`--logFile`/ `--log-file`**Path to a file to write debug logs to. Set the env variable `DEBUG` to `*` to enable verbose logs. Useful for submitting bug reports.- **Type:** string@@ -90,11 +105,6 @@ The Chrome DevTools MCP server supports the following configuration option:- **Type:** string- **Default:** `false`-- **`--proxyServer`/ `--proxy-server`**- Proxy server configuration for Chrome passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details.- - **Type:** string- - **Default:** `false`-- **`--acceptInsecureCerts`/ `--accept-insecure-certs`**If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.- **Type:** boolean@@ -145,11 +155,6 @@ The Chrome DevTools MCP server supports the following configuration option:- **Type:** number- **Default:** `false`-- **`--chromeArg`/ `--chrome-arg`**- Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.- - **Type:** array- - **Default:** `false`-- **`--blockedUrlPattern`/ `--blocked-url-pattern`**Restricts browser's network access by blocking specified URL patterns (uses https://urlpattern.spec.whatwg.org/). Silently detaches from targets with blocked URLs upon connection, and blocks runtime requests (including navigations and subresources). Accepts an array of patterns.- **Type:** array@@ -160,11 +165,6 @@ The Chrome DevTools MCP server supports the following configuration option:- **Type:** array- **Default:** `false`-- **`--ignoreDefaultChromeArg`/ `--ignore-default-chrome-arg`**- Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.- - **Type:** array- - **Default:** `false`-- **`--performanceCrux`/ `--performance-crux`**Set to false to disable sending URLs from performance traces to CrUX API to get field performance data.- **Type:** booleandiff --git a/src/config/browser-options.ts b/src/config/browser-options.tsnew file mode 100644index 00000000..6fbfac53--- /dev/null+++ b/src/config/browser-options.ts@@ -0,0 +1,136 @@+/**+ * @license+ * Copyright 2026 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */++import type {YargsOptions} from '../third_party/index.js';++export const browserOptions = {+ autoConnect: {+ type: 'boolean',+ 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 remote debugging server to be started in the Chrome instance via chrome://inspect/#remote-debugging.',+ conflicts: ['isolated', 'executablePath'],+ default: false,+ coerce: (value: boolean | undefined) => {+ if (!value) {+ return;+ }+ return value;+ },+ },+ browserUrl: {+ type: 'string',+ description:+ 'Connect to a running, debuggable Chrome instance (e.g. `http://127.0.0.1:9222`). For more details see: https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/advanced-usage.md#connecting-to-a-running-chrome-instance.',+ alias: 'u',+ conflicts: ['wsEndpoint'],+ coerce: (url: string | undefined) => {+ if (!url) {+ return;+ }+ try {+ new URL(url);+ } catch {+ throw new Error(`Provided browserUrl ${url} is not valid URL.`);+ }+ return url;+ },+ },+ wsEndpoint: {+ type: 'string',+ description:+ 'WebSocket endpoint to connect to a running Chrome instance (e.g., ws://127.0.0.1:9222/devtools/browser/<id>). Alternative to --browserUrl.',+ alias: 'w',+ conflicts: ['browserUrl'],+ coerce: (url: string | undefined) => {+ if (!url) {+ return;+ }+ try {+ const parsed = new URL(url);+ if (parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:') {+ throw new Error(+ `Provided wsEndpoint ${url} must use ws:// or wss:// protocol.`,+ );+ }+ return url;+ } catch (error) {+ if ((error as Error).message.includes('ws://')) {+ throw error;+ }+ throw new Error(`Provided wsEndpoint ${url} is not valid URL.`);+ }+ },+ },+ wsHeaders: {+ type: 'string',+ description:+ 'Custom headers for WebSocket connection in JSON format (e.g., \'{"Authorization":"Bearer token"}\'). Only works with --wsEndpoint.',+ implies: 'wsEndpoint',+ coerce: (val: string | undefined) => {+ if (!val) {+ return;+ }+ try {+ const parsed = JSON.parse(val);+ if (typeof parsed !== 'object' || Array.isArray(parsed)) {+ throw new Error('Headers must be a JSON object');+ }+ return parsed as Record<string, string>;+ } catch (error) {+ throw new Error(+ `Invalid JSON for wsHeaders: ${(error as Error).message}`,+ );+ }+ },+ },+ 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', 'wsEndpoint'],+ alias: 'e',+ },+ isolated: {+ type: 'boolean',+ description:+ 'If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed. Defaults to false.',+ },+ userDataDir: {+ type: 'string',+ description:+ 'Path to the user data directory for Chrome. Default is $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE',+ conflicts: ['browserUrl', 'wsEndpoint', 'isolated'],+ },+ channel: {+ type: 'string',+ description:+ 'Specify a different Chrome channel that should be used. The default is the stable channel version.',+ choices: ['canary', 'dev', 'beta', 'stable'] as const,+ conflicts: ['browserUrl', 'wsEndpoint', 'executablePath'],+ },+ proxyServer: {+ type: 'string',+ description: `Proxy server configuration for Chrome passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details.`,+ },+ 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.',+ },+} satisfies Record<string, YargsOptions>;++export function getBrowserOptions(): typeof browserOptions {+ return browserOptions;+}diff --git a/src/config/mcp-options.ts b/src/config/mcp-options.tsindex d7c0d1ff..8fe83fb3 100644--- a/src/config/mcp-options.ts+++ b/src/config/mcp-options.ts@@ -11,117 +11,11 @@ import os from 'node:os';export const DEFAULT_FILESYSTEM_ROOT = [os.tmpdir()];import {getCategoryOptions} from './category-options.js';+import {getBrowserOptions} from './browser-options.js';export const mcpOptions = {...getCategoryOptions(),- autoConnect: {- type: 'boolean',- 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 remote debugging server to be started in the Chrome instance via chrome://inspect/#remote-debugging.',- conflicts: ['isolated', 'executablePath'],- default: false,- coerce: (value: boolean | undefined) => {- if (!value) {- return;- }- return value;- },- },- browserUrl: {- type: 'string',- description:- 'Connect to a running, debuggable Chrome instance (e.g. `http://127.0.0.1:9222`). For more details see: https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/advanced-usage.md#connecting-to-a-running-chrome-instance.',- alias: 'u',- conflicts: ['wsEndpoint'],- coerce: (url: string | undefined) => {- if (!url) {- return;- }- try {- new URL(url);- } catch {- throw new Error(`Provided browserUrl ${url} is not valid URL.`);- }- return url;- },- },- wsEndpoint: {- type: 'string',- description:- 'WebSocket endpoint to connect to a running Chrome instance (e.g., ws://127.0.0.1:9222/devtools/browser/<id>). Alternative to --browserUrl.',- alias: 'w',- conflicts: ['browserUrl'],- coerce: (url: string | undefined) => {- if (!url) {- return;- }- try {- const parsed = new URL(url);- if (parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:') {- throw new Error(- `Provided wsEndpoint ${url} must use ws:// or wss:// protocol.`,- );- }- return url;- } catch (error) {- if ((error as Error).message.includes('ws://')) {- throw error;- }- throw new Error(`Provided wsEndpoint ${url} is not valid URL.`);- }- },- },- wsHeaders: {- type: 'string',- description:- 'Custom headers for WebSocket connection in JSON format (e.g., \'{"Authorization":"Bearer token"}\'). Only works with --wsEndpoint.',- implies: 'wsEndpoint',- coerce: (val: string | undefined) => {- if (!val) {- return;- }- try {- const parsed = JSON.parse(val);- if (typeof parsed !== 'object' || Array.isArray(parsed)) {- throw new Error('Headers must be a JSON object');- }- return parsed as Record<string, string>;- } catch (error) {- throw new Error(- `Invalid JSON for wsHeaders: ${(error as Error).message}`,- );- }- },- },- 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', 'wsEndpoint'],- alias: 'e',- },- isolated: {- type: 'boolean',- description:- 'If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed. Defaults to false.',- },- userDataDir: {- type: 'string',- description:- 'Path to the user data directory for Chrome. Default is $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE',- conflicts: ['browserUrl', 'wsEndpoint', 'isolated'],- },- channel: {- type: 'string',- description:- 'Specify a different Chrome channel that should be used. The default is the stable channel version.',- choices: ['canary', 'dev', 'beta', 'stable'] as const,- conflicts: ['browserUrl', 'wsEndpoint', 'executablePath'],- },+ ...getBrowserOptions(),logFile: {type: 'string',describe:@@ -145,10 +39,6 @@ export const mcpOptions = {};},},- proxyServer: {- type: 'string',- description: `Proxy server configuration for Chrome passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details.`,- },acceptInsecureCerts: {type: 'boolean',description: `If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.`,@@ -229,11 +119,6 @@ export const mcpOptions = {return value;},},- chromeArg: {- type: 'array',- describe:- 'Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',- },blockedUrlPattern: {type: 'array',describe:@@ -246,11 +131,6 @@ export const mcpOptions = {"Restricts browser's network access by allowing only specified URL patterns (uses https://urlpattern.spec.whatwg.org/). Requires Chrome 149+. Silently detaches from targets with unallowed URLs upon connection, and blocks runtime requests (including navigations and subresources). Accepts an array of patterns.",conflicts: ['blockedUrlPattern'],},- ignoreDefaultChromeArg: {- type: 'array',- describe:- 'Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',- },performanceCrux: {type: 'boolean',default: true,