Skip to content

Chrome DevTools for coding agents

chore(config): support reloadable configurations (#3048)

Nikolay Vitkovc84b687a0725
diff --git a/src/bin/chrome-devtools.ts b/src/bin/chrome-devtools.ts
index 15ef405f..13900d33 100644
--- a/src/bin/chrome-devtools.ts
+++ b/src/bin/chrome-devtools.ts
@@ -230,7 +230,9 @@ for (const [commandName, commandDef] of Object.entries(commands)) {
type: type as Options['type'],
};
if (opt.default !== undefined) {
- options.default = opt.default;
+ // 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>;
diff --git a/src/config/ConfigParser.ts b/src/config/ConfigParser.ts
index 355b356e..a4381ba3 100644
--- a/src/config/ConfigParser.ts
+++ b/src/config/ConfigParser.ts
@@ -18,6 +18,7 @@ import {
CONFLICTING_ARGS,
IMPLICATIONS,
DEFAULT_FILESYSTEM_ROOT,
+ isReloadableOption,
withoutDefaults,
} from './mcp-options.js';
import {ConfigLocator} from './ConfigLocator.js';
@@ -41,21 +42,47 @@ function stripYargsPositionalArgs<T extends {_?: unknown; $0?: unknown}>(
export type ParsedArguments = InferredOptionTypes<typeof mcpOptions>;
+function isMcpOptionKey(key: string): key is keyof ParsedArguments {
+ return key in mcpOptions;
+}
+
+function copyOption<K extends keyof ParsedArguments>(
+ target: Partial<ParsedArguments>,
+ source: Partial<ParsedArguments>,
+ key: K,
+): void {
+ if (key in source) {
+ target[key] = source[key];
+ } else {
+ delete target[key];
+ }
+}
+
+const explicitArgsByParsed = new WeakMap<
+ ParsedArguments,
+ {parser: ConfigParser; explicitArgs: Partial<ParsedArguments>}
+>();
+
export class ConfigParser {
#configPath?: string;
+ #usageStatisticsNoticeShown = false;
readonly configLocator: ConfigLocator;
- /**
- * @param configLocator Finds the config file when `--config` is not passed.
- * Config file discovery is off without it, for example in tests.
- */
constructor(
private version: string,
private argv = process.argv,
private env = process.env,
private exitProcess = true,
+ configLocator?: ConfigLocator,
) {
- this.configLocator = new ConfigLocator();
+ this.configLocator = configLocator ?? new ConfigLocator();
+ }
+
+ /**
+ * The config file resolved by the last `parse()` call, if any.
+ */
+ get configPath(): string | undefined {
+ return this.#configPath;
}
buildCliParser(
@@ -131,7 +158,7 @@ export class ConfigParser {
* Step 4: rejects mutually exclusive inputs. Only explicit inputs are checked,
* so defaults never conflict.
*/
- validateConflicts(explicitArgs: Partial<ParsedArguments>): void {
+ static validateConflicts(explicitArgs: Partial<ParsedArguments>): void {
const activeArgs = new Set<string>();
for (const [key, val] of Object.entries(explicitArgs)) {
if (val !== undefined && val !== false) {
@@ -149,7 +176,7 @@ export class ConfigParser {
}
}
- validateImplications(explicitArgs: Partial<ParsedArguments>): void {
+ static validateImplications(explicitArgs: Partial<ParsedArguments>): void {
for (const [key, implied] of IMPLICATIONS) {
const isKeySet =
explicitArgs[key] !== undefined && explicitArgs[key] !== false;
@@ -219,9 +246,12 @@ export class ConfigParser {
}
if (this.env['CI'] || this.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.",
- );
+ if (!this.#usageStatisticsNoticeShown) {
+ this.#usageStatisticsNoticeShown = true;
+ console.error(
+ "turning off usage statistics. process.env['CI'] || process.env['CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS'] is set.",
+ );
+ }
resolvedArgs.usageStatistics = false;
}
@@ -235,13 +265,18 @@ export class ConfigParser {
// The merge and the default loop lose the static type that yargs infers from
// `mcpOptions`. Every value was produced by the same option definitions (CLI
// parser, strict config-file parser, option defaults), so the shape matches.
- return resolvedArgs as unknown as ParsedArguments;
+ const parsed: ParsedArguments = resolvedArgs as unknown as ParsedArguments;
+ explicitArgsByParsed.set(parsed, {
+ parser: this,
+ explicitArgs: {...explicitArgs},
+ });
+ return parsed;
}
parse(): ParsedArguments {
try {
const cliArgs = this.parseCliArgs();
- this.#configPath = cliArgs.config ?? this.configLocator?.locate(this.env);
+ this.#configPath = cliArgs.config ?? this.configLocator.locate(this.env);
this.warnUnknownArgs(cliArgs);
return this.#resolve(cliArgs);
} catch (error) {
@@ -266,13 +301,40 @@ export class ConfigParser {
const configPath = this.#configPath;
const configFileArgs = configPath ? this.parseConfigFile(configPath) : {};
// Step 3: merges the explicit inputs. The CLI wins over the config file.
- const explicitArgs = {
+ const explicitArgs: Partial<ParsedArguments> = {
...configFileArgs,
...cliArgs,
...(configPath ? {config: configPath} : {}),
};
- this.validateConflicts(explicitArgs);
- this.validateImplications(explicitArgs);
+ ConfigParser.validateConflicts(explicitArgs);
+ ConfigParser.validateImplications(explicitArgs);
return this.applyDefaults(explicitArgs);
}
+ /**
+ * Merges explicit inputs so that a running server continues with `next` for
+ * reloadable options and `previous` for everything else, then validates and
+ * applies defaults.
+ */
+ static mergeReloadableOptions(
+ previous: ParsedArguments,
+ next: ParsedArguments,
+ ): ParsedArguments {
+ const previousEntry = explicitArgsByParsed.get(previous);
+ const nextEntry = explicitArgsByParsed.get(next);
+ const previousExplicit: Partial<ParsedArguments> =
+ previousEntry?.explicitArgs ?? previous;
+ const nextExplicit: Partial<ParsedArguments> =
+ nextEntry?.explicitArgs ?? next;
+ const merged: Partial<ParsedArguments> = {...previousExplicit};
+ for (const name of Object.keys(mcpOptions)) {
+ if (isMcpOptionKey(name) && isReloadableOption(name)) {
+ copyOption(merged, nextExplicit, name);
+ }
+ }
+ ConfigParser.validateConflicts(merged);
+ ConfigParser.validateImplications(merged);
+ const parser =
+ nextEntry?.parser ?? previousEntry?.parser ?? new ConfigParser('');
+ return parser.applyDefaults(merged);
+ }
}
diff --git a/src/config/category-options.ts b/src/config/category-options.ts
index 5e4aec0c..c393a0dd 100644
--- a/src/config/category-options.ts
+++ b/src/config/category-options.ts
@@ -12,6 +12,7 @@ export interface CategoryOption {
default?: boolean;
defaultDescription?: string;
hidden?: boolean;
+ reloadable?: boolean;
}
export type CategoryFlagName<T extends ToolCategory = ToolCategory> =
@@ -27,6 +28,7 @@ const categoryOverrides: Record<
describe?: string;
hidden?: boolean;
offByDefault?: boolean;
+ reloadable?: boolean;
}
> = {
[ToolCategory.INPUT]: {},
@@ -44,6 +46,7 @@ const categoryOverrides: Record<
[ToolCategory.EXTENSIONS]: {
describe: 'Set to true to include tools related to extensions.',
offByDefault: true,
+ reloadable: false,
},
[ToolCategory.THIRD_PARTY]: {
describe:
@@ -66,6 +69,7 @@ function createOption(category: ToolCategory): CategoryOption {
return {
type: 'boolean',
describe,
+ reloadable: true,
...overrides,
// Off-by-default categories have no default so that they stay unset unless
// passed explicitly. This keeps them out of conflict checks and lets
diff --git a/src/config/mcp-options.ts b/src/config/mcp-options.ts
index 47e41424..a62acc80 100644
--- a/src/config/mcp-options.ts
+++ b/src/config/mcp-options.ts
@@ -13,6 +13,14 @@ import {getBrowserOptions} from './browser-options.js';
import {puppeteerOptions} from './puppeteer-options.js';
import {toolOptions} from './tool-options.js';
+export interface McpOption extends YargsOptions {
+ /**
+ * Whether changes to this option in a config file can be applied to a running
+ * server without restarting it.
+ */
+ reloadable?: boolean;
+}
+
export const DEFAULT_FILESYSTEM_ROOT = [os.tmpdir()];
export const mcpOptions = {
@@ -30,6 +38,7 @@ export const mcpOptions = {
describe:
'Require pageId on page-scoped tools and route requests by page ID (useful for concurrent agent sessions). Use --no-page-id-routing to disable.',
default: true,
+ reloadable: true,
},
devtoolsComments: {
type: 'boolean',
@@ -37,6 +46,7 @@ export const mcpOptions = {
'Whether to enable DevTools comments tools. Internal WIP feature.',
hidden: true,
default: false,
+ reloadable: true,
},
experimentalDevtools: {
type: 'boolean',
@@ -49,17 +59,20 @@ export const mcpOptions = {
default: false,
describe:
'Whether to enable coordinate-based tools such as click_at(x,y). Usually requires a computer-use model able to produce accurate coordinates by looking at screenshots.',
+ reloadable: true,
},
memoryDebugging: {
type: 'boolean',
default: false,
describe: 'Whether to enable memory debugging tools.',
alias: 'experimentalMemory',
+ reloadable: true,
},
experimentalStructuredContent: {
type: 'boolean',
default: false,
describe: 'Whether to output structured formatted content.',
+ reloadable: true,
},
experimentalToonFormat: {
type: 'boolean',
@@ -67,6 +80,7 @@ export const mcpOptions = {
describe:
'Deprecated: use --experimentalDataFormat=toon instead. Whether to format structured data using TOON (requires @toon-format/toon).',
hidden: true,
+ reloadable: true,
},
experimentalDataFormat: {
type: 'string',
@@ -75,33 +89,39 @@ export const mcpOptions = {
'Override format for structured data in text responses. Default uses built-in formatters. "toon" (requires @toon-format/toon) or "gcf" (requires @blackwell-systems/gcf) replace structured content with the specified encoding.',
choices: ['default', 'toon', 'gcf'] as const,
hidden: true,
+ reloadable: true,
},
experimentalIncludeAllPages: {
type: 'boolean',
default: false,
describe:
'Whether to include all kinds of pages such as webviews or background pages as pages.',
+ reloadable: true,
},
experimentalInteropTools: {
type: 'boolean',
default: false,
describe: 'Whether to enable interoperability tools',
hidden: true,
+ reloadable: true,
},
experimentalScreencast: {
type: 'boolean',
default: false,
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.',
+ reloadable: true,
},
experimentalFfmpegPath: {
type: 'string',
describe: 'Path to ffmpeg executable for screencast recording.',
+ reloadable: true,
},
experimentalScreencastFps: {
type: 'number',
describe:
'Frames per second to use for screencast recording. Lower values can reduce memory pressure on pages that produce frames faster than ffmpeg can encode them.',
+ reloadable: true,
coerce: (value: number | undefined) => {
if (value === undefined) {
return;
@@ -119,6 +139,7 @@ export const mcpOptions = {
default: true,
describe:
'Set to false to disable sending URLs from performance traces to CrUX API to get field performance data.',
+ reloadable: true,
},
usageStatistics: {
type: 'boolean',
@@ -131,18 +152,21 @@ export const mcpOptions = {
default: true,
describe:
'Set to false to disable the server entry points for evaluating caller-provided JavaScript: evaluation tools (evaluate_script and slim evaluate) are disabled, the initScript parameter in navigate_page is turned off, and navigating to javascript:, data:, or vbscript: URLs is disallowed. This is not a JavaScript sandbox: page scripts and JavaScript triggered through other permitted browser interactions (e.g. clicks or typing) still run. If --experimentalDevtools is also enabled, the DevTools UI, including the Console that evaluates code in the inspected page, can be automated and is not restricted by this option. The client remains responsible for validating tool calls and parameters.',
+ reloadable: true,
},
fileNavigations: {
type: 'boolean',
default: true,
describe:
'Set to false to disallow navigating to file: URLs. When disabled, new_page, navigate_page and the slim navigate tool reject file: URLs, including view-source: URLs that target them. This restricts navigations the server performs. It is not a filesystem sandbox: it does not affect pages the browser already had open when the server connected, and the browser can reach the filesystem by other means. Use OS sandboxing for full filesystem confinement.',
+ reloadable: true,
},
sourceMaps: {
type: 'boolean',
default: true,
describe:
'Whether to enable source maps in DevTools. Use --no-source-maps to disable.',
+ reloadable: true,
},
clearcutEndpoint: {
type: 'string',
@@ -165,6 +189,7 @@ export const mcpOptions = {
default: false,
describe:
'Exposes a "slim" set of 3 tools covering navigation, script execution and screenshots only. Useful for basic browser tasks.',
+ reloadable: true,
},
viaCli: {
type: 'boolean',
@@ -178,6 +203,7 @@ export const mcpOptions = {
describe:
'If true, redacts some of the network headers considered sensitive before returning to the client.',
default: false,
+ reloadable: true,
},
allowUnrestrictedPaths: {
type: 'boolean',
@@ -188,6 +214,7 @@ export const mcpOptions = {
'the roots capability. By default, tools that read or write local files are restricted to the OS temp directory when ' +
'no roots are configured. Use this only when connecting a trusted local client that does not implement ' +
'MCP roots and requires access to paths outside the temp directory.',
+ reloadable: true,
},
filesystemRoot: {
type: 'array',
@@ -197,6 +224,7 @@ export const mcpOptions = {
defaultDescription: 'OS temp directory',
describe:
'A directory that filesystem tools are allowed to access. May be specified more than once.',
+ reloadable: true,
},
config: {
type: 'string',
@@ -208,7 +236,7 @@ export const mcpOptions = {
return path.resolve(configPath);
},
},
-} satisfies Record<string, YargsOptions>;
+} satisfies Record<string, McpOption>;
export function getMcpOptionsForViaCli(): Record<
keyof typeof mcpOptions,
@@ -364,3 +392,8 @@ export function withoutDefaults(
}
return result;
}
+
+export function isReloadableOption(name: keyof typeof mcpOptions): boolean {
+ const option: McpOption = mcpOptions[name];
+ return option.reloadable === true;
+}
diff --git a/src/config/tool-options.ts b/src/config/tool-options.ts
index 71b0295d..c78c7956 100644
--- a/src/config/tool-options.ts
+++ b/src/config/tool-options.ts
@@ -6,6 +6,10 @@
import type {YargsOptions} from '../third_party/index.js';
+interface ToolOption extends YargsOptions {
+ reloadable: true;
+}
+
/**
* Options that change the default behavior of tools.
*/
@@ -16,11 +20,13 @@ export const toolOptions = {
description:
'Override the default output format used by take_screenshot when the caller does not specify one. JPEG and WebP are ~3-5x smaller than PNG, which reduces transfer and storage size. To reduce context size use --screenshotMaxWidth / --screenshotMaxHeight, since image tokens scale with dimensions rather than encoded bytes. Unset preserves the existing default ("png").',
choices: ['jpeg', 'png', 'webp'] as const,
+ reloadable: true,
},
screenshotQuality: {
type: 'number',
description:
'Override the default compression quality (0-100) used by take_screenshot for JPEG and WebP when the caller does not specify one. Lower values mean smaller files. Ignored for PNG. Unset preserves the Puppeteer default.',
+ reloadable: true,
coerce: (value: number | undefined) => {
if (value === undefined) {
return;
@@ -37,6 +43,7 @@ export const toolOptions = {
type: 'number',
description:
'Maximum width in pixels for screenshots. If the captured image is wider, it is downscaled (preserving aspect ratio) before being returned. Reduces context size in AI conversations. Unset means no resize.',
+ reloadable: true,
coerce: (value: number | undefined) => {
if (value === undefined) {
return;
@@ -53,6 +60,7 @@ export const toolOptions = {
type: 'number',
description:
'Maximum height in pixels for screenshots. If the captured image is taller, it is downscaled (preserving aspect ratio) before being returned. Can be combined with --screenshot-max-width; the smaller scale factor wins. Unset means no resize.',
+ reloadable: true,
coerce: (value: number | undefined) => {
if (value === undefined) {
return;
@@ -65,4 +73,4 @@ export const toolOptions = {
return value;
},
},
-} satisfies Record<string, YargsOptions>;
+} satisfies Record<string, ToolOption>;
diff --git a/tests/config/mcp-options.test.ts b/tests/config/mcp-options.test.ts
index 6f456ea2..757b02fb 100644
--- a/tests/config/mcp-options.test.ts
+++ b/tests/config/mcp-options.test.ts
@@ -20,13 +20,6 @@ describe('mcp-options steps', () => {
const parser = new ConfigParser('0.0.0');
- describe('constructor', () => {
- it('initializes configLocator', () => {
- const testParser = new ConfigParser('0.0.0');
- assert.ok(testParser.configLocator instanceof ConfigLocator);
- });
- });
-
describe('parseCliArgs', () => {
it('returns only explicitly passed flags', () => {
const args = new ConfigParser('0.0.0', [
@@ -81,11 +74,11 @@ describe('mcp-options steps', () => {
describe('validateConflicts', () => {
it('accepts a single argument from a conflict group', () => {
- parser.validateConflicts({browserUrl: 'http://localhost:9222'});
+ ConfigParser.validateConflicts({browserUrl: 'http://localhost:9222'});
});
it('ignores false and undefined values', () => {
- parser.validateConflicts({
+ ConfigParser.validateConflicts({
browserUrl: 'http://localhost:9222',
wsEndpoint: undefined,
categoryExtensions: false,
@@ -95,7 +88,7 @@ describe('mcp-options steps', () => {
it('rejects two arguments from the same group', () => {
assert.throws(
() =>
- parser.validateConflicts({
+ ConfigParser.validateConflicts({
browserUrl: 'http://localhost:9222',
channel: 'canary',
}),
@@ -105,11 +98,11 @@ describe('mcp-options steps', () => {
describe('validateImplications', () => {
it('accepts when implying key is not set', () => {
- parser.validateImplications({wsEndpoint: 'ws://localhost:9222'});
+ ConfigParser.validateImplications({wsEndpoint: 'ws://localhost:9222'});
});
it('accepts when both implying and implied keys are set', () => {
- parser.validateImplications({
+ ConfigParser.validateImplications({
wsHeaders: {Auth: 'token'},
wsEndpoint: 'ws://localhost:9222',
});
@@ -117,7 +110,7 @@ describe('mcp-options steps', () => {
it('rejects when implying key is set but implied key is missing', () => {
assert.throws(
- () => parser.validateImplications({wsHeaders: {Auth: 'token'}}),
+ () => ConfigParser.validateImplications({wsHeaders: {Auth: 'token'}}),
/Implications failed:\n {2}wsHeaders -> wsEndpoint/,
);
});
@@ -125,7 +118,7 @@ describe('mcp-options steps', () => {
it('rejects when implying key is set but implied key is negated', () => {
assert.throws(
() =>
- parser.validateImplications({
+ ConfigParser.validateImplications({
experimentalFfmpegPath: '/bin/ffmpeg',
experimentalScreencast: false,
}),
@@ -197,13 +190,32 @@ describe('mcp-options steps', () => {
});
assert.strictEqual(args.usageStatistics, false);
});
+
+ it('prints the usage statistics notice once', () => {
+ const consoleError = sinon.stub(console, 'error');
+ const parser = new ConfigParser('0.0.0', [], {CI: 'true'});
+
+ parser.applyDefaults({});
+ const args = parser.applyDefaults({});
+
+ assert.strictEqual(args.usageStatistics, false);
+ sinon.assert.calledOnce(consoleError);
+ });
});
describe('config discovery', () => {
- it('does not discover a config file without a locator', () => {
- const parser = new ConfigParser('0.0.0', ['node', 'main.js'], {}, false);
- sinon.stub(parser.configLocator, 'locate').returns(undefined);
+ it('does not discover a config file when locator returns undefined', () => {
+ const locator = new ConfigLocator();
+ sinon.stub(locator, 'locate').returns(undefined);
+ const parser = new ConfigParser(
+ '0.0.0',
+ ['node', 'main.js'],
+ {},
+ false,
+ locator,
+ );
assert.strictEqual(parser.parse().config, undefined);
+ assert.strictEqual(parser.configPath, undefined);
});
it('uses the config file found by the locator', () => {
@@ -212,15 +224,13 @@ describe('mcp-options steps', () => {
'cd4a.config.json',
);
const parser = new ConfigParser('0.0.0', ['node', 'main.js'], {}, false);
- const locateStub = sinon
- .stub(parser.configLocator, 'locate')
- .returns(configFile.path);
+ sinon.stub(parser.configLocator, 'locate').returns(configFile.path);
const args = parser.parse();
assert.strictEqual(args.headless, true);
assert.strictEqual(args.config, configFile.path);
- sinon.assert.calledOnce(locateStub);
+ assert.strictEqual(parser.configPath, configFile.path);
});
it('prefers --config over a discovered config file', () => {
@@ -300,4 +310,83 @@ describe('mcp-options steps', () => {
assert.throws(() => parser.reload(), /Invalid JSON config file/);
});
});
+
+ describe('mergeReloadableOptions', () => {
+ function parseArgs(argv: string[] = []) {
+ const locator = new ConfigLocator();
+ sinon.stub(locator, 'locate').returns(undefined);
+ return new ConfigParser(
+ '0.0.0',
+ ['node', 'main.js', ...argv],
+ {},
+ false,
+ locator,
+ ).parse();
+ }
+
+ it('applies reloadable options', () => {
+ const merged = ConfigParser.mergeReloadableOptions(
+ parseArgs(),
+ parseArgs([
+ '--memoryDebugging',
+ '--no-category-network',
+ '--no-file-navigations',
+ '--slim',
+ ]),
+ );
+
+ assert.strictEqual(merged.memoryDebugging, true);
+ assert.strictEqual(merged.categoryNetwork, false);
+ assert.strictEqual(merged.fileNavigations, false);
+ assert.strictEqual(merged.slim, true);
+ });
+
+ it('keeps restart-required options', () => {
+ const merged = ConfigParser.mergeReloadableOptions(
+ parseArgs(),
+ parseArgs([
+ '--categoryExtensions',
+ '--blockedUrlPattern=https://example.com/*',
+ '--experimentalDevtools',
+ ]),
+ );
+
+ assert.strictEqual(merged.categoryExtensions, undefined);
+ assert.strictEqual(merged.blockedUrlPattern, undefined);
+ assert.strictEqual(merged.experimentalDevtools, false);
+ });
+
+ it('keeps options derived from restart-required options', () => {
+ const previous = parseArgs(['--viaCli']);
+ const next = parseArgs([
+ '--viaCli',
+ '--browserUrl=http://127.0.0.1:9222',
+ ]);
+
+ const merged = ConfigParser.mergeReloadableOptions(previous, next);
+
+ assert.strictEqual(merged.categoryExtensions, true);
+ assert.strictEqual(merged.browserUrl, undefined);
+ });
+
+ it('rejects reloadable options that conflict with startup restart-required options', () => {
+ const previous = parseArgs(['--browserUrl=http://127.0.0.1:9222']);
+ const next = parseArgs(['--categoryPwa']);
+
+ assert.throws(
+ () => ConfigParser.mergeReloadableOptions(previous, next),
+ /Arguments categoryPwa and browserUrl are mutually exclusive/,
+ );
+ });
+
+ it('does not conflict with default options', () => {
+ const merged = ConfigParser.mergeReloadableOptions(
+ parseArgs(),
+ parseArgs(['--allow-unrestricted-paths']),
+ );
+
+ assert.strictEqual(merged.allowUnrestrictedPaths, true);
+ assert.strictEqual(merged.filesystemRoot, DEFAULT_FILESYSTEM_ROOT);
+ });
+ });
});