Chrome DevTools for coding agents
feat: allow configuring tool categories (#454)
Alex Rudenko0fe2b8a2b4d6
diff --git a/README.md b/README.mdindex a4e8fab7..91faecde 100644--- a/README.md+++ b/README.md@@ -331,6 +331,21 @@ The Chrome DevTools MCP server supports the following configuration option:Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.- **Type:** array+- **`--categoryEmulation`**+ Set to false to exlcude tools related to emulation.+ - **Type:** boolean+ - **Default:** `true`++- **`--categoryPerformance`**+ Set to false to exlcude tools related to performance.+ - **Type:** boolean+ - **Default:** `true`++- **`--categoryNetwork`**+ Set to false to exlcude tools related to network.+ - **Type:** boolean+ - **Default:** `true`+<!-- 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.tsindex aaba4631..7466ab93 100644--- a/scripts/generate-docs.ts+++ b/scripts/generate-docs.ts@@ -11,7 +11,7 @@ import {StdioClientTransport} from '@modelcontextprotocol/sdk/client/stdio.js';import type {Tool} from '@modelcontextprotocol/sdk/types.js';import {cliOptions} from '../build/src/cli.js';-import {ToolCategories} from '../build/src/tools/categories.js';+import {ToolCategory, labels} from '../build/src/tools/categories.js';const MCP_SERVER_PATH = 'build/src/index.js';const OUTPUT_PATH = './docs/tool-reference.md';@@ -21,7 +21,7 @@ const README_PATH = './README.md';interface ToolWithAnnotations extends Tool {annotations?: {title?: string;- category?: ToolCategories;+ category?: typeof ToolCategory;};}@@ -67,7 +67,7 @@ function generateToolsTOC(for (const category of sortedCategories) {const categoryTools = categories[category];- const categoryName = category;+ const categoryName = labels[category];toc += `- **${categoryName}** (${categoryTools.length} tools)\n`;// Sort tools within category for TOC@@ -209,7 +209,7 @@ async function generateToolDocumentation(): Promise<void> {});// Sort categories using the enum order- const categoryOrder = Object.values(ToolCategories);+ const categoryOrder = Object.values(ToolCategory);const sortedCategories = Object.keys(categories).sort((a, b) => {const aIndex = categoryOrder.indexOf(a);const bIndex = categoryOrder.indexOf(b);@@ -223,8 +223,8 @@ async function generateToolDocumentation(): Promise<void> {// Generate table of contentsfor (const category of sortedCategories) {const categoryTools = categories[category];- const categoryName = category;- const anchorName = category.toLowerCase().replace(/\s+/g, '-');+ const categoryName = labels[category];+ const anchorName = categoryName.toLowerCase().replace(/\s+/g, '-');markdown += `- **[${categoryName}](#${anchorName})** (${categoryTools.length} tools)\n`;// Sort tools within category for TOC@@ -239,8 +239,9 @@ async function generateToolDocumentation(): Promise<void> {for (const category of sortedCategories) {const categoryTools = categories[category];+ const categoryName = labels[category];- markdown += `## ${category}\n\n`;+ markdown += `## ${categoryName}\n\n`;// Sort tools within categorycategoryTools.sort((a: Tool, b: Tool) => a.name.localeCompare(b.name));diff --git a/src/cli.ts b/src/cli.tsindex 54c83282..5e811ba2 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -139,6 +139,21 @@ export const cliOptions = {describe:'Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',},+ categoryEmulation: {+ type: 'boolean',+ default: true,+ describe: 'Set to false to exlcude tools related to emulation.',+ },+ categoryPerformance: {+ type: 'boolean',+ default: true,+ describe: 'Set to false to exlcude tools related to performance.',+ },+ categoryNetwork: {+ type: 'boolean',+ default: true,+ describe: 'Set to false to exlcude tools related to network.',+ },} satisfies Record<string, YargsOptions>;export function parseArguments(version: string, argv = process.argv) {@@ -185,6 +200,12 @@ export function parseArguments(version: string, argv = process.argv) {`$0 --chrome-arg='--no-sandbox' --chrome-arg='--disable-setuid-sandbox'`,'Launch Chrome without sandboxes. Use with caution.',],+ ['$0 --no-category-emulation', 'Disable tools in the emulation category'],+ [+ '$0 --no-category-performance',+ 'Disable tools in the performance category',+ ],+ ['$0 --no-category-network', 'Disable tools in the network category'],]);return yargsInstancediff --git a/src/main.ts b/src/main.tsindex c1fb8303..44a08c71 100644--- a/src/main.ts+++ b/src/main.ts@@ -19,6 +19,7 @@ import {type CallToolResult,SetLevelRequestSchema,} from './third_party/index.js';+import {ToolCategory} from './tools/categories.js';import * as consoleTools from './tools/console.js';import * as emulationTools from './tools/emulation.js';import * as inputTools from './tools/input.js';@@ -96,6 +97,24 @@ Avoid sharing sensitive or personal information that you do not want to share wiconst toolMutex = new Mutex();function registerTool(tool: ToolDefinition): void {+ if (+ tool.annotations.category === ToolCategory.EMULATION &&+ args.categoryEmulation === false+ ) {+ return;+ }+ if (+ tool.annotations.category === ToolCategory.PERFORMANCE &&+ args.categoryPerformance === false+ ) {+ return;+ }+ if (+ tool.annotations.category === ToolCategory.NETWORK &&+ args.categoryNetwork === false+ ) {+ return;+ }server.registerTool(tool.name,{diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.tsindex d36d473d..00b85a43 100644--- a/src/tools/ToolDefinition.ts+++ b/src/tools/ToolDefinition.ts@@ -10,7 +10,7 @@ import type {Dialog, ElementHandle, Page} from '../third_party/index.js';import type {TraceResult} from '../trace-processing/parse.js';import type {PaginationOptions} from '../utils/types.js';-import type {ToolCategories} from './categories.js';+import type {ToolCategory} from './categories.js';export interface ToolDefinition<Schema extends zod.ZodRawShape = zod.ZodRawShape,@@ -19,7 +19,7 @@ export interface ToolDefinition<description: string;annotations: {title?: string;- category: ToolCategories;+ category: ToolCategory;/*** If true, the tool does not modify its environment.*/diff --git a/src/tools/categories.ts b/src/tools/categories.tsindex 084be6fe..f27a8036 100644--- a/src/tools/categories.ts+++ b/src/tools/categories.ts@@ -4,11 +4,20 @@* SPDX-License-Identifier: Apache-2.0*/-export enum ToolCategories {- INPUT_AUTOMATION = 'Input automation',- NAVIGATION_AUTOMATION = 'Navigation automation',- EMULATION = 'Emulation',- PERFORMANCE = 'Performance',- NETWORK = 'Network',- DEBUGGING = 'Debugging',+export enum ToolCategory {+ INPUT = 'input',+ NAVIGATION = 'navigation',+ EMULATION = 'emulation',+ PERFORMANCE = 'performance',+ NETWORK = 'network',+ DEBUGGING = 'debugging',}++export const labels = {+ [ToolCategory.INPUT]: 'Input automation',+ [ToolCategory.NAVIGATION]: 'Navigation automation',+ [ToolCategory.EMULATION]: 'Emulation',+ [ToolCategory.PERFORMANCE]: 'Performance',+ [ToolCategory.NETWORK]: 'Network',+ [ToolCategory.DEBUGGING]: 'Debugging',+};diff --git a/src/tools/console.ts b/src/tools/console.tsindex 324e04a1..7851930e 100644--- a/src/tools/console.ts+++ b/src/tools/console.ts@@ -7,7 +7,7 @@import {zod} from '../third_party/index.js';import type {ConsoleMessageType} from '../third_party/index.js';-import {ToolCategories} from './categories.js';+import {ToolCategory} from './categories.js';import {defineTool} from './ToolDefinition.js';const FILTERABLE_MESSAGE_TYPES: readonly [@@ -40,7 +40,7 @@ export const listConsoleMessages = defineTool({description:'List all console messages for the currently selected page since the last navigation.',annotations: {- category: ToolCategories.DEBUGGING,+ category: ToolCategory.DEBUGGING,readOnlyHint: true,},schema: {@@ -86,7 +86,7 @@ export const getConsoleMessage = defineTool({name: 'get_console_message',description: `Gets a console message by its ID. You can get all messages by calling ${listConsoleMessages.name}.`,annotations: {- category: ToolCategories.DEBUGGING,+ category: ToolCategory.DEBUGGING,readOnlyHint: true,},schema: {diff --git a/src/tools/emulation.ts b/src/tools/emulation.tsindex eceaa53b..2222e4e3 100644--- a/src/tools/emulation.ts+++ b/src/tools/emulation.ts@@ -6,7 +6,7 @@import {zod, PredefinedNetworkConditions} from '../third_party/index.js';-import {ToolCategories} from './categories.js';+import {ToolCategory} from './categories.js';import {defineTool} from './ToolDefinition.js';const throttlingOptions: [string, ...string[]] = [@@ -19,7 +19,7 @@ export const emulateNetwork = defineTool({name: 'emulate_network',description: `Emulates network conditions such as throttling or offline mode on the selected page.`,annotations: {- category: ToolCategories.EMULATION,+ category: ToolCategory.EMULATION,readOnlyHint: false,},schema: {@@ -65,7 +65,7 @@ export const emulateCpu = defineTool({name: 'emulate_cpu',description: `Emulates CPU throttling by slowing down the selected page's execution.`,annotations: {- category: ToolCategories.EMULATION,+ category: ToolCategory.EMULATION,readOnlyHint: false,},schema: {diff --git a/src/tools/input.ts b/src/tools/input.tsindex 78a1372a..9913ee56 100644--- a/src/tools/input.ts+++ b/src/tools/input.ts@@ -8,14 +8,14 @@ import type {McpContext, TextSnapshotNode} from '../McpContext.js';import {zod} from '../third_party/index.js';import type {ElementHandle} from '../third_party/index.js';-import {ToolCategories} from './categories.js';+import {ToolCategory} from './categories.js';import {defineTool} from './ToolDefinition.js';export const click = defineTool({name: 'click',description: `Clicks on the provided element`,annotations: {- category: ToolCategories.INPUT_AUTOMATION,+ category: ToolCategory.INPUT,readOnlyHint: false,},schema: {@@ -54,7 +54,7 @@ export const hover = defineTool({name: 'hover',description: `Hover over the provided element`,annotations: {- category: ToolCategories.INPUT_AUTOMATION,+ category: ToolCategory.INPUT,readOnlyHint: false,},schema: {@@ -138,7 +138,7 @@ export const fill = defineTool({name: 'fill',description: `Type text into a input, text area or select an option from a <select> element.`,annotations: {- category: ToolCategories.INPUT_AUTOMATION,+ category: ToolCategory.INPUT,readOnlyHint: false,},schema: {@@ -166,7 +166,7 @@ export const drag = defineTool({name: 'drag',description: `Drag an element onto another element`,annotations: {- category: ToolCategories.INPUT_AUTOMATION,+ category: ToolCategory.INPUT,readOnlyHint: false,},schema: {@@ -195,7 +195,7 @@ export const fillForm = defineTool({name: 'fill_form',description: `Fill out multiple form elements at once`,annotations: {- category: ToolCategories.INPUT_AUTOMATION,+ category: ToolCategory.INPUT,readOnlyHint: false,},schema: {@@ -227,7 +227,7 @@ export const uploadFile = defineTool({name: 'upload_file',description: 'Upload a file through a provided element.',annotations: {- category: ToolCategories.INPUT_AUTOMATION,+ category: ToolCategory.INPUT,readOnlyHint: false,},schema: {diff --git a/src/tools/network.ts b/src/tools/network.tsindex f31bd27a..a4f21595 100644--- a/src/tools/network.ts+++ b/src/tools/network.ts@@ -7,7 +7,7 @@import {zod} from '../third_party/index.js';import type {ResourceType} from '../third_party/index.js';-import {ToolCategories} from './categories.js';+import {ToolCategory} from './categories.js';import {defineTool} from './ToolDefinition.js';const FILTERABLE_RESOURCE_TYPES: readonly [ResourceType, ...ResourceType[]] = [@@ -36,7 +36,7 @@ export const listNetworkRequests = defineTool({name: 'list_network_requests',description: `List all requests for the currently selected page since the last navigation.`,annotations: {- category: ToolCategories.NETWORK,+ category: ToolCategory.NETWORK,readOnlyHint: true,},schema: {@@ -82,7 +82,7 @@ export const getNetworkRequest = defineTool({name: 'get_network_request',description: `Gets a network request by URL. You can get all requests by calling ${listNetworkRequests.name}.`,annotations: {- category: ToolCategories.NETWORK,+ category: ToolCategory.NETWORK,readOnlyHint: true,},schema: {diff --git a/src/tools/pages.ts b/src/tools/pages.tsindex a1c39bee..0dbaa39b 100644--- a/src/tools/pages.ts+++ b/src/tools/pages.ts@@ -7,14 +7,14 @@import {logger} from '../logger.js';import {zod} from '../third_party/index.js';-import {ToolCategories} from './categories.js';+import {ToolCategory} from './categories.js';import {CLOSE_PAGE_ERROR, defineTool, timeoutSchema} from './ToolDefinition.js';export const listPages = defineTool({name: 'list_pages',description: `Get a list of pages open in the browser.`,annotations: {- category: ToolCategories.NAVIGATION_AUTOMATION,+ category: ToolCategory.NAVIGATION,readOnlyHint: true,},schema: {},@@ -27,7 +27,7 @@ export const selectPage = defineTool({name: 'select_page',description: `Select a page as a context for future tool calls.`,annotations: {- category: ToolCategories.NAVIGATION_AUTOMATION,+ category: ToolCategory.NAVIGATION,readOnlyHint: true,},schema: {@@ -49,7 +49,7 @@ export const closePage = defineTool({name: 'close_page',description: `Closes the page by its index. The last open page cannot be closed.`,annotations: {- category: ToolCategories.NAVIGATION_AUTOMATION,+ category: ToolCategory.NAVIGATION,readOnlyHint: false,},schema: {@@ -77,7 +77,7 @@ export const newPage = defineTool({name: 'new_page',description: `Creates a new page`,annotations: {- category: ToolCategories.NAVIGATION_AUTOMATION,+ category: ToolCategory.NAVIGATION,readOnlyHint: false,},schema: {@@ -101,7 +101,7 @@ export const navigatePage = defineTool({name: 'navigate_page',description: `Navigates the currently selected page to a URL.`,annotations: {- category: ToolCategories.NAVIGATION_AUTOMATION,+ category: ToolCategory.NAVIGATION,readOnlyHint: false,},schema: {@@ -125,7 +125,7 @@ export const navigatePageHistory = defineTool({name: 'navigate_page_history',description: `Navigates the currently selected page.`,annotations: {- category: ToolCategories.NAVIGATION_AUTOMATION,+ category: ToolCategory.NAVIGATION,readOnlyHint: false,},schema: {@@ -162,7 +162,7 @@ export const resizePage = defineTool({name: 'resize_page',description: `Resizes the selected page's window so that the page has specified dimension`,annotations: {- category: ToolCategories.EMULATION,+ category: ToolCategory.EMULATION,readOnlyHint: false,},schema: {@@ -186,7 +186,7 @@ export const handleDialog = defineTool({name: 'handle_dialog',description: `If a browser dialog was opened, use this command to handle it`,annotations: {- category: ToolCategories.INPUT_AUTOMATION,+ category: ToolCategory.INPUT,readOnlyHint: false,},schema: {diff --git a/src/tools/performance.ts b/src/tools/performance.tsindex 8b587499..420a6213 100644--- a/src/tools/performance.ts+++ b/src/tools/performance.ts@@ -15,7 +15,7 @@ import {traceResultIsSuccess,} from '../trace-processing/parse.js';-import {ToolCategories} from './categories.js';+import {ToolCategory} from './categories.js';import type {Context, Response} from './ToolDefinition.js';import {defineTool} from './ToolDefinition.js';@@ -24,7 +24,7 @@ export const startTrace = defineTool({description:'Starts a performance trace recording on the selected page. This can be used to look for performance problems and insights to improve the performance of the page. It will also report Core Web Vital (CWV) scores for the page.',annotations: {- category: ToolCategories.PERFORMANCE,+ category: ToolCategory.PERFORMANCE,readOnlyHint: true,},schema: {@@ -105,7 +105,7 @@ export const stopTrace = defineTool({description:'Stops the active performance trace recording on the selected page.',annotations: {- category: ToolCategories.PERFORMANCE,+ category: ToolCategory.PERFORMANCE,readOnlyHint: true,},schema: {},@@ -123,7 +123,7 @@ export const analyzeInsight = defineTool({description:'Provides more detailed information on a specific Performance Insight that was highlighted in the results of a trace recording.',annotations: {- category: ToolCategories.PERFORMANCE,+ category: ToolCategory.PERFORMANCE,readOnlyHint: true,},schema: {diff --git a/src/tools/screenshot.ts b/src/tools/screenshot.tsindex 91afa25d..9f38b11b 100644--- a/src/tools/screenshot.ts+++ b/src/tools/screenshot.ts@@ -7,14 +7,14 @@import {zod} from '../third_party/index.js';import type {ElementHandle, Page} from '../third_party/index.js';-import {ToolCategories} from './categories.js';+import {ToolCategory} from './categories.js';import {defineTool} from './ToolDefinition.js';export const screenshot = defineTool({name: 'take_screenshot',description: `Take a screenshot of the page or element.`,annotations: {- category: ToolCategories.DEBUGGING,+ category: ToolCategory.DEBUGGING,readOnlyHint: true,},schema: {diff --git a/src/tools/script.ts b/src/tools/script.tsindex 70115fc3..de28fe0b 100644--- a/src/tools/script.ts+++ b/src/tools/script.ts@@ -7,7 +7,7 @@import {zod} from '../third_party/index.js';import type {Frame, JSHandle, Page} from '../third_party/index.js';-import {ToolCategories} from './categories.js';+import {ToolCategory} from './categories.js';import {defineTool} from './ToolDefinition.js';export const evaluateScript = defineTool({@@ -15,7 +15,7 @@ export const evaluateScript = defineTool({description: `Evaluate a JavaScript function inside the currently selected page. Returns the response as JSONso returned values have to JSON-serializable.`,annotations: {- category: ToolCategories.DEBUGGING,+ category: ToolCategory.DEBUGGING,readOnlyHint: false,},schema: {diff --git a/src/tools/snapshot.ts b/src/tools/snapshot.tsindex 05df1734..9b108d30 100644--- a/src/tools/snapshot.ts+++ b/src/tools/snapshot.ts@@ -6,7 +6,7 @@import {zod} from '../third_party/index.js';-import {ToolCategories} from './categories.js';+import {ToolCategory} from './categories.js';import {defineTool, timeoutSchema} from './ToolDefinition.js';export const takeSnapshot = defineTool({@@ -14,7 +14,7 @@ export const takeSnapshot = defineTool({description: `Take a text snapshot of the currently selected page based on the a11y tree. The snapshot lists page elements along with a uniqueidentifier (uid). Always use the latest snapshot. Prefer taking a snapshot over taking a screenshot.`,annotations: {- category: ToolCategories.DEBUGGING,+ category: ToolCategory.DEBUGGING,readOnlyHint: true,},schema: {@@ -34,7 +34,7 @@ export const waitFor = defineTool({name: 'wait_for',description: `Wait for the specified text to appear on the selected page.`,annotations: {- category: ToolCategories.NAVIGATION_AUTOMATION,+ category: ToolCategory.NAVIGATION,readOnlyHint: true,},schema: {diff --git a/tests/cli.test.ts b/tests/cli.test.tsindex 2c66ac13..19502e28 100644--- a/tests/cli.test.ts+++ b/tests/cli.test.ts@@ -9,9 +9,19 @@ import {describe, it} from 'node:test';import {parseArguments} from '../src/cli.js';describe('cli args parsing', () => {+ const defaultArgs = {+ 'category-emulation': true,+ categoryEmulation: true,+ 'category-performance': true,+ categoryPerformance: true,+ 'category-network': true,+ categoryNetwork: true,+ };+it('parses with default args', async () => {const args = parseArguments('1.0.0', ['node', 'main.js']);assert.deepStrictEqual(args, {+ ...defaultArgs,_: [],headless: false,isolated: false,@@ -28,6 +38,7 @@ describe('cli args parsing', () => {'http://localhost:3000',]);assert.deepStrictEqual(args, {+ ...defaultArgs,_: [],headless: false,isolated: false,@@ -46,6 +57,7 @@ describe('cli args parsing', () => {'',]);assert.deepStrictEqual(args, {+ ...defaultArgs,_: [],headless: false,isolated: false,@@ -65,6 +77,7 @@ describe('cli args parsing', () => {'/tmp/test 123/chrome',]);assert.deepStrictEqual(args, {+ ...defaultArgs,_: [],headless: false,isolated: false,@@ -83,6 +96,7 @@ describe('cli args parsing', () => {'888x777',]);assert.deepStrictEqual(args, {+ ...defaultArgs,_: [],headless: false,isolated: false,@@ -103,6 +117,7 @@ describe('cli args parsing', () => {`--chrome-arg='--disable-setuid-sandbox'`,]);assert.deepStrictEqual(args, {+ ...defaultArgs,_: [],headless: false,isolated: false,@@ -121,6 +136,7 @@ describe('cli args parsing', () => {'ws://127.0.0.1:9222/devtools/browser/abc123',]);assert.deepStrictEqual(args, {+ ...defaultArgs,_: [],headless: false,isolated: false,@@ -139,6 +155,7 @@ describe('cli args parsing', () => {'wss://example.com:9222/devtools/browser/abc123',]);assert.deepStrictEqual(args, {+ ...defaultArgs,_: [],headless: false,isolated: false,@@ -163,4 +180,22 @@ describe('cli args parsing', () => {'X-Custom': 'value',});});++ it('parses disabled category', async () => {+ const args = parseArguments('1.0.0', [+ 'node',+ 'main.js',+ '--no-category-emulation',+ ]);+ assert.deepStrictEqual(args, {+ ...defaultArgs,+ _: [],+ headless: false,+ isolated: false,+ $0: 'npx chrome-devtools-mcp@latest',+ channel: 'stable',+ 'category-emulation': false,+ categoryEmulation: false,+ });+ });});