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.tsindex 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.tsindex 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 documentationconst 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.tsindex 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.tsindex 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.tsindex 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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);+ });+ }+});