Chrome DevTools for coding agents
feat: support debugging WebMCP tools in third-party developer tools (#2900)
Wolfgang Beyer0db519f07933
diff --git a/docs/configuration.md b/docs/configuration.mdindex 67389cf0..7e28b632 100644--- a/docs/configuration.md+++ b/docs/configuration.md@@ -40,7 +40,7 @@ The Chrome DevTools MCP server supports the following configuration option:- **Default:** `false`- **`--categoryExperimentalThirdParty`/ `--category-experimental-third-party`**- Set to true to enable third-party developer tools exposed by the inspected page itself+ Set to true to enable third-party developer tools exposed by the inspected page itself (via WebMCP or devtoolstooldiscovery)- **Type:** boolean- **Default:** `false`@@ -50,7 +50,7 @@ The Chrome DevTools MCP server supports the following configuration option:- **Default:** `true`- **`--categoryExperimentalWebmcp`/ `--category-experimental-webmcp`**- Set to true to enable debugging WebMCP tools. Requires Chrome 150+ with the following flag: `--enable-features=WebMCP`+ Set to true to enable WebMCP tools (excluding debugging tools, which are exposed under the third-party developer tools category). Requires Chrome 150+ with the following flag: `--enable-features=WebMCP`- **Type:** boolean- **Default:** `false`diff --git a/docs/tool-reference.md b/docs/tool-reference.mdindex 5806ccaa..d3da9a3c 100644--- a/docs/tool-reference.md+++ b/docs/tool-reference.md@@ -751,7 +751,7 @@ in the DevTools Elements panel (if any).### `execute_3p_developer_tool`-**Description:** Executes a tool exposed by the page. (requires flag: --categoryExperimentalThirdParty=true)+**Description:** Executes a third-party developer tool exposed by the page. (requires flag: --categoryExperimentalThirdParty=true)**Parameters:**@@ -763,9 +763,9 @@ in the DevTools Elements panel (if any).### `list_3p_developer_tools`-**Description:** Lists all third-party developer tools the page exposes for providing runtime information.+**Description:** Lists all third-party developer tools the page exposes for providing runtime information (including debugging WebMCP tools and tools exposed via the 'devtoolstooldiscovery' event).Third-party developer tools can be called via the '[`execute_3p_developer_tool`](#execute_3p_developer_tool)()' MCP tool.-Alternatively, third-party developer tools can be executed by calling '[`evaluate_script`](#evaluate_script)' and adding the+Alternatively, third-party developer tools exposed via the 'devtoolstooldiscovery' event can be executed by calling '[`evaluate_script`](#evaluate_script)' and adding thefollowing command to the script:`window.__dtmcp.executeTool(toolName, params)`This might be helpful when the third-party developer tools return non-serializable values or when composing@@ -783,7 +783,7 @@ third-party developer tools with additional functionality. (requires flag: --cat### `execute_webmcp_tool`-**Description:** Executes a WebMCP tool exposed by the page. (requires flag: --categoryExperimentalWebmcp=true)+**Description:** Executes a WebMCP tool exposed by the page (for debugging tools, use '[`execute_3p_developer_tool`](#execute_3p_developer_tool)'). (requires flag: --categoryExperimentalWebmcp=true)**Parameters:**@@ -795,7 +795,7 @@ third-party developer tools with additional functionality. (requires flag: --cat### `list_webmcp_tools`-**Description:** Lists all WebMCP tools the page exposes. (requires flag: --categoryExperimentalWebmcp=true)+**Description:** Lists all WebMCP tools the page exposes (excluding debugging tools, which are exposed via '[`list_3p_developer_tools`](#list_3p_developer_tools)'). (requires flag: --categoryExperimentalWebmcp=true)**Parameters:**diff --git a/src/McpPage.ts b/src/McpPage.tsindex 8b0d56ea..5b0ae627 100644--- a/src/McpPage.ts+++ b/src/McpPage.ts@@ -4,6 +4,56 @@* SPDX-License-Identifier: Apache-2.0*/+import {DevToolsCommentBridge} from './devtools/DevToolsCommentBridge.js';+import {+ createTargetUniverse,+ type TargetUniverse,+} from './devtools/DevtoolsUtils.js';+import {+ ConsoleCollector,+ NetworkCollector,+ type ListenerMap,+ type UncaughtError,+} from './collectors/PageCollector.js';+import {TextSnapshot} from './TextSnapshot.js';+import type {Locator} from './third_party/index.js';+import {+ PredefinedNetworkConditions,+ type Dialog,+ type ElementHandle,+ type Viewport,+ type WebMCPTool,+ type Protocol,+ type Page,+ type Target,+ type ConsoleMessage,+ type HTTPRequest,+ DevTools,+ type JSONSchema7Definition,+} from './third_party/index.js';+import type {ToolGroups} from './tools/thirdPartyDeveloper.js';+import type {+ ContextPage,+ DevToolsData,+ MatchedStyles,+ Response,+} from './tools/ToolDefinition.js';+import type {+ EmulationSettings,+ GeolocationOptions,+ TextSnapshotNode,+} from './types.js';+import {logger} from './utils/logger.js';+import {+ getNetworkMultiplierFromString,+ WaitForHelper,+ type WaitForEventsResult,+ type DialogAction,+} from './utils/WaitForHelper.js';++const DEFAULT_TIMEOUT = 5_000;+const NAVIGATION_TIMEOUT = 10_000;+export function replaceHtmlElementsWithUids(schema: JSONSchema7Definition) {if (typeof schema === 'boolean') {return;@@ -55,54 +105,13 @@ export function replaceHtmlElementsWithUids(schema: JSONSchema7Definition) {}}-import {DevToolsCommentBridge} from './devtools/DevToolsCommentBridge.js';-import {- createTargetUniverse,- type TargetUniverse,-} from './devtools/DevtoolsUtils.js';-import {- ConsoleCollector,- NetworkCollector,- type ListenerMap,- type UncaughtError,-} from './collectors/PageCollector.js';-import {TextSnapshot} from './TextSnapshot.js';-import type {Locator} from './third_party/index.js';-import {- PredefinedNetworkConditions,- type Dialog,- type ElementHandle,- type Viewport,- type WebMCPTool,- type Protocol,- type Page,- type Target,- type ConsoleMessage,- type HTTPRequest,- DevTools,- type JSONSchema7Definition,-} from './third_party/index.js';-import type {ToolGroups} from './tools/thirdPartyDeveloper.js';-const DEFAULT_TIMEOUT = 5_000;-const NAVIGATION_TIMEOUT = 10_000;-import type {- ContextPage,- DevToolsData,- MatchedStyles,- Response,-} from './tools/ToolDefinition.js';-import type {- EmulationSettings,- GeolocationOptions,- TextSnapshotNode,-} from './types.js';-import {logger} from './utils/logger.js';-import {- getNetworkMultiplierFromString,- WaitForHelper,- type WaitForEventsResult,- type DialogAction,-} from './utils/WaitForHelper.js';+function isDebuggingWebMcpTool(tool: WebMCPTool): boolean {+ return Boolean(+ tool.annotations &&+ 'debugging' in tool.annotations &&+ tool.annotations.debugging === true,+ );+}function isBackendNodeId(id: unknown,@@ -143,7 +152,7 @@ export class McpPage implements ContextPage {#dialog?: Dialog;#dialogHandler: (dialog: Dialog) => void;- thirdPartyDeveloperTools: ToolGroups = [];+ eventBasedThirdPartyTools: ToolGroups = [];#networkCollector?: NetworkCollector;#consoleCollector?: ConsoleCollector;@@ -336,8 +345,34 @@ export class McpPage implements ContextPage {}}+ #getDebuggingWebMcpToolGroups(): ToolGroups {+ if (!this.#pptrPage) {+ return [];+ }+ const webmcpTools = this.#pptrPage.webmcp+ .tools()+ .filter(isDebuggingWebMcpTool);+ if (webmcpTools.length === 0) {+ return [];+ }+ return [+ {+ name: 'WebMCP Tools',+ description: 'Tools exposed via WebMCP',+ tools: webmcpTools.map(tool => ({+ name: tool.name,+ description: tool.description,+ inputSchema: structuredClone(tool.inputSchema ?? {}),+ })),+ },+ ];+ }+getThirdPartyDeveloperTools(): ToolGroups {- return this.thirdPartyDeveloperTools;+ return [+ ...this.#getDebuggingWebMcpToolGroups(),+ ...this.eventBasedThirdPartyTools,+ ];}async getToolGroups(): Promise<ToolGroups> {@@ -345,15 +380,16 @@ export class McpPage implements ContextPage {using windowHandle = await this.pptrPage.evaluateHandle(() => window);// @ts-expect-error internal APIconst client = this.pptrPage._client();- const {listeners}: {listeners: Protocol.DOMDebugger.EventListener[]} =+ const {listeners = []}: {listeners?: Protocol.DOMDebugger.EventListener[]} =await client.send('DOMDebugger.getEventListeners', {objectId: windowHandle.remoteObject().objectId,});if (listeners.find(l => l.type === 'devtoolstooldiscovery') === undefined) {- return [];+ this.eventBasedThirdPartyTools = [];+ return this.getThirdPartyDeveloperTools();}- const toolGroups = await this.pptrPage.evaluate(() => {+ const eventToolGroups = await this.pptrPage.evaluate(() => {if (window.__dtmcp) {window.__dtmcp.toolGroups = [];}@@ -430,19 +466,21 @@ export class McpPage implements ContextPage {});});- for (const group of toolGroups) {+ for (const group of eventToolGroups) {for (const tool of group.tools ?? []) {replaceHtmlElementsWithUids(tool.inputSchema);}}- this.thirdPartyDeveloperTools = toolGroups;+ this.eventBasedThirdPartyTools = eventToolGroups;- return toolGroups;+ return this.getThirdPartyDeveloperTools();}getWebMcpTools(): WebMCPTool[] {- return this.pptrPage.webmcp.tools();+ return this.pptrPage.webmcp+ .tools()+ .filter(tool => !isDebuggingWebMcpTool(tool));}resolveCdpRequestId(cdpRequestId: string): number | undefined {@@ -595,6 +633,22 @@ export class McpPage implements ContextPage {params: Record<string, unknown>,response: Response,): Promise<void> {+ const webmcpTool = this.pptrPage.webmcp+ .tools()+ .find(t => t.name === toolName && isDebuggingWebMcpTool(t));+ if (webmcpTool) {+ const {status, output, errorText} = await webmcpTool.execute(params);+ if (status !== 'Completed') {+ throw new Error(errorText || `Tool execution failed: ${status}`);+ }+ if (output !== undefined) {+ response.appendResponseLine(JSON.stringify(output, null, 2));+ } else {+ response.appendResponseLine('Tool returned no result.');+ }+ return;+ }+// Creates array of ElementHandles from the UIDs in the params.// We do not replace the uids with the ElementsHandles yet, because// the `evaluate` function only turns them into DOM elements if theydiff --git a/src/config/category-options.ts b/src/config/category-options.tsindex cbb73cb7..1dea2dfe 100644--- a/src/config/category-options.ts+++ b/src/config/category-options.ts@@ -38,7 +38,7 @@ const categoryOverrides: Record<[ToolCategory.MEMORY]: {},[ToolCategory.WEBMCP]: {describe:- 'Set to true to enable debugging WebMCP tools. Requires Chrome 150+ with the following flag: `--enable-features=WebMCP`',+ 'Set to true to enable WebMCP tools (excluding debugging tools, which are exposed under the third-party developer tools category). Requires Chrome 150+ with the following flag: `--enable-features=WebMCP`',offByDefault: true,},[ToolCategory.EXTENSIONS]: {@@ -48,7 +48,7 @@ const categoryOverrides: Record<},[ToolCategory.THIRD_PARTY]: {describe:- 'Set to true to enable third-party developer tools exposed by the inspected page itself',+ 'Set to true to enable third-party developer tools exposed by the inspected page itself (via WebMCP or devtoolstooldiscovery)',offByDefault: true,},[ToolCategory.PWA]: {diff --git a/src/config/cli-options.ts b/src/config/cli-options.tsindex 30ef5e85..b7b030de 100644--- a/src/config/cli-options.ts+++ b/src/config/cli-options.ts@@ -364,7 +364,7 @@ export const commands: Commands = {},execute_3p_developer_tool: {description:- 'Executes a tool exposed by the page. (requires flag: --categoryExperimentalThirdParty=true)',+ 'Executes a third-party developer tool exposed by the page. (requires flag: --categoryExperimentalThirdParty=true)',category: 'Third-party',args: {pageId: {@@ -389,7 +389,7 @@ export const commands: Commands = {},execute_webmcp_tool: {description:- 'Executes a WebMCP tool exposed by the page. (requires flag: --categoryExperimentalWebmcp=true)',+ "Executes a WebMCP tool exposed by the page (for debugging tools, use 'execute_3p_developer_tool'). (requires flag: --categoryExperimentalWebmcp=true)",category: 'WebMCP',args: {pageId: {@@ -1056,7 +1056,7 @@ export const commands: Commands = {},list_3p_developer_tools: {description:- "Lists all third-party developer tools the page exposes for providing runtime information.\nThird-party developer tools can be called via the 'execute_3p_developer_tool()' MCP tool.\nAlternatively, third-party developer tools can be executed by calling 'evaluate_script' and adding the\nfollowing command to the script:\n`window.__dtmcp.executeTool(toolName, params)`\nThis might be helpful when the third-party developer tools return non-serializable values or when composing\nthird-party developer tools with additional functionality. (requires flag: --categoryExperimentalThirdParty=true)",+ "Lists all third-party developer tools the page exposes for providing runtime information (including debugging WebMCP tools and tools exposed via the 'devtoolstooldiscovery' event).\nThird-party developer tools can be called via the 'execute_3p_developer_tool()' MCP tool.\nAlternatively, third-party developer tools exposed via the 'devtoolstooldiscovery' event can be executed by calling 'evaluate_script' and adding the\nfollowing command to the script:\n`window.__dtmcp.executeTool(toolName, params)`\nThis might be helpful when the third-party developer tools return non-serializable values or when composing\nthird-party developer tools with additional functionality. (requires flag: --categoryExperimentalThirdParty=true)",category: 'Third-party',args: {pageId: {@@ -1180,7 +1180,7 @@ export const commands: Commands = {},list_webmcp_tools: {description:- 'Lists all WebMCP tools the page exposes. (requires flag: --categoryExperimentalWebmcp=true)',+ "Lists all WebMCP tools the page exposes (excluding debugging tools, which are exposed via 'list_3p_developer_tools'). (requires flag: --categoryExperimentalWebmcp=true)",category: 'WebMCP',args: {pageId: {diff --git a/src/third_party/index.ts b/src/third_party/index.tsindex 5aa71302..0a2aa227 100644--- a/src/third_party/index.ts+++ b/src/third_party/index.ts@@ -55,6 +55,8 @@ export {TargetType,TimeoutError,WebWorker,+ WebMCP,+ WebMCPTool,} from 'puppeteer-core';export {default as puppeteer} from 'puppeteer-core';export type * from 'puppeteer-core';diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.tsindex e51ad82f..73c502a9 100644--- a/src/tools/ToolDefinition.ts+++ b/src/tools/ToolDefinition.ts@@ -35,6 +35,7 @@ import type {DevTools,Protocol,Page,+ WebMCPTool,} from '../third_party/index.js';import type {InsightName, TraceResult} from '../processors/PerformanceTrace.js';import type {@@ -409,6 +410,7 @@ export type ContextPage = Readonly<{DialogAction | Partial<Record<Protocol.Page.DialogType, DialogAction>>;},): Promise<WaitForEventsResult>;+ getWebMcpTools(): WebMCPTool[];getThirdPartyDeveloperTools(): ToolGroups;executeThirdPartyDeveloperTool(diff --git a/src/tools/thirdPartyDeveloper.ts b/src/tools/thirdPartyDeveloper.tsindex a665b4b4..79af6b9f 100644--- a/src/tools/thirdPartyDeveloper.ts+++ b/src/tools/thirdPartyDeveloper.ts@@ -44,9 +44,9 @@ declare global {export const listThirdPartyDeveloperTools = definePageTool(() => ({name: 'list_3p_developer_tools',- description: `Lists all third-party developer tools the page exposes for providing runtime information.+ description: `Lists all third-party developer tools the page exposes for providing runtime information (including debugging WebMCP tools and tools exposed via the 'devtoolstooldiscovery' event).Third-party developer tools can be called via the 'execute_3p_developer_tool()' MCP tool.-Alternatively, third-party developer tools can be executed by calling 'evaluate_script' and adding the+Alternatively, third-party developer tools exposed via the 'devtoolstooldiscovery' event can be executed by calling 'evaluate_script' and adding thefollowing command to the script:\`window.__dtmcp.executeTool(toolName, params)\`This might be helpful when the third-party developer tools return non-serializable values or when composing@@ -65,7 +65,7 @@ third-party developer tools with additional functionality.`,export const executeThirdPartyDeveloperTool = definePageTool(() => ({name: 'execute_3p_developer_tool',- description: `Executes a tool exposed by the page.`,+ description: `Executes a third-party developer tool exposed by the page.`,annotations: {category: ToolCategory.THIRD_PARTY,readOnlyHint: false,diff --git a/src/tools/webmcp.ts b/src/tools/webmcp.tsindex 0c8a7a76..61600762 100644--- a/src/tools/webmcp.ts+++ b/src/tools/webmcp.ts@@ -11,7 +11,7 @@ import {definePageTool} from './ToolDefinition.js';export const listWebMcpTools = definePageTool(() => ({name: 'list_webmcp_tools',- description: `Lists all WebMCP tools the page exposes.`,+ description: `Lists all WebMCP tools the page exposes (excluding debugging tools, which are exposed via 'list_3p_developer_tools').`,annotations: {category: ToolCategory.WEBMCP,readOnlyHint: true,@@ -26,7 +26,7 @@ export const listWebMcpTools = definePageTool(() => ({export const executeWebMcpTool = definePageTool(() => ({name: 'execute_webmcp_tool',- description: `Executes a WebMCP tool exposed by the page.`,+ description: `Executes a WebMCP tool exposed by the page (for debugging tools, use 'execute_3p_developer_tool').`,annotations: {category: ToolCategory.WEBMCP,readOnlyHint: false,@@ -62,7 +62,7 @@ export const executeWebMcpTool = definePageTool(() => ({}}- const tools = request.page.pptrPage.webmcp.tools();+ const tools = request.page.getWebMcpTools();const tool = tools.find(t => t.name === toolName);if (!tool) {throw new Error(`Tool ${toolName} not found`);diff --git a/tests/McpPage.test.ts b/tests/McpPage.test.tsindex 1e02ba91..0bfe47ec 100644--- a/tests/McpPage.test.ts+++ b/tests/McpPage.test.ts@@ -20,6 +20,7 @@ import {createMockMcpResponse,createMockPuppeteerPage,createMockPuppeteerTarget,+ createMockWebMCPTool,} from './mocks.js';import {serverHooks} from './server.js';import {getMockRequest, html, withMcpContext} from './utils.js';@@ -1255,4 +1256,273 @@ describe('McpPage', () => {sinon.assert.notCalled(response.appendResponseLine);});});++ describe('WebMCP third-party developer tools', () => {+ afterEach(() => {+ sinon.restore();+ });++ it('filters WebMCP tools by annotations.debugging in getToolGroups()', async () => {+ const {mcpPage, pptrPage} = await createMcpPage();++ const debuggingTool = createMockWebMCPTool({+ name: 'debug_tool',+ description: 'A debugging WebMCP tool',+ inputSchema: {type: 'object'},+ annotations: {debugging: true},+ });+ const nonDebuggingTool = createMockWebMCPTool({+ name: 'user_tool',+ description: 'A non-debugging WebMCP tool',+ inputSchema: {type: 'object'},+ annotations: {debugging: false},+ });+ const unannotatedTool = createMockWebMCPTool({+ name: 'legacy_webmcp_tool',+ description: 'A WebMCP tool without debugging annotation',+ inputSchema: {type: 'object'},+ });+ pptrPage.webmcp.tools.returns([+ debuggingTool,+ nonDebuggingTool,+ unannotatedTool,+ ]);++ const groups = await mcpPage.getToolGroups();+ assert.deepStrictEqual(groups, [+ {+ name: 'WebMCP Tools',+ description: 'Tools exposed via WebMCP',+ tools: [+ {+ name: 'debug_tool',+ description: 'A debugging WebMCP tool',+ inputSchema: {type: 'object'},+ },+ ],+ },+ ]);+ assert.deepStrictEqual(mcpPage.getThirdPartyDeveloperTools(), groups);+ });++ it('combines WebMCP debugging tools and devtoolstooldiscovery tools in getThirdPartyDeveloperTools()', async () => {+ const {mcpPage, pptrPage} = await createMcpPage();++ const debuggingTool = createMockWebMCPTool({+ name: 'debug_tool',+ description: 'A debugging WebMCP tool',+ annotations: {debugging: true},+ });+ pptrPage.webmcp.tools.returns([debuggingTool]);+ mcpPage.eventBasedThirdPartyTools = [+ {+ name: 'Custom Tools',+ description: 'Tools exposed via event',+ tools: [+ {+ name: 'custom_tool',+ description: 'A custom tool',+ inputSchema: {+ type: 'object',+ properties: {+ el: {+ properties: {uid: {type: 'string'}},+ required: ['uid'],+ },+ },+ },+ },+ ],+ },+ ];++ const groups = mcpPage.getThirdPartyDeveloperTools();+ assert.deepStrictEqual(groups, [+ {+ name: 'WebMCP Tools',+ description: 'Tools exposed via WebMCP',+ tools: [+ {+ name: 'debug_tool',+ description: 'A debugging WebMCP tool',+ inputSchema: {},+ },+ ],+ },+ {+ name: 'Custom Tools',+ description: 'Tools exposed via event',+ tools: [+ {+ name: 'custom_tool',+ description: 'A custom tool',+ inputSchema: {+ type: 'object',+ properties: {+ el: {+ properties: {uid: {type: 'string'}},+ required: ['uid'],+ },+ },+ },+ },+ ],+ },+ ]);+ });++ it('reflects dynamically added and removed WebMCP debugging tools in getThirdPartyDeveloperTools()', async () => {+ const {mcpPage, pptrPage} = await createMcpPage();++ assert.deepStrictEqual(mcpPage.getThirdPartyDeveloperTools(), []);++ const debuggingTool = createMockWebMCPTool({+ name: 'dynamic_debug_tool',+ description: 'Added dynamically',+ inputSchema: {type: 'object'},+ annotations: {debugging: true},+ });+ pptrPage.webmcp.tools.returns([debuggingTool]);++ assert.deepStrictEqual(mcpPage.getThirdPartyDeveloperTools(), [+ {+ name: 'WebMCP Tools',+ description: 'Tools exposed via WebMCP',+ tools: [+ {+ name: 'dynamic_debug_tool',+ description: 'Added dynamically',+ inputSchema: {type: 'object'},+ },+ ],+ },+ ]);++ pptrPage.webmcp.tools.returns([]);+ assert.deepStrictEqual(mcpPage.getThirdPartyDeveloperTools(), []);+ });++ it('executes a WebMCP tool in executeThirdPartyDeveloperTool()', async () => {+ const {mcpPage, pptrPage} = await createMcpPage();+ const mockTool = createMockWebMCPTool({+ name: 'webmcp_tool',+ description: 'A WebMCP tool',+ annotations: {debugging: true},+ });+ mockTool.execute.resolves({+ id: 'call-1',+ status: 'Completed',+ output: {result: 42},+ });+ pptrPage.webmcp.tools.returns([mockTool]);+ const response = createMockMcpResponse();++ await mcpPage.executeThirdPartyDeveloperTool(+ 'webmcp_tool',+ {x: 21},+ response,+ );++ sinon.assert.calledOnceWithExactly(mockTool.execute, {x: 21});+ sinon.assert.calledOnceWithExactly(+ response.appendResponseLine,+ JSON.stringify({result: 42}, null, 2),+ );+ sinon.assert.notCalled(pptrPage.evaluate);+ });++ it('appends "Tool returned no result." when WebMCP tool output is undefined in executeThirdPartyDeveloperTool()', async () => {+ const {mcpPage, pptrPage} = await createMcpPage();+ const mockTool = createMockWebMCPTool({+ name: 'webmcp_void_tool',+ annotations: {debugging: true},+ });+ mockTool.execute.resolves({+ id: 'call-1',+ status: 'Completed',+ output: undefined,+ });+ pptrPage.webmcp.tools.returns([mockTool]);+ const response = createMockMcpResponse();++ await mcpPage.executeThirdPartyDeveloperTool(+ 'webmcp_void_tool',+ {},+ response,+ );++ sinon.assert.calledOnceWithExactly(mockTool.execute, {});+ sinon.assert.calledOnceWithExactly(+ response.appendResponseLine,+ 'Tool returned no result.',+ );+ });++ it('does not execute non-debugging WebMCP tools in executeThirdPartyDeveloperTool()', async () => {+ const {mcpPage, pptrPage} = await createMcpPage();+ const nonDebuggingTool = createMockWebMCPTool({+ name: 'user_tool',+ annotations: {debugging: false},+ });+ pptrPage.webmcp.tools.returns([nonDebuggingTool]);+ pptrPage.evaluate.rejects(new Error('No tools found on the page'));+ const response = createMockMcpResponse();++ await assert.rejects(+ () => mcpPage.executeThirdPartyDeveloperTool('user_tool', {}, response),+ /No tools found on the page/,+ );+ sinon.assert.notCalled(nonDebuggingTool.execute);+ });++ it('throws when WebMCP tool execution fails in executeThirdPartyDeveloperTool()', async () => {+ const {mcpPage, pptrPage} = await createMcpPage();+ const mockTool = createMockWebMCPTool({+ name: 'webmcp_tool',+ annotations: {debugging: true},+ });+ mockTool.execute.resolves({+ id: 'call-1',+ status: 'Error',+ errorText: 'Execution failed in page',+ });+ pptrPage.webmcp.tools.returns([mockTool]);+ const response = createMockMcpResponse();++ await assert.rejects(+ () =>+ mcpPage.executeThirdPartyDeveloperTool('webmcp_tool', {}, response),+ /Execution failed in page/,+ );+ });++ it('excludes debugging WebMCP tools from getWebMcpTools()', async () => {+ const {mcpPage, pptrPage} = await createMcpPage();++ const debuggingTool = createMockWebMCPTool({+ name: 'debug_tool',+ description: 'A debugging WebMCP tool',+ annotations: {debugging: true},+ });+ const nonDebuggingTool = createMockWebMCPTool({+ name: 'user_tool',+ description: 'A non-debugging WebMCP tool',+ annotations: {debugging: false},+ });+ const unannotatedTool = createMockWebMCPTool({+ name: 'legacy_webmcp_tool',+ description: 'A WebMCP tool without debugging annotation',+ });+ pptrPage.webmcp.tools.returns([+ debuggingTool,+ nonDebuggingTool,+ unannotatedTool,+ ]);++ assert.deepStrictEqual(mcpPage.getWebMcpTools(), [+ nonDebuggingTool,+ unannotatedTool,+ ]);+ });+ });});diff --git a/tests/mocks.ts b/tests/mocks.tsindex 3f56d7a6..42164289 100644--- a/tests/mocks.ts+++ b/tests/mocks.ts@@ -53,6 +53,8 @@ import {Target,TargetType,WebWorker,+ WebMCP,+ WebMCPTool,} from '../src/third_party/index.js';import type {Browser,@@ -168,7 +170,9 @@ export function createMockPuppeteerBrowser(): sinon.SinonStubbedInstance<Browserreturn browser;}-export function createMockPuppeteerPage(): sinon.SinonStubbedInstance<Page> {+export function createMockPuppeteerPage(): sinon.SinonStubbedInstance<Page> & {+ webmcp: sinon.SinonStubbedInstance<WebMCP>;+} {const page = sinon.createStubInstance(CdpPage,) as unknown as sinon.SinonStubbedInstance<Page>;@@ -223,7 +227,31 @@ export function createMockPuppeteerPage(): sinon.SinonStubbedInstance<Page> {// @ts-expect-error internal APIpage._client = sinon.stub().returns(cdpSession);- return page;+ const webmcp = sinon.createStubInstance(WebMCP);+ webmcp.tools.returns([]);+ Object.defineProperty(page, 'webmcp', {+ value: webmcp,+ writable: true,+ configurable: true,+ });++ page.evaluateHandle.resolves(createMockElementHandle().handle);++ return Object.assign(page, {webmcp});+}++export function createMockWebMCPTool(options: {+ name: string;+ description?: string;+ inputSchema?: object;+ annotations?: Protocol.WebMCP.Annotation & {debugging?: boolean};+}): sinon.SinonStubbedInstance<WebMCPTool> {+ const tool = sinon.createStubInstance(WebMCPTool);+ tool.name = options.name;+ tool.description = options.description ?? '';+ tool.inputSchema = options.inputSchema;+ tool.annotations = options.annotations;+ return tool;}export class MockTarget extends Target {@@ -298,6 +326,7 @@ export function createMockMcpPage(await action(new AbortController().signal);return {};});+ page.getWebMcpTools.returns([]);Object.defineProperty(page, 'pptrPage', {value: pptrPage,writable: true,@@ -326,6 +355,7 @@ export function createMockElementHandle(): {} {const handle =sinon.createStubInstance<ElementHandle<Element>>(ElementHandle);+ handle.remoteObject.returns({type: 'object', objectId: '<mock-object-id>'});handle.dispose.resolves();const locator = sinon.createStubInstance<Locator<Element>>(Locator);locator.setTimeout.returns(locator);diff --git a/tests/tools/thirdPartyDeveloper.test.ts b/tests/tools/thirdPartyDeveloper.test.tsindex c80e1a73..7340d818 100644--- a/tests/tools/thirdPartyDeveloper.test.ts+++ b/tests/tools/thirdPartyDeveloper.test.ts@@ -500,7 +500,7 @@ describe('thirdPartyDeveloperTools', () => {const page = await context.newPage();response.setPage(page);- page.thirdPartyDeveloperTools = [+ page.eventBasedThirdPartyTools = [{name: 'test-group',description: 'test description',@@ -740,7 +740,7 @@ describe('thirdPartyDeveloperTools', () => {const page = await context.newPage();response.setPage(page);- page.thirdPartyDeveloperTools = [+ page.eventBasedThirdPartyTools = [{name: 'test-group',description: 'test description',@@ -816,7 +816,7 @@ describe('thirdPartyDeveloperTools', () => {const page = await context.newPage();response.setPage(page);- page.thirdPartyDeveloperTools = [+ page.eventBasedThirdPartyTools = [{name: 'test-group',description: 'test description',@@ -869,7 +869,7 @@ describe('thirdPartyDeveloperTools', () => {const page = await context.newPage();response.setPage(page);- page.thirdPartyDeveloperTools = [+ page.eventBasedThirdPartyTools = [{name: 'test-group',description: 'test description',@@ -922,7 +922,7 @@ describe('thirdPartyDeveloperTools', () => {const page = await context.newPage();response.setPage(page);- page.thirdPartyDeveloperTools = [+ page.eventBasedThirdPartyTools = [{name: 'test-group',description: 'test description',diff --git a/tests/tools/webmcp.test.ts b/tests/tools/webmcp.test.tsindex 5a9bfe89..99037810 100644--- a/tests/tools/webmcp.test.ts+++ b/tests/tools/webmcp.test.ts@@ -12,7 +12,7 @@ import sinon from 'sinon';import type {McpPage} from '../../src/McpPage.js';import {listPages, navigatePage, selectPage} from '../../src/tools/pages.js';import {executeWebMcpTool} from '../../src/tools/webmcp.js';-import {createHandlerMocks} from '../mocks.js';+import {createHandlerMocks, createMockWebMCPTool} from '../mocks.js';import {html, withMcpContext} from '../utils.js';describe('webmcp', () => {@@ -117,6 +117,58 @@ describe('webmcp', () => {);});+ it('looks up tools via page.getWebMcpTools and throws if not returned', async () => {+ const {page, context, response, args} = createHandlerMocks();+ page.getWebMcpTools.returns([]);++ await assert.rejects(+ executeWebMcpTool(args).handler(+ {+ params: {toolName: 'debug_tool', input: '{}'},+ page,+ },+ response,+ context,+ ),+ {message: /Tool debug_tool not found/},+ );+ sinon.assert.calledOnceWithExactly(page.getWebMcpTools);+ });++ it('executes a matching tool returned by page.getWebMcpTools', async () => {+ const {page, context, response, args} = createHandlerMocks();+ const tool = createMockWebMCPTool({+ name: 'my_tool',+ });+ tool.execute.resolves({+ id: 'call-1',+ status: 'Completed',+ output: {ok: true},+ errorText: undefined,+ });+ page.getWebMcpTools.returns([tool]);++ await executeWebMcpTool(args).handler(+ {+ params: {toolName: 'my_tool', input: '{"key":"val"}'},+ page,+ },+ response,+ context,+ );++ sinon.assert.calledOnceWithExactly(page.getWebMcpTools);+ sinon.assert.calledOnceWithExactly(tool.execute, {key: 'val'});+ sinon.assert.calledOnceWithExactly(+ response.appendResponseLine,+ JSON.stringify(+ {status: 'Completed', output: {ok: true}, errorText: undefined},+ null,+ 2,+ ),+ );+ });+it('rejects JSON array input', async () => {const {page, context, response, args} = createHandlerMocks();await assert.rejects(