Add explore memory snapshot tool

Author: Lightning00Blade

rollup.config.mjs

@@ -296,4 +296,11 @@ export default [
     },
     (_source, _importer, _isResolved) => false,
   ),
+  bundleDependency(
+    'devtools-heap-snapshot-worker.js',
+    {
+      inlineDynamicImports: true,
+    },
+    (_source, _importer, _isResolved) => false,
+  ),
 ];

src/McpContext.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import fsSync from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
@@ -16,7 +17,6 @@ import {
   type ListenerMap,
   type UncaughtError,
 } from './PageCollector.js';
-import type {DevTools} from './third_party/index.js';
 import type {
   Browser,
   BrowserContext,
@@ -29,6 +29,7 @@ import type {
   Viewport,
   Target,
 } from './third_party/index.js';
+import {DevTools} from './third_party/index.js';
 import {Locator} from './third_party/index.js';
 import {PredefinedNetworkConditions} from './third_party/index.js';
 import {listPages} from './tools/pages.js';
@@ -905,4 +906,49 @@ export class McpContext implements Context {
   getExtension(id: string): InstalledExtension | undefined {
     return this.#extensionRegistry.getById(id);
   }
+
+  async getHeapSnapshotProxy(
+    heapsnapshotPath: string,
+  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotProxy.HeapSnapshotProxy> {
+    const workerProxy =
+      new DevTools.HeapSnapshotModel.HeapSnapshotProxy.HeapSnapshotWorkerProxy(
+        () => {
+          /* noop */
+        },
+        import.meta.resolve('../third_party/devtools-heap-snapshot-worker.js'),
+      );
+
+    const absolutePath = path.resolve(heapsnapshotPath);
+
+    try {
+      const {promise: snapshotPromise, resolve: resolveSnapshot} =
+        Promise.withResolvers<DevTools.HeapSnapshotModel.HeapSnapshotProxy.HeapSnapshotProxy>();
+
+      const loaderProxy = workerProxy.createLoader(
+        1,
+        (
+          snapshotProxy: DevTools.HeapSnapshotModel.HeapSnapshotProxy.HeapSnapshotProxy,
+        ) => {
+          resolveSnapshot(snapshotProxy);
+        },
+      );
+
+      const fileStream = fsSync.createReadStream(absolutePath, {
+        encoding: 'utf-8',
+        highWaterMark: 1024 * 1024,
+      });
+
+      for await (const chunk of fileStream) {
+        await loaderProxy.write(chunk);
+      }
+
+      await loaderProxy.close();
+
+      const snapshot = await snapshotPromise;
+
+      return snapshot;
+    } finally {
+      workerProxy.dispose();
+    }
+  }
 }

src/McpResponse.ts

@@ -6,6 +6,7 @@
 
 import type {ParsedArguments} from './bin/chrome-devtools-mcp-cli-options.js';
 import {ConsoleFormatter} from './formatters/ConsoleFormatter.js';
+import {HeapSnapshotFormatter} from './formatters/HeapSnapshotFormatter.js';
 import {IssueFormatter} from './formatters/IssueFormatter.js';
 import {NetworkFormatter} from './formatters/NetworkFormatter.js';
 import {SnapshotFormatter} from './formatters/SnapshotFormatter.js';
@@ -166,6 +167,14 @@ export class McpResponse implements Response {
   #attachedLighthouseResult?: LighthouseData;
   #textResponseLines: string[] = [];
   #images: ImageContentData[] = [];
+  #heapSnapshotOptions?: {
+    include: boolean;
+    aggregates: Record<
+      string,
+      DevTools.HeapSnapshotModel.HeapSnapshotModel.AggregatedInfo
+    >;
+    pagination?: PaginationOptions;
+  };
   #networkRequestsOptions?: {
     include: boolean;
     pagination?: PaginationOptions;
@@ -358,6 +367,20 @@ export class McpResponse implements Response {
     this.#textResponseLines.push(value);
   }
 
+  setHeapSnapshot(
+    aggregates: Record<
+      string,
+      DevTools.HeapSnapshotModel.HeapSnapshotModel.AggregatedInfo
+    >,
+    options?: PaginationOptions,
+  ) {
+    this.#heapSnapshotOptions = {
+      include: true,
+      aggregates,
+      pagination: options,
+    };
+  }
+
   attachImage(value: ImageContentData): void {
     this.#images.push(value);
   }
@@ -638,6 +661,7 @@ export class McpResponse implements Response {
       };
       pages?: object[];
       pagination?: object;
+      heapSnapshot?: object[];
       extensionServiceWorkers?: object[];
       extensionPages?: object[];
     } = {};
@@ -834,6 +858,26 @@ Call ${handleDialog.name} to handle it before continuing.`);
       }
     }
 
+    if (this.#heapSnapshotOptions?.include) {
+      const aggregates = this.#heapSnapshotOptions.aggregates;
+      const entries = Object.entries(aggregates);
+      const sortedEntries = entries.sort((a, b) => b[1].self - a[1].self);
+
+      const paginationData = this.#dataWithPagination(
+        sortedEntries,
+        this.#heapSnapshotOptions.pagination,
+      );
+
+      structuredContent.pagination = paginationData.pagination;
+      response.push(...paginationData.info);
+
+      const paginatedRecord = Object.fromEntries(paginationData.items);
+      const formatter = new HeapSnapshotFormatter(paginatedRecord);
+
+      response.push(formatter.toString());
+      structuredContent.heapSnapshot = formatter.toJSON();
+    }
+
     if (data.detailedNetworkRequest) {
       response.push(data.detailedNetworkRequest.toStringDetailed());
       structuredContent.networkRequest =

src/formatters/HeapSnapshotFormatter.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {DevTools} from '../third_party/index.js';
+
+export interface FormattedSnapshotEntry {
+  className: string;
+  count: number;
+  selfSize: number;
+  retainedSize: number;
+}
+
+export class HeapSnapshotFormatter {
+  #aggregates: Record<
+    string,
+    DevTools.HeapSnapshotModel.HeapSnapshotModel.AggregatedInfo
+  >;
+
+  constructor(
+    aggregates: Record<
+      string,
+      DevTools.HeapSnapshotModel.HeapSnapshotModel.AggregatedInfo
+    >,
+  ) {
+    this.#aggregates = aggregates;
+  }
+
+  #getSortedAggregates(): DevTools.HeapSnapshotModel.HeapSnapshotModel.AggregatedInfo[] {
+    return Object.values(this.#aggregates).sort((a, b) => b.self - a.self);
+  }
+
+  toString(): string {
+    const sorted = this.#getSortedAggregates();
+    const lines: string[] = [];
+    lines.push('className,count,selfSize,maxRetainedSize');
+
+    for (const info of sorted) {
+      lines.push(`"${info.name}",${info.count},${info.self},${info.maxRet}`);
+    }
+
+    return lines.join('\n');
+  }
+
+  toJSON(): FormattedSnapshotEntry[] {
+    const sorted = this.#getSortedAggregates();
+    return sorted.map(info => ({
+      className: info.name,
+      count: info.count,
+      selfSize: info.self,
+      retainedSize: info.maxRet,
+    }));
+  }
+}

src/third_party/devtools-heap-snapshot-worker.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// eslint-disable-next-line no-restricted-imports
+import '../../node_modules/chrome-devtools-frontend/front_end/entrypoints/heap_snapshot_worker/heap_snapshot_worker-entrypoint.js';

src/tools/ToolDefinition.ts

@@ -13,6 +13,7 @@ import type {
   Page,
   ScreenRecorder,
   Viewport,
+  DevTools,
 } from '../third_party/index.js';
 import type {InsightName, TraceResult} from '../trace-processing/parse.js';
 import type {
@@ -99,6 +100,13 @@ export interface DevToolsData {
 
 export interface Response {
   appendResponseLine(value: string): void;
+  setHeapSnapshot(
+    aggregates: Record<
+      string,
+      DevTools.HeapSnapshotModel.HeapSnapshotModel.AggregatedInfo
+    >,
+    options?: PaginationOptions,
+  ): void;
   setIncludePages(value: boolean): void;
   setIncludeNetworkRequests(
     value: boolean,
@@ -118,7 +126,7 @@ export interface Response {
   includeSnapshot(params?: SnapshotParams): void;
   attachImage(value: ImageContentData): void;
   attachNetworkRequest(
-    reqid: number,
+    reqId: number,
     options?: {requestFilePath?: string; responseFilePath?: string},
   ): void;
   attachConsoleMessage(msgid: number): void;
@@ -199,6 +207,9 @@ export type Context = Readonly<{
   getExtensionServiceWorkerId(
     extensionServiceWorker: ExtensionServiceWorker,
   ): string | undefined;
+  getHeapSnapshotProxy(
+    heapsnapshotPath: string,
+  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotProxy.HeapSnapshotProxy>;
 }>;
 
 export type ContextPage = Readonly<{

src/tools/memory.ts

@@ -4,10 +4,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import {zod} from '../third_party/index.js';
+import {zod, DevTools} from '../third_party/index.js';
 
 import {ToolCategory} from './categories.js';
-import {definePageTool} from './ToolDefinition.js';
+import {definePageTool, defineTool} from './ToolDefinition.js';
 
 export const takeMemorySnapshot = definePageTool({
   name: 'take_memory_snapshot',
@@ -33,3 +33,37 @@ export const takeMemorySnapshot = definePageTool({
     );
   },
 });
+
+export const exploreMemorySnapshot = defineTool({
+  name: 'explored_memory_snapshot',
+  description: 'Explose ',
+  annotations: {
+    category: ToolCategory.PERFORMANCE,
+    readOnlyHint: true,
+  },
+  schema: {
+    filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+    pageSize: zod.number().optional().describe('Page size for pagination.'),
+    pageIdx: zod.number().optional().describe('Page index for pagination.'),
+  },
+  handler: async (request, response, context) => {
+    const snapshot = await context.getHeapSnapshotProxy(
+      request.params.filePath,
+    );
+    const stats = await snapshot.getStatistics();
+
+    response.appendResponseLine(
+      `Statistics: ${JSON.stringify(stats, null, 2)}`,
+    );
+    response.appendResponseLine(
+      `Static Data: ${JSON.stringify(snapshot.staticData, null, 2)}`,
+    );
+
+    const filter =
+      new DevTools.HeapSnapshotModel.HeapSnapshotModel.NodeFilter();
+    const aggregates = await snapshot.aggregatesWithFilter(filter);
+
+    const {pageSize, pageIdx} = request.params;
+    response.setHeapSnapshot(aggregates, {pageSize, pageIdx});
+  },
+});

tests/tools/memory.test.ts

@@ -11,7 +11,10 @@ import {tmpdir} from 'node:os';
 import {join} from 'node:path';
 import {describe, it} from 'node:test';
 
-import {takeMemorySnapshot} from '../../src/tools/memory.js';
+import {
+  takeMemorySnapshot,
+  exploreMemorySnapshot,
+} from '../../src/tools/memory.js';
 import {withMcpContext} from '../utils.js';
 
 describe('memory', () => {
@@ -36,4 +39,38 @@ describe('memory', () => {
       });
     });
   });
+
+  describe('explore_memory_snapshot', () => {
+    it('with default options', async () => {
+      await withMcpContext(async (response, context) => {
+        const filePath = join(tmpdir(), 'test-explore.heapsnapshot');
+        try {
+          await takeMemorySnapshot.handler(
+            {params: {filePath}, page: context.getSelectedMcpPage()},
+            response,
+            context,
+          );
+
+          await exploreMemorySnapshot.handler(
+            {params: {filePath}},
+            response,
+            context,
+          );
+
+          assert.equal(
+            response.responseLines.at(0),
+            `Heap snapshot saved to ${filePath}`,
+          );
+          assert.ok(existsSync(filePath));
+
+          // Check if response contains Statistics or Static Data
+          const output = response.responseLines.join('\n');
+          assert.ok(output.includes('Statistics:'));
+          assert.ok(output.includes('Static Data:'));
+        } finally {
+          await rm(filePath, {force: true});
+        }
+      });
+    });
+  });
 });

tsconfig.json

@@ -33,6 +33,7 @@
     "node_modules/chrome-devtools-frontend/front_end/core/root",
     "node_modules/chrome-devtools-frontend/front_end/core/sdk",
     "node_modules/chrome-devtools-frontend/front_end/entrypoints/formatter_worker",
+    "node_modules/chrome-devtools-frontend/front_end/entrypoints/heap_snapshot_worker",
     "node_modules/chrome-devtools-frontend/front_end/foundation/foundation.ts",
     "node_modules/chrome-devtools-frontend/front_end/foundation/Universe.ts",
     "node_modules/chrome-devtools-frontend/front_end/generated",