feat: Add query_heapsnapshot MCP tool (#2553)

`query_heapsnapshot_objects` allows the agent to filter objects by
properties like class name, self size, retained size, property name
and/or detachedness. The resulting list of objects can be sorted as
well.

Author: dinfuehr

README.md

@@ -557,7 +557,7 @@ 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** (12 tools)
+- **Memory** (13 tools)
   - [`take_heapsnapshot`](docs/tool-reference.md#take_heapsnapshot)
   - [`close_heapsnapshot`](docs/tool-reference.md#close_heapsnapshot)
   - [`compare_heapsnapshots`](docs/tool-reference.md#compare_heapsnapshots)
@@ -570,6 +570,7 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
   - [`get_heapsnapshot_retainers`](docs/tool-reference.md#get_heapsnapshot_retainers)
   - [`get_heapsnapshot_retaining_paths`](docs/tool-reference.md#get_heapsnapshot_retaining_paths)
   - [`get_heapsnapshot_summary`](docs/tool-reference.md#get_heapsnapshot_summary)
+  - [`query_heapsnapshot_objects`](docs/tool-reference.md#query_heapsnapshot_objects)
 - **Extensions** (5 tools)
   - [`install_extension`](docs/tool-reference.md#install_extension)
   - [`list_extensions`](docs/tool-reference.md#list_extensions)

docs/tool-reference.md

@@ -39,7 +39,7 @@
   - [`take_snapshot`](#take_snapshot)
   - [`screencast_start`](#screencast_start)
   - [`screencast_stop`](#screencast_stop)
-- **[Memory](#memory)** (12 tools)
+- **[Memory](#memory)** (13 tools)
   - [`take_heapsnapshot`](#take_heapsnapshot)
   - [`close_heapsnapshot`](#close_heapsnapshot)
   - [`compare_heapsnapshots`](#compare_heapsnapshots)
@@ -52,6 +52,7 @@
   - [`get_heapsnapshot_retainers`](#get_heapsnapshot_retainers)
   - [`get_heapsnapshot_retaining_paths`](#get_heapsnapshot_retaining_paths)
   - [`get_heapsnapshot_summary`](#get_heapsnapshot_summary)
+  - [`query_heapsnapshot_objects`](#query_heapsnapshot_objects)
 - **[Extensions](#extensions)** (5 tools)
   - [`install_extension`](#install_extension)
   - [`list_extensions`](#list_extensions)
@@ -600,6 +601,27 @@ in the DevTools Elements panel (if any).
 
 ---
 
+### `query_heapsnapshot_objects`
+
+**Description:** Loads a memory heapsnapshot and queries objects matching specific filters (className, propertyName, nodeType, minRetainedSize, maxRetainedSize, minSelfSize, isDetached, sortBy). (requires flag: --memoryDebugging=true)
+
+**Parameters:**
+
+- **filePath** (string) **(required)**: A path to a .heapsnapshot file to read.
+- **className** (string) _(optional)_: Optional regex or text matching object class name.
+- **isDetached** (boolean) _(optional)_: Whether to filter for detached DOM nodes.
+- **maxRetainedSize** (number) _(optional)_: Maximum retained size in bytes.
+- **maxSelfSize** (number) _(optional)_: Maximum self size in bytes.
+- **minRetainedSize** (number) _(optional)_: Minimum retained size in bytes.
+- **minSelfSize** (number) _(optional)_: Minimum self size in bytes.
+- **nodeType** (string) _(optional)_: Optional V8 node type filter (e.g. object, closure, string, array, code).
+- **pageIdx** (number) _(optional)_: The page index for pagination.
+- **pageSize** (number) _(optional)_: The page size for pagination.
+- **propertyName** (string) _(optional)_: Optional property name filter for outgoing reference edges.
+- **sortBy** (enum: "retainedSize", "selfSize", "id") _(optional)_: Sort order for results. Default is retainedSize.
+
+---
+
 ## Extensions
 
 > NOTE: The Extensions category is not active by default. Use the '--categoryExtensions' flag.

src/McpContext.ts

@@ -17,6 +17,7 @@ import type {
   HeapSnapshotDetailedClassDiff,
   DuplicateStringGroup,
   HeapEdgesQueryOptions,
+  HeapQueryOptions,
 } from './processors/HeapSnapshotManager.js';
 import {McpPage} from './McpPage.js';
 import {type UncaughtError} from './collectors/PageCollector.js';
@@ -750,6 +751,13 @@ export class McpContext implements Context {
     return await this.#heapSnapshotManager.getDuplicateStrings(filePath);
   }
 
+  async queryHeapSnapshotObjects(
+    filePath: string,
+    options: HeapQueryOptions,
+  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange> {
+    return await this.#heapSnapshotManager.queryObjects(filePath, options);
+  }
+
   async getHeapSnapshotStats(
     filePath: string,
   ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.Statistics> {

src/config/cli-options.ts

@@ -1100,6 +1100,88 @@ export const commands: Commands = {
       },
     },
   },
+  query_heapsnapshot_objects: {
+    description:
+      'Loads a memory heapsnapshot and queries objects matching specific filters (className, propertyName, nodeType, minRetainedSize, maxRetainedSize, minSelfSize, isDetached, sortBy). (requires flag: --memoryDebugging=true)',
+    category: 'Memory',
+    args: {
+      filePath: {
+        name: 'filePath',
+        type: 'string',
+        description: 'A path to a .heapsnapshot file to read.',
+        required: true,
+      },
+      className: {
+        name: 'className',
+        type: 'string',
+        description: 'Optional regex or text matching object class name.',
+        required: false,
+      },
+      propertyName: {
+        name: 'propertyName',
+        type: 'string',
+        description:
+          'Optional property name filter for outgoing reference edges.',
+        required: false,
+      },
+      nodeType: {
+        name: 'nodeType',
+        type: 'string',
+        description:
+          'Optional V8 node type filter (e.g. object, closure, string, array, code).',
+        required: false,
+      },
+      minRetainedSize: {
+        name: 'minRetainedSize',
+        type: 'number',
+        description: 'Minimum retained size in bytes.',
+        required: false,
+      },
+      maxRetainedSize: {
+        name: 'maxRetainedSize',
+        type: 'number',
+        description: 'Maximum retained size in bytes.',
+        required: false,
+      },
+      minSelfSize: {
+        name: 'minSelfSize',
+        type: 'number',
+        description: 'Minimum self size in bytes.',
+        required: false,
+      },
+      maxSelfSize: {
+        name: 'maxSelfSize',
+        type: 'number',
+        description: 'Maximum self size in bytes.',
+        required: false,
+      },
+      isDetached: {
+        name: 'isDetached',
+        type: 'boolean',
+        description: 'Whether to filter for detached DOM nodes.',
+        required: false,
+      },
+      sortBy: {
+        name: 'sortBy',
+        type: 'string',
+        description: 'Sort order for results. Default is retainedSize.',
+        required: false,
+        enum: ['retainedSize', 'selfSize', 'id'],
+      },
+      pageIdx: {
+        name: 'pageIdx',
+        type: 'number',
+        description: 'The page index for pagination.',
+        required: false,
+      },
+      pageSize: {
+        name: 'pageSize',
+        type: 'number',
+        description: 'The page size for pagination.',
+        required: false,
+      },
+    },
+  },
   reload_extension: {
     description:
       'Reloads an unpacked Chrome extension by its ID. (requires flag: --categoryExtensions=true)',

src/processors/HeapSnapshotManager.ts

@@ -48,7 +48,6 @@ export type HeapQueryOptions =
 
 export type HeapEdgesQueryOptions =
   DevTools.HeapSnapshotModel.HeapSnapshotModel.HeapEdgesQueryOptions;
-
 const VALID_EXTENSIONS: readonly string[] = ['.heapsnapshot', '.heaptimeline'];
 
 function hasValidHeapSnapshotExtension(filePath: string): boolean {
@@ -423,6 +422,15 @@ export class HeapSnapshotManager {
     return await snapshot.getDuplicateStrings();
   }
 
+  async queryObjects(
+    filePath: string,
+    options: HeapQueryOptions,
+  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange> {
+    const snapshot = await this.getSnapshot(filePath);
+    const provider = snapshot.queryObjects(options);
+    return await provider.serializeItemsRange(0, Infinity);
+  }
+
   hasSnapshots(): boolean {
     return this.#snapshots.size > 0;
   }

src/telemetry/tool_call_metrics.json

@@ -978,5 +978,58 @@
         "argType": "number"
       }
     ]
+  },
+  {
+    "name": "query_heapsnapshot_objects",
+    "args": [
+      {
+        "name": "file_path_length",
+        "argType": "number"
+      },
+      {
+        "name": "class_name_length",
+        "argType": "number"
+      },
+      {
+        "name": "property_name_length",
+        "argType": "number"
+      },
+      {
+        "name": "node_type_length",
+        "argType": "number"
+      },
+      {
+        "name": "min_retained_size",
+        "argType": "number"
+      },
+      {
+        "name": "max_retained_size",
+        "argType": "number"
+      },
+      {
+        "name": "min_self_size",
+        "argType": "number"
+      },
+      {
+        "name": "max_self_size",
+        "argType": "number"
+      },
+      {
+        "name": "is_detached",
+        "argType": "boolean"
+      },
+      {
+        "name": "sort_by",
+        "argType": "string"
+      },
+      {
+        "name": "page_idx",
+        "argType": "number"
+      },
+      {
+        "name": "page_size",
+        "argType": "number"
+      }
+    ]
   }
 ]

src/tools/ToolDefinition.ts

@@ -11,6 +11,7 @@ import type {
   HeapSnapshotDetailedClassDiff,
   DuplicateStringGroup,
   HeapEdgesQueryOptions,
+  HeapQueryOptions,
 } from '../processors/HeapSnapshotManager.js';
 import type {McpPage} from '../McpPage.js';
 import {zod} from '../third_party/index.js';
@@ -315,6 +316,10 @@ export type Context = Readonly<{
     currentFilePath: string,
     classIndex: number,
   ): Promise<HeapSnapshotDetailedClassDiff>;
+  queryHeapSnapshotObjects(
+    filePath: string,
+    options: HeapQueryOptions,
+  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange>;
 }>;
 
 /**

src/tools/memory.ts

@@ -465,3 +465,80 @@ export const getHeapSnapshotObjectDetails = defineTool({
     response.setHeapSnapshotObjectDetails(objectInfo);
   },
 });
+
+export const queryHeapSnapshotObjects = defineTool({
+  name: 'query_heapsnapshot_objects',
+  description:
+    'Loads a memory heapsnapshot and queries objects matching specific filters (className, propertyName, nodeType, minRetainedSize, maxRetainedSize, minSelfSize, isDetached, sortBy).',
+  annotations: {
+    category: ToolCategory.MEMORY,
+    readOnlyHint: true,
+    conditions: ['memoryDebugging'],
+  },
+  blockedByDialog: false,
+  verifyFilesSchema: {filePath: true},
+  schema: {
+    filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+    className: zod
+      .string()
+      .optional()
+      .describe('Optional regex or text matching object class name.'),
+    propertyName: zod
+      .string()
+      .optional()
+      .describe('Optional property name filter for outgoing reference edges.'),
+    nodeType: zod
+      .string()
+      .optional()
+      .describe(
+        'Optional V8 node type filter (e.g. object, closure, string, array, code).',
+      ),
+    minRetainedSize: zod
+      .number()
+      .optional()
+      .describe('Minimum retained size in bytes.'),
+    maxRetainedSize: zod
+      .number()
+      .optional()
+      .describe('Maximum retained size in bytes.'),
+    minSelfSize: zod
+      .number()
+      .optional()
+      .describe('Minimum self size in bytes.'),
+    maxSelfSize: zod
+      .number()
+      .optional()
+      .describe('Maximum self size in bytes.'),
+    isDetached: zod
+      .boolean()
+      .optional()
+      .describe('Whether to filter for detached DOM nodes.'),
+    sortBy: zod
+      .enum(['retainedSize', 'selfSize', 'id'])
+      .optional()
+      .describe('Sort order for results. Default is retainedSize.'),
+    pageIdx: zod.number().optional().describe('The page index for pagination.'),
+    pageSize: zod.number().optional().describe('The page size for pagination.'),
+  },
+  handler: async (request, response, context) => {
+    const range = await context.queryHeapSnapshotObjects(
+      request.params.filePath,
+      {
+        className: request.params.className,
+        propertyName: request.params.propertyName,
+        nodeType: request.params.nodeType,
+        minRetainedSize: request.params.minRetainedSize,
+        maxRetainedSize: request.params.maxRetainedSize,
+        minSelfSize: request.params.minSelfSize,
+        maxSelfSize: request.params.maxSelfSize,
+        isDetached: request.params.isDetached,
+        sortBy: request.params.sortBy,
+      },
+    );
+
+    response.setHeapSnapshotNodes(range, {
+      pageIdx: request.params.pageIdx,
+      pageSize: request.params.pageSize,
+    });
+  },
+});