Chrome DevTools for coding agents
feat: Add get_heapsnapshot_object_details MCP tool (#2374)
Dominik Inführ8432cb97a2a1
diff --git a/README.md b/README.mdindex a8b18a85..3bb64ae6 100644--- a/README.md+++ b/README.md@@ -524,7 +524,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** (11 tools)+- **Memory** (12 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)@@ -533,6 +533,7 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles- [`get_heapsnapshot_dominators`](docs/tool-reference.md#get_heapsnapshot_dominators)- [`get_heapsnapshot_duplicate_strings`](docs/tool-reference.md#get_heapsnapshot_duplicate_strings)- [`get_heapsnapshot_edges`](docs/tool-reference.md#get_heapsnapshot_edges)+ - [`get_heapsnapshot_object_details`](docs/tool-reference.md#get_heapsnapshot_object_details)- [`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)diff --git a/docs/tool-reference.md b/docs/tool-reference.mdindex ba875495..f2a1c983 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)** (11 tools)+- **[Memory](#memory)** (12 tools)- [`take_heapsnapshot`](#take_heapsnapshot)- [`close_heapsnapshot`](#close_heapsnapshot)- [`compare_heapsnapshots`](#compare_heapsnapshots)@@ -48,6 +48,7 @@- [`get_heapsnapshot_dominators`](#get_heapsnapshot_dominators)- [`get_heapsnapshot_duplicate_strings`](#get_heapsnapshot_duplicate_strings)- [`get_heapsnapshot_edges`](#get_heapsnapshot_edges)+ - [`get_heapsnapshot_object_details`](#get_heapsnapshot_object_details)- [`get_heapsnapshot_retainers`](#get_heapsnapshot_retainers)- [`get_heapsnapshot_retaining_paths`](#get_heapsnapshot_retaining_paths)- [`get_heapsnapshot_summary`](#get_heapsnapshot_summary)@@ -539,6 +540,17 @@ in the DevTools Elements panel (if any).---+### `get_heapsnapshot_object_details`++**Description:** Loads a memory heapsnapshot and returns detailed information about a specific object by its node ID, including size, type, distance, and DOM detachedness. (requires flag: --memoryDebugging=true)++**Parameters:**++- **filePath** (string) **(required)**: A path to a .heapsnapshot file to read.+- **nodeId** (number) **(required)**: The node ID to get object details for.++---+### `get_heapsnapshot_retainers`**Description:** Loads a memory heapsnapshot and returns retainers for a specific node ID. (requires flag: --memoryDebugging=true)diff --git a/src/HeapSnapshotManager.ts b/src/HeapSnapshotManager.tsindex 5d7a0e1f..9ef3e499 100644--- a/src/HeapSnapshotManager.ts+++ b/src/HeapSnapshotManager.ts@@ -174,6 +174,18 @@ export class HeapSnapshotManager {return await provider.serializeItemsRange(0, Infinity);}+ async getObjectInfo(+ filePath: string,+ nodeId: number,+ ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ObjectInfo> {+ const snapshot = await this.getSnapshot(filePath);+ const nodeIndex = await snapshot.nodeIndexForId(nodeId);+ if (nodeIndex === undefined) {+ throw new Error(`Node with ID ${nodeId} not found`);+ }+ return await snapshot.getObjectInfo(nodeIndex);+ }+async getRetainingPaths(filePath: string,nodeId: number,diff --git a/src/McpContext.ts b/src/McpContext.tsindex 00331a9c..b5834cbc 100644--- a/src/McpContext.ts+++ b/src/McpContext.ts@@ -693,6 +693,13 @@ export class McpContext implements Context {return await this.#heapSnapshotManager.getRetainers(filePath, nodeId);}+ async getHeapSnapshotObjectDetails(+ filePath: string,+ nodeId: number,+ ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ObjectInfo> {+ return await this.#heapSnapshotManager.getObjectInfo(filePath, nodeId);+ }+async closeHeapSnapshot(filePath: string): Promise<boolean> {return this.#heapSnapshotManager.dispose(filePath);}diff --git a/src/McpResponse.ts b/src/McpResponse.tsindex 30af2521..549c3157 100644--- a/src/McpResponse.ts+++ b/src/McpResponse.ts@@ -90,6 +90,7 @@ export class McpResponse implements Response {classDiffs?: HeapSnapshotClassDiff[];detailedClassDiff?: HeapSnapshotDetailedClassDiff;duplicateStrings?: DuplicateStringGroup[];+ objectInfo?: DevTools.HeapSnapshotModel.HeapSnapshotModel.ObjectInfo;};#networkRequestsOptions?: {include: boolean;@@ -404,6 +405,16 @@ export class McpResponse implements Response {};}+ setHeapSnapshotObjectDetails(+ objectInfo: DevTools.HeapSnapshotModel.HeapSnapshotModel.ObjectInfo,+ ) {+ this.#heapSnapshotOptions = {+ ...this.#heapSnapshotOptions,+ include: true,+ objectInfo,+ };+ }+attachImage(value: ImageContentData): void {this.#images.push(value);}@@ -746,6 +757,7 @@ export class McpResponse implements Response {heapSnapshotClassDiffs?: HeapSnapshotClassDiff[];heapSnapshotDetailedClassDiff?: HeapSnapshotDetailedClassDiff;heapSnapshotDuplicateStrings?: readonly DuplicateStringGroup[];+ heapSnapshotObjectDetails?: DevTools.HeapSnapshotModel.HeapSnapshotModel.ObjectInfo;extensionServiceWorkers?: object[];extensionPages?: object[];errorMessage?: string;@@ -1177,6 +1189,16 @@ Call ${handleDialog.name} to handle it before continuing.`);structuredContent.heapSnapshotDuplicateStrings = paginationData.items;}+ const objectInfo = this.#heapSnapshotOptions.objectInfo;+ if (objectInfo) {+ response.push('### Object Details');+ response.push(+ compactEncode+ ? compactEncode(objectInfo)+ : HeapSnapshotFormatter.formatObjectInfo(objectInfo),+ );+ structuredContent.heapSnapshotObjectDetails = objectInfo;+ }}if (data.detailedNetworkRequest) {diff --git a/src/bin/chrome-devtools-cli-options.ts b/src/bin/chrome-devtools-cli-options.tsindex fb37c2e0..d82cb1e2 100644--- a/src/bin/chrome-devtools-cli-options.ts+++ b/src/bin/chrome-devtools-cli-options.ts@@ -487,6 +487,25 @@ export const commands: Commands = {},},},+ get_heapsnapshot_object_details: {+ description:+ 'Loads a memory heapsnapshot and returns detailed information about a specific object by its node ID, including size, type, distance, and DOM detachedness. (requires flag: --memoryDebugging=true)',+ category: 'Memory',+ args: {+ filePath: {+ name: 'filePath',+ type: 'string',+ description: 'A path to a .heapsnapshot file to read.',+ required: true,+ },+ nodeId: {+ name: 'nodeId',+ type: 'number',+ description: 'The node ID to get object details for.',+ required: true,+ },+ },+ },get_heapsnapshot_retainers: {description:'Loads a memory heapsnapshot and returns retainers for a specific node ID. (requires flag: --memoryDebugging=true)',diff --git a/src/formatters/HeapSnapshotFormatter.ts b/src/formatters/HeapSnapshotFormatter.tsindex 3ec686d4..f85ef58d 100644--- a/src/formatters/HeapSnapshotFormatter.ts+++ b/src/formatters/HeapSnapshotFormatter.ts@@ -243,6 +243,37 @@ export class HeapSnapshotFormatter {return lines.join('\n');}++ static formatObjectInfo(+ info: DevTools.HeapSnapshotModel.HeapSnapshotModel.ObjectInfo,+ ): string {+ const lines = [+ `id: @${info.id}`,+ `name: ${info.name}`,+ `type: ${info.type}`,+ `detachedness: ${formatDOMLinkState(info.detachedness)}`,+ `selfSize: ${DevTools.I18n.ByteUtilities.formatBytesToKb(info.selfSize)}`,+ `retainedSize: ${DevTools.I18n.ByteUtilities.formatBytesToKb(info.retainedSize)}`,+ `distance: ${info.distance}`,+ `edgeCount: ${info.edgeCount}`,+ `retainerCount: ${info.retainerCount}`,+ ];+ return lines.join('\n');+ }+}++function formatDOMLinkState(+ state: DevTools.HeapSnapshotModel.HeapSnapshotModel.DOMLinkState,+): string {+ switch (state) {+ case DevTools.HeapSnapshotModel.HeapSnapshotModel.DOMLinkState.ATTACHED:+ return 'attached';+ case DevTools.HeapSnapshotModel.HeapSnapshotModel.DOMLinkState.DETACHED:+ return 'detached';+ case DevTools.HeapSnapshotModel.HeapSnapshotModel.DOMLinkState.UNKNOWN:+ default:+ return 'unknown';+ }}function formatSignedCount(n: number): string {diff --git a/src/telemetry/tool_call_metrics.json b/src/telemetry/tool_call_metrics.jsonindex 6b19f895..a41da140 100644--- a/src/telemetry/tool_call_metrics.json+++ b/src/telemetry/tool_call_metrics.json@@ -884,5 +884,18 @@"argType": "number"}]+ },+ {+ "name": "get_heapsnapshot_object_details",+ "args": [+ {+ "name": "file_path_length",+ "argType": "number"+ },+ {+ "name": "node_id",+ "argType": "number"+ }+ ]}]diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.tsindex ed22237b..841accde 100644--- a/src/tools/ToolDefinition.ts+++ b/src/tools/ToolDefinition.ts@@ -134,6 +134,9 @@ export interface Response {setHeapSnapshotDetailedClassDiff(detailedClassDiff: HeapSnapshotDetailedClassDiff,): void;+ setHeapSnapshotObjectDetails(+ objectInfo: DevTools.HeapSnapshotModel.HeapSnapshotModel.ObjectInfo,+ ): void;setIncludePages(value: boolean): void;setIncludeNetworkRequests(value: boolean,@@ -256,6 +259,10 @@ export type Context = Readonly<{filePath: string,nodeId: number,): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange>;+ getHeapSnapshotObjectDetails(+ filePath: string,+ nodeId: number,+ ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ObjectInfo>;closeHeapSnapshot(filePath: string): Promise<boolean>;getHeapSnapshotRetainingPaths(filePath: string,diff --git a/src/tools/memory.ts b/src/tools/memory.tsindex 8eff06b8..2f1267db 100644--- a/src/tools/memory.ts+++ b/src/tools/memory.ts@@ -372,3 +372,28 @@ export const getHeapSnapshotDuplicateStrings = defineTool({});},});++export const getHeapSnapshotObjectDetails = defineTool({+ name: 'get_heapsnapshot_object_details',+ description:+ 'Loads a memory heapsnapshot and returns detailed information about a specific object by its node ID, including size, type, distance, and DOM detachedness.',+ annotations: {+ category: ToolCategory.MEMORY,+ readOnlyHint: true,+ conditions: ['memoryDebugging'],+ },+ blockedByDialog: false,+ verifyFilesSchema: ['filePath'],+ schema: {+ filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),+ nodeId: zod.number().describe('The node ID to get object details for.'),+ },+ handler: async (request, response, context) => {+ const objectInfo = await context.getHeapSnapshotObjectDetails(+ request.params.filePath,+ request.params.nodeId,+ );++ response.setHeapSnapshotObjectDetails(objectInfo);+ },+});diff --git a/tests/tools/memory.test.js.snapshot b/tests/tools/memory.test.js.snapshotindex eb82c040..03b54643 100644--- a/tests/tools/memory.test.js.snapshot+++ b/tests/tools/memory.test.js.snapshot@@ -332,6 +332,20 @@ map,internal,25577,system / MapShowing 1-56 of 56 (Page 1 of 1).`;+exports[`memory > get_heapsnapshot_object_details > with valid nodeId 1`] = `+## Heap Snapshot Data+### Object Details+id: @25341+name: String+type: object+detachedness: unknown+selfSize: 0.2 kB+retainedSize: 1.6 kB+distance: 2+edgeCount: 56+retainerCount: 3+`;+exports[`memory > get_heapsnapshot_retainers > with valid nodeId 1`] = `## Heap Snapshot Dataname,type,nodeId,nodeNamediff --git a/tests/tools/memory.test.ts b/tests/tools/memory.test.tsindex 639f5127..300b7710 100644--- a/tests/tools/memory.test.ts+++ b/tests/tools/memory.test.ts@@ -23,6 +23,7 @@ import {getHeapSnapshotDominators,compareHeapSnapshots,getHeapSnapshotDuplicateStrings,+ getHeapSnapshotObjectDetails,} from '../../src/tools/memory.js';import {stableIdSymbol} from '../../src/utils/id.js';import {withMcpContext} from '../utils.js';@@ -246,6 +247,33 @@ describe('memory', () => {});});+ describe('get_heapsnapshot_object_details', () => {+ it('with valid nodeId', async t => {+ await withMcpContext(async (response, context) => {+ const filePath = join(+ process.cwd(),+ 'tests/fixtures/example.heapsnapshot',+ );++ await getHeapSnapshotObjectDetails.handler(+ {params: {filePath, nodeId: 25341}},+ response,+ context,+ );++ const responseData = await response.handle(+ getHeapSnapshotObjectDetails.name,+ context,+ );+ const output = responseData.content+ .map(c => (c.type === 'text' ? c.text : ''))+ .join('\n');++ t.assert.snapshot(output);+ });+ });+ });+describe('close_heapsnapshot', () => {it('with default options', async () => {await withMcpContext(async (response, context) => {