Skip to content

Chrome DevTools for coding agents

feat: Add query_heapsnapshot MCP tool (#2553)

Dominik Inführfadbf41d96db
diff --git a/README.md b/README.md
index 3ad97b12..c0ae2f34 100644
--- a/README.md
+++ b/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)
diff --git a/docs/tool-reference.md b/docs/tool-reference.md
index 3ccc6f83..ff32db7c 100644
--- a/docs/tool-reference.md
+++ b/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.
diff --git a/src/McpContext.ts b/src/McpContext.ts
index 7be2bbaa..e667a21b 100644
--- a/src/McpContext.ts
+++ b/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> {
diff --git a/src/config/cli-options.ts b/src/config/cli-options.ts
index 39d167d7..58ba94e9 100644
--- a/src/config/cli-options.ts
+++ b/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)',
diff --git a/src/processors/HeapSnapshotManager.ts b/src/processors/HeapSnapshotManager.ts
index ebfa40de..170d66c4 100644
--- a/src/processors/HeapSnapshotManager.ts
+++ b/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;
}
diff --git a/src/telemetry/tool_call_metrics.json b/src/telemetry/tool_call_metrics.json
index 3fe3bb49..4f84c149 100644
--- a/src/telemetry/tool_call_metrics.json
+++ b/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"
+ }
+ ]
}
]
diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.ts
index ed9b1fbd..b8a80626 100644
--- a/src/tools/ToolDefinition.ts
+++ b/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>;
}>;
/**
diff --git a/src/tools/memory.ts b/src/tools/memory.ts
index 8747b1c6..c6f34d1a 100644
--- a/src/tools/memory.ts
+++ b/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,
+ });
+ },
+});
diff --git a/tests/tools/memory.test.js.snapshot b/tests/tools/memory.test.js.snapshot
index 34169e01..931720af 100644
--- a/tests/tools/memory.test.js.snapshot
+++ b/tests/tools/memory.test.js.snapshot
@@ -449,3 +449,66 @@ Retained by context size: 3.5 kB (148 objects)
Not retained by context size: 798 kB (11792 objects)
Total size: 802 kB
`;
+
+exports[`memory > query_heapsnapshot_objects > with className filter 1`] = `
+## Heap Snapshot Data
+nodeId,nodeName,type,distance,selfSize,retainedSize
+27635,Window (global*) / https://example.com,object,2,40.5 kB,51.0 kB
+30887,Window (global*) / https://example.com,object,2,40.5 kB,50.9 kB
+30967,Window (prototype) / https://example.com,object,4,26.6 kB,26.7 kB
+42085,Window (prototype) / https://example.com,object,4,26.6 kB,26.7 kB
+32995,Window (internal cache) / https://example.com,object,3,0.2 kB,10.1 kB
+41995,Window (internal cache) / https://example.com,object,3,0.2 kB,10.1 kB
+16321,Window / https://example.com,native,2,0.9 kB,1.9 kB
+16329,Window,closure,3,0.1 kB,0.4 kB
+16341,Window,closure,3,0.1 kB,0.4 kB
+30975,Window (prototype) / https://example.com,object,3,0.0 kB,0.2 kB
+Showing 1-10 of 34 (Page 1 of 4).
+Next page: 1
+`;
+
+exports[`memory > query_heapsnapshot_objects > with default options 1`] = `
+## Heap Snapshot Data
+nodeId,nodeName,type,distance,selfSize,retainedSize
+1,,synthetic,100000000,0.0 kB,802 kB
+7249,system / NativeContext / https://example.com,hidden,1,1.2 kB,350 kB
+7199,system / NativeContext,hidden,1,1.2 kB,84.4 kB
+7307,system / NativeContext,hidden,1,1.2 kB,84.4 kB
+7195,system / NativeContext / https://example.com,hidden,1,1.2 kB,60.1 kB
+27635,Window (global*) / https://example.com,object,2,40.5 kB,51.0 kB
+30887,Window (global*) / https://example.com,object,2,40.5 kB,50.9 kB
+3,(GC roots),synthetic,100000001,0.0 kB,45.6 kB
+49547,,array,2,4.1 kB,41.0 kB
+36241,,array,2,4.1 kB,41.0 kB
+Showing 1-10 of 27466 (Page 1 of 2747).
+Next page: 1
+`;
+
+exports[`memory > query_heapsnapshot_objects > with minRetainedSize filter 1`] = `
+## Heap Snapshot Data
+nodeId,nodeName,type,distance,selfSize,retainedSize
+1,,synthetic,100000000,0.0 kB,802 kB
+7249,system / NativeContext / https://example.com,hidden,1,1.2 kB,350 kB
+7199,system / NativeContext,hidden,1,1.2 kB,84.4 kB
+7307,system / NativeContext,hidden,1,1.2 kB,84.4 kB
+7195,system / NativeContext / https://example.com,hidden,1,1.2 kB,60.1 kB
+27635,Window (global*) / https://example.com,object,2,40.5 kB,51.0 kB
+30887,Window (global*) / https://example.com,object,2,40.5 kB,50.9 kB
+3,(GC roots),synthetic,100000001,0.0 kB,45.6 kB
+49547,,array,2,4.1 kB,41.0 kB
+36241,,array,2,4.1 kB,41.0 kB
+Showing 1-10 of 148 (Page 1 of 15).
+Next page: 1
+`;
+
+exports[`memory > query_heapsnapshot_objects > with sortBy selfSize and pagination 1`] = `
+## Heap Snapshot Data
+nodeId,nodeName,type,distance,selfSize,retainedSize
+1,,synthetic,100000000,0.0 kB,802 kB
+7249,system / NativeContext / https://example.com,hidden,1,1.2 kB,350 kB
+7199,system / NativeContext,hidden,1,1.2 kB,84.4 kB
+7307,system / NativeContext,hidden,1,1.2 kB,84.4 kB
+7195,system / NativeContext / https://example.com,hidden,1,1.2 kB,60.1 kB
+Showing 1-5 of 27466 (Page 1 of 5494).
+Next page: 1
+`;
diff --git a/tests/tools/memory.test.ts b/tests/tools/memory.test.ts
index c9fdd2e1..4e40b582 100644
--- a/tests/tools/memory.test.ts
+++ b/tests/tools/memory.test.ts
@@ -24,6 +24,7 @@ import {
compareHeapSnapshots,
getHeapSnapshotDuplicateStrings,
getHeapSnapshotObjectDetails,
+ queryHeapSnapshotObjects,
} from '../../src/tools/memory.js';
import {stableIdSymbol} from '../../src/utils/id.js';
import {resolveCanonicalPath} from '../../src/utils/files.js';
@@ -650,4 +651,94 @@ describe('memory', () => {
});
});
});
+
+ describe('query_heapsnapshot_objects', () => {
+ it('with default options', async t => {
+ await withMcpContext(async (response, context) => {
+ const filePath = join(
+ process.cwd(),
+ 'tests/fixtures/example.heapsnapshot',
+ );
+
+ await queryHeapSnapshotObjects.handler(
+ {params: {filePath, pageSize: 10}},
+ response,
+ context,
+ );
+
+ const responseData = await response.handle(context);
+ const output = responseData.content
+ .map(c => (c.type === 'text' ? c.text : ''))
+ .join('\n');
+
+ t.assert.snapshot(output);
+ });
+ });
+
+ it('with className filter', async t => {
+ await withMcpContext(async (response, context) => {
+ const filePath = join(
+ process.cwd(),
+ 'tests/fixtures/example.heapsnapshot',
+ );
+
+ await queryHeapSnapshotObjects.handler(
+ {params: {filePath, className: 'Window', pageSize: 10}},
+ response,
+ context,
+ );
+
+ const responseData = await response.handle(context);
+ const output = responseData.content
+ .map(c => (c.type === 'text' ? c.text : ''))
+ .join('\n');
+
+ t.assert.snapshot(output);
+ });
+ });
+
+ it('with minRetainedSize filter', async t => {
+ await withMcpContext(async (response, context) => {
+ const filePath = join(
+ process.cwd(),
+ 'tests/fixtures/example.heapsnapshot',
+ );
+
+ await queryHeapSnapshotObjects.handler(
+ {params: {filePath, minRetainedSize: 1000, pageSize: 10}},
+ response,
+ context,
+ );
+
+ const responseData = await response.handle(context);
+ const output = responseData.content
+ .map(c => (c.type === 'text' ? c.text : ''))
+ .join('\n');
+
+ t.assert.snapshot(output);
+ });
+ });
+
+ it('with sortBy selfSize and pagination', async t => {
+ await withMcpContext(async (response, context) => {
+ const filePath = join(
+ process.cwd(),
+ 'tests/fixtures/example.heapsnapshot',
+ );
+
+ await queryHeapSnapshotObjects.handler(
+ {params: {filePath, sortBy: 'selfSize', pageSize: 5, pageIdx: 0}},
+ response,
+ context,
+ );
+
+ const responseData = await response.handle(context);
+ const output = responseData.content
+ .map(c => (c.type === 'text' ? c.text : ''))
+ .join('\n');
+
+ t.assert.snapshot(output);
+ });
+ });
+ });
});