Skip to content

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.md
index 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.md
index 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 the
following 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.ts
index 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 API
const 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 they
diff --git a/src/config/category-options.ts b/src/config/category-options.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 the
following 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.ts
index 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.ts
index 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.ts
index 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<Browser
return 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 API
page._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.ts
index 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.ts
index 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(