Chrome DevTools for coding agents
feat(config): add --watchConfig to reload config file changes (#3248)
Nikolay Vitkovb48561f6ca3b
diff --git a/docs/configuration.md b/docs/configuration.mdindex 6558bec8..8218c9ab 100644--- a/docs/configuration.md+++ b/docs/configuration.md@@ -243,6 +243,11 @@ The Chrome DevTools MCP server supports the following configuration option:Path to JSON configuration file.- **Type:** string+- **`--watchConfig`/ `--watch-config`**+ Watch the config file for changes and apply them without restarting. Tools (except --categoryExtensions) are enabled, disabled and updated on the fly; options used to launch or connect to the browser still require a restart.+ - **Type:** boolean+ - **Default:** `false`+<!-- END AUTO GENERATED OPTIONS -->Pass them via the `args` property in the JSON configuration. For example:@@ -296,6 +301,20 @@ Set the `CHROME_DEVTOOLS_MCP_NO_CONFIG_DISCOVERY` env variable to turn off thesearch for config files, for example in tests. A config file passed via`--config` is still used.+### Applying changes without a restart++Pass `--watchConfig` to reload the config file whenever it changes. Watching is+off by default. On a change, the server re-reads the file, updates the list of+available tools, and notifies the MCP client with+`notifications/tools/list_changed`. If the new file is invalid, the server logs+the error to stderr and keeps the previous configuration.++Tool categories (except `categoryExtensions`) and tool-specific options apply+immediately. Options that configure the browser, such as `headless`, `channel`,+`viewport`, `blockedUrlPattern`, or `categoryExtensions`, only apply after+restarting chrome-devtools-mcp. The server logs a message to stderr when a+change requires a restart.+### Locking down the configuration file from agent access> [!WARNING]diff --git a/src/bin/chrome-devtools-mcp-main.ts b/src/bin/chrome-devtools-mcp-main.tsindex 8185c467..8bcd9a5f 100644--- a/src/bin/chrome-devtools-mcp-main.ts+++ b/src/bin/chrome-devtools-mcp-main.ts@@ -85,6 +85,9 @@ process.on('SIGHUP', () => {});const server = await serverPromise;+if (args.watchConfig) {+ server.watchConfig(() => configParser.reloadConfig());+}const transport = new StdioServerTransport();await server.connect(transport);logger?.('Chrome DevTools MCP Server connected');diff --git a/src/config/ServerConfig.ts b/src/config/ServerConfig.tsindex a4f941a4..7a47c167 100644--- a/src/config/ServerConfig.ts+++ b/src/config/ServerConfig.ts@@ -4,6 +4,8 @@* SPDX-License-Identifier: Apache-2.0*/+import {isDeepStrictEqual} from 'node:util';+import type {InferredOptionTypes} from '../third_party/cli.js';import {yargs} from '../third_party/cli.js';@@ -306,6 +308,26 @@ export class ServerConfig implements ReadonlyServerConfig {});}+ /**+ * Returns the restart-required options whose resolved values differ between+ * this config and `next`.+ */+ getRestartRequiredChanges(next: ServerConfig): Array<keyof ParsedArguments> {+ const changed: Array<keyof ParsedArguments> = [];+ for (const name of Object.keys(mcpOptions)) {+ if (+ isMcpOptionKey(name) &&+ !isReloadableOption(name) &&+ (!isDeepStrictEqual(this.#fileArgs[name], next.#fileArgs[name]) ||+ !isDeepStrictEqual(this.#cliArgs[name], next.#cliArgs[name])) &&+ !isDeepStrictEqual(this.#resolved[name], next.#resolved[name])+ ) {+ changed.push(name);+ }+ }+ return changed;+ }+/*** Commits a previously validated {@link ServerConfig} snapshot in place so* all shared {@link ReadonlyServerConfig} readers observe the new values.diff --git a/src/config/mcp-options.ts b/src/config/mcp-options.tsindex ba3cbbd6..3018f90e 100644--- a/src/config/mcp-options.ts+++ b/src/config/mcp-options.ts@@ -238,6 +238,12 @@ export const mcpOptions = {return path.resolve(configPath);},},+ watchConfig: {+ type: 'boolean',+ default: false,+ describe:+ 'Watch the config file for changes and apply them without restarting. Tools (except --categoryExtensions) are enabled, disabled and updated on the fly; options used to launch or connect to the browser still require a restart.',+ },} satisfies Record<string, McpOption>;export const mcpOptionsForViaCli = {diff --git a/src/daemon/daemon.ts b/src/daemon/daemon.tsindex fcd615ea..42be3d8f 100644--- a/src/daemon/daemon.ts+++ b/src/daemon/daemon.ts@@ -151,6 +151,9 @@ async function setupMCPServer(): Promise<void> {browserManager,logFile,});+ if (args.watchConfig) {+ mcpServer.watchConfig(() => configParser.reloadConfig());+ }ClearcutLogger.get()?.setClientName(DAEMON_CLIENT_NAME);void ClearcutLogger.get()?.logDailyActiveIfNeeded();void ClearcutLogger.get()?.logServerStart(computeFlagUsage(args, mcpOptions));diff --git a/src/index.ts b/src/index.tsindex ac05d456..381e9e98 100644--- a/src/index.ts+++ b/src/index.ts@@ -10,6 +10,7 @@ import {pathToFileURL} from 'node:url';import {BrowserManager} from './BrowserManager.js';import type {ParsedArguments} from './config/ConfigParser.js';+import {ConfigWatcher} from './config/ConfigWatcher.js';import {DEFAULT_FILESYSTEM_ROOT} from './config/mcp-options.js';import {ServerConfig} from './config/ServerConfig.js';import {loadIssueDescriptions} from './devtools/issueDescriptions.js';@@ -32,6 +33,7 @@ import {ToolHandler} from './ToolHandler.js';import type {AnyToolDefinition} from './tools/ToolDefinition.js';import {createTools} from './tools/tools.js';import {logCruxDisclaimer} from './utils/disclaimers.js';+import {getErrorMessage} from './utils/errorHandling.js';import {logger} from './utils/logger.js';import {VERSION} from './version.js';@@ -76,6 +78,7 @@ export class McpServer {*/#awaitedInitialRoots = false;#toolMutex = new Mutex();+ #configWatcher?: ConfigWatcher;#tools = new Map<string, ToolEntry>();private constructor(config: ServerConfig, options: McpServerOptions) {@@ -178,8 +181,11 @@ export class McpServer {*/async applyConfig(config: ServerConfig): Promise<void> {using guard = await this.#toolMutex.acquire();+ await this.#applyConfigLocked(this.#config.mergeReloadable(config));+ }++ async #applyConfigLocked(nextConfig: ServerConfig): Promise<void> {const previousArgs = this.#config.resolved;- const nextConfig = this.#config.mergeReloadable(config);const nextArgs = nextConfig.resolved;// Build everything before committing so that a throwing tool factory// leaves the server untouched.@@ -214,10 +220,70 @@ export class McpServer {await this.#context.onConfigChanged(previousArgs);}+ /**+ * Watches the config file and applies its changes to the running server.+ *+ * @param reload Re-reads the config file and returns the new configuration.+ */+ watchConfig(reload: () => ServerConfig): void {+ const configPath = this.#config.configPath;+ if (!configPath) {+ console.error(+ '--watchConfig has no effect because no config file was found.',+ );+ return;+ }+ this.#configWatcher?.dispose();+ this.#configWatcher = undefined;+ const watcher = new ConfigWatcher(configPath, () =>+ this.#reloadConfig(watcher, configPath, reload),+ );+ try {+ watcher.start();+ } catch (err) {+ watcher.dispose();+ console.error(`Failed to watch ${configPath}: ${getErrorMessage(err)}`);+ return;+ }+ this.#configWatcher = watcher;+ }++ async #reloadConfig(+ watcher: ConfigWatcher,+ configPath: string,+ reload: () => ServerConfig,+ ): Promise<void> {+ using guard = await this.#toolMutex.acquire();+ if (this.#configWatcher !== watcher) {+ return;+ }+ let config: ServerConfig;+ let nextConfig: ServerConfig;+ try {+ config = reload();+ nextConfig = this.#config.mergeReloadable(config);+ } catch (err) {+ const message = `Keeping the previous configuration, failed to reload ${configPath}: ${getErrorMessage(err)}`;+ logger?.(message);+ console.error(message);+ return;+ }+ await this.#applyConfigLocked(nextConfig);+ const restartRequired = this.#config.getRestartRequiredChanges(config);+ logger?.(`Applied config changes from ${configPath}`);+ if (restartRequired.length > 0) {+ const message = `Restart chrome-devtools-mcp to fully apply changes to ${restartRequired.map(name => `--${name}`).join(', ')} from ${configPath}.`;+ logger?.(message);+ console.error(message);+ }+ }+/*** Closes the MCP connection and disposes internal context/listeners.*/async close(): Promise<void> {+ this.#configWatcher?.dispose();+ this.#configWatcher = undefined;try {this.#context.dispose();} catch (err) {diff --git a/src/telemetry/flag_usage_metrics.json b/src/telemetry/flag_usage_metrics.jsonindex d13eb04b..eb308d3d 100644--- a/src/telemetry/flag_usage_metrics.json+++ b/src/telemetry/flag_usage_metrics.json@@ -470,5 +470,13 @@{"name": "screencast_fps_present","flagType": "boolean"+ },+ {+ "name": "watch_config_present",+ "flagType": "boolean"+ },+ {+ "name": "watch_config",+ "flagType": "boolean"}]diff --git a/tests/McpServer.test.ts b/tests/McpServer.test.tsindex 155ac78c..7c27f41a 100644--- a/tests/McpServer.test.ts+++ b/tests/McpServer.test.ts@@ -15,13 +15,16 @@ import sinon from 'sinon';import {BrowserManager} from '../src/BrowserManager.js';import {getOffByDefaultCategories} from '../src/config/category-options.js';+import {ConfigLocator} from '../src/config/ConfigLocator.js';import {ConfigParser} from '../src/config/ConfigParser.js';+import {ConfigWatcher} from '../src/config/ConfigWatcher.js';import {mcpOptions} from '../src/config/mcp-options.js';import {McpServer} from '../src/index.js';import {McpContext} from '../src/McpContext.js';import {ClearcutLogger} from '../src/telemetry/ClearcutLogger.js';import type {ToolCategory} from '../src/tools/categories.js';import type {ToolDefinition} from '../src/tools/ToolDefinition.js';+import {saveLogsToFile} from '../src/utils/logger.js';import {createMockMcpContext, createMockPuppeteerBrowser} from './mocks.js';import {createTempFile} from './utils.js';@@ -31,10 +34,22 @@ describe('McpServer', () => {ClearcutLogger.resetForTesting();});+ function createConfigParser(argv: string[] = []) {+ const locator = new ConfigLocator();+ sinon.stub(locator, 'locate').returns(undefined);+ return new ConfigParser(+ '1.0.0',+ ['node', 'script.js', ...argv],+ {+ CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: 'true',+ },+ false,+ locator,+ );+ }+function parseConfig(argv: string[] = []) {- return new ConfigParser('1.0.0', ['node', 'script.js', ...argv], {- CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: 'true',- }).parseConfig();+ return createConfigParser(argv).parseConfig();}async function createTestServer(@@ -52,9 +67,10 @@ describe('McpServer', () => {sinon.stub(McpContext, 'create').returns(context);}- const config = parseConfig(extraArgs);+ const configParser = createConfigParser(extraArgs);+ const config = configParser.parseConfig();const server = await McpServer.from(config, {browserManager});- return {server, browserManager, context, config};+ return {server, browserManager, context, config, configParser};}async function connectClient(server: McpServer): Promise<Client> {@@ -528,6 +544,263 @@ describe('McpServer', () => {await server.close();});});++ describe('watchConfig', () => {+ async function watchTestServer(configPath: string) {+ const logStream = sinon.createStubInstance(fs.WriteStream);+ sinon.stub(fs, 'createWriteStream').returns(logStream);+ saveLogsToFile('test.log');+ let watchListener: fs.WatchListener<string> | undefined;+ const watchStub = sinon+ .stub(fs, 'watch')+ .callsFake(+ (+ filename: fs.PathLike,+ options?:+ | fs.WatchOptions+ | BufferEncoding+ | fs.WatchListener<string>+ | null,+ listener?: fs.WatchListener<string>,+ ) => {+ assert.ok(listener);+ watchListener = listener;+ return watchStub.wrappedMethod(filename, () => {}).unref();+ },+ );+ const clock = sinon.useFakeTimers({+ toFake: ['setTimeout', 'clearTimeout'],+ });+ const {server, context, config, configParser} = await createTestServer([+ '--config',+ configPath,+ ]);+ server.watchConfig(() => configParser.reloadConfig());+ logStream.write.resetHistory();++ async function updateConfigFile(content: string) {+ fs.writeFileSync(configPath, content);+ assert.ok(watchListener);+ watchListener('change', path.basename(configPath));+ await clock.tickAsync(200);+ }++ return {+ server,+ context,+ config,+ logStream,+ updateConfigFile,+ async [Symbol.asyncDispose]() {+ await server.close();+ },+ };+ }++ it('does not start a watcher when no config file was resolved', async () => {+ const startStub = sinon.stub(ConfigWatcher.prototype, 'start');+ const {server, configParser} = await createTestServer();+ const consoleError = sinon.stub(console, 'error');++ server.watchConfig(() => configParser.reloadConfig());++ sinon.assert.notCalled(startStub);+ sinon.assert.calledOnceWithExactly(+ consoleError,+ '--watchConfig has no effect because no config file was found.',+ );+ });++ it('logs an error and disposes the watcher when starting the watcher fails', async () => {+ using configFile = createTempFile('{}', 'cd4a.watch.error.json');+ sinon+ .stub(ConfigWatcher.prototype, 'start')+ .throws(new Error('watch limit reached'));+ const disposeStub = sinon.stub(ConfigWatcher.prototype, 'dispose');+ const {server, configParser} = await createTestServer([+ '--config',+ configFile.path,+ ]);+ const consoleError = sinon.stub(console, 'error');++ server.watchConfig(() => configParser.reloadConfig());++ sinon.assert.calledOnceWithExactly(disposeStub);+ sinon.assert.calledOnceWithExactly(+ consoleError,+ `Failed to watch ${configFile.path}: watch limit reached`,+ );+ });++ it('disposes the previous watcher when called again and on close', async () => {+ using configFile = createTempFile('{}', 'cd4a.watch.lifecycle.json');+ const startStub = sinon.stub(ConfigWatcher.prototype, 'start');+ const disposeStub = sinon.stub(ConfigWatcher.prototype, 'dispose');+ const {server, configParser} = await createTestServer([+ '--config',+ configFile.path,+ ]);++ server.watchConfig(() => configParser.reloadConfig());+ sinon.assert.calledOnceWithExactly(startStub);+ sinon.assert.notCalled(disposeStub);++ server.watchConfig(() => configParser.reloadConfig());+ sinon.assert.calledTwice(startStub);+ sinon.assert.calledOnceWithExactly(disposeStub);++ await server.close();+ sinon.assert.calledTwice(disposeStub);++ await server.close();+ sinon.assert.calledTwice(disposeStub);+ });++ it('applies reloadable config changes when the config file changes', async () => {+ using configFile = createTempFile(+ JSON.stringify({memoryDebugging: false}),+ 'cd4a.watch.reloadable.json',+ );+ await using watched = await watchTestServer(configFile.path);+ const consoleError = sinon.stub(console, 'error');++ await watched.updateConfigFile(JSON.stringify({memoryDebugging: true}));++ assert.strictEqual(watched.config.resolved.memoryDebugging, true);+ assert.ok(+ (await listServerToolNames(watched.server)).includes(+ 'get_heapsnapshot_summary',+ ),+ );+ sinon.assert.notCalled(consoleError);+ });++ it('does not apply a queued reload after the server is closed', async () => {+ using configFile = createTempFile(+ JSON.stringify({memoryDebugging: false}),+ 'cd4a.watch.closed.json',+ );+ await using watched = await watchTestServer(configFile.path);+ const {promise: toolBrowser, resolve: releaseToolCall} =+ Promise.withResolvers<ReturnType<typeof createMockPuppeteerBrowser>>();+ const {promise: toolEntered, resolve: markToolEntered} =+ Promise.withResolvers<void>();+ watched.context.ensureBrowser.onFirstCall().callsFake(async () => {+ markToolEntered();+ return await toolBrowser;+ });++ const toolCall = watched.server.callTool('list_pages');+ await toolEntered;++ const reloadPromise = watched.updateConfigFile(+ JSON.stringify({memoryDebugging: true}),+ );+ await watched.server.close();+ releaseToolCall(createMockPuppeteerBrowser());+ await toolCall;+ await reloadPromise;++ assert.strictEqual(watched.config.resolved.memoryDebugging, false);+ sinon.assert.notCalled(watched.context.onConfigChanged);+ });++ it('logs a restart notice when restart-required options change', async () => {+ using configFile = createTempFile(+ JSON.stringify({+ headless: false,+ memoryDebugging: false,+ }),+ 'cd4a.watch.restart.json',+ );+ await using watched = await watchTestServer(configFile.path);+ const consoleError = sinon.stub(console, 'error');++ await watched.updateConfigFile(+ JSON.stringify({+ headless: true,+ memoryDebugging: true,+ categoryExtensions: true,+ }),+ );++ assert.strictEqual(watched.config.resolved.memoryDebugging, true);+ assert.strictEqual(watched.config.resolved.headless, false);+ assert.strictEqual(watched.config.resolved.categoryExtensions, undefined);+ const expectedNotice = `Restart chrome-devtools-mcp to fully apply changes to --categoryExtensions, --headless from ${configFile.path}.`;+ sinon.assert.calledOnceWithExactly(consoleError, expectedNotice);+ sinon.assert.calledTwice(watched.logStream.write);+ sinon.assert.calledWithMatch(+ watched.logStream.write.firstCall,+ `Applied config changes from ${configFile.path}\n`,+ );+ sinon.assert.calledWithMatch(+ watched.logStream.write.secondCall,+ `${expectedNotice}\n`,+ );+ });++ it('keeps the previous configuration when reloading the config file fails', async () => {+ using configFile = createTempFile(+ JSON.stringify({memoryDebugging: true}),+ 'cd4a.watch.invalid.json',+ );+ await using watched = await watchTestServer(configFile.path);+ const consoleError = sinon.stub(console, 'error');++ await watched.updateConfigFile('[]');++ assert.strictEqual(watched.config.resolved.memoryDebugging, true);+ sinon.assert.notCalled(watched.context.onConfigChanged);+ const expectedError = `Keeping the previous configuration, failed to reload ${configFile.path}: Invalid JSON config file: Config must be a JSON object`;+ sinon.assert.calledOnceWithExactly(consoleError, expectedError);+ sinon.assert.calledOnceWithMatch(+ watched.logStream.write,+ `${expectedError}\n`,+ );+ });++ it('keeps the previous configuration when reloaded options conflict with startup options', async () => {+ using configFile = createTempFile(+ JSON.stringify({browserUrl: 'http://127.0.0.1:9222'}),+ 'cd4a.watch.conflict.json',+ );+ await using watched = await watchTestServer(configFile.path);+ const consoleError = sinon.stub(console, 'error');++ await watched.updateConfigFile(JSON.stringify({categoryPwa: true}));++ assert.strictEqual(watched.config.resolved.categoryPwa, undefined);+ sinon.assert.notCalled(watched.context.onConfigChanged);+ const expectedError = `Keeping the previous configuration, failed to reload ${configFile.path}: Arguments categoryPwa and browserUrl are mutually exclusive`;+ sinon.assert.calledOnceWithExactly(consoleError, expectedError);+ sinon.assert.calledOnceWithMatch(+ watched.logStream.write,+ `${expectedError}\n`,+ );+ });++ it('does not log keeping the previous configuration when applying committed config fails', async () => {+ using configFile = createTempFile(+ JSON.stringify({memoryDebugging: false}),+ 'cd4a.watch.apply-error.json',+ );+ await using watched = await watchTestServer(configFile.path);+ const applyError = new Error('failed to update pages');+ watched.context.onConfigChanged.rejects(applyError);+ const consoleError = sinon.stub(console, 'error');++ await watched.updateConfigFile(JSON.stringify({memoryDebugging: true}));++ assert.strictEqual(watched.config.resolved.memoryDebugging, true);+ sinon.assert.calledOnceWithExactly(+ consoleError,+ `Failed to apply ${configFile.path}:`,+ applyError,+ );+ sinon.assert.notCalled(watched.logStream.write);+ });+ });});async function getToolsWithFilteredCategories(diff --git a/tests/cli.test.ts b/tests/cli.test.tsindex bfcf8521..a2202811 100644--- a/tests/cli.test.ts+++ b/tests/cli.test.ts@@ -69,6 +69,7 @@ describe('cli args parsing', () => {slim: false,viaCli: false,devtoolsComments: false,+ watchConfig: false,};it('parses with default args', async () => {diff --git a/tests/config/ServerConfig.test.ts b/tests/config/ServerConfig.test.tsindex 9b437b6f..c34d8fd4 100644--- a/tests/config/ServerConfig.test.ts+++ b/tests/config/ServerConfig.test.ts@@ -350,4 +350,62 @@ describe('ServerConfig', () => {assert.strictEqual(readonlyView.resolved.headless, true);});});++ describe('getRestartRequiredChanges', () => {+ it('ignores reloadable option changes', () => {+ const previous = parseConfig();+ const next = parseConfig([+ '--memoryDebugging',+ '--no-category-network',+ '--slim',+ ]);++ assert.deepStrictEqual(previous.getRestartRequiredChanges(next), []);+ });++ it('returns restart-required options that changed', () => {+ const previous = parseConfig();+ const next = parseConfig([+ '--headless',+ '--categoryExtensions',+ '--memoryDebugging',+ ]);++ assert.deepStrictEqual(previous.getRestartRequiredChanges(next), [+ 'categoryExtensions',+ 'headless',+ ]);+ });++ it('compares restart-required array and object options by value', () => {+ const previous = parseConfig([+ '--blockedUrlPattern=https://example.com/*',+ ]);+ const same = parseConfig(['--blockedUrlPattern=https://example.com/*']);+ const changed = parseConfig(['--blockedUrlPattern=https://other.com/*']);++ assert.deepStrictEqual(previous.getRestartRequiredChanges(same), []);+ assert.deepStrictEqual(previous.getRestartRequiredChanges(changed), [+ 'blockedUrlPattern',+ ]);+ });++ it('ignores restart-required options whose defaults are derived from other options', () => {+ const previous = parseConfig(['--viaCli']);+ const next = parseConfig([+ '--viaCli',+ '--browserUrl=http://127.0.0.1:9222',+ ]);++ assert.strictEqual(previous.resolved.categoryExtensions, true);+ assert.strictEqual(next.resolved.categoryExtensions, undefined);+ assert.strictEqual(previous.resolved.isolated, true);+ assert.strictEqual(next.resolved.isolated, false);+ assert.strictEqual(previous.resolved.channel, 'stable');+ assert.strictEqual(next.resolved.channel, undefined);+ assert.deepStrictEqual(previous.getRestartRequiredChanges(next), [+ 'browserUrl',+ ]);+ });+ });});