Skip to content

Chrome DevTools for coding agents

refactor: extract category config into a seprate file (#2652)

Nikolay Vitkov401a1192b6e7
diff --git a/docs/configuration.md b/docs/configuration.md
index 6230e8e9..83806f95 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -4,6 +4,36 @@ The Chrome DevTools MCP server supports the following configuration option:
<!-- BEGIN AUTO GENERATED OPTIONS -->
+- **`--categoryEmulation`/ `--category-emulation`**
+ Set to false to exclude tools related to emulation.
+ - **Type:** boolean
+ - **Default:** `true`
+
+- **`--categoryPerformance`/ `--category-performance`**
+ Set to false to exclude tools related to performance.
+ - **Type:** boolean
+ - **Default:** `true`
+
+- **`--categoryNetwork`/ `--category-network`**
+ Set to false to exclude tools related to network.
+ - **Type:** boolean
+ - **Default:** `true`
+
+- **`--categoryExtensions`/ `--category-extensions`**
+ Set to true to include tools related to extensions. Note: This feature is currently only supported with a pipe connection. autoConnect, browserUrl, and wsEndpoint are not supported with this feature until 149 will be released.
+ - **Type:** boolean
+ - **Default:** `false`
+
+- **`--categoryExperimentalThirdParty`/ `--category-experimental-third-party`**
+ Set to true to enable third-party developer tools exposed by the inspected page itself
+ - **Type:** boolean
+ - **Default:** `false`
+
+- **`--categoryPwa`/ `--category-pwa`**
+ Set to true to include tools for automating Progressive Web Apps (install, launch, uninstall, and OS state). This feature is only supported with a pipe connection; autoConnect, browserUrl, and wsEndpoint are not supported.
+ - **Type:** boolean
+ - **Default:** `false`
+
- **`--autoConnect`/ `--auto-connect`**
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.
- **Type:** boolean
@@ -115,11 +145,6 @@ The Chrome DevTools MCP server supports the following configuration option:
- **Type:** number
- **Default:** `false`
-- **`--categoryExperimentalWebmcp`/ `--category-experimental-webmcp`**
- Set to true to enable debugging WebMCP tools. Requires Chrome 150+ with the following flag: `--enable-features=WebMCP`
- - **Type:** boolean
- - **Default:** `false`
-
- **`--chromeArg`/ `--chrome-arg`**
Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.
- **Type:** array
@@ -140,36 +165,6 @@ The Chrome DevTools MCP server supports the following configuration option:
- **Type:** array
- **Default:** `false`
-- **`--categoryEmulation`/ `--category-emulation`**
- Set to false to exclude tools related to emulation.
- - **Type:** boolean
- - **Default:** `true`
-
-- **`--categoryPerformance`/ `--category-performance`**
- Set to false to exclude tools related to performance.
- - **Type:** boolean
- - **Default:** `true`
-
-- **`--categoryNetwork`/ `--category-network`**
- Set to false to exclude tools related to network.
- - **Type:** boolean
- - **Default:** `true`
-
-- **`--categoryExtensions`/ `--category-extensions`**
- Set to true to include tools related to extensions. Note: This feature is currently only supported with a pipe connection. autoConnect, browserUrl, and wsEndpoint are not supported with this feature until 149 will be released.
- - **Type:** boolean
- - **Default:** `false`
-
-- **`--categoryExperimentalThirdParty`/ `--category-experimental-third-party`**
- Set to true to enable third-party developer tools exposed by the inspected page itself
- - **Type:** boolean
- - **Default:** `false`
-
-- **`--categoryPwa`/ `--category-pwa`**
- Set to true to include tools for automating Progressive Web Apps (install, launch, uninstall, and OS state). This feature is only supported with a pipe connection; autoConnect, browserUrl, and wsEndpoint are not supported.
- - **Type:** boolean
- - **Default:** `false`
-
- **`--performanceCrux`/ `--performance-crux`**
Set to false to disable sending URLs from performance traces to CrUX API to get field performance data.
- **Type:** boolean
diff --git a/scripts/generate-cli.ts b/scripts/generate-cli.ts
index cacc90c8..5fba0b68 100644
--- a/scripts/generate-cli.ts
+++ b/scripts/generate-cli.ts
@@ -11,12 +11,11 @@ import {Client} from '@modelcontextprotocol/sdk/client/index.js';
import {StdioClientTransport} from '@modelcontextprotocol/sdk/client/stdio.js';
import {mcpOptions, parseArguments} from '../build/src/config/mcp-options.js';
-import {buildFlag} from '../build/src/index.js';
import {
- labels,
- ToolCategory,
- OFF_BY_DEFAULT_CATEGORIES,
-} from '../build/src/tools/categories.js';
+ isCategoryOffByDefault,
+ categoryToFlagName,
+} from '../build/src/config/category-options.js';
+import {labels, ToolCategory} from '../build/src/tools/categories.js';
import {createTools} from '../build/src/tools/tools.js';
const OUTPUT_PATH = path.join(
@@ -166,9 +165,9 @@ async function generateCli() {
let description = tool.description;
const requiredFlags: string[] = [];
- const isOffByDefault = OFF_BY_DEFAULT_CATEGORIES.includes(categoryEnum);
+ const isOffByDefault = isCategoryOffByDefault(categoryEnum);
if (isOffByDefault) {
- const categoryFlag = buildFlag(categoryEnum);
+ const categoryFlag = categoryToFlagName(categoryEnum);
requiredFlags.push(`--${categoryFlag}=true`);
}
diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts
index e43880e9..e496d335 100644
--- a/scripts/generate-docs.ts
+++ b/scripts/generate-docs.ts
@@ -12,12 +12,11 @@ import {
mcpOptions,
type ParsedArguments,
} from '../build/src/config/mcp-options.js';
-import {buildFlag} from '../build/src/ToolHandler.js';
import {
- ToolCategory,
- OFF_BY_DEFAULT_CATEGORIES,
- labels,
-} from '../build/src/tools/categories.js';
+ isCategoryOffByDefault,
+ categoryToFlagName,
+} from '../build/src/config/category-options.js';
+import {ToolCategory, labels} from '../build/src/tools/categories.js';
import {pageIdSchema} from '../build/src/tools/ToolDefinition.js';
import {createTools} from '../build/src/tools/tools.js';
@@ -312,8 +311,8 @@ async function generateReference(
markdown += `## ${categoryName}\n\n`;
- if (OFF_BY_DEFAULT_CATEGORIES.includes(category)) {
- const flagName = `--${buildFlag(category)}`;
+ if (isCategoryOffByDefault(category)) {
+ const flagName = `--${categoryToFlagName(category)}`;
markdown += `> NOTE: The ${categoryName} category is not active by default. Use the '${flagName}' flag.\n\n`;
}
@@ -330,9 +329,9 @@ async function generateReference(
const requiredFlags: string[] = [];
- const isOffByDefault = OFF_BY_DEFAULT_CATEGORIES.includes(category);
+ const isOffByDefault = isCategoryOffByDefault(category);
if (isOffByDefault) {
- const categoryFlag = buildFlag(category);
+ const categoryFlag = categoryToFlagName(category);
requiredFlags.push(`--${categoryFlag}=true`);
}
@@ -478,8 +477,8 @@ function getToolsAndCategories(tools: any, slim = false) {
// Sort categories using the enum order
const categoryOrder = Object.values(ToolCategory);
const sortedCategories = Object.keys(categories).sort((a, b) => {
- const aOff = OFF_BY_DEFAULT_CATEGORIES.includes(a as ToolCategory);
- const bOff = OFF_BY_DEFAULT_CATEGORIES.includes(b as ToolCategory);
+ const aOff = isCategoryOffByDefault(a);
+ const bOff = isCategoryOffByDefault(b);
if (aOff !== bOff) {
return aOff ? 1 : -1;
diff --git a/src/ToolHandler.ts b/src/ToolHandler.ts
index 52ff1b7f..12313009 100644
--- a/src/ToolHandler.ts
+++ b/src/ToolHandler.ts
@@ -13,8 +13,8 @@ import {SlimMcpResponse} from './SlimMcpResponse.js';
import {ClearcutLogger} from './telemetry/ClearcutLogger.js';
import type {CallToolResult} from './third_party/index.js';
import {zod} from './third_party/index.js';
-import type {ToolCategory} from './tools/categories.js';
-import {labels, OFF_BY_DEFAULT_CATEGORIES} from './tools/categories.js';
+import {labels} from './tools/categories.js';
+import {categoryToFlagName} from './config/category-options.js';
import type {
DefinedPageTool,
DevToolsData,
@@ -27,10 +27,6 @@ import type {Mutex} from './third_party/index.js';
import {fileURLToPath, pathToFileURL} from 'node:url';
import {isLocalhost} from './utils/url.js';
-export function buildFlag(category: ToolCategory) {
- return `category${category.charAt(0).toUpperCase() + category.slice(1)}`;
-}
-
function buildDisabledMessage(
toolName: string,
flag: string,
@@ -43,80 +39,26 @@ function buildDisabledMessage(
return `Tool ${toolName} ${reason} is currently disabled. Enable it by running chrome-devtools start ${flag}=true. For more information check the README.`;
}
-function getCategoryStatus(
- category: ToolCategory,
- serverArgs: ParsedArguments,
-): {categoryFlag?: string; disabled: boolean} {
- const categoryFlag = buildFlag(category);
-
- const flagValue = serverArgs[categoryFlag];
-
- const isDisabled = OFF_BY_DEFAULT_CATEGORIES.includes(category)
- ? !flagValue
- : flagValue === false;
-
- if (isDisabled) {
- return {
- categoryFlag,
- disabled: true,
- };
- }
-
- return {
- disabled: false,
- };
-}
-
-function getConditionStatus(
- condition: string,
- serverArgs: ParsedArguments,
-): {conditionFlag?: string; disabled: boolean} {
- if (condition && !serverArgs[condition]) {
- return {conditionFlag: condition, disabled: true};
- }
-
- return {disabled: false};
-}
-
function getToolStatusInfo(
tool: ToolDefinition | DefinedPageTool,
serverArgs: ParsedArguments,
): {disabled: boolean; reason?: string} {
const category = tool.annotations.category;
- const categoryCheck = getCategoryStatus(category, serverArgs);
-
- if (category && categoryCheck.disabled) {
- if (!categoryCheck.categoryFlag) {
- throw new Error(
- 'when the category is disabled there should always be a flag set',
- );
+ if (category) {
+ const flag = categoryToFlagName(category);
+ if (!serverArgs[flag]) {
+ return {
+ disabled: true,
+ reason: buildDisabledMessage(tool.name, `--${flag}`, labels[category]),
+ };
}
-
- return {
- disabled: true,
- reason: buildDisabledMessage(
- tool.name,
- `--${categoryCheck.categoryFlag}`,
- labels[category!],
- ),
- };
}
for (const condition of tool.annotations.conditions || []) {
- const conditionCheck = getConditionStatus(condition, serverArgs);
- if (conditionCheck.disabled) {
- if (!conditionCheck.conditionFlag) {
- throw new Error(
- 'when the condition is disabled there should always be a flag set',
- );
- }
-
+ if (!serverArgs[condition]) {
return {
disabled: true,
- reason: buildDisabledMessage(
- tool.name,
- `--${conditionCheck.conditionFlag}`,
- ),
+ reason: buildDisabledMessage(tool.name, `--${condition}`),
};
}
}
diff --git a/src/config/category-options.ts b/src/config/category-options.ts
new file mode 100644
index 00000000..f2a17b32
--- /dev/null
+++ b/src/config/category-options.ts
@@ -0,0 +1,115 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {ToolCategory} from '../tools/categories.js';
+
+export interface CategoryOption {
+ type: 'boolean';
+ describe: string;
+ default?: boolean;
+ hidden?: boolean;
+ conflicts?: string[];
+}
+
+export type CategoryFlagName<T extends ToolCategory = ToolCategory> =
+ `category${Capitalize<T>}`;
+
+export type CategoryFlags = {
+ [K in ToolCategory as CategoryFlagName<K>]: CategoryOption;
+};
+
+const categoryOverrides: Record<
+ ToolCategory,
+ {
+ describe?: string;
+ hidden?: boolean;
+ conflicts?: string[];
+ offByDefault?: boolean;
+ }
+> = {
+ [ToolCategory.INPUT]: {},
+ [ToolCategory.NAVIGATION]: {},
+ [ToolCategory.EMULATION]: {
+ hidden: false,
+ },
+ [ToolCategory.PERFORMANCE]: {
+ hidden: false,
+ },
+ [ToolCategory.NETWORK]: {
+ hidden: false,
+ },
+ [ToolCategory.DEBUGGING]: {},
+ [ToolCategory.MEMORY]: {},
+ [ToolCategory.WEBMCP]: {
+ describe:
+ 'Set to true to enable debugging WebMCP tools. Requires Chrome 150+ with the following flag: `--enable-features=WebMCP`',
+ offByDefault: true,
+ },
+ [ToolCategory.EXTENSIONS]: {
+ describe:
+ 'Set to true to include tools related to extensions. Note: This feature is currently only supported with a pipe connection. autoConnect, browserUrl, and wsEndpoint are not supported with this feature until 149 will be released.',
+ hidden: false,
+ offByDefault: true,
+ },
+ [ToolCategory.THIRD_PARTY]: {
+ describe:
+ 'Set to true to enable third-party developer tools exposed by the inspected page itself',
+ hidden: false,
+ offByDefault: true,
+ },
+ [ToolCategory.PWA]: {
+ describe:
+ 'Set to true to include tools for automating Progressive Web Apps (install, launch, uninstall, and OS state). This feature is only supported with a pipe connection; autoConnect, browserUrl, and wsEndpoint are not supported.',
+ conflicts: ['autoConnect', 'browserUrl', 'wsEndpoint'],
+ hidden: false,
+ offByDefault: true,
+ },
+};
+
+function createOption(category: ToolCategory): CategoryOption {
+ const overrides = categoryOverrides[category];
+ const describe = overrides.offByDefault
+ ? `Set to true to include tools related to ${category}.`
+ : `Set to false to exclude tools related to ${category}.`;
+
+ return {
+ type: 'boolean',
+ describe,
+ hidden: true,
+ ...overrides,
+ ...(overrides.offByDefault ? {} : {default: true}),
+ };
+}
+
+export function categoryToFlagName(category: ToolCategory): CategoryFlagName {
+ return `category${category.charAt(0).toUpperCase()}${category.slice(1)}` as CategoryFlagName;
+}
+
+export function getCategoryOptions(): CategoryFlags {
+ const options = {} as CategoryFlags;
+ for (const category of Object.values(ToolCategory)) {
+ const flagName = categoryToFlagName(category);
+ options[flagName] = createOption(category);
+ }
+
+ return options;
+}
+
+export function isCategoryOffByDefault(category: ToolCategory): boolean {
+ const flagName = categoryToFlagName(category);
+ const option = getCategoryOptions()[flagName];
+ return !('default' in option) || option.default !== true;
+}
+
+export function getOffByDefaultCategories(): ToolCategory[] {
+ const result: ToolCategory[] = [];
+ for (const category of Object.values(ToolCategory)) {
+ if (isCategoryOffByDefault(category)) {
+ result.push(category);
+ }
+ }
+ return result;
+}
diff --git a/src/config/mcp-options.ts b/src/config/mcp-options.ts
index c6f0be5c..bfb15e06 100644
--- a/src/config/mcp-options.ts
+++ b/src/config/mcp-options.ts
@@ -10,7 +10,10 @@ import os from 'node:os';
export const DEFAULT_FILESYSTEM_ROOT = [os.tmpdir()];
+import {getCategoryOptions} from './category-options.js';
+
export const mcpOptions = {
+ ...getCategoryOptions(),
autoConnect: {
type: 'boolean',
description:
@@ -226,11 +229,6 @@ export const mcpOptions = {
return value;
},
},
- categoryExperimentalWebmcp: {
- type: 'boolean',
- describe:
- 'Set to true to enable debugging WebMCP tools. Requires Chrome 150+ with the following flag: `--enable-features=WebMCP`',
- },
chromeArg: {
type: 'array',
describe:
@@ -253,41 +251,6 @@ export const mcpOptions = {
describe:
'Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',
},
- categoryEmulation: {
- type: 'boolean',
- default: true,
- describe: 'Set to false to exclude tools related to emulation.',
- },
- categoryPerformance: {
- type: 'boolean',
- default: true,
- describe: 'Set to false to exclude tools related to performance.',
- },
- categoryNetwork: {
- type: 'boolean',
- default: true,
- describe: 'Set to false to exclude tools related to network.',
- },
- categoryExtensions: {
- type: 'boolean',
- hidden: false,
- default: false,
- describe:
- 'Set to true to include tools related to extensions. Note: This feature is currently only supported with a pipe connection. autoConnect, browserUrl, and wsEndpoint are not supported with this feature until 149 will be released.',
- },
- categoryExperimentalThirdParty: {
- type: 'boolean',
- default: false,
- describe:
- 'Set to true to enable third-party developer tools exposed by the inspected page itself',
- },
- categoryPwa: {
- type: 'boolean',
- hidden: false,
- conflicts: ['autoConnect', 'browserUrl', 'wsEndpoint'],
- describe:
- 'Set to true to include tools for automating Progressive Web Apps (install, launch, uninstall, and OS state). This feature is only supported with a pipe connection; autoConnect, browserUrl, and wsEndpoint are not supported.',
- },
performanceCrux: {
type: 'boolean',
default: true,
diff --git a/src/index.ts b/src/index.ts
index 8090bd13..38ab29bd 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -32,8 +32,6 @@ import {createTools} from './tools/tools.js';
import {logger} from './utils/logger.js';
import {VERSION} from './version.js';
-export {buildFlag} from './ToolHandler.js';
-
puppeteer.setFollowSymlinks(false);
/**
diff --git a/src/telemetry/flag_usage_metrics.json b/src/telemetry/flag_usage_metrics.json
index b962f149..cc85e3ef 100644
--- a/src/telemetry/flag_usage_metrics.json
+++ b/src/telemetry/flag_usage_metrics.json
@@ -405,5 +405,37 @@
{
"name": "filesystem_root_present",
"flagType": "boolean"
+ },
+ {
+ "name": "category_input_present",
+ "flagType": "boolean"
+ },
+ {
+ "name": "category_input",
+ "flagType": "boolean"
+ },
+ {
+ "name": "category_navigation_present",
+ "flagType": "boolean"
+ },
+ {
+ "name": "category_navigation",
+ "flagType": "boolean"
+ },
+ {
+ "name": "category_debugging_present",
+ "flagType": "boolean"
+ },
+ {
+ "name": "category_debugging",
+ "flagType": "boolean"
+ },
+ {
+ "name": "category_memory_present",
+ "flagType": "boolean"
+ },
+ {
+ "name": "category_memory",
+ "flagType": "boolean"
}
]
diff --git a/src/tools/categories.ts b/src/tools/categories.ts
index a7874b2a..e7c7ffcb 100644
--- a/src/tools/categories.ts
+++ b/src/tools/categories.ts
@@ -31,10 +31,3 @@ export const labels = {
[ToolCategory.WEBMCP]: 'WebMCP',
[ToolCategory.PWA]: 'Progressive Web Apps',
};
-
-export const OFF_BY_DEFAULT_CATEGORIES = [
- ToolCategory.EXTENSIONS,
- ToolCategory.THIRD_PARTY,
- ToolCategory.WEBMCP,
- ToolCategory.PWA,
-];
diff --git a/tests/cli.test.ts b/tests/cli.test.ts
index 1576b41f..54d9324e 100644
--- a/tests/cli.test.ts
+++ b/tests/cli.test.ts
@@ -21,11 +21,13 @@ function parseArguments(argv: string[], env: NodeJS.ProcessEnv = {}) {
describe('cli args parsing', () => {
const defaultArgs = {
+ categoryInput: true,
+ categoryNavigation: true,
categoryEmulation: true,
categoryPerformance: true,
categoryNetwork: true,
- categoryExtensions: false,
- categoryExperimentalThirdParty: false,
+ categoryDebugging: true,
+ categoryMemory: true,
autoConnect: undefined,
performanceCrux: true,
usageStatistics: true,
diff --git a/tests/index.test.ts b/tests/index.test.ts
index a7446193..e0170223 100644
--- a/tests/index.test.ts
+++ b/tests/index.test.ts
@@ -22,8 +22,8 @@ import {
import {executablePath} from 'puppeteer';
import {mcpOptions} from '../src/config/mcp-options.js';
+import {getOffByDefaultCategories} from '../src/config/category-options.js';
import type {ToolCategory} from '../src/tools/categories.js';
-import {OFF_BY_DEFAULT_CATEGORIES} from '../src/tools/categories.js';
import type {ToolDefinition} from '../src/tools/ToolDefinition.js';
describe('e2e', () => {
@@ -113,7 +113,7 @@ describe('e2e', () => {
definedNames.sort();
assert.deepStrictEqual(exposedNames, definedNames);
},
- OFF_BY_DEFAULT_CATEGORIES.map(category => `--category-${category}`),
+ getOffByDefaultCategories().map(category => `--category-${category}`),
);
});
@@ -122,7 +122,7 @@ describe('e2e', () => {
const {tools} = await client.listTools();
const exposedNames = tools.map(t => t.name).sort();
const definedNames = await getToolsWithFilteredCategories(
- OFF_BY_DEFAULT_CATEGORIES,
+ getOffByDefaultCategories(),
);
definedNames.sort();
assert.deepStrictEqual(exposedNames, definedNames);