Chrome DevTools for coding agents
feat: Add a new tool for listing in-page tools (gated behind a command line flag) (#1239)
Wolfgang Beyercea963be683b
diff --git a/src/McpResponse.ts b/src/McpResponse.tsindex 12a0605d..1651c772 100644--- a/src/McpResponse.ts+++ b/src/McpResponse.ts@@ -12,7 +12,7 @@ import {SnapshotFormatter} from './formatters/SnapshotFormatter.js';import type {McpContext} from './McpContext.js';import type {McpPage} from './McpPage.js';import {UncaughtError} from './PageCollector.js';-import {DevTools} from './third_party/index.js';+import {DevTools, type Protocol} from './third_party/index.js';import type {ConsoleMessage,ImageContent,@@ -20,6 +20,7 @@ import type {ResourceType,TextContent,} from './third_party/index.js';+import type {ToolGroup, ToolDefinition} from './tools/inPage.js';import {handleDialog} from './tools/pages.js';import type {DevToolsData,@@ -40,6 +41,59 @@ interface TraceInsightData {insightName: InsightName;}+async function getToolGroup(+ page: McpPage,+): Promise<ToolGroup<ToolDefinition> | undefined> {+ // Check if there is a `devtoolstooldiscovery` event listener+ const windowHandle = await page.pptrPage.evaluateHandle(() => window);+ // @ts-expect-error internal API+ const client = page.pptrPage._client();+ const {listeners}: {listeners: Protocol.DOMDebugger.EventListener[]} =+ await client.send('DOMDebugger.getEventListeners', {+ objectId: windowHandle.remoteObject().objectId,+ });+ if (listeners.find(l => l.type === 'devtoolstooldiscovery') === undefined) {+ return;+ }++ const toolGroup = await page.pptrPage.evaluate(() => {+ return new Promise<ToolGroup<ToolDefinition> | undefined>(resolve => {+ const event = new CustomEvent('devtoolstooldiscovery');+ // @ts-expect-error Adding custom property+ event.respondWith = (toolGroup: ToolGroup) => {+ if (!window.__dtmcp) {+ window.__dtmcp = {};+ }+ window.__dtmcp.toolGroup = toolGroup;++ // When receiving a toolGroup for the first time, expose a simple execution helper+ if (!window.__dtmcp.executeTool) {+ window.__dtmcp.executeTool = async (toolName, args) => {+ if (!window.__dtmcp?.toolGroup) {+ throw new Error('No tools found on the page');+ }+ const tool = window.__dtmcp.toolGroup.tools.find(+ t => t.name === toolName,+ );+ if (!tool) {+ throw new Error(`Tool ${toolName} not found`);+ }+ return await tool.execute(args);+ };+ }++ resolve(toolGroup);+ };+ window.dispatchEvent(event);+ // If the page does not synchronously call `event.respondWith`, return instead of timing out+ setTimeout(() => {+ resolve(undefined);+ }, 0);+ });+ });+ return toolGroup;+}+export class McpResponse implements Response {#includePages = false;#includeExtensionServiceWorkers = false;@@ -70,6 +124,7 @@ export class McpResponse implements Response {includePreservedMessages?: boolean;};#listExtensions?: boolean;+ #listInPageTools?: boolean;#devToolsData?: DevToolsData;#tabId?: string;#args: ParsedArguments;@@ -110,6 +165,12 @@ export class McpResponse implements Response {this.#listExtensions = true;}+ setListInPageTools(): void {+ if (this.#args.categoryInPageTools) {+ this.#listInPageTools = true;+ }+ }+setIncludeNetworkRequests(value: boolean,options?: PaginationOptions & {@@ -357,6 +418,12 @@ export class McpResponse implements Response {if (this.#listExtensions) {extensions = context.listExtensions();}++ let inPageTools: ToolGroup<ToolDefinition> | undefined;+ if (this.#listInPageTools) {+ inPageTools = await getToolGroup(context.getSelectedMcpPage());+ }+let consoleMessages: Array<ConsoleFormatter | IssueFormatter> | undefined;if (this.#consoleDataOptions?.include) {if (!this.#page) {@@ -459,6 +526,7 @@ export class McpResponse implements Response {traceSummary: this.#attachedTraceSummary,extensions,lighthouseResult: this.#attachedLighthouseResult,+ inPageTools,});}@@ -475,6 +543,7 @@ export class McpResponse implements Response {traceInsight?: TraceInsightData;extensions?: InstalledExtension[];lighthouseResult?: LighthouseData;+ inPageTools?: ToolGroup<ToolDefinition>;},): {content: Array<TextContent | ImageContent>; structuredContent: object} {const structuredContent: {@@ -489,6 +558,7 @@ export class McpResponse implements Response {traceInsights?: Array<{insightName: string; insightKey: string}>;lighthouseResult?: object;extensions?: object[];+ inPageTools?: object;message?: string;networkConditions?: string;navigationTimeout?: number;@@ -726,6 +796,26 @@ Call ${handleDialog.name} to handle it before continuing.`);}}+ if (this.#listInPageTools) {+ structuredContent.inPageTools = data.inPageTools ?? undefined;+ response.push('## In-page tools');+ if (!data.inPageTools || !data.inPageTools.tools) {+ response.push('No in-page tools available.');+ } else {+ const toolGroup = data.inPageTools;+ response.push(`${toolGroup.name}: ${toolGroup.description}`);+ response.push('Available tools:');+ const toolDefinitionsMessage = toolGroup.tools+ .map(tool => {+ return `name="${tool.name}", description="${tool.description}", inputSchema=${JSON.stringify(+ tool.inputSchema,+ )}`;+ })+ .join('\n');+ response.push(toolDefinitionsMessage);+ }+ }+if (this.#networkRequestsOptions?.include && data.networkRequests) {const requests = data.networkRequests;diff --git a/src/bin/chrome-devtools-mcp-cli-options.ts b/src/bin/chrome-devtools-mcp-cli-options.tsindex b4792629..80046b11 100644--- a/src/bin/chrome-devtools-mcp-cli-options.ts+++ b/src/bin/chrome-devtools-mcp-cli-options.ts@@ -216,6 +216,12 @@ export const cliOptions = {describe:'Set to true to include tools related to extensions. Note: This feature is only supported with a pipe connection. autoConnect is not supported.',},+ categoryInPageTools: {+ type: 'boolean',+ hidden: true,+ describe:+ 'Set to true to enable tools exposed by the inspected page itself',+ },performanceCrux: {type: 'boolean',default: true,diff --git a/src/bin/chrome-devtools.ts b/src/bin/chrome-devtools.tsindex 09f4def5..53a8eba5 100644--- a/src/bin/chrome-devtools.ts+++ b/src/bin/chrome-devtools.ts@@ -41,7 +41,7 @@ delete startCliOptions.autoConnect;// Missing CLI serialization.delete startCliOptions.viewport;// CLI is generated based on the default tool definitions. To enable conditional-// tools, they needs to be enabled during CLI generation.+// tools, they need to be enabled during CLI generation.delete startCliOptions.experimentalPageIdRouting;delete startCliOptions.experimentalVision;delete startCliOptions.experimentalInteropTools;diff --git a/src/index.ts b/src/index.tsindex 2689e34a..362f2348 100644--- a/src/index.ts+++ b/src/index.ts@@ -140,6 +140,12 @@ export async function createMcpServer() {return;}+ if (+ tool.annotations.category === ToolCategory.IN_PAGE &&+ !serverArgs.categoryInPageTools+ ) {+ return;+ }if (tool.annotations.conditions?.includes('computerVision') &&!serverArgs.experimentalVisiondiff --git a/src/third_party/index.ts b/src/third_party/index.tsindex f719f4df..0acd5ca8 100644--- a/src/third_party/index.ts+++ b/src/third_party/index.ts@@ -39,6 +39,7 @@ export {default as puppeteer} from 'puppeteer-core';export type * from 'puppeteer-core';export {PipeTransport} from 'puppeteer-core/internal/node/PipeTransport.js';export type {CdpPage} from 'puppeteer-core/internal/cdp/Page.js';+export type {JSONSchema7} from 'json-schema';export {resolveDefaultUserDataDir,detectBrowserPlatform,diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.tsindex 17019880..9a0ef435 100644--- a/src/tools/ToolDefinition.ts+++ b/src/tools/ToolDefinition.ts@@ -129,6 +129,7 @@ export interface Response {): void;setListExtensions(): void;attachLighthouseResult(result: LighthouseData): void;+ setListInPageTools(): void;}/**diff --git a/src/tools/categories.ts b/src/tools/categories.tsindex 9e351268..c8e92c17 100644--- a/src/tools/categories.ts+++ b/src/tools/categories.ts@@ -12,6 +12,7 @@ export enum ToolCategory {NETWORK = 'network',DEBUGGING = 'debugging',EXTENSIONS = 'extensions',+ IN_PAGE = 'in-page',}export const labels = {@@ -22,4 +23,5 @@ export const labels = {[ToolCategory.NETWORK]: 'Network',[ToolCategory.DEBUGGING]: 'Debugging',[ToolCategory.EXTENSIONS]: 'Extensions',+ [ToolCategory.IN_PAGE]: 'In-page tools',};diff --git a/src/tools/inPage.ts b/src/tools/inPage.tsnew file mode 100644index 00000000..2e1deb00--- /dev/null+++ b/src/tools/inPage.ts@@ -0,0 +1,52 @@+/**+ * @license+ * Copyright 2026 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */++import {type JSONSchema7} from '../third_party/index.js';++import {ToolCategory} from './categories.js';+import {definePageTool} from './ToolDefinition.js';++export interface ToolDefinition {+ name: string;+ description: string;+ inputSchema: JSONSchema7;+}++export interface ToolGroup<T extends ToolDefinition> {+ name: string;+ description: string;+ tools: T[];+}++declare global {+ interface Window {+ __dtmcp?: {+ toolGroup?: ToolGroup<+ ToolDefinition & {execute: (args: Record<string, unknown>) => unknown}+ >;+ executeTool?: (+ toolName: string,+ args: Record<string, unknown>,+ ) => unknown;+ };+ }+}++export const listInPageTools = definePageTool({+ name: 'list_in_page_tools',+ description: `Lists all in-page-tools the page exposes for providing runtime information.+ To call 'list_in_page_tools', call 'evaluate_script' with+ 'window.__dtmcp.executeTool("list_in_page_tools", {})'.`,+ annotations: {+ category: ToolCategory.IN_PAGE,+ readOnlyHint: true,+ conditions: ['inPageTools'],+ },+ schema: {},+ handler: async (_request, response, _context) => {+ response.setListInPageTools();+ },+});diff --git a/src/tools/tools.ts b/src/tools/tools.tsindex d448552b..3c74115c 100644--- a/src/tools/tools.ts+++ b/src/tools/tools.ts@@ -9,6 +9,7 @@ import type {ParsedArguments} from '../bin/chrome-devtools-mcp-cli-options.js';import * as consoleTools from './console.js';import * as emulationTools from './emulation.js';import * as extensionTools from './extensions.js';+import * as inPageTools from './inPage.js';import * as inputTools from './input.js';import * as lighthouseTools from './lighthouse.js';import * as memoryTools from './memory.js';@@ -29,6 +30,7 @@ export const createTools = (args: ParsedArguments) => {...Object.values(consoleTools),...Object.values(emulationTools),...Object.values(extensionTools),+ ...Object.values(inPageTools),...Object.values(inputTools),...Object.values(lighthouseTools),...Object.values(memoryTools),diff --git a/tests/McpResponse.test.js.snapshot b/tests/McpResponse.test.js.snapshotindex a5b2e826..fdf8cc5a 100644--- a/tests/McpResponse.test.js.snapshot+++ b/tests/McpResponse.test.js.snapshot@@ -1206,6 +1206,36 @@ exports[`extensions > lists extensions 2`] = `}`;+exports[`inPage tools > lists in-page tools 1`] = `+## In-page tools+My Tool Group: A group of tools+Available tools:+name="myTool", description="Does something", inputSchema={"type":"object","properties":{"foo":{"type":"string"}}}+`;++exports[`inPage tools > lists in-page tools 2`] = `+{+ "inPageTools": {+ "name": "My Tool Group",+ "description": "A group of tools",+ "tools": [+ {+ "name": "myTool",+ "description": "Does something",+ "inputSchema": {+ "type": "object",+ "properties": {+ "foo": {+ "type": "string"+ }+ }+ }+ }+ ]+ }+}+`;+exports[`lighthouse > includes lighthouse report paths 1`] = `## Lighthouse Audit ResultsMode: navigationdiff --git a/tests/McpResponse.test.ts b/tests/McpResponse.test.tsindex 7b2964d5..dbdb9c57 100644--- a/tests/McpResponse.test.ts+++ b/tests/McpResponse.test.ts@@ -10,6 +10,9 @@ import {tmpdir} from 'node:os';import {join} from 'node:path';import {describe, it} from 'node:test';+import sinon from 'sinon';++import type {ParsedArguments} from '../src/bin/chrome-devtools-mcp-cli-options.js';import type {InsightName} from '../src/trace-processing/parse.js';import {parseRawTraceBuffer,@@ -1013,3 +1016,79 @@ describe('lighthouse', () => {});});});++describe('inPage tools', () => {+ function stubToolDiscovery(page: object) {+ // @ts-expect-error Internal API+ const client = page._client();+ const originalSend = client.send.bind(client);+ sinon+ .stub(client, 'send')+ .callsFake(async (method: string, params?: Record<string, unknown>) => {+ if (method === 'DOMDebugger.getEventListeners') {+ return {+ listeners: [+ {+ type: 'devtoolstooldiscovery',+ useCapture: false,+ passive: false,+ once: false,+ scriptId: '0',+ lineNumber: 0,+ columnNumber: 0,+ },+ ],+ };+ }+ return originalSend(method, params);+ });+ }++ it('lists in-page tools', async t => {+ await withMcpContext(+ async (response, context) => {+ response.setListInPageTools();+ const emptyResult = await response.handle('test', context);+ const emptyText = getTextContent(emptyResult.content[0]);+ assert.ok(+ emptyText.includes('No in-page tools available.'),+ 'Should show message for empty in-page tools',+ );++ response.resetResponseLineForTesting();+ const mcpPage = context.getSelectedMcpPage();+ stubToolDiscovery(mcpPage.pptrPage);+ sinon.stub(mcpPage.pptrPage, 'evaluate').resolves({+ name: 'My Tool Group',+ description: 'A group of tools',+ tools: [+ {+ name: 'myTool',+ description: 'Does something',+ inputSchema: {+ type: 'object',+ properties: {+ foo: {type: 'string'},+ },+ },+ },+ ],+ });+ response.setListInPageTools();+ const {content, structuredContent} = await response.handle(+ 'test',+ context,+ );+ const responseText = getTextContent(content[0]);+ t.assert.snapshot?.(responseText);+ assert.ok(+ responseText.includes('inputSchema={"type":"object"'),+ 'Response should include inputSchema',+ );+ t.assert.snapshot?.(JSON.stringify(structuredContent, null, 2));+ },+ undefined,+ {categoryInPageTools: true} as ParsedArguments,+ );+ });+});diff --git a/tests/index.test.ts b/tests/index.test.tsindex 4df17bb6..f08350c0 100644--- a/tests/index.test.ts+++ b/tests/index.test.ts@@ -115,12 +115,27 @@ describe('e2e', () => {});});+ it('has experimental in-Page tools', async () => {+ await withClient(+ async client => {+ const {tools} = await client.listTools();+ const listInPageTools = tools.find(+ t => t.name === 'list_in_page_tools',+ );+ assert.ok(listInPageTools);+ },+ ['--category-in-page-tools'],+ );+ });+it('has experimental extensions tools', async () => {await withClient(async client => {const {tools} = await client.listTools();- const clickAt = tools.find(t => t.name === 'install_extension');- assert.ok(clickAt);+ const installExtension = tools.find(+ t => t.name === 'install_extension',+ );+ assert.ok(installExtension);},['--category-extensions'],);diff --git a/tests/tools/inPage.test.ts b/tests/tools/inPage.test.tsnew file mode 100644index 00000000..79540811--- /dev/null+++ b/tests/tools/inPage.test.ts@@ -0,0 +1,139 @@+/**+ * @license+ * Copyright 2026 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */++import assert from 'node:assert';+import {describe, it} from 'node:test';++import type {ParsedArguments} from '../../src/bin/chrome-devtools-mcp-cli-options.js';+import {listInPageTools} from '../../src/tools/inPage.js';+import {withMcpContext} from '../utils.js';++describe('inPage', () => {+ describe('list_in_page_tools', () => {+ it('lists tools', async () => {+ await withMcpContext(+ async (response, context) => {+ const page = await context.newPage();++ await page.pptrPage.evaluate(() => {+ window.__dtmcp = {+ toolGroup: {+ name: 'test-group',+ description: 'test description',+ tools: [+ {+ name: 'test-tool',+ description: 'test tool description',+ inputSchema: {+ type: 'object',+ properties: {+ arg: {type: 'string'},+ },+ },+ execute: () => 'result',+ },+ ],+ },+ };+ window.addEventListener('devtoolstooldiscovery', (e: Event) => {+ // @ts-expect-error Event has `respondWith`+ e.respondWith(window.__dtmcp?.toolGroup);+ });+ });++ await listInPageTools.handler({params: {}, page}, response, context);++ const result = await response.handle('list_in_page_tools', context);+ // @ts-expect-error `structuredContent` has `inPageTools`+ const actualGroup = result.structuredContent.inPageTools;+ assert.strictEqual(actualGroup.name, 'test-group');+ assert.strictEqual(actualGroup.description, 'test description');+ assert.strictEqual(actualGroup.tools.length, 1);+ assert.strictEqual(actualGroup.tools[0].name, 'test-tool');+ assert.strictEqual(+ actualGroup.tools[0].description,+ 'test tool description',+ );+ assert.deepEqual(actualGroup.tools[0].inputSchema, {+ type: 'object',+ properties: {+ arg: {type: 'string'},+ },+ });+ },+ undefined,+ {categoryInPageTools: true} as ParsedArguments,+ );+ });++ it('handles empty response', async () => {+ await withMcpContext(+ async (response, context) => {+ const page = await context.newPage();+ await page.pptrPage.evaluate(() => {+ window.addEventListener('devtoolstooldiscovery', (e: Event) => {+ // @ts-expect-error Event has `respondWith`+ e.respondWith({});+ });+ });++ await listInPageTools.handler({params: {}, page}, response, context);++ const result = await response.handle('list_in_page_tools', context);+ assert.ok('inPageTools' in result.structuredContent);+ assert.deepEqual(+ (result.structuredContent as {inPageTools: undefined}).inPageTools,+ {},+ );+ },+ undefined,+ {categoryInPageTools: true} as ParsedArguments,+ );+ });++ it('handles no response', async () => {+ await withMcpContext(+ async (response, context) => {+ const page = await context.newPage();+ await page.pptrPage.evaluate(() => {+ window.addEventListener('devtoolstooldiscovery', () => {+ // do nothing+ });+ });++ await listInPageTools.handler({params: {}, page}, response, context);++ const result = await response.handle('list_in_page_tools', context);+ assert.ok('inPageTools' in result.structuredContent);+ assert.strictEqual(+ (result.structuredContent as {inPageTools: undefined}).inPageTools,+ undefined,+ );+ },+ undefined,+ {categoryInPageTools: true} as ParsedArguments,+ );+ });++ it('handles no eventListener', async () => {+ await withMcpContext(+ async (response, context) => {+ const page = await context.newPage();+ await listInPageTools.handler({params: {}, page}, response, context);++ const result = await response.handle('list_in_page_tools', context);+ assert.ok('inPageTools' in result.structuredContent);+ assert.strictEqual(+ (result.structuredContent as {inPageTools: undefined}).inPageTools,+ undefined,+ );+ },+ undefined,+ {categoryInPageTools: true} as ParsedArguments,+ );+ });+ });+});