feat: Add MCP tool for heap snapshot comparison

README.md

@@ -514,9 +514,11 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
   - [`take_snapshot`](docs/tool-reference.md#take_snapshot)
   - [`screencast_start`](docs/tool-reference.md#screencast_start)
   - [`screencast_stop`](docs/tool-reference.md#screencast_stop)
-- **Memory** (8 tools)
+- **Memory** (10 tools)
   - [`take_heapsnapshot`](docs/tool-reference.md#take_heapsnapshot)
   - [`close_heapsnapshot`](docs/tool-reference.md#close_heapsnapshot)
+  - [`compare_heapsnapshots_class_nodes`](docs/tool-reference.md#compare_heapsnapshots_class_nodes)
+  - [`compare_heapsnapshots_summary`](docs/tool-reference.md#compare_heapsnapshots_summary)
   - [`get_heapsnapshot_class_nodes`](docs/tool-reference.md#get_heapsnapshot_class_nodes)
   - [`get_heapsnapshot_details`](docs/tool-reference.md#get_heapsnapshot_details)
   - [`get_heapsnapshot_edges`](docs/tool-reference.md#get_heapsnapshot_edges)

docs/tool-reference.md

@@ -39,9 +39,11 @@
   - [`take_snapshot`](#take_snapshot)
   - [`screencast_start`](#screencast_start)
   - [`screencast_stop`](#screencast_stop)
-- **[Memory](#memory)** (8 tools)
+- **[Memory](#memory)** (10 tools)
   - [`take_heapsnapshot`](#take_heapsnapshot)
   - [`close_heapsnapshot`](#close_heapsnapshot)
+  - [`compare_heapsnapshots_class_nodes`](#compare_heapsnapshots_class_nodes)
+  - [`compare_heapsnapshots_summary`](#compare_heapsnapshots_summary)
   - [`get_heapsnapshot_class_nodes`](#get_heapsnapshot_class_nodes)
   - [`get_heapsnapshot_details`](#get_heapsnapshot_details)
   - [`get_heapsnapshot_edges`](#get_heapsnapshot_edges)
@@ -468,6 +470,29 @@ in the DevTools Elements panel (if any).
 
 ---
 
+### `compare_heapsnapshots_class_nodes`
+
+**Description:** Loads two memory heapsnapshots and returns the diff details (added/deleted instances) for a specific class. (requires flag: --memoryDebugging=true)
+
+**Parameters:**
+
+- **baseFilePath** (string) **(required)**: A path to the base .heapsnapshot file (earlier snapshot).
+- **classIndex** (number) **(required)**: 0-based index of the class in the summary list to filter results, showing individual objects.
+- **currentFilePath** (string) **(required)**: A path to the current .heapsnapshot file (later snapshot).
+
+---
+
+### `compare_heapsnapshots_summary`
+
+**Description:** Loads two memory heapsnapshots and returns the summary diff between them (classes with changes). (requires flag: --memoryDebugging=true)
+
+**Parameters:**
+
+- **baseFilePath** (string) **(required)**: A path to the base .heapsnapshot file (earlier snapshot).
+- **currentFilePath** (string) **(required)**: A path to the current .heapsnapshot file (later snapshot).
+
+---
+
 ### `get_heapsnapshot_class_nodes`
 
 **Description:** Loads a memory heapsnapshot and returns instances of a specific class with their IDs. (requires flag: --memoryDebugging=true)

eslint.config.mjs

@@ -18,6 +18,7 @@ export default defineConfig([
     '**/node_modules',
     '**/build/',
     'tests/tools/fixtures/',
+    'tests/fixtures/',
     'src/third_party/lighthouse-devtools-mcp-bundle.js',
   ]),
   importPlugin.flatConfigs.typescript,

package.json

@@ -63,7 +63,7 @@
     "@types/yargs": "^17.0.33",
     "@typescript-eslint/eslint-plugin": "^8.43.0",
     "@typescript-eslint/parser": "^8.43.0",
-    "chrome-devtools-frontend": "1.0.1642845",
+    "chrome-devtools-frontend": "1.0.1645245",
     "core-js": "3.49.0",
     "debug": "4.4.3",
     "eslint": "^9.35.0",

src/HeapSnapshotManager.ts

@@ -18,11 +18,13 @@ export type AggregatedInfoWithId =
   WithSymbolId<DevTools.HeapSnapshotModel.HeapSnapshotModel.AggregatedInfo>;
 
 export class HeapSnapshotManager {
+  #snapshotIdGenerator = createIdGenerator();
   #snapshots = new Map<
     string,
     {
       snapshot: DevTools.HeapSnapshotModel.HeapSnapshotProxy.HeapSnapshotProxy;
       worker: DevTools.HeapSnapshotModel.HeapSnapshotProxy.HeapSnapshotWorkerProxy;
+      diffCacheKey: number;
       // TODO: use a multimap
       idToClassKey: Map<number, string>;
       classKeyToId: Map<string, number>;
@@ -43,6 +45,7 @@ export class HeapSnapshotManager {
     this.#snapshots.set(absolutePath, {
       snapshot,
       worker,
+      diffCacheKey: this.#snapshotIdGenerator(),
       idToClassKey: new Map<number, string>(),
       classKeyToId: new Map<string, number>(),
       idGenerator: createIdGenerator(),
@@ -161,6 +164,25 @@ export class HeapSnapshotManager {
     return await provider.serializeItemsRange(0, Infinity);
   }
 
+  async compareSnapshots(
+    baseFilePath: string,
+    currentFilePath: string,
+  ): Promise<
+    Record<string, DevTools.HeapSnapshotModel.HeapSnapshotModel.Diff>
+  > {
+    const baseSnapshot = await this.getSnapshot(baseFilePath);
+    const currentSnapshot = await this.getSnapshot(currentFilePath);
+
+    const interfaceDefinitions = await currentSnapshot.interfaceDefinitions();
+    const aggregatesForDiff =
+      await baseSnapshot.aggregatesForDiff(interfaceDefinitions);
+    const cachedBaseSnapshot = this.#getCachedSnapshot(baseFilePath);
+    return await currentSnapshot.calculateSnapshotDiff(
+      cachedBaseSnapshot.diffCacheKey,
+      aggregatesForDiff,
+    );
+  }
+
   #getCachedSnapshot(filePath: string) {
     const absolutePath = path.resolve(filePath);
     const cached = this.#snapshots.get(absolutePath);

src/McpContext.ts

@@ -975,4 +975,16 @@ export class McpContext implements Context {
   ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange> {
     return await this.#heapSnapshotManager.getEdges(filePath, nodeId);
   }
+
+  async compareHeapSnapshots(
+    baseFilePath: string,
+    currentFilePath: string,
+  ): Promise<
+    Record<string, DevTools.HeapSnapshotModel.HeapSnapshotModel.Diff>
+  > {
+    return await this.#heapSnapshotManager.compareSnapshots(
+      baseFilePath,
+      currentFilePath,
+    );
+  }
 }

src/McpResponse.ts

@@ -8,8 +8,12 @@ import type {WebMCPTool} from 'puppeteer-core';
 
 import type {ParsedArguments} from './bin/chrome-devtools-mcp-cli-options.js';
 import {ConsoleFormatter} from './formatters/ConsoleFormatter.js';
-import {HeapSnapshotFormatter} from './formatters/HeapSnapshotFormatter.js';
-import {isEdgeLike, isNodeLike} from './formatters/HeapSnapshotFormatter.js';
+import {
+  HeapSnapshotFormatter,
+  isEdgeLike,
+  isNodeLike,
+  type HeapSnapshotDiffSummary,
+} from './formatters/HeapSnapshotFormatter.js';
 import {IssueFormatter} from './formatters/IssueFormatter.js';
 import {NetworkFormatter} from './formatters/NetworkFormatter.js';
 import {SnapshotFormatter} from './formatters/SnapshotFormatter.js';
@@ -223,6 +227,8 @@ export class McpResponse implements Response {
     staticData?: DevTools.HeapSnapshotModel.HeapSnapshotModel.StaticData | null;
     nodes?: DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange;
     retainingPaths?: DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainingPaths;
+    diff?: Record<string, DevTools.HeapSnapshotModel.HeapSnapshotModel.Diff>;
+    diffDetails?: DevTools.HeapSnapshotModel.HeapSnapshotModel.Diff;
   };
   #networkRequestsOptions?: {
     include: boolean;
@@ -489,6 +495,26 @@ export class McpResponse implements Response {
     };
   }
 
+  setHeapSnapshotDiff(
+    diff: Record<string, DevTools.HeapSnapshotModel.HeapSnapshotModel.Diff>,
+  ) {
+    this.#heapSnapshotOptions = {
+      ...this.#heapSnapshotOptions,
+      include: true,
+      diff,
+    };
+  }
+
+  setHeapSnapshotDiffDetails(
+    diff: DevTools.HeapSnapshotModel.HeapSnapshotModel.Diff,
+  ) {
+    this.#heapSnapshotOptions = {
+      ...this.#heapSnapshotOptions,
+      include: true,
+      diffDetails: diff,
+    };
+  }
+
   attachImage(value: ImageContentData): void {
     this.#images.push(value);
   }
@@ -819,6 +845,8 @@ export class McpResponse implements Response {
       heapSnapshotData?: object[];
       heapSnapshotNodes?: readonly object[];
       heapSnapshotRetainingPaths?: object;
+      heapSnapshotDiff?: Record<string, HeapSnapshotDiffSummary>;
+      heapSnapshotDiffDetails?: HeapSnapshotDiffSummary;
       extensionServiceWorkers?: object[];
       extensionPages?: object[];
       errorMessage?: string;
@@ -1133,6 +1161,28 @@ Call ${handleDialog.name} to handle it before continuing.`);
         structuredContent.heapSnapshotRetainingPaths =
           retainingPaths as unknown as object;
       }
+      const diff = this.#heapSnapshotOptions.diff;
+      const diffDetails = this.#heapSnapshotOptions.diffDetails;
+      if (diff) {
+        response.push('### Heap Snapshot Diff');
+        const summarizedDiff = HeapSnapshotFormatter.prepareDiffSummary(diff);
+        response.push(
+          useToon
+            ? toonEncode(summarizedDiff)
+            : HeapSnapshotFormatter.formatDiffSummary(summarizedDiff),
+        );
+        structuredContent.heapSnapshotDiff = summarizedDiff;
+      } else if (diffDetails) {
+        response.push('### Heap Snapshot Diff');
+        const summarizedDiff =
+          HeapSnapshotFormatter.prepareDiffDetails(diffDetails);
+        response.push(
+          useToon
+            ? toonEncode(summarizedDiff)
+            : HeapSnapshotFormatter.formatDiffDetails(summarizedDiff),
+        );
+        structuredContent.heapSnapshotDiffDetails = summarizedDiff;
+      }
     }
 
     if (data.detailedNetworkRequest) {

src/bin/chrome-devtools-cli-options.ts

@@ -108,6 +108,55 @@ export const commands: Commands = {
       },
     },
   },
+  compare_heapsnapshots_class_nodes: {
+    description:
+      'Loads two memory heapsnapshots and returns the diff details (added/deleted instances) for a specific class. (requires flag: --memoryDebugging=true)',
+    category: 'Memory',
+    args: {
+      baseFilePath: {
+        name: 'baseFilePath',
+        type: 'string',
+        description:
+          'A path to the base .heapsnapshot file (earlier snapshot).',
+        required: true,
+      },
+      currentFilePath: {
+        name: 'currentFilePath',
+        type: 'string',
+        description:
+          'A path to the current .heapsnapshot file (later snapshot).',
+        required: true,
+      },
+      classIndex: {
+        name: 'classIndex',
+        type: 'number',
+        description:
+          '0-based index of the class in the summary list to filter results, showing individual objects.',
+        required: true,
+      },
+    },
+  },
+  compare_heapsnapshots_summary: {
+    description:
+      'Loads two memory heapsnapshots and returns the summary diff between them (classes with changes). (requires flag: --memoryDebugging=true)',
+    category: 'Memory',
+    args: {
+      baseFilePath: {
+        name: 'baseFilePath',
+        type: 'string',
+        description:
+          'A path to the base .heapsnapshot file (earlier snapshot).',
+        required: true,
+      },
+      currentFilePath: {
+        name: 'currentFilePath',
+        type: 'string',
+        description:
+          'A path to the current .heapsnapshot file (later snapshot).',
+        required: true,
+      },
+    },
+  },
   drag: {
     description: 'Drag an element onto another element',
     category: 'Input automation',