Skip to content

Chrome DevTools for coding agents

feat: support configurable filesystem roots (#2605)

Joseph Bd00e6f8239d9
diff --git a/docs/cli.md b/docs/cli.md
index 50c94e34..af7a664c 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -11,6 +11,16 @@ npm i chrome-devtools-mcp@latest -g
chrome-devtools status # check if install worked.
```
+The CLI enables unrestricted filesystem access by default. Use `--workspace`
+to limit file tools to specific directories. Repeat the flag for more than one
+directory.
+`--allow-unrestricted-paths` still works on its own for compatibility, but it
+cannot be combined with `--workspace`.
+
+```sh
+chrome-devtools start --workspace=/path/to/project --workspace=/path/to/output
+```
+
## How it works
The CLI acts as a client to a background `chrome-devtools-mcp` daemon (uses Unix sockets on Linux/Mac and named pipes on Windows).
diff --git a/docs/configuration.md b/docs/configuration.md
index 813cc699..6230e8e9 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -85,7 +85,7 @@ The Chrome DevTools MCP server supports the following configuration option:
- **Type:** boolean
- **Default:** `false`
-- **`--memoryDebugging`/ `--memory-debugging`, `-experimentalMemory`**
+- **`--memoryDebugging`/ `--memory-debugging`, `--experimentalMemory`**
Whether to enable memory debugging tools.
- **Type:** boolean
- **Default:** `false`
@@ -221,6 +221,11 @@ The Chrome DevTools MCP server supports the following configuration option:
- **Type:** boolean
- **Default:** `false`
+- **`--filesystemRoot`/ `--filesystem-root`, `--workspace`**
+ A directory that filesystem tools are allowed to access. May be specified more than once.
+ - **Type:** array
+ - **Default:** `OS temp directory`
+
<!-- END AUTO GENERATED OPTIONS -->
Pass them via the `args` property in the JSON configuration. For example:
diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts
index 002b0861..e43880e9 100644
--- a/scripts/generate-docs.ts
+++ b/scripts/generate-docs.ts
@@ -139,7 +139,9 @@ function generateConfigOptionsMarkdown(): string {
continue;
}
- const aliasText = optionConfig.alias ? `, \`-${optionConfig.alias}\`` : '';
+ const aliasText = optionConfig.alias
+ ? `, \`${optionConfig.alias.length === 1 ? '-' : '--'}${optionConfig.alias}\``
+ : '';
const description = optionConfig.description || optionConfig.describe || '';
// Convert camelCase to dash-case
@@ -164,7 +166,7 @@ function generateConfigOptionsMarkdown(): string {
}
// Add default if available
- markdown += ` - **Default:** \`${optionConfig.default ?? 'false'}\`\n`;
+ markdown += ` - **Default:** \`${optionConfig.defaultDescription ?? optionConfig.default ?? 'false'}\`\n`;
markdown += '\n';
}
diff --git a/src/config/mcp-options.ts b/src/config/mcp-options.ts
index c1d41d79..c6f0be5c 100644
--- a/src/config/mcp-options.ts
+++ b/src/config/mcp-options.ts
@@ -6,6 +6,9 @@
import type {YargsOptions} from '../third_party/index.js';
import {yargs, hideBin} from '../third_party/index.js';
+import os from 'node:os';
+
+export const DEFAULT_FILESYSTEM_ROOT = [os.tmpdir()];
export const mcpOptions = {
autoConnect: {
@@ -392,12 +395,21 @@ export const mcpOptions = {
allowUnrestrictedPaths: {
type: 'boolean',
default: false,
+ deprecated: 'Use --workspace=/ instead.',
describe:
'If set, disables the default path restriction that applies when the MCP client does not negotiate ' +
'the roots capability. By default, file-writing tools 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.',
},
+ filesystemRoot: {
+ type: 'array',
+ alias: 'workspace',
+ default: DEFAULT_FILESYSTEM_ROOT,
+ defaultDescription: 'OS temp directory',
+ describe:
+ 'A directory that filesystem tools are allowed to access. May be specified more than once.',
+ },
} satisfies Record<string, YargsOptions>;
export type ParsedArguments = ReturnType<typeof parseArguments>;
@@ -406,11 +418,6 @@ export function getMcpOptionsForViaCli(): typeof mcpOptions {
if (!('default' in mcpOptions.headless)) {
throw new Error('headless cli option unexpectedly does not have a default');
}
- if (!('default' in mcpOptions.allowUnrestrictedPaths)) {
- throw new Error(
- 'allowUnrestrictedPaths cli option unexpectedly does not have a default',
- );
- }
if (!('default' in mcpOptions.experimentalStructuredContent)) {
throw new Error(
'experimentalStructuredContent cli option unexpectedly does not have a default',
@@ -422,10 +429,6 @@ export function getMcpOptionsForViaCli(): typeof mcpOptions {
return {
...mcpOptions,
- allowUnrestrictedPaths: {
- ...mcpOptions.allowUnrestrictedPaths,
- default: true,
- },
headless: {
...mcpOptions.headless,
default: true,
@@ -470,6 +473,14 @@ export function parser(
.options(options)
.showHelpOnFail(false, 'Specify --help for available options')
.middleware(args => {
+ if (isViaCli && args.filesystemRoot === DEFAULT_FILESYSTEM_ROOT) {
+ const cliFilesystemArgs: {
+ allowUnrestrictedPaths?: boolean;
+ filesystemRoot?: unknown;
+ } = args;
+ cliFilesystemArgs.allowUnrestrictedPaths = true;
+ cliFilesystemArgs.filesystemRoot = undefined;
+ }
// We can't set default in the options else
// Yargs will complain
if (
diff --git a/src/daemon/utils.ts b/src/daemon/utils.ts
index 7e30c9c6..f832c90b 100644
--- a/src/daemon/utils.ts
+++ b/src/daemon/utils.ts
@@ -132,6 +132,12 @@ export function serializeArgs(
continue;
}
const value = argv[key];
+ const option = options[key];
+ // Yargs reuses the option `default` object; skip it so the daemon parser
+ // still sees the original default (needed for filesystemRoot identity).
+ if (option !== undefined && value === option.default) {
+ continue;
+ }
const kebabKey = key.replace(/[A-Z]/g, m => `-${m.toLowerCase()}`);
if (typeof value === 'boolean') {
diff --git a/src/index.ts b/src/index.ts
index 2c35b00d..5db2af37 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -5,6 +5,8 @@
*/
import type fs from 'node:fs';
+import path from 'node:path';
+import {pathToFileURL} from 'node:url';
import type {Channel} from './browser.js';
import {ensureBrowserConnected, ensureBrowserLaunched} from './browser.js';
@@ -55,11 +57,11 @@ export class McpServer {
#context?: McpContext;
/**
- * Roots are client state rather than browser state, so the last listing stays
- * valid across browser reconnects and only the client can invalidate it, via
- * the `roots/list_changed` notification handled below
+ * Client roots stay valid across browser reconnects and only the client can
+ * invalidate them through a `roots/list_changed` notification. CLI-configured
+ * roots are read from `#serverArgs` when combining roots.
*/
- #lastRoots?: Root[];
+ #lastClientRoots?: Root[];
#toolMutex = new Mutex();
private constructor(
@@ -107,7 +109,10 @@ export class McpServer {
void this.#updateRoots();
},
);
- } else if (!this.#serverArgs.allowUnrestrictedPaths) {
+ } else if (
+ !this.#serverArgs.allowUnrestrictedPaths &&
+ (this.#serverArgs.filesystemRoot ?? []).length === 0
+ ) {
console.warn(
'[chrome-devtools-mcp] The connecting client did not negotiate the MCP roots ' +
'capability. File-writing tools will be restricted to the OS temp directory. ' +
@@ -158,6 +163,24 @@ export class McpServer {
await loadIssueDescriptions();
}
+ #combinedRoots(): Root[] | undefined {
+ const configuredRoots = (
+ this.#serverArgs.allowUnrestrictedPaths
+ ? []
+ : (this.#serverArgs.filesystemRoot ?? [])
+ ).map(root => {
+ const rootPath = path.resolve(String(root));
+ return {
+ uri: pathToFileURL(rootPath).href,
+ name: path.basename(rootPath) || rootPath,
+ };
+ });
+ if (configuredRoots.length === 0 && this.#lastClientRoots === undefined) {
+ return undefined;
+ }
+ return [...configuredRoots, ...(this.#lastClientRoots ?? [])];
+ }
+
/**
* `timeout` is only passed where a tool call is waiting on the result – the
* background refreshes below block nobody, so bounding them would just discard
@@ -173,8 +196,8 @@ export class McpServer {
ListRootsResultSchema,
timeout === undefined ? undefined : {timeout},
);
- this.#lastRoots = roots.roots;
- this.#context?.setRoots(this.#lastRoots);
+ this.#lastClientRoots = roots.roots;
+ this.#context?.setRoots(this.#combinedRoots());
} catch (e) {
logger?.('Failed to list roots', e);
}
@@ -244,14 +267,14 @@ export class McpServer {
// Surfaces a one-time note in the next response after a reconnect.
reconnected: this.#context !== undefined,
});
- if (this.#lastRoots === undefined) {
+ this.#context.setRoots(this.#combinedRoots());
+ if (this.#lastClientRoots === undefined) {
// Nothing listed yet, so this call has to wait – bounded, since it is
// holding the tool mutex, and a later background refresh still lands
await this.#updateRoots(ROOTS_REQUEST_TIMEOUT);
} else {
// Carry the known roots over and refresh out of band, so a reconnect
// never pays for a client round-trip
- this.#context.setRoots(this.#lastRoots);
void this.#updateRoots();
}
}
diff --git a/src/telemetry/flag_usage_metrics.json b/src/telemetry/flag_usage_metrics.json
index 7a30aeee..b962f149 100644
--- a/src/telemetry/flag_usage_metrics.json
+++ b/src/telemetry/flag_usage_metrics.json
@@ -401,5 +401,9 @@
{
"name": "experimental_screencast_fps_present",
"flagType": "boolean"
+ },
+ {
+ "name": "filesystem_root_present",
+ "flagType": "boolean"
}
]
diff --git a/tests/cli.test.ts b/tests/cli.test.ts
index 6047f239..1576b41f 100644
--- a/tests/cli.test.ts
+++ b/tests/cli.test.ts
@@ -7,7 +7,11 @@
import assert from 'node:assert';
import {describe, it} from 'node:test';
-import {mcpOptions, parser} from '../src/config/mcp-options.js';
+import {
+ DEFAULT_FILESYSTEM_ROOT,
+ mcpOptions,
+ parser,
+} from '../src/config/mcp-options.js';
function parseArguments(argv: string[], env: NodeJS.ProcessEnv = {}) {
return parser('0.0.0', ['node', 'main.js', ...argv], env)
@@ -28,6 +32,7 @@ describe('cli args parsing', () => {
javascriptEvaluation: true,
redactNetworkHeaders: false,
allowUnrestrictedPaths: false,
+ filesystemRoot: DEFAULT_FILESYSTEM_ROOT,
memoryDebugging: false,
experimentalStructuredContent: false,
pageIdRouting: true,
@@ -150,6 +155,46 @@ describe('cli args parsing', () => {
});
});
+ describe('filesystem roots', () => {
+ it('parses filesystem roots', async () => {
+ const args = parseArguments([
+ '--filesystem-root=/tmp/one',
+ '--filesystem-root=/tmp/two',
+ ]);
+ assert.deepStrictEqual(args.filesystemRoot, ['/tmp/one', '/tmp/two']);
+ });
+
+ it('parses workspace as an alias for filesystem roots', async () => {
+ const args = parseArguments([
+ '--workspace=/tmp/one',
+ '--workspace=/tmp/two',
+ ]);
+ assert.deepStrictEqual(args.filesystemRoot, ['/tmp/one', '/tmp/two']);
+ });
+
+ it('still accepts unrestricted paths without an explicit root', async () => {
+ const args = parseArguments(['--allow-unrestricted-paths']);
+ assert.strictEqual(args.allowUnrestrictedPaths, true);
+ });
+
+ it('lets an explicit workspace override the CLI unrestricted default', async () => {
+ const args = parseArguments(['--viaCli', '--workspace=/tmp/one']);
+ assert.strictEqual(args.allowUnrestrictedPaths, false);
+ assert.deepStrictEqual(args.filesystemRoot, ['/tmp/one']);
+ });
+
+ it('keeps the CLI unrestricted default when no workspace is set', async () => {
+ const args = parseArguments(['--viaCli']);
+ assert.strictEqual(args.allowUnrestrictedPaths, true);
+ assert.strictEqual(args.filesystemRoot, undefined);
+ });
+
+ it('uses yargs default identity to detect an unset CLI workspace', async () => {
+ const args = parseArguments([]);
+ assert.strictEqual(args.filesystemRoot, DEFAULT_FILESYSTEM_ROOT);
+ });
+ });
+
it('parses ignore chrome args', async () => {
const args = parseArguments([
`--ignore-default-chrome-arg='--disable-extensions'`,
diff --git a/tests/e2e/chrome-devtools-start-stop.test.ts b/tests/e2e/chrome-devtools-start-stop.test.ts
index 1db73a05..b83b1ec2 100644
--- a/tests/e2e/chrome-devtools-start-stop.test.ts
+++ b/tests/e2e/chrome-devtools-start-stop.test.ts
@@ -78,4 +78,32 @@ describe('chrome-devtools', () => {
await assertDaemonIsRunning(sessionId);
});
+
+ it('can start the daemon with a workspace', async () => {
+ const workspace = fs.mkdtempSync(
+ path.join(os.tmpdir(), 'chrome-devtools-workspace-'),
+ );
+
+ try {
+ const startResult = await runCli(
+ ['start', '--workspace', workspace],
+ sessionId,
+ );
+ assert.strictEqual(
+ startResult.status,
+ 0,
+ `start command failed: ${startResult.stderr}`,
+ );
+
+ const statusResult = await runCli(['status'], sessionId);
+ assert.strictEqual(statusResult.status, 0);
+ assert.ok(
+ statusResult.stdout.includes('--filesystem-root=') &&
+ statusResult.stdout.includes(path.basename(workspace)),
+ `workspace was not forwarded: ${statusResult.stdout}`,
+ );
+ } finally {
+ fs.rmSync(workspace, {recursive: true, force: true});
+ }
+ });
});
diff --git a/tests/index.test.ts b/tests/index.test.ts
index d4f6330b..a7446193 100644
--- a/tests/index.test.ts
+++ b/tests/index.test.ts
@@ -246,6 +246,51 @@ describe('e2e', () => {
);
});
+ it('combines configured filesystem roots with client roots', async () => {
+ const configuredRoot = await fs.promises.mkdtemp(
+ path.join(os.homedir(), '.configured-root-'),
+ );
+ const clientRoot = await fs.promises.mkdtemp(
+ path.join(os.homedir(), '.client-root-'),
+ );
+
+ try {
+ await withClient(
+ async client => {
+ client.setRequestHandler(ListRootsRequestSchema, () => {
+ return {
+ roots: [
+ {uri: pathToFileURL(clientRoot).href, name: 'client-root'},
+ ],
+ };
+ });
+
+ for (const outputPath of [
+ path.join(configuredRoot, 'configured.png'),
+ path.join(clientRoot, 'client.png'),
+ ]) {
+ const result = await client.callTool({
+ name: 'take_screenshot',
+ arguments: {pageId: 1, filePath: outputPath},
+ });
+ assert.strictEqual(result.isError, undefined);
+ const content = result.content as TextContent[];
+ assert.match(content[0].text, /Saved screenshot to/);
+ }
+ },
+ [`--filesystem-root=${configuredRoot}`],
+ {
+ capabilities: {
+ roots: {listChanged: true},
+ },
+ },
+ );
+ } finally {
+ await fs.promises.rm(configuredRoot, {recursive: true, force: true});
+ await fs.promises.rm(clientRoot, {recursive: true, force: true});
+ }
+ });
+
it('denies file access if roots list is empty', async () => {
await withClient(
async client => {