From d1774198aeb2296d525effa2e0339c2a435b664e Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Thu, 19 Mar 2026 11:05:08 +0100 Subject: [PATCH 1/6] test: ensure snapshot files are copied to build directory --- scripts/post-build.ts | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/scripts/post-build.ts b/scripts/post-build.ts index edf822599..7fe0a482b 100644 --- a/scripts/post-build.ts +++ b/scripts/post-build.ts @@ -94,6 +94,42 @@ export const ExperimentName = { writeFile(runtimeFile, runtimeContent); copyDevToolsDescriptionFiles(); + copySnapshotFiles(); +} + +function copySnapshotFiles() { + const testsDir = path.join(process.cwd(), 'tests'); + const buildTestsDir = path.join(BUILD_DIR, 'tests'); + + if (!fs.existsSync(buildTestsDir)) { + fs.mkdirSync(buildTestsDir, {recursive: true}); + } + + const files = fs.readdirSync(testsDir); + for (const file of files) { + if (file.endsWith('.snapshot')) { + fs.copyFileSync(path.join(testsDir, file), path.join(buildTestsDir, file)); + } + } + + // Also handle subdirectories if needed, but for now we only have snapshots in the root of tests/ + // Wait, let's check tools/ + const toolsTestsDir = path.join(testsDir, 'tools'); + const buildToolsTestsDir = path.join(buildTestsDir, 'tools'); + if (fs.existsSync(toolsTestsDir)) { + if (!fs.existsSync(buildToolsTestsDir)) { + fs.mkdirSync(buildToolsTestsDir, {recursive: true}); + } + const toolsFiles = fs.readdirSync(toolsTestsDir); + for (const file of toolsFiles) { + if (file.endsWith('.snapshot')) { + fs.copyFileSync( + path.join(toolsTestsDir, file), + path.join(buildToolsTestsDir, file), + ); + } + } + } } function copyDevToolsDescriptionFiles() { From 8dd62bd229b5320f7494f58c53115bf4a917d9fc Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Thu, 19 Mar 2026 11:09:16 +0100 Subject: [PATCH 2/6] feat: add session-based snapshot diffing to take_snapshot (--diff) --- src/McpContext.ts | 52 +- src/McpPage.ts | 7 + src/McpResponse.ts | 3 + src/bin/cliDefinitions.ts | 1275 +++++++++++++-------------- src/formatters/SnapshotFormatter.ts | 36 +- src/tools/ToolDefinition.ts | 1 + src/tools/snapshot.ts | 7 + src/types.ts | 5 + tests/McpContext.test.ts | 53 ++ 9 files changed, 779 insertions(+), 660 deletions(-) diff --git a/src/McpContext.ts b/src/McpContext.ts index 4647c6118..6cbc8e5a2 100644 --- a/src/McpContext.ts +++ b/src/McpContext.ts @@ -728,6 +728,9 @@ export class McpContext implements Context { page: McpPage, verbose = false, devtoolsData: DevToolsData | undefined = undefined, + options: { + diff?: boolean; + } = {}, ): Promise { const rootNode = await page.pptrPage.accessibility.snapshot({ includeIframes: true, @@ -745,10 +748,20 @@ export class McpContext implements Context { let idCounter = 0; const idToNode = new Map(); const seenUniqueIds = new Set(); - const assignIds = (node: SerializedAXNode): TextSnapshotNode => { + const assignIds = ( + node: SerializedAXNode, + parentId = 'root', + index = 0, + ): TextSnapshotNode => { let id = ''; - // @ts-expect-error untyped loaderId & backendNodeId. - const uniqueBackendId = `${node.loaderId}_${node.backendNodeId}`; + const nodeAny = node as any; + // StaticText nodes often have unstable backendNodeIds in some contexts, + // or we might want to group them by their parent. + const uniqueBackendId = + nodeAny.backendNodeId && node.role !== 'StaticText' + ? `${nodeAny.loaderId}_${nodeAny.backendNodeId}` + : `${nodeAny.loaderId}_${nodeAny.role}_${parentId}_${index}`; + if (uniqueBackendNodeIdToMcpId.has(uniqueBackendId)) { // Re-use MCP exposed ID if the uniqueId is the same. id = uniqueBackendNodeIdToMcpId.get(uniqueBackendId)!; @@ -763,7 +776,7 @@ export class McpContext implements Context { ...node, id, children: node.children - ? node.children.map(child => assignIds(child)) + ? node.children.map((child, i) => assignIds(child, id, i)) : [], }; @@ -788,7 +801,38 @@ export class McpContext implements Context { hasSelectedElement: false, verbose, }; + + if (options.diff && page.lastSnapshot) { + const lastIdToNode = page.lastSnapshot.idToNode; + const added: string[] = []; + const changed: string[] = []; + const removed: string[] = []; + + for (const [id, node] of idToNode) { + const lastNode = lastIdToNode.get(id); + if (!lastNode) { + added.push(id); + } else if ( + node.name !== lastNode.name || + node.value !== lastNode.value || + node.description !== lastNode.description || + node.role !== lastNode.role + ) { + changed.push(id); + } + } + + for (const id of lastIdToNode.keys()) { + if (!idToNode.has(id)) { + removed.push(id); + } + } + + snapshot.diff = {added, changed, removed}; + } + page.textSnapshot = snapshot; + page.lastSnapshot = snapshot; const data = devtoolsData ?? (await this.getDevToolsData(page)); if (data?.cdpBackendNodeId) { snapshot.hasSelectedElement = true; diff --git a/src/McpPage.ts b/src/McpPage.ts index 73717464b..c734f3189 100644 --- a/src/McpPage.ts +++ b/src/McpPage.ts @@ -33,6 +33,7 @@ export class McpPage implements ContextPage { // Snapshot textSnapshot: TextSnapshot | null = null; + lastSnapshot: TextSnapshot | null = null; uniqueBackendNodeIdToMcpId = new Map(); // Emulation @@ -45,6 +46,7 @@ export class McpPage implements ContextPage { // Dialog #dialog?: Dialog; #dialogHandler: (dialog: Dialog) => void; + #navigationHandler: () => void; constructor(page: Page, id: number) { this.pptrPage = page; @@ -52,7 +54,11 @@ export class McpPage implements ContextPage { this.#dialogHandler = (dialog: Dialog): void => { this.#dialog = dialog; }; + this.#navigationHandler = (): void => { + this.lastSnapshot = null; + }; page.on('dialog', this.#dialogHandler); + page.on('framenavigated', this.#navigationHandler); } get dialog(): Dialog | undefined { @@ -93,6 +99,7 @@ export class McpPage implements ContextPage { dispose(): void { this.pptrPage.off('dialog', this.#dialogHandler); + this.pptrPage.off('framenavigated', this.#navigationHandler); } async getElementByUid(uid: string): Promise> { diff --git a/src/McpResponse.ts b/src/McpResponse.ts index b6162c27c..511e3022b 100644 --- a/src/McpResponse.ts +++ b/src/McpResponse.ts @@ -276,6 +276,9 @@ export class McpResponse implements Response { this.#page, this.#snapshotParams.verbose, this.#devToolsData, + { + diff: this.#snapshotParams.diff, + }, ); const textSnapshot = this.#page.textSnapshot; if (textSnapshot) { diff --git a/src/bin/cliDefinitions.ts b/src/bin/cliDefinitions.ts index d32705617..924fec778 100644 --- a/src/bin/cliDefinitions.ts +++ b/src/bin/cliDefinitions.ts @@ -19,688 +19,653 @@ export type Commands = Record< { description: string; category: string; - args: Record; + args: Record } >; export const commands: Commands = { - click: { - description: 'Clicks on the provided element', - category: 'Input automation', - args: { - uid: { - name: 'uid', - type: 'string', - description: - 'The uid of an element on the page from the page content snapshot', - required: true, - }, - dblClick: { - name: 'dblClick', - type: 'boolean', - description: 'Set to true for double clicks. Default is false.', - required: false, - }, - includeSnapshot: { - name: 'includeSnapshot', - type: 'boolean', - description: - 'Whether to include a snapshot in the response. Default is false.', - required: false, - }, - }, + "click": { + "description": "Clicks on the provided element", + "category": "Input automation", + "args": { + "uid": { + "name": "uid", + "type": "string", + "description": "The uid of an element on the page from the page content snapshot", + "required": true + }, + "dblClick": { + "name": "dblClick", + "type": "boolean", + "description": "Set to true for double clicks. Default is false.", + "required": false + }, + "includeSnapshot": { + "name": "includeSnapshot", + "type": "boolean", + "description": "Whether to include a snapshot in the response. Default is false.", + "required": false + } + } }, - close_page: { - description: - 'Closes the page by its index. The last open page cannot be closed.', - category: 'Navigation automation', - args: { - pageId: { - name: 'pageId', - type: 'number', - description: - 'The ID of the page to close. Call list_pages to list pages.', - required: true, - }, - }, + "close_page": { + "description": "Closes the page by its index. The last open page cannot be closed.", + "category": "Navigation automation", + "args": { + "pageId": { + "name": "pageId", + "type": "number", + "description": "The ID of the page to close. Call list_pages to list pages.", + "required": true + } + } }, - drag: { - description: 'Drag an element onto another element', - category: 'Input automation', - args: { - from_uid: { - name: 'from_uid', - type: 'string', - description: 'The uid of the element to drag', - required: true, - }, - to_uid: { - name: 'to_uid', - type: 'string', - description: 'The uid of the element to drop into', - required: true, - }, - includeSnapshot: { - name: 'includeSnapshot', - type: 'boolean', - description: - 'Whether to include a snapshot in the response. Default is false.', - required: false, - }, - }, + "drag": { + "description": "Drag an element onto another element", + "category": "Input automation", + "args": { + "from_uid": { + "name": "from_uid", + "type": "string", + "description": "The uid of the element to drag", + "required": true + }, + "to_uid": { + "name": "to_uid", + "type": "string", + "description": "The uid of the element to drop into", + "required": true + }, + "includeSnapshot": { + "name": "includeSnapshot", + "type": "boolean", + "description": "Whether to include a snapshot in the response. Default is false.", + "required": false + } + } }, - emulate: { - description: 'Emulates various features on the selected page.', - category: 'Emulation', - args: { - networkConditions: { - name: 'networkConditions', - type: 'string', - description: 'Throttle network. Omit to disable throttling.', - required: false, - enum: ['Offline', 'Slow 3G', 'Fast 3G', 'Slow 4G', 'Fast 4G'], - }, - cpuThrottlingRate: { - name: 'cpuThrottlingRate', - type: 'number', - description: - 'Represents the CPU slowdown factor. Omit or set the rate to 1 to disable throttling', - required: false, - }, - geolocation: { - name: 'geolocation', - type: 'string', - description: - 'Geolocation (`x`) to emulate. Latitude between -90 and 90. Longitude between -180 and 180. Omit clear the geolocation override.', - required: false, - }, - userAgent: { - name: 'userAgent', - type: 'string', - description: - 'User agent to emulate. Set to empty string to clear the user agent override.', - required: false, - }, - colorScheme: { - name: 'colorScheme', - type: 'string', - description: - 'Emulate the dark or the light mode. Set to "auto" to reset to the default.', - required: false, - enum: ['dark', 'light', 'auto'], - }, - viewport: { - name: 'viewport', - type: 'string', - description: - "Emulate device viewports 'xx[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to emulate mobile devices. 'landscape' to emulate landscape mode.", - required: false, - }, - }, + "emulate": { + "description": "Emulates various features on the selected page.", + "category": "Emulation", + "args": { + "networkConditions": { + "name": "networkConditions", + "type": "string", + "description": "Throttle network. Omit to disable throttling.", + "required": false, + "enum": [ + "Offline", + "Slow 3G", + "Fast 3G", + "Slow 4G", + "Fast 4G" + ] + }, + "cpuThrottlingRate": { + "name": "cpuThrottlingRate", + "type": "number", + "description": "Represents the CPU slowdown factor. Omit or set the rate to 1 to disable throttling", + "required": false + }, + "geolocation": { + "name": "geolocation", + "type": "string", + "description": "Geolocation (`x`) to emulate. Latitude between -90 and 90. Longitude between -180 and 180. Omit clear the geolocation override.", + "required": false + }, + "userAgent": { + "name": "userAgent", + "type": "string", + "description": "User agent to emulate. Set to empty string to clear the user agent override.", + "required": false + }, + "colorScheme": { + "name": "colorScheme", + "type": "string", + "description": "Emulate the dark or the light mode. Set to \"auto\" to reset to the default.", + "required": false, + "enum": [ + "dark", + "light", + "auto" + ] + }, + "viewport": { + "name": "viewport", + "type": "string", + "description": "Emulate device viewports 'xx[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to emulate mobile devices. 'landscape' to emulate landscape mode.", + "required": false + } + } }, - evaluate_script: { - description: - 'Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON,\nso returned values have to be JSON-serializable.', - category: 'Debugging', - args: { - function: { - name: 'function', - type: 'string', - description: - 'A JavaScript function declaration to be executed by the tool in the currently selected page.\nExample without arguments: `() => {\n return document.title\n}` or `async () => {\n return await fetch("example.com")\n}`.\nExample with arguments: `(el) => {\n return el.innerText;\n}`\n', - required: true, - }, - args: { - name: 'args', - type: 'array', - description: 'An optional list of arguments to pass to the function.', - required: false, - }, - }, + "evaluate_script": { + "description": "Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON,\nso returned values have to be JSON-serializable.", + "category": "Debugging", + "args": { + "function": { + "name": "function", + "type": "string", + "description": "A JavaScript function declaration to be executed by the tool in the currently selected page.\nExample without arguments: `() => {\n return document.title\n}` or `async () => {\n return await fetch(\"example.com\")\n}`.\nExample with arguments: `(el) => {\n return el.innerText;\n}`\n", + "required": true + }, + "args": { + "name": "args", + "type": "array", + "description": "An optional list of arguments to pass to the function.", + "required": false + } + } }, - fill: { - description: - 'Type text into a input, text area or select an option from a element.", + "category": "Input automation", + "args": { + "uid": { + "name": "uid", + "type": "string", + "description": "The uid of an element on the page from the page content snapshot", + "required": true + }, + "value": { + "name": "value", + "type": "string", + "description": "The value to fill in", + "required": true + }, + "includeSnapshot": { + "name": "includeSnapshot", + "type": "boolean", + "description": "Whether to include a snapshot in the response. Default is false.", + "required": false + } + } }, - get_console_message: { - description: - 'Gets a console message by its ID. You can get all messages by calling list_console_messages.', - category: 'Debugging', - args: { - msgid: { - name: 'msgid', - type: 'number', - description: - 'The msgid of a console message on the page from the listed console messages', - required: true, - }, - }, + "get_console_message": { + "description": "Gets a console message by its ID. You can get all messages by calling list_console_messages.", + "category": "Debugging", + "args": { + "msgid": { + "name": "msgid", + "type": "number", + "description": "The msgid of a console message on the page from the listed console messages", + "required": true + } + } }, - get_network_request: { - description: - 'Gets a network request by an optional reqid, if omitted returns the currently selected request in the DevTools Network panel.', - category: 'Network', - args: { - reqid: { - name: 'reqid', - type: 'number', - description: - 'The reqid of the network request. If omitted returns the currently selected request in the DevTools Network panel.', - required: false, - }, - requestFilePath: { - name: 'requestFilePath', - type: 'string', - description: - 'The absolute or relative path to save the request body to. If omitted, the body is returned inline.', - required: false, - }, - responseFilePath: { - name: 'responseFilePath', - type: 'string', - description: - 'The absolute or relative path to save the response body to. If omitted, the body is returned inline.', - required: false, - }, - }, + "get_network_request": { + "description": "Gets a network request by an optional reqid, if omitted returns the currently selected request in the DevTools Network panel.", + "category": "Network", + "args": { + "reqid": { + "name": "reqid", + "type": "number", + "description": "The reqid of the network request. If omitted returns the currently selected request in the DevTools Network panel.", + "required": false + }, + "requestFilePath": { + "name": "requestFilePath", + "type": "string", + "description": "The absolute or relative path to save the request body to. If omitted, the body is returned inline.", + "required": false + }, + "responseFilePath": { + "name": "responseFilePath", + "type": "string", + "description": "The absolute or relative path to save the response body to. If omitted, the body is returned inline.", + "required": false + } + } }, - handle_dialog: { - description: - 'If a browser dialog was opened, use this command to handle it', - category: 'Input automation', - args: { - action: { - name: 'action', - type: 'string', - description: 'Whether to dismiss or accept the dialog', - required: true, - enum: ['accept', 'dismiss'], - }, - promptText: { - name: 'promptText', - type: 'string', - description: 'Optional prompt text to enter into the dialog.', - required: false, - }, - }, + "handle_dialog": { + "description": "If a browser dialog was opened, use this command to handle it", + "category": "Input automation", + "args": { + "action": { + "name": "action", + "type": "string", + "description": "Whether to dismiss or accept the dialog", + "required": true, + "enum": [ + "accept", + "dismiss" + ] + }, + "promptText": { + "name": "promptText", + "type": "string", + "description": "Optional prompt text to enter into the dialog.", + "required": false + } + } }, - hover: { - description: 'Hover over the provided element', - category: 'Input automation', - args: { - uid: { - name: 'uid', - type: 'string', - description: - 'The uid of an element on the page from the page content snapshot', - required: true, - }, - includeSnapshot: { - name: 'includeSnapshot', - type: 'boolean', - description: - 'Whether to include a snapshot in the response. Default is false.', - required: false, - }, - }, + "hover": { + "description": "Hover over the provided element", + "category": "Input automation", + "args": { + "uid": { + "name": "uid", + "type": "string", + "description": "The uid of an element on the page from the page content snapshot", + "required": true + }, + "includeSnapshot": { + "name": "includeSnapshot", + "type": "boolean", + "description": "Whether to include a snapshot in the response. Default is false.", + "required": false + } + } }, - lighthouse_audit: { - description: - 'Get Lighthouse score and reports for accessibility, SEO and best practices. This excludes performance. For performance audits, run performance_start_trace', - category: 'Debugging', - args: { - mode: { - name: 'mode', - type: 'string', - description: - '"navigation" reloads & audits. "snapshot" analyzes current state.', - required: false, - default: 'navigation', - enum: ['navigation', 'snapshot'], - }, - device: { - name: 'device', - type: 'string', - description: 'Device to emulate.', - required: false, - default: 'desktop', - enum: ['desktop', 'mobile'], - }, - outputDirPath: { - name: 'outputDirPath', - type: 'string', - description: 'Directory for reports. If omitted, uses temporary files.', - required: false, - }, - }, + "lighthouse_audit": { + "description": "Get Lighthouse score and reports for accessibility, SEO and best practices. This excludes performance. For performance audits, run performance_start_trace", + "category": "Debugging", + "args": { + "mode": { + "name": "mode", + "type": "string", + "description": "\"navigation\" reloads & audits. \"snapshot\" analyzes current state.", + "required": false, + "default": "navigation", + "enum": [ + "navigation", + "snapshot" + ] + }, + "device": { + "name": "device", + "type": "string", + "description": "Device to emulate.", + "required": false, + "default": "desktop", + "enum": [ + "desktop", + "mobile" + ] + }, + "outputDirPath": { + "name": "outputDirPath", + "type": "string", + "description": "Directory for reports. If omitted, uses temporary files.", + "required": false + } + } }, - list_console_messages: { - description: - 'List all console messages for the currently selected page since the last navigation.', - category: 'Debugging', - args: { - pageSize: { - name: 'pageSize', - type: 'integer', - description: - 'Maximum number of messages to return. When omitted, returns all requests.', - required: false, - }, - pageIdx: { - name: 'pageIdx', - type: 'integer', - description: - 'Page number to return (0-based). When omitted, returns the first page.', - required: false, - }, - types: { - name: 'types', - type: 'array', - description: - 'Filter messages to only return messages of the specified resource types. When omitted or empty, returns all messages.', - required: false, - }, - includePreservedMessages: { - name: 'includePreservedMessages', - type: 'boolean', - description: - 'Set to true to return the preserved messages over the last 3 navigations.', - required: false, - default: false, - }, - }, + "list_console_messages": { + "description": "List all console messages for the currently selected page since the last navigation.", + "category": "Debugging", + "args": { + "pageSize": { + "name": "pageSize", + "type": "integer", + "description": "Maximum number of messages to return. When omitted, returns all requests.", + "required": false + }, + "pageIdx": { + "name": "pageIdx", + "type": "integer", + "description": "Page number to return (0-based). When omitted, returns the first page.", + "required": false + }, + "types": { + "name": "types", + "type": "array", + "description": "Filter messages to only return messages of the specified resource types. When omitted or empty, returns all messages.", + "required": false + }, + "includePreservedMessages": { + "name": "includePreservedMessages", + "type": "boolean", + "description": "Set to true to return the preserved messages over the last 3 navigations.", + "required": false, + "default": false + } + } }, - list_network_requests: { - description: - 'List all requests for the currently selected page since the last navigation.', - category: 'Network', - args: { - pageSize: { - name: 'pageSize', - type: 'integer', - description: - 'Maximum number of requests to return. When omitted, returns all requests.', - required: false, - }, - pageIdx: { - name: 'pageIdx', - type: 'integer', - description: - 'Page number to return (0-based). When omitted, returns the first page.', - required: false, - }, - resourceTypes: { - name: 'resourceTypes', - type: 'array', - description: - 'Filter requests to only return requests of the specified resource types. When omitted or empty, returns all requests.', - required: false, - }, - includePreservedRequests: { - name: 'includePreservedRequests', - type: 'boolean', - description: - 'Set to true to return the preserved requests over the last 3 navigations.', - required: false, - default: false, - }, - }, + "list_network_requests": { + "description": "List all requests for the currently selected page since the last navigation.", + "category": "Network", + "args": { + "pageSize": { + "name": "pageSize", + "type": "integer", + "description": "Maximum number of requests to return. When omitted, returns all requests.", + "required": false + }, + "pageIdx": { + "name": "pageIdx", + "type": "integer", + "description": "Page number to return (0-based). When omitted, returns the first page.", + "required": false + }, + "resourceTypes": { + "name": "resourceTypes", + "type": "array", + "description": "Filter requests to only return requests of the specified resource types. When omitted or empty, returns all requests.", + "required": false + }, + "includePreservedRequests": { + "name": "includePreservedRequests", + "type": "boolean", + "description": "Set to true to return the preserved requests over the last 3 navigations.", + "required": false, + "default": false + } + } }, - list_pages: { - description: 'Get a list of pages open in the browser.', - category: 'Navigation automation', - args: {}, + "list_pages": { + "description": "Get a list of pages open in the browser.", + "category": "Navigation automation", + "args": {} }, - navigate_page: { - description: - 'Go to a URL, or back, forward, or reload. Use project URL if not specified otherwise.', - category: 'Navigation automation', - args: { - type: { - name: 'type', - type: 'string', - description: - 'Navigate the page by URL, back or forward in history, or reload.', - required: false, - enum: ['url', 'back', 'forward', 'reload'], - }, - url: { - name: 'url', - type: 'string', - description: 'Target URL (only type=url)', - required: false, - }, - ignoreCache: { - name: 'ignoreCache', - type: 'boolean', - description: 'Whether to ignore cache on reload.', - required: false, - }, - handleBeforeUnload: { - name: 'handleBeforeUnload', - type: 'string', - description: - 'Whether to auto accept or beforeunload dialogs triggered by this navigation. Default is accept.', - required: false, - enum: ['accept', 'decline'], - }, - initScript: { - name: 'initScript', - type: 'string', - description: - 'A JavaScript script to be executed on each new document before any other scripts for the next navigation.', - required: false, - }, - timeout: { - name: 'timeout', - type: 'integer', - description: - 'Maximum wait time in milliseconds. If set to 0, the default timeout will be used.', - required: false, - }, - }, + "navigate_page": { + "description": "Go to a URL, or back, forward, or reload. Use project URL if not specified otherwise.", + "category": "Navigation automation", + "args": { + "type": { + "name": "type", + "type": "string", + "description": "Navigate the page by URL, back or forward in history, or reload.", + "required": false, + "enum": [ + "url", + "back", + "forward", + "reload" + ] + }, + "url": { + "name": "url", + "type": "string", + "description": "Target URL (only type=url)", + "required": false + }, + "ignoreCache": { + "name": "ignoreCache", + "type": "boolean", + "description": "Whether to ignore cache on reload.", + "required": false + }, + "handleBeforeUnload": { + "name": "handleBeforeUnload", + "type": "string", + "description": "Whether to auto accept or beforeunload dialogs triggered by this navigation. Default is accept.", + "required": false, + "enum": [ + "accept", + "decline" + ] + }, + "initScript": { + "name": "initScript", + "type": "string", + "description": "A JavaScript script to be executed on each new document before any other scripts for the next navigation.", + "required": false + }, + "timeout": { + "name": "timeout", + "type": "integer", + "description": "Maximum wait time in milliseconds. If set to 0, the default timeout will be used.", + "required": false + } + } }, - new_page: { - description: - 'Open a new tab and load a URL. Use project URL if not specified otherwise.', - category: 'Navigation automation', - args: { - url: { - name: 'url', - type: 'string', - description: 'URL to load in a new page.', - required: true, - }, - background: { - name: 'background', - type: 'boolean', - description: - 'Whether to open the page in the background without bringing it to the front. Default is false (foreground).', - required: false, - }, - isolatedContext: { - name: 'isolatedContext', - type: 'string', - description: - 'If specified, the page is created in an isolated browser context with the given name. Pages in the same browser context share cookies and storage. Pages in different browser contexts are fully isolated.', - required: false, - }, - timeout: { - name: 'timeout', - type: 'integer', - description: - 'Maximum wait time in milliseconds. If set to 0, the default timeout will be used.', - required: false, - }, - }, + "new_page": { + "description": "Open a new tab and load a URL. Use project URL if not specified otherwise.", + "category": "Navigation automation", + "args": { + "url": { + "name": "url", + "type": "string", + "description": "URL to load in a new page.", + "required": true + }, + "background": { + "name": "background", + "type": "boolean", + "description": "Whether to open the page in the background without bringing it to the front. Default is false (foreground).", + "required": false + }, + "isolatedContext": { + "name": "isolatedContext", + "type": "string", + "description": "If specified, the page is created in an isolated browser context with the given name. Pages in the same browser context share cookies and storage. Pages in different browser contexts are fully isolated.", + "required": false + }, + "timeout": { + "name": "timeout", + "type": "integer", + "description": "Maximum wait time in milliseconds. If set to 0, the default timeout will be used.", + "required": false + } + } }, - performance_analyze_insight: { - description: - 'Provides more detailed information on a specific Performance Insight of an insight set that was highlighted in the results of a trace recording.', - category: 'Performance', - args: { - insightSetId: { - name: 'insightSetId', - type: 'string', - description: - 'The id for the specific insight set. Only use the ids given in the "Available insight sets" list.', - required: true, - }, - insightName: { - name: 'insightName', - type: 'string', - description: - 'The name of the Insight you want more information on. For example: "DocumentLatency" or "LCPBreakdown"', - required: true, - }, - }, + "performance_analyze_insight": { + "description": "Provides more detailed information on a specific Performance Insight of an insight set that was highlighted in the results of a trace recording.", + "category": "Performance", + "args": { + "insightSetId": { + "name": "insightSetId", + "type": "string", + "description": "The id for the specific insight set. Only use the ids given in the \"Available insight sets\" list.", + "required": true + }, + "insightName": { + "name": "insightName", + "type": "string", + "description": "The name of the Insight you want more information on. For example: \"DocumentLatency\" or \"LCPBreakdown\"", + "required": true + } + } }, - performance_start_trace: { - description: - 'Start a performance trace on the selected webpage. Use to find frontend performance issues, Core Web Vitals (LCP, INP, CLS), and improve page load speed.', - category: 'Performance', - args: { - reload: { - name: 'reload', - type: 'boolean', - description: - 'Determines if, once tracing has started, the current selected page should be automatically reloaded. Navigate the page to the right URL using the navigate_page tool BEFORE starting the trace if reload or autoStop is set to true.', - required: false, - default: true, - }, - autoStop: { - name: 'autoStop', - type: 'boolean', - description: - 'Determines if the trace recording should be automatically stopped.', - required: false, - default: true, - }, - filePath: { - name: 'filePath', - type: 'string', - description: - 'The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).', - required: false, - }, - }, + "performance_start_trace": { + "description": "Start a performance trace on the selected webpage. Use to find frontend performance issues, Core Web Vitals (LCP, INP, CLS), and improve page load speed.", + "category": "Performance", + "args": { + "reload": { + "name": "reload", + "type": "boolean", + "description": "Determines if, once tracing has started, the current selected page should be automatically reloaded. Navigate the page to the right URL using the navigate_page tool BEFORE starting the trace if reload or autoStop is set to true.", + "required": false, + "default": true + }, + "autoStop": { + "name": "autoStop", + "type": "boolean", + "description": "Determines if the trace recording should be automatically stopped.", + "required": false, + "default": true + }, + "filePath": { + "name": "filePath", + "type": "string", + "description": "The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).", + "required": false + } + } }, - performance_stop_trace: { - description: - 'Stop the active performance trace recording on the selected webpage.', - category: 'Performance', - args: { - filePath: { - name: 'filePath', - type: 'string', - description: - 'The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).', - required: false, - }, - }, + "performance_stop_trace": { + "description": "Stop the active performance trace recording on the selected webpage.", + "category": "Performance", + "args": { + "filePath": { + "name": "filePath", + "type": "string", + "description": "The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).", + "required": false + } + } }, - press_key: { - description: - 'Press a key or key combination. Use this when other input methods like fill() cannot be used (e.g., keyboard shortcuts, navigation keys, or special key combinations).', - category: 'Input automation', - args: { - key: { - name: 'key', - type: 'string', - description: - 'A key or a combination (e.g., "Enter", "Control+A", "Control++", "Control+Shift+R"). Modifiers: Control, Shift, Alt, Meta', - required: true, - }, - includeSnapshot: { - name: 'includeSnapshot', - type: 'boolean', - description: - 'Whether to include a snapshot in the response. Default is false.', - required: false, - }, - }, + "press_key": { + "description": "Press a key or key combination. Use this when other input methods like fill() cannot be used (e.g., keyboard shortcuts, navigation keys, or special key combinations).", + "category": "Input automation", + "args": { + "key": { + "name": "key", + "type": "string", + "description": "A key or a combination (e.g., \"Enter\", \"Control+A\", \"Control++\", \"Control+Shift+R\"). Modifiers: Control, Shift, Alt, Meta", + "required": true + }, + "includeSnapshot": { + "name": "includeSnapshot", + "type": "boolean", + "description": "Whether to include a snapshot in the response. Default is false.", + "required": false + } + } }, - resize_page: { - description: - "Resizes the selected page's window so that the page has specified dimension", - category: 'Emulation', - args: { - width: { - name: 'width', - type: 'number', - description: 'Page width', - required: true, - }, - height: { - name: 'height', - type: 'number', - description: 'Page height', - required: true, - }, - }, + "resize_page": { + "description": "Resizes the selected page's window so that the page has specified dimension", + "category": "Emulation", + "args": { + "width": { + "name": "width", + "type": "number", + "description": "Page width", + "required": true + }, + "height": { + "name": "height", + "type": "number", + "description": "Page height", + "required": true + } + } }, - select_page: { - description: 'Select a page as a context for future tool calls.', - category: 'Navigation automation', - args: { - pageId: { - name: 'pageId', - type: 'number', - description: - 'The ID of the page to select. Call list_pages to get available pages.', - required: true, - }, - bringToFront: { - name: 'bringToFront', - type: 'boolean', - description: 'Whether to focus the page and bring it to the top.', - required: false, - }, - }, + "select_page": { + "description": "Select a page as a context for future tool calls.", + "category": "Navigation automation", + "args": { + "pageId": { + "name": "pageId", + "type": "number", + "description": "The ID of the page to select. Call list_pages to get available pages.", + "required": true + }, + "bringToFront": { + "name": "bringToFront", + "type": "boolean", + "description": "Whether to focus the page and bring it to the top.", + "required": false + } + } }, - take_memory_snapshot: { - description: - 'Capture a memory heapsnapshot of the currently selected page to memory leak debugging', - category: 'Performance', - args: { - filePath: { - name: 'filePath', - type: 'string', - description: - 'A path to a .heapsnapshot file to save the heapsnapshot to.', - required: true, - }, - }, + "take_memory_snapshot": { + "description": "Capture a memory heapsnapshot of the currently selected page to memory leak debugging", + "category": "Performance", + "args": { + "filePath": { + "name": "filePath", + "type": "string", + "description": "A path to a .heapsnapshot file to save the heapsnapshot to.", + "required": true + } + } }, - take_screenshot: { - description: 'Take a screenshot of the page or element.', - category: 'Debugging', - args: { - format: { - name: 'format', - type: 'string', - description: - 'Type of format to save the screenshot as. Default is "png"', - required: false, - default: 'png', - enum: ['png', 'jpeg', 'webp'], - }, - quality: { - name: 'quality', - type: 'number', - description: - 'Compression quality for JPEG and WebP formats (0-100). Higher values mean better quality but larger file sizes. Ignored for PNG format.', - required: false, - }, - uid: { - name: 'uid', - type: 'string', - description: - 'The uid of an element on the page from the page content snapshot. If omitted takes a pages screenshot.', - required: false, - }, - fullPage: { - name: 'fullPage', - type: 'boolean', - description: - 'If set to true takes a screenshot of the full page instead of the currently visible viewport. Incompatible with uid.', - required: false, - }, - filePath: { - name: 'filePath', - type: 'string', - description: - 'The absolute path, or a path relative to the current working directory, to save the screenshot to instead of attaching it to the response.', - required: false, - }, - }, + "take_screenshot": { + "description": "Take a screenshot of the page or element.", + "category": "Debugging", + "args": { + "format": { + "name": "format", + "type": "string", + "description": "Type of format to save the screenshot as. Default is \"png\"", + "required": false, + "default": "png", + "enum": [ + "png", + "jpeg", + "webp" + ] + }, + "quality": { + "name": "quality", + "type": "number", + "description": "Compression quality for JPEG and WebP formats (0-100). Higher values mean better quality but larger file sizes. Ignored for PNG format.", + "required": false + }, + "uid": { + "name": "uid", + "type": "string", + "description": "The uid of an element on the page from the page content snapshot. If omitted takes a pages screenshot.", + "required": false + }, + "fullPage": { + "name": "fullPage", + "type": "boolean", + "description": "If set to true takes a screenshot of the full page instead of the currently visible viewport. Incompatible with uid.", + "required": false + }, + "filePath": { + "name": "filePath", + "type": "string", + "description": "The absolute path, or a path relative to the current working directory, to save the screenshot to instead of attaching it to the response.", + "required": false + } + } }, - take_snapshot: { - description: - 'Take a text snapshot of the currently selected page based on the a11y tree. The snapshot lists page elements along with a unique\nidentifier (uid). Always use the latest snapshot. Prefer taking a snapshot over taking a screenshot. The snapshot indicates the element selected\nin the DevTools Elements panel (if any).', - category: 'Debugging', - args: { - verbose: { - name: 'verbose', - type: 'boolean', - description: - 'Whether to include all possible information available in the full a11y tree. Default is false.', - required: false, - }, - filePath: { - name: 'filePath', - type: 'string', - description: - 'The absolute path, or a path relative to the current working directory, to save the snapshot to instead of attaching it to the response.', - required: false, - }, - }, + "take_snapshot": { + "description": "Take a text snapshot of the currently selected page based on the a11y tree. The snapshot lists page elements along with a unique\nidentifier (uid). Always use the latest snapshot. Prefer taking a snapshot over taking a screenshot. The snapshot indicates the element selected\nin the DevTools Elements panel (if any).", + "category": "Debugging", + "args": { + "verbose": { + "name": "verbose", + "type": "boolean", + "description": "Whether to include all possible information available in the full a11y tree. Default is false.", + "required": false + }, + "filePath": { + "name": "filePath", + "type": "string", + "description": "The absolute path, or a path relative to the current working directory, to save the snapshot to instead of attaching it to the response.", + "required": false + }, + "diff": { + "name": "diff", + "type": "boolean", + "description": "Return only the changes since the last snapshot. The cache is reset on navigation.", + "required": false + } + } }, - type_text: { - description: 'Type text using keyboard into a previously focused input', - category: 'Input automation', - args: { - text: { - name: 'text', - type: 'string', - description: 'The text to type', - required: true, - }, - submitKey: { - name: 'submitKey', - type: 'string', - description: - 'Optional key to press after typing. E.g., "Enter", "Tab", "Escape"', - required: false, - }, - }, - }, - upload_file: { - description: 'Upload a file through a provided element.', - category: 'Input automation', - args: { - uid: { - name: 'uid', - type: 'string', - description: - 'The uid of the file input element or an element that will open file chooser on the page from the page content snapshot', - required: true, - }, - filePath: { - name: 'filePath', - type: 'string', - description: 'The local path of the file to upload', - required: true, - }, - includeSnapshot: { - name: 'includeSnapshot', - type: 'boolean', - description: - 'Whether to include a snapshot in the response. Default is false.', - required: false, - }, - }, + "type_text": { + "description": "Type text using keyboard into a previously focused input", + "category": "Input automation", + "args": { + "text": { + "name": "text", + "type": "string", + "description": "The text to type", + "required": true + }, + "submitKey": { + "name": "submitKey", + "type": "string", + "description": "Optional key to press after typing. E.g., \"Enter\", \"Tab\", \"Escape\"", + "required": false + } + } }, + "upload_file": { + "description": "Upload a file through a provided element.", + "category": "Input automation", + "args": { + "uid": { + "name": "uid", + "type": "string", + "description": "The uid of the file input element or an element that will open file chooser on the page from the page content snapshot", + "required": true + }, + "filePath": { + "name": "filePath", + "type": "string", + "description": "The local path of the file to upload", + "required": true + }, + "includeSnapshot": { + "name": "includeSnapshot", + "type": "boolean", + "description": "Whether to include a snapshot in the response. Default is false.", + "required": false + } + } + } } as const; diff --git a/src/formatters/SnapshotFormatter.ts b/src/formatters/SnapshotFormatter.ts index 2ec80e751..1f53a2c8f 100644 --- a/src/formatters/SnapshotFormatter.ts +++ b/src/formatters/SnapshotFormatter.ts @@ -27,19 +27,53 @@ export class SnapshotFormatter { Get a verbose snapshot to include all elements if you are interested in the selected element.\n\n`); } + if (this.#snapshot.diff) { + const {added, changed, removed} = this.#snapshot.diff; + if (added.length === 0 && changed.length === 0 && removed.length === 0) { + chunks.push('No changes since last snapshot.\n'); + return chunks.join(''); + } + } + chunks.push(this.#formatNode(root, 0)); + + if (this.#snapshot.diff?.removed.length) { + chunks.push('\n[REMOVED] elements:\n'); + for (const uid of this.#snapshot.diff.removed) { + chunks.push(`- uid=${uid}\n`); + } + } + return chunks.join(''); } toJSON(): object { - return this.#nodeToJSON(this.#snapshot.root); + const result = this.#nodeToJSON(this.#snapshot.root) as Record< + string, + unknown + >; + if (this.#snapshot.diff) { + result.diff = this.#snapshot.diff; + } + return result; } #formatNode(node: TextSnapshotNode, depth = 0): string { const chunks: string[] = []; const attributes = this.#getAttributes(node); + + let prefix = ''; + if (this.#snapshot.diff) { + if (this.#snapshot.diff.added.includes(node.id)) { + prefix = '[ADDED] '; + } else if (this.#snapshot.diff.changed.includes(node.id)) { + prefix = '[CHANGED] '; + } + } + const line = ' '.repeat(depth * 2) + + prefix + attributes.join(' ') + (node.id === this.#snapshot.selectedElementUid ? ' [selected in the DevTools Elements panel]' diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.ts index 170198803..0bafe1f2d 100644 --- a/src/tools/ToolDefinition.ts +++ b/src/tools/ToolDefinition.ts @@ -65,6 +65,7 @@ export interface ImageContentData { export interface SnapshotParams { verbose?: boolean; filePath?: string; + diff?: boolean; } export interface LighthouseData { diff --git a/src/tools/snapshot.ts b/src/tools/snapshot.ts index 338bd6794..1c48f1449 100644 --- a/src/tools/snapshot.ts +++ b/src/tools/snapshot.ts @@ -32,11 +32,18 @@ in the DevTools Elements panel (if any).`, .describe( 'The absolute path, or a path relative to the current working directory, to save the snapshot to instead of attaching it to the response.', ), + diff: zod + .boolean() + .optional() + .describe( + 'Return only the changes since the last snapshot. The cache is reset on navigation.', + ), }, handler: async (request, response) => { response.includeSnapshot({ verbose: request.params.verbose ?? false, filePath: request.params.filePath, + diff: request.params.diff, }); }, }); diff --git a/src/types.ts b/src/types.ts index 4efd8dc93..318482e64 100644 --- a/src/types.ts +++ b/src/types.ts @@ -33,6 +33,11 @@ export interface TextSnapshot { // snapshot. This flag indicates if there is any selected element. hasSelectedElement: boolean; verbose: boolean; + diff?: { + added: string[]; + removed: string[]; + changed: string[]; + }; } export interface EmulationSettings { diff --git a/tests/McpContext.test.ts b/tests/McpContext.test.ts index 075c94742..fa6d8b5f2 100644 --- a/tests/McpContext.test.ts +++ b/tests/McpContext.test.ts @@ -130,6 +130,59 @@ describe('McpContext', () => { }); }); + describe('take_snapshot diffing', () => { + it('should support snapshot diffing', async () => { + await withMcpContext(async (_response, context) => { + const page = context.getSelectedMcpPage(); + + // 1. Initial snapshot + await page.pptrPage.setContent(html``); + await context.createTextSnapshot(page, false, undefined, {diff: true}); + assert.strictEqual(page.textSnapshot?.diff, undefined); // First one has no diff + + // 2. Add an element + await page.pptrPage.setContent( + html``, + ); + await context.createTextSnapshot(page, false, undefined, {diff: true}); + let snapshot = page.textSnapshot; + assert.ok(snapshot?.diff); + assert.ok(snapshot!.diff!.added.length >= 1); + // Verify that Button 2 is in the added list + const addedNodes = snapshot!.diff!.added.map(id => + snapshot!.idToNode.get(id), + ); + assert.ok(addedNodes.some(n => n?.name === 'Button 2')); + + // 3. Change an element + await page.pptrPage.setContent( + html``, + ); + await context.createTextSnapshot(page, false, undefined, {diff: true}); + snapshot = page.textSnapshot; + assert.ok(snapshot?.diff); + // At least one of added/changed/removed should have something. + assert.ok( + snapshot!.diff!.changed.length >= 1 || + (snapshot!.diff!.added.length >= 1 && + snapshot!.diff!.removed.length >= 1), + ); + + // 4. Remove an element + await page.pptrPage.setContent(html``); + await context.createTextSnapshot(page, false, undefined, {diff: true}); + snapshot = page.textSnapshot; + assert.ok(snapshot?.diff); + assert.ok(snapshot!.diff!.removed.length >= 1); + + // 5. Navigation should reset + await page.pptrPage.goto('about:blank'); + await context.createTextSnapshot(page, false, undefined, {diff: true}); + assert.strictEqual(page.textSnapshot?.diff, undefined); // Should be reset + }); + }); + }); + it('should include network requests in structured content', async t => { await withMcpContext(async (response, context) => { const mockRequest = getMockRequest({ From e2f31426c583dfd87e9e703e440ca4141c244f8d Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Thu, 19 Mar 2026 20:22:34 +0100 Subject: [PATCH 3/6] fix: update CLI to use generated definitions and bundle dependencies for distribution --- docs/tool-reference.md | 3 +- package.json | 2 +- scripts/post-build.ts | 5 +- snapshot_improvement_plan.md | 75 ++ src/McpContext.ts | 4 +- src/bin/chrome-devtools-cli-options.ts | 745 -------------- src/bin/chrome-devtools.ts | 2 +- src/bin/cliDefinitions.ts | 1282 ++++++++++++------------ tests/McpContext.test.ts | 3 +- 9 files changed, 749 insertions(+), 1372 deletions(-) create mode 100644 snapshot_improvement_plan.md delete mode 100644 src/bin/chrome-devtools-cli-options.ts diff --git a/docs/tool-reference.md b/docs/tool-reference.md index 50b4c02c5..f56afdca4 100644 --- a/docs/tool-reference.md +++ b/docs/tool-reference.md @@ -1,6 +1,6 @@ -# Chrome DevTools MCP Tool Reference (~6940 cl100k_base tokens) +# Chrome DevTools MCP Tool Reference (~6975 cl100k_base tokens) - **[Input automation](#input-automation)** (9 tools) - [`click`](#click) @@ -393,6 +393,7 @@ in the DevTools Elements panel (if any). **Parameters:** +- **diff** (boolean) _(optional)_: Return only the changes since the last snapshot. The cache is reset on navigation. - **filePath** (string) _(optional)_: The absolute path, or a path relative to the current working directory, to save the snapshot to instead of attaching it to the response. - **verbose** (boolean) _(optional)_: Whether to include all possible information available in the full a11y tree. Default is false. diff --git a/package.json b/package.json index 873d62498..294a0cf33 100644 --- a/package.json +++ b/package.json @@ -16,7 +16,7 @@ "typecheck": "tsc --noEmit", "format": "eslint --cache --fix . && prettier --write --cache .", "check-format": "eslint --cache . && prettier --check --cache .;", - "gen": "npm run build && npm run docs:generate && npm run cli:generate && npm run format", + "gen": "npm run bundle && npm run docs:generate && npm run cli:generate && npm run format", "docs:generate": "node --experimental-strip-types scripts/generate-docs.ts", "start": "npm run build && node build/src/index.js", "start-debug": "DEBUG=mcp:* DEBUG_COLORS=false npm run build && node build/src/index.js", diff --git a/scripts/post-build.ts b/scripts/post-build.ts index 7fe0a482b..b90fbe3c8 100644 --- a/scripts/post-build.ts +++ b/scripts/post-build.ts @@ -108,7 +108,10 @@ function copySnapshotFiles() { const files = fs.readdirSync(testsDir); for (const file of files) { if (file.endsWith('.snapshot')) { - fs.copyFileSync(path.join(testsDir, file), path.join(buildTestsDir, file)); + fs.copyFileSync( + path.join(testsDir, file), + path.join(buildTestsDir, file), + ); } } diff --git a/snapshot_improvement_plan.md b/snapshot_improvement_plan.md new file mode 100644 index 000000000..886f6532a --- /dev/null +++ b/snapshot_improvement_plan.md @@ -0,0 +1,75 @@ +# Implementation Plan: Chrome DevTools CLI & MCP Optimizations + +This plan implements optimizations for the `take_snapshot` tool to improve agent efficiency by reducing the volume of DOM data transmitted. It ensures full compatibility with both the Model Context Protocol (MCP) and the `chrome-devtools` CLI. + +## Progress Overview + +- [x] **Step 0: Save Plan to Project** + - [x] Save this plan to `/Users/hablich/src/internal/chrome-devtools-mcp/snapshot_improvement_plan.md` +- [x] **Step 0: Save Plan to Project** +- [x] **PR 1: Native Semantic Filtering** (`feat/semantic-filtering`) + - [x] Create branch and apply filtering changes + - [x] Include `post-build.ts` fix (on `main`) + - [x] Verify tests and CLI + - [x] Commit +- [x] **PR 2: Built-in "Interactive Only" Mode** (`feat/interactive-mode`) + - [x] Create branch and apply interactive mode changes + - [x] Include `post-build.ts` fix + - [x] Verify tests and CLI + - [x] Commit +- [x] **PR 3: Session-Based Snapshot Diffs** (`feat/snapshot-diffs`) + - [x] Create branch and apply diffing + UID stability changes + - [x] Include `post-build.ts` fix + - [x] Verify tests and CLI + - [x] Commit +- [x] **Verification** + - [x] Check if each branch works independently from each other. + +--- + +## PR 1: Native Semantic Filtering + +**Objective**: Enable agents to request only specific types of elements from the accessibility tree. + +- **Flags**: `role`, `name`, `text` +- **Tasks**: + - [ ] Update `SnapshotParams` in `src/tools/ToolDefinition.ts`. + - [ ] Update `take_snapshot` tool schema in `src/tools/snapshot.ts`. + - [ ] Implement `filterTree` in `McpContext.ts` to prune nodes that do not match and do not have matching descendants. + - [ ] Update `createTextSnapshot` to use `filterTree`. + - [ ] Add tests to `tests/McpContext.test.ts` verifying `role`, `name`, and `text` filters. + +## PR 2: Built-in "Interactive Only" Mode + +**Objective**: Strip non-actionable content from snapshots. + +- **Flag**: `interactive` +- **Tasks**: + - [ ] Define "interactive" roles: `button`, `link`, `menuitem`, `checkbox`, `radio`, `textbox`, `searchbox`, `combobox`. + - [ ] Implement `isInteractive` check in `McpContext.ts`. + - [ ] Use `DOMDebugger.getEventListeners` to include nodes with event listeners. + - [ ] Update `createTextSnapshot` to use this logic when `interactive: true`. + - [ ] Add tests to `tests/tools/snapshot.test.ts` with complex HTML to verify pruning of static text. + +## PR 3: Session-Based Snapshot Diffs + +**Objective**: Send only changes since the last observation. + +- **Flag**: `diff` +- **Tasks**: + - [ ] Update `McpPage` to store `lastSnapshot` and reset on `framenavigated` / `load`. + - [ ] Implement semantic diffing by `uid`. + - [ ] Update `SnapshotFormatter` to render diffs with `[+]`, `[-]`, `[*]`. + - [ ] Add tests to `tests/McpContext.test.ts` for multiple snapshot calls, ensuring only deltas are returned and navigation resets the cache. + +--- + +## Verification & Testing Strategy + +- **Infrastructure**: Use `withMcpContext` in existing test files. +- **MCP Verification**: Run the server and call `take_snapshot` with new parameters. +- **CLI Verification**: + - Run `npm run cli:generate` after each PR. + - Run `chrome-devtools take_snapshot --help` to check for new flags. + - Execute commands like `chrome-devtools take_snapshot --role button` and verify output. +- **Daemon Verification**: Ensure that `diff` mode works correctly when calling the CLI multiple times (state should be preserved in the running daemon). diff --git a/src/McpContext.ts b/src/McpContext.ts index 6cbc8e5a2..fa8080549 100644 --- a/src/McpContext.ts +++ b/src/McpContext.ts @@ -754,13 +754,13 @@ export class McpContext implements Context { index = 0, ): TextSnapshotNode => { let id = ''; - const nodeAny = node as any; + const nodeAny = node as unknown as Record; // StaticText nodes often have unstable backendNodeIds in some contexts, // or we might want to group them by their parent. const uniqueBackendId = nodeAny.backendNodeId && node.role !== 'StaticText' ? `${nodeAny.loaderId}_${nodeAny.backendNodeId}` - : `${nodeAny.loaderId}_${nodeAny.role}_${parentId}_${index}`; + : `${nodeAny.loaderId}_${node.role}_${parentId}_${index}`; if (uniqueBackendNodeIdToMcpId.has(uniqueBackendId)) { // Re-use MCP exposed ID if the uniqueId is the same. diff --git a/src/bin/chrome-devtools-cli-options.ts b/src/bin/chrome-devtools-cli-options.ts deleted file mode 100644 index 6e317a333..000000000 --- a/src/bin/chrome-devtools-cli-options.ts +++ /dev/null @@ -1,745 +0,0 @@ -/** - * @license - * Copyright 2026 Google LLC - * SPDX-License-Identifier: Apache-2.0 - */ - -// NOTE: do not edit manually. Auto-generated by 'npm run cli:generate'. - -export interface ArgDef { - name: string; - type: string; - description: string; - required: boolean; - default?: string | number | boolean; - enum?: ReadonlyArray; -} -export type Commands = Record< - string, - { - description: string; - category: string; - args: Record; - } ->; -export const commands: Commands = { - click: { - description: 'Clicks on the provided element', - category: 'Input automation', - args: { - uid: { - name: 'uid', - type: 'string', - description: - 'The uid of an element on the page from the page content snapshot', - required: true, - }, - dblClick: { - name: 'dblClick', - type: 'boolean', - description: 'Set to true for double clicks. Default is false.', - required: false, - }, - includeSnapshot: { - name: 'includeSnapshot', - type: 'boolean', - description: - 'Whether to include a snapshot in the response. Default is false.', - required: false, - }, - }, - }, - close_page: { - description: - 'Closes the page by its index. The last open page cannot be closed.', - category: 'Navigation automation', - args: { - pageId: { - name: 'pageId', - type: 'number', - description: - 'The ID of the page to close. Call list_pages to list pages.', - required: true, - }, - }, - }, - drag: { - description: 'Drag an element onto another element', - category: 'Input automation', - args: { - from_uid: { - name: 'from_uid', - type: 'string', - description: 'The uid of the element to drag', - required: true, - }, - to_uid: { - name: 'to_uid', - type: 'string', - description: 'The uid of the element to drop into', - required: true, - }, - includeSnapshot: { - name: 'includeSnapshot', - type: 'boolean', - description: - 'Whether to include a snapshot in the response. Default is false.', - required: false, - }, - }, - }, - emulate: { - description: 'Emulates various features on the selected page.', - category: 'Emulation', - args: { - networkConditions: { - name: 'networkConditions', - type: 'string', - description: 'Throttle network. Omit to disable throttling.', - required: false, - enum: ['Offline', 'Slow 3G', 'Fast 3G', 'Slow 4G', 'Fast 4G'], - }, - cpuThrottlingRate: { - name: 'cpuThrottlingRate', - type: 'number', - description: - 'Represents the CPU slowdown factor. Omit or set the rate to 1 to disable throttling', - required: false, - }, - geolocation: { - name: 'geolocation', - type: 'string', - description: - 'Geolocation (`x`) to emulate. Latitude between -90 and 90. Longitude between -180 and 180. Omit clear the geolocation override.', - required: false, - }, - userAgent: { - name: 'userAgent', - type: 'string', - description: - 'User agent to emulate. Set to empty string to clear the user agent override.', - required: false, - }, - colorScheme: { - name: 'colorScheme', - type: 'string', - description: - 'Emulate the dark or the light mode. Set to "auto" to reset to the default.', - required: false, - enum: ['dark', 'light', 'auto'], - }, - viewport: { - name: 'viewport', - type: 'string', - description: - "Emulate device viewports 'xx[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to emulate mobile devices. 'landscape' to emulate landscape mode.", - required: false, - }, - }, - }, - evaluate_script: { - description: - 'Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON,\nso returned values have to be JSON-serializable.', - category: 'Debugging', - args: { - function: { - name: 'function', - type: 'string', - description: - 'A JavaScript function declaration to be executed by the tool in the currently selected page.\nExample without arguments: `() => {\n return document.title\n}` or `async () => {\n return await fetch("example.com")\n}`.\nExample with arguments: `(el) => {\n return el.innerText;\n}`\n', - required: true, - }, - args: { - name: 'args', - type: 'array', - description: 'An optional list of arguments to pass to the function.', - required: false, - }, - }, - }, - fill: { - description: - 'Type text into a input, text area or select an option from a element.", - "category": "Input automation", - "args": { - "uid": { - "name": "uid", - "type": "string", - "description": "The uid of an element on the page from the page content snapshot", - "required": true - }, - "value": { - "name": "value", - "type": "string", - "description": "The value to fill in", - "required": true - }, - "includeSnapshot": { - "name": "includeSnapshot", - "type": "boolean", - "description": "Whether to include a snapshot in the response. Default is false.", - "required": false - } - } + fill: { + description: + 'Type text into a input, text area or select an option from a