Skip to content

Chrome DevTools for coding agents

refactor: create all tools and register per slim mode (#2874)

Nikolay Vitkov99847a71ab8d
diff --git a/scripts/generate-cli.ts b/scripts/generate-cli.ts
index 3e3ae7fd..0f19bfd2 100644
--- a/scripts/generate-cli.ts
+++ b/scripts/generate-cli.ts
@@ -15,7 +15,8 @@ import {mcpOptions} from '../build/src/config/mcp-options.js';
import {ConfigParser} from '../build/src/config/ConfigParser.js';
import {zod} from '../build/src/third_party/index.js';
import {labels, ToolCategory} from '../build/src/tools/categories.js';
-import {createTools} from '../build/src/tools/tools.js';
+import {isSlimTool} from '../build/src/tools/ToolDefinition.js';
+import {createTools, requiresHiddenFlag} from '../build/src/tools/tools.js';
const OUTPUT_PATH = path.join(
import.meta.dirname,
@@ -74,6 +75,10 @@ async function generateCli() {
const sortedTools = tools
.sort((a, b) => a.name.localeCompare(b.name))
.filter(tool => {
+ // Skipping slim tools and tools behind internal flags.
+ if (isSlimTool(tool) || requiresHiddenFlag(tool)) {
+ return false;
+ }
// Skipping fill_form because it is not relevant in shell scripts
// and CLI does not handle array/JSON args well.
if (tool.name === 'fill_form') {
diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts
index deda610f..61f80108 100644
--- a/scripts/generate-docs.ts
+++ b/scripts/generate-docs.ts
@@ -16,11 +16,12 @@ import {
import type {ParsedArguments} from '../build/src/config/ConfigParser.js';
import {zod} from '../build/src/third_party/index.js';
import {ToolCategory, labels} from '../build/src/tools/categories.js';
+import {isSlimTool} from '../build/src/tools/ToolDefinition.js';
import type {
DefinedPageTool,
ToolDefinition,
} from '../src/tools/ToolDefinition.js';
-import {createTools} from '../build/src/tools/tools.js';
+import {createTools, requiresHiddenFlag} from '../build/src/tools/tools.js';
const OUTPUT_PATH = './docs/tool-reference.md';
const SLIM_OUTPUT_PATH = './docs/slim-tool-reference.md';
@@ -84,6 +85,9 @@ function addCrossLinks(text: string, tools: ToolWithAnnotations[]): string {
function hasOffByDefaultConditions(tool: ToolWithAnnotations): boolean {
for (const condition of tool.annotations?.conditions || []) {
+ if (condition === 'slim') {
+ continue;
+ }
const option = mcpOptions[condition];
if (!option || !('default' in option) || option.default !== true) {
return true;
@@ -247,6 +251,9 @@ async function generateReference(
const conditions = tool.annotations?.conditions || [];
for (const condition of conditions) {
+ if (condition === 'slim') {
+ continue;
+ }
const option = mcpOptions[condition];
if (!option || !('default' in option) || option.default !== true) {
requiredFlags.push(`--${condition}=true`);
@@ -338,6 +345,11 @@ function getToolsAndCategories(
return false;
}
+ // Skipping tools behind internal flags.
+ if (requiresHiddenFlag(tool)) {
+ return false;
+ }
+
// Skipping internal interop tools not meant for public documentation
const skipTools = ['get_tab_id'];
if (skipTools.includes(tool.name)) {
@@ -399,12 +411,12 @@ function getToolsAndCategories(
async function generateToolDocumentation(): Promise<void> {
try {
console.log('Generating tool documentation from definitions...');
+ // Returns both the regular and the slim tools.
+ const tools = createTools({pageIdRouting: true} as ParsedArguments);
{
const {toolsWithAnnotations, categories, sortedCategories} =
- getToolsAndCategories(
- createTools({slim: false, pageIdRouting: true} as ParsedArguments),
- );
+ getToolsAndCategories(tools.filter(tool => !isSlimTool(tool)));
await generateReference(
'Chrome DevTools MCP Tool Reference',
OUTPUT_PATH,
@@ -416,7 +428,7 @@ async function generateToolDocumentation(): Promise<void> {
{
const {toolsWithAnnotations, categories, sortedCategories} =
- getToolsAndCategories(createTools({slim: true}));
+ getToolsAndCategories(tools.filter(tool => isSlimTool(tool)));
await generateReference(
'Chrome DevTools MCP Slim Tool Reference',
SLIM_OUTPUT_PATH,
diff --git a/scripts/update_metrics.ts b/scripts/update_metrics.ts
index 320c9d72..5423b292 100644
--- a/scripts/update_metrics.ts
+++ b/scripts/update_metrics.ts
@@ -37,12 +37,7 @@ function writeToolCallMetricsConfig() {
}
// Avoid 'as ParsedArguments' by using parseArguments
- const fullTools = createTools(new ConfigParser('0.0.0', ['', '']).parse());
- const slimTools = createTools(
- new ConfigParser('0.0.0', ['', '', '--slim']).parse(),
- );
-
- const allTools = [...fullTools, ...slimTools];
+ const allTools = createTools(new ConfigParser('0.0.0', ['', '']).parse());
if (!HaveUniqueNames(allTools)) {
throw new Error('Error: Duplicate tool names found.');
diff --git a/src/ToolHandler.ts b/src/ToolHandler.ts
index c07155b7..49ad2b9c 100644
--- a/src/ToolHandler.ts
+++ b/src/ToolHandler.ts
@@ -20,6 +20,7 @@ import type {
FileVerificationOption,
ToolDefinition,
} from './tools/ToolDefinition.js';
+import {isAvailableInMode, isSlimTool} from './tools/ToolDefinition.js';
import {logger} from './utils/logger.js';
import type {Mutex} from './third_party/index.js';
import {fileURLToPath, pathToFileURL} from 'node:url';
@@ -55,7 +56,17 @@ function buildDisabledMessage(
function getToolStatusInfo(
tool: ToolDefinition | DefinedPageTool,
serverArgs: ParsedArguments,
-): {disabled: boolean; reason?: string} {
+): {disabled: boolean; reason?: string; unavailableInMode?: boolean} {
+ if (!isAvailableInMode(tool, serverArgs)) {
+ return {
+ disabled: true,
+ unavailableInMode: true,
+ reason: isSlimTool(tool)
+ ? `Tool ${tool.name} is only available with --slim.`
+ : `Tool ${tool.name} is not available with --slim.`,
+ };
+ }
+
const category = tool.annotations.category;
if (category) {
const flag = categoryToFlagName(category);
@@ -180,9 +191,13 @@ export class ToolHandler {
private readonly forgetBrowserOnTimeout: (browser: Browser) => void,
private readonly abandonPendingBrowserAttemptOnTimeout: () => void,
) {
- const {disabled, reason} = getToolStatusInfo(tool, serverArgs);
+ const {disabled, reason, unavailableInMode} = getToolStatusInfo(
+ tool,
+ serverArgs,
+ );
this.disabledReason = reason;
- this.disabled = disabled && !serverArgs.viaCli;
+ this.disabled =
+ disabled && (Boolean(unavailableInMode) || !serverArgs.viaCli);
this.inputSchema = tool.schema;
this.registeredInputSchema = zod.object(this.inputSchema).strict();
@@ -276,7 +291,7 @@ export class ToolHandler {
page =
this.serverArgs.pageIdRouting &&
pageId !== undefined &&
- !this.serverArgs.slim
+ !isSlimTool(this.tool)
? context.getPageById(pageId)
: context.getSelectedMcpPage();
await page?.init();
diff --git a/src/index.ts b/src/index.ts
index 47c73e2e..1fb88fd5 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -17,13 +17,18 @@ import {FilePersistence} from './telemetry/persistence.js';
import {
type CallToolResult,
McpServer as SdkMcpServer,
+ type RegisteredTool,
type Root,
type Transport,
Mutex,
puppeteer,
} from './third_party/index.js';
import {ToolHandler} from './ToolHandler.js';
-import type {DefinedPageTool, ToolDefinition} from './tools/ToolDefinition.js';
+import {
+ type DefinedPageTool,
+ isAvailableInMode,
+ type ToolDefinition,
+} from './tools/ToolDefinition.js';
import {createTools} from './tools/tools.js';
import {logger} from './utils/logger.js';
import {VERSION} from './version.js';
@@ -45,6 +50,11 @@ export interface McpServerOptions {
logFile?: fs.WriteStream;
}
+interface ToolEntry {
+ handler: ToolHandler;
+ registeredTool: RegisteredTool;
+}
+
export class McpServer {
readonly server: SdkMcpServer;
#serverArgs: ParsedArguments;
@@ -58,7 +68,7 @@ export class McpServer {
*/
#lastClientRoots?: Root[];
#toolMutex = new Mutex();
- #tools = new Map<string, ToolHandler>();
+ #tools = new Map<string, ToolEntry>();
private constructor(serverArgs: ParsedArguments, options: McpServerOptions) {
this.#serverArgs = serverArgs;
@@ -82,7 +92,11 @@ export class McpServer {
title: 'Chrome DevTools MCP server',
version: VERSION,
},
- {capabilities: {logging: {}}},
+ {
+ capabilities: {logging: {}, tools: {listChanged: true}},
+ // Enabling or updating many tools at once sends a single notification.
+ debouncedNotificationMethods: ['notifications/tools/list_changed'],
+ },
);
this.server.server.setRequestHandler('logging/setLevel', () => {
@@ -124,7 +138,7 @@ export class McpServer {
name: string,
args: Record<string, unknown> = {},
): Promise<CallToolResult> {
- const toolHandler = this.#tools.get(name);
+ const toolHandler = this.#tools.get(name)?.handler;
if (!toolHandler) {
return {
content: [
@@ -194,9 +208,11 @@ export class McpServer {
}
async #init(): Promise<void> {
- const tools = createTools(this.#serverArgs);
- for (const tool of tools) {
- this.#registerTool(tool);
+ for (const tool of createTools(this.#serverArgs)) {
+ // Slim and regular tools may share names, only register the current mode.
+ if (isAvailableInMode(tool, this.#serverArgs)) {
+ this.#registerTool(tool);
+ }
}
await loadIssueDescriptions();
}
@@ -283,8 +299,8 @@ export class McpServer {
return this.#context;
}
- #registerTool(tool: ToolDefinition | DefinedPageTool): void {
- const toolHandler = new ToolHandler(
+ #createToolHandler(tool: ToolDefinition | DefinedPageTool): ToolHandler {
+ return new ToolHandler(
tool,
this.#serverArgs,
() => this.#getContext(),
@@ -292,22 +308,26 @@ export class McpServer {
browser => this.#browserManager.forget(browser),
() => this.#browserManager.abandonPendingAttempt(),
);
+ }
- this.#tools.set(tool.name, toolHandler);
+ #registerTool(tool: ToolDefinition | DefinedPageTool): void {
+ const handler = this.#createToolHandler(tool);
const registeredTool = this.server.registerTool(
tool.name,
{
description: tool.description,
- inputSchema: toolHandler.registeredInputSchema,
+ inputSchema: handler.registeredInputSchema,
annotations: tool.annotations,
},
- toolHandler.handle,
+ handler.handle,
);
- if (toolHandler.disabled) {
+ if (handler.disabled) {
registeredTool.disable();
}
+
+ this.#tools.set(tool.name, {handler, registeredTool});
}
}
diff --git a/src/telemetry/tool_call_metrics.json b/src/telemetry/tool_call_metrics.json
index c3d43e42..2126df0c 100644
--- a/src/telemetry/tool_call_metrics.json
+++ b/src/telemetry/tool_call_metrics.json
@@ -1222,5 +1222,53 @@
"argType": "number"
}
]
+ },
+ {
+ "name": "get_devtools_comments",
+ "args": [
+ {
+ "name": "page_id",
+ "argType": "number"
+ }
+ ]
+ },
+ {
+ "name": "open_devtools",
+ "args": [
+ {
+ "name": "page_id",
+ "argType": "number"
+ }
+ ]
+ },
+ {
+ "name": "resolve_devtools_comment",
+ "args": [
+ {
+ "name": "page_id",
+ "argType": "number"
+ },
+ {
+ "name": "thread_id_length",
+ "argType": "number"
+ },
+ {
+ "name": "reply_text_length",
+ "argType": "number"
+ }
+ ]
+ },
+ {
+ "name": "reveal_in_devtools",
+ "args": [
+ {
+ "name": "page_id",
+ "argType": "number"
+ },
+ {
+ "name": "panel_name_length",
+ "argType": "number"
+ }
+ ]
}
]
diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.ts
index 4027f014..bbd3425b 100644
--- a/src/tools/ToolDefinition.ts
+++ b/src/tools/ToolDefinition.ts
@@ -84,6 +84,11 @@ export interface BaseToolDefinition<
* If true, the tool does not modify its environment.
*/
readOnlyHint: boolean;
+ /**
+ * If `'slim'` is included, the tool is only available with `--slim`. Tools
+ * without `'slim'` are only available without `--slim`. Slim tools may
+ * reuse the names of other tools, see {@link isAvailableInMode}.
+ */
conditions?: Array<keyof ParsedArguments>;
};
schema: Schema;
@@ -456,7 +461,7 @@ export function definePageTool<Schema extends zod.ZodRawShape>(
return {
...tool,
schema: {
- ...(args.pageIdRouting && !args.slim ? pageIdSchema : {}),
+ ...(args.pageIdRouting && !isSlimTool(tool) ? pageIdSchema : {}),
...tool.schema,
},
pageScoped: true,
@@ -551,3 +556,22 @@ export function geolocationTransform(arg: string | undefined) {
longitude,
};
}
+
+export function isSlimTool(
+ tool: Pick<BaseToolDefinition, 'annotations'>,
+): boolean {
+ return Boolean(tool.annotations.conditions?.includes('slim'));
+}
+
+/**
+ * Slim mode replaces the regular tools with the slim tools. Only the tools of
+ * the current mode are registered, so a slim tool may share its name with a
+ * regular tool. `--slim` requires a restart, so the mode never changes while
+ * the server is running.
+ */
+export function isAvailableInMode(
+ tool: Pick<BaseToolDefinition, 'annotations'>,
+ serverArgs: Pick<ParsedArguments, 'slim'>,
+): boolean {
+ return isSlimTool(tool) === Boolean(serverArgs.slim);
+}
diff --git a/src/tools/slim/tools.ts b/src/tools/slim/tools.ts
index 7d433ffc..ed17ca38 100644
--- a/src/tools/slim/tools.ts
+++ b/src/tools/slim/tools.ts
@@ -18,6 +18,7 @@ export const screenshot = definePageTool(() => ({
category: ToolCategory.DEBUGGING,
// Not read-only due to filePath param.
readOnlyHint: false,
+ conditions: ['slim'],
},
schema: {},
blockedByDialog: true,
@@ -43,6 +44,7 @@ export const navigate = definePageTool((args: ParsedArguments) => {
annotations: {
category: ToolCategory.NAVIGATION,
readOnlyHint: false,
+ conditions: ['slim'],
},
schema: {
url: zod.string().describe('URL to navigate to'),
@@ -88,7 +90,7 @@ export const evaluate = definePageTool(() => ({
annotations: {
category: ToolCategory.DEBUGGING,
readOnlyHint: false,
- conditions: ['javascriptEvaluation'],
+ conditions: ['slim', 'javascriptEvaluation'],
},
schema: {
script: zod.string().describe(`JS script to run on the page`),
diff --git a/src/tools/tools.ts b/src/tools/tools.ts
index 1c8522da..32c34212 100644
--- a/src/tools/tools.ts
+++ b/src/tools/tools.ts
@@ -5,6 +5,8 @@
*/
import type {ParsedArguments} from '../config/ConfigParser.js';
+import {mcpOptions} from '../config/mcp-options.js';
+import type {YargsOptions} from '../third_party/index.js';
import * as commentsTools from './comments.js';
import * as consoleTools from './console.js';
@@ -28,28 +30,27 @@ import type {DefinedPageTool, ToolDefinition} from './ToolDefinition.js';
import * as webmcpTools from './webmcp.js';
export const createTools = (args: ParsedArguments) => {
- const rawTools = args.slim
- ? Object.values(slimTools)
- : [
- ...(args.devtoolsComments ? Object.values(commentsTools) : []),
- ...Object.values(consoleTools),
- ...Object.values(cssTools),
- ...Object.values(emulationTools),
- ...Object.values(extensionTools),
- ...Object.values(inputTools),
- ...Object.values(lighthouseTools),
- ...Object.values(memoryTools),
- ...Object.values(networkTools),
- ...Object.values(pagesTools),
- ...Object.values(performanceTools),
- ...Object.values(pwaTools),
- ...Object.values(screencastTools),
- ...Object.values(screenshotTools),
- ...Object.values(scriptTools),
- ...Object.values(snapshotTools),
- ...Object.values(thirdPartyDeveloperTools),
- ...Object.values(webmcpTools),
- ];
+ const rawTools = [
+ ...Object.values(commentsTools),
+ ...Object.values(consoleTools),
+ ...Object.values(cssTools),
+ ...Object.values(emulationTools),
+ ...Object.values(extensionTools),
+ ...Object.values(inputTools),
+ ...Object.values(lighthouseTools),
+ ...Object.values(memoryTools),
+ ...Object.values(networkTools),
+ ...Object.values(pagesTools),
+ ...Object.values(performanceTools),
+ ...Object.values(pwaTools),
+ ...Object.values(screencastTools),
+ ...Object.values(screenshotTools),
+ ...Object.values(scriptTools),
+ ...Object.values(slimTools),
+ ...Object.values(snapshotTools),
+ ...Object.values(thirdPartyDeveloperTools),
+ ...Object.values(webmcpTools),
+ ];
const tools: Array<ToolDefinition | DefinedPageTool> = [];
for (const tool of rawTools) {
@@ -60,3 +61,19 @@ export const createTools = (args: ParsedArguments) => {
return tools;
};
+
+/**
+ * Returns true if the tool is gated behind a hidden (internal) flag. Such
+ * tools are excluded from the generated documentation and CLI.
+ */
+export function requiresHiddenFlag(
+ tool: ToolDefinition | DefinedPageTool,
+): boolean {
+ for (const condition of tool.annotations.conditions ?? []) {
+ const option: YargsOptions = mcpOptions[condition];
+ if (option.hidden) {
+ return true;
+ }
+ }
+ return false;
+}
diff --git a/tests/McpServer.test.ts b/tests/McpServer.test.ts
index ced1cd8b..12cd5081 100644
--- a/tests/McpServer.test.ts
+++ b/tests/McpServer.test.ts
@@ -23,7 +23,7 @@ describe('McpServer', () => {
ClearcutLogger.resetForTesting();
});
- async function createTestServer() {
+ async function createTestServer(extraArgs: string[] = []) {
const browserManager = sinon.createStubInstance(BrowserManager);
const browser = createMockPuppeteerBrowser();
browserManager.ensureBrowser.resolves(browser);
@@ -33,9 +33,13 @@ describe('McpServer', () => {
context.getPages.returns([]);
sinon.stub(McpContext, 'from').resolves(context);
- const serverArgs = new ConfigParser('1.0.0', ['node', 'script.js'], {
- CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: 'true',
- }).parse();
+ const serverArgs = new ConfigParser(
+ '1.0.0',
+ ['node', 'script.js', ...extraArgs],
+ {
+ CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: 'true',
+ },
+ ).parse();
const server = await McpServer.from(serverArgs, {browserManager});
return {server, browserManager, context};
}
@@ -82,4 +86,26 @@ describe('McpServer', () => {
sinon.assert.calledOnce(context.createPagesSnapshot);
});
});
+
+ describe('slim mode', () => {
+ it('does not register slim tools without --slim', async () => {
+ const {server} = await createTestServer();
+
+ const result = await server.callTool('navigate', {url: 'about:blank'});
+
+ assert.deepStrictEqual(result.content, [
+ {type: 'text', text: 'Tool navigate not found'},
+ ]);
+ });
+
+ it('registers only slim tools with --slim', async () => {
+ const {server} = await createTestServer(['--slim']);
+
+ const result = await server.callTool('list_pages');
+
+ assert.deepStrictEqual(result.content, [
+ {type: 'text', text: 'Tool list_pages not found'},
+ ]);
+ });
+ });
});
diff --git a/tests/ToolHandler.test.ts b/tests/ToolHandler.test.ts
index 40965416..fa835be8 100644
--- a/tests/ToolHandler.test.ts
+++ b/tests/ToolHandler.test.ts
@@ -544,6 +544,64 @@ describe('ToolHandler', () => {
assert.strictEqual(disabledHandler.disabled, true);
});
+ describe('slim mode', () => {
+ function createHandler(toolName: string, argv: string[]) {
+ const serverArgs = new ConfigParser(
+ '1.0.0',
+ ['node', 'script.js', ...argv],
+ {CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: 'true'},
+ ).parse();
+ const tool = createTools(serverArgs).find(t => t.name === toolName);
+ if (!tool) {
+ assert.fail(`${toolName} not found`);
+ }
+ return new ToolHandler(
+ tool,
+ serverArgs,
+ async () => sinon.createStubInstance(McpContext),
+ new Mutex(),
+ sinon.spy(),
+ sinon.spy(),
+ );
+ }
+
+ it('disables slim tools without --slim', async () => {
+ const handler = createHandler('navigate', []);
+
+ assert.strictEqual(handler.disabled, true);
+ const result = await handler.handle({url: 'https://example.com'});
+ assert.strictEqual(result.isError, true);
+ assert.deepStrictEqual(result.content, [
+ {type: 'text', text: 'Tool navigate is only available with --slim.'},
+ ]);
+ });
+
+ it('disables non-slim tools with --slim', async () => {
+ const handler = createHandler('navigate_page', ['--slim']);
+
+ assert.strictEqual(handler.disabled, true);
+ const result = await handler.handle({url: 'https://example.com'});
+ assert.strictEqual(result.isError, true);
+ assert.deepStrictEqual(result.content, [
+ {
+ type: 'text',
+ text: 'Tool navigate_page is not available with --slim.',
+ },
+ ]);
+ });
+
+ it('enables slim tools with --slim', () => {
+ assert.strictEqual(createHandler('navigate', ['--slim']).disabled, false);
+ });
+
+ it('disables tools from the other mode even via CLI', () => {
+ assert.strictEqual(
+ createHandler('navigate', ['--viaCli']).disabled,
+ true,
+ );
+ });
+ });
+
it('validates files specified in verifyFilesSchema and rewrites input with validated paths/URLs', async () => {
let handlerCalled = false;
let receivedParams: Record<string, unknown> | undefined;
diff --git a/tests/tools/tools.test.ts b/tests/tools/tools.test.ts
new file mode 100644
index 00000000..01d09637
--- /dev/null
+++ b/tests/tools/tools.test.ts
@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert';
+import {describe, it} from 'node:test';
+
+import {ConfigParser} from '../../src/config/ConfigParser.js';
+import {isAvailableInMode} from '../../src/tools/ToolDefinition.js';
+import {createTools} from '../../src/tools/tools.js';
+
+describe('createTools', () => {
+ for (const extraArgs of [[], ['--slim']]) {
+ it(`has unique tool names with [${extraArgs.join(' ')}]`, () => {
+ const serverArgs = new ConfigParser(
+ '0.0.0',
+ ['node', 'script.js', ...extraArgs],
+ {},
+ ).parse();
+
+ const names = createTools(serverArgs)
+ .filter(tool => isAvailableInMode(tool, serverArgs))
+ .map(tool => tool.name);
+
+ assert.strictEqual(new Set(names).size, names.length);
+ });
+ }
+});