fix: update CLI to use generated definitions and bundle dependencies for distribution

Author: natorion

docs/tool-reference.md

@@ -1,6 +1,6 @@
 <!-- AUTO GENERATED DO NOT EDIT - run 'npm run gen' to update-->
 
-# 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.
 

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",

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),
+      );
     }
   }
 

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).

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<string, unknown>;
       // 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.