Skip to content

Chrome DevTools for coding agents

feat: Add the get_heapsnapshot_edges MCP tool (#2180)

Dominik Inführ4f8eb7ad6bee
diff --git a/README.md b/README.md
index d92c80d7..b155b162 100644
--- a/README.md
+++ b/README.md
@@ -514,11 +514,12 @@ 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** (7 tools)
+- **Memory** (8 tools)
- [`take_heapsnapshot`](docs/tool-reference.md#take_heapsnapshot)
- [`close_heapsnapshot`](docs/tool-reference.md#close_heapsnapshot)
- [`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)
- [`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.md
index 5d7b6168..8d9c5902 100644
--- a/docs/tool-reference.md
+++ b/docs/tool-reference.md
@@ -39,11 +39,12 @@
- [`take_snapshot`](#take_snapshot)
- [`screencast_start`](#screencast_start)
- [`screencast_stop`](#screencast_stop)
-- **[Memory](#memory)** (7 tools)
+- **[Memory](#memory)** (8 tools)
- [`take_heapsnapshot`](#take_heapsnapshot)
- [`close_heapsnapshot`](#close_heapsnapshot)
- [`get_heapsnapshot_class_nodes`](#get_heapsnapshot_class_nodes)
- [`get_heapsnapshot_details`](#get_heapsnapshot_details)
+ - [`get_heapsnapshot_edges`](#get_heapsnapshot_edges)
- [`get_heapsnapshot_retainers`](#get_heapsnapshot_retainers)
- [`get_heapsnapshot_retaining_paths`](#get_heapsnapshot_retaining_paths)
- [`get_heapsnapshot_summary`](#get_heapsnapshot_summary)
@@ -492,6 +493,19 @@ in the DevTools Elements panel (if any).
---
+### `get_heapsnapshot_edges`
+
+**Description:** Loads a memory heapsnapshot and returns outgoing edges (references) for a specific node ID. (requires flag: --memoryDebugging=true)
+
+**Parameters:**
+
+- **filePath** (string) **(required)**: A path to a .heapsnapshot file to read.
+- **nodeId** (number) **(required)**: The node ID to get outgoing edges for.
+- **pageIdx** (number) _(optional)_: The page index for pagination.
+- **pageSize** (number) _(optional)_: The page size for pagination.
+
+---
+
### `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.ts
index 035496e9..69d616cc 100644
--- a/src/HeapSnapshotManager.ts
+++ b/src/HeapSnapshotManager.ts
@@ -148,6 +148,19 @@ export class HeapSnapshotManager {
);
}
+ async getEdges(
+ filePath: string,
+ nodeId: number,
+ ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange> {
+ const snapshot = await this.getSnapshot(filePath);
+ const nodeIndex = await snapshot.nodeIndexForId(nodeId);
+ if (nodeIndex === undefined) {
+ throw new Error(`Node with ID ${nodeId} not found`);
+ }
+ const provider = snapshot.createEdgesProvider(nodeIndex);
+ return await provider.serializeItemsRange(0, Infinity);
+ }
+
#getCachedSnapshot(filePath: string) {
const absolutePath = path.resolve(filePath);
const cached = this.#snapshots.get(absolutePath);
diff --git a/src/McpContext.ts b/src/McpContext.ts
index 756ad007..3965e4e3 100644
--- a/src/McpContext.ts
+++ b/src/McpContext.ts
@@ -968,4 +968,11 @@ export class McpContext implements Context {
throw new Error(`Unsupported protocol for: ${url}`);
}
}
+
+ async getHeapSnapshotEdges(
+ filePath: string,
+ nodeId: number,
+ ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange> {
+ return await this.#heapSnapshotManager.getEdges(filePath, nodeId);
+ }
}
diff --git a/src/bin/chrome-devtools-cli-options.ts b/src/bin/chrome-devtools-cli-options.ts
index af522d91..3a37e64b 100644
--- a/src/bin/chrome-devtools-cli-options.ts
+++ b/src/bin/chrome-devtools-cli-options.ts
@@ -360,6 +360,37 @@ export const commands: Commands = {
},
},
},
+ get_heapsnapshot_edges: {
+ description:
+ 'Loads a memory heapsnapshot and returns outgoing edges (references) for a specific node ID. (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 outgoing edges for.',
+ required: true,
+ },
+ 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,
+ },
+ },
+ },
get_heapsnapshot_retainers: {
description:
'Loads a memory heapsnapshot and returns retainers for a specific node ID. (requires flag: --memoryDebugging=true)',
diff --git a/src/telemetry/tool_call_metrics.json b/src/telemetry/tool_call_metrics.json
index 70f94497..24b1f7bc 100644
--- a/src/telemetry/tool_call_metrics.json
+++ b/src/telemetry/tool_call_metrics.json
@@ -776,5 +776,26 @@
"argType": "number"
}
]
+ },
+ {
+ "name": "get_heapsnapshot_edges",
+ "args": [
+ {
+ "name": "file_path_length",
+ "argType": "number"
+ },
+ {
+ "name": "node_id",
+ "argType": "number"
+ },
+ {
+ "name": "page_idx",
+ "argType": "number"
+ },
+ {
+ "name": "page_size",
+ "argType": "number"
+ }
+ ]
}
]
diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.ts
index 565743d0..24f58df1 100644
--- a/src/tools/ToolDefinition.ts
+++ b/src/tools/ToolDefinition.ts
@@ -260,6 +260,10 @@ export type Context = Readonly<{
maxNodes?: number,
maxSiblings?: number,
): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainingPaths>;
+ getHeapSnapshotEdges(
+ filePath: string,
+ nodeId: number,
+ ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange>;
}>;
/**
diff --git a/src/tools/memory.ts b/src/tools/memory.ts
index c4448b0c..a510b32b 100644
--- a/src/tools/memory.ts
+++ b/src/tools/memory.ts
@@ -223,3 +223,33 @@ export const getHeapSnapshotRetainingPaths = defineTool({
response.setHeapSnapshotRetainingPaths(retainingPaths);
},
});
+
+export const getHeapSnapshotEdges = defineTool({
+ name: 'get_heapsnapshot_edges',
+ description:
+ 'Loads a memory heapsnapshot and returns outgoing edges (references) for a specific node ID.',
+ 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 outgoing edges for.'),
+ 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 edges = await context.getHeapSnapshotEdges(
+ request.params.filePath,
+ request.params.nodeId,
+ );
+
+ response.setHeapSnapshotNodes(edges, {
+ 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 0d700ed0..cef739ce 100644
--- a/tests/tools/memory.test.js.snapshot
+++ b/tests/tools/memory.test.js.snapshot
@@ -175,6 +175,77 @@ id,name,count,selfSize,maxRetainedSize
108,HTMLBodyElement (internal cache) / https://example.com,1,0.0 kB,0.0 kB
`;
+exports[`memory > get_heapsnapshot_edges > with pagination 1`] = `
+## Heap Snapshot Data
+name,type,nodeId,nodeName
+constructor,property,25575,String
+anchor,property,29295,anchor
+Showing 1-2 of 56 (Page 1 of 28).
+Next page: 1
+`;
+
+exports[`memory > get_heapsnapshot_edges > with valid nodeId 1`] = `
+## Heap Snapshot Data
+name,type,nodeId,nodeName
+constructor,property,25575,String
+anchor,property,29295,anchor
+at,property,29297,at
+big,property,29299,big
+blink,property,29301,blink
+bold,property,29303,bold
+charAt,property,29305,charAt
+charCodeAt,property,29307,charCodeAt
+codePointAt,property,29309,codePointAt
+concat,property,29311,concat
+endsWith,property,29313,endsWith
+fontcolor,property,29315,fontcolor
+fontsize,property,29317,fontsize
+fixed,property,29319,fixed
+includes,property,29321,includes
+indexOf,property,29323,indexOf
+isWellFormed,property,29325,isWellFormed
+italics,property,29327,italics
+lastIndexOf,property,29329,lastIndexOf
+link,property,29331,link
+localeCompare,property,29333,localeCompare
+match,property,29335,match
+matchAll,property,29337,matchAll
+normalize,property,29339,normalize
+padEnd,property,29341,padEnd
+padStart,property,29343,padStart
+repeat,property,29345,repeat
+replace,property,29347,replace
+replaceAll,property,29349,replaceAll
+search,property,29351,search
+slice,property,29353,slice
+small,property,29355,small
+split,property,29357,split
+strike,property,29359,strike
+sub,property,29361,sub
+substr,property,29363,substr
+substring,property,29365,substring
+sup,property,29367,sup
+startsWith,property,29369,startsWith
+toString,property,29371,toString
+toWellFormed,property,29373,toWellFormed
+trim,property,29375,trim
+trimStart,property,29377,trimStart
+trimLeft,property,29377,trimStart
+trimEnd,property,29379,trimEnd
+trimRight,property,29379,trimEnd
+toLocaleLowerCase,property,29381,toLocaleLowerCase
+toLocaleUpperCase,property,29383,toLocaleUpperCase
+toLowerCase,property,29385,toLowerCase
+toUpperCase,property,29387,toUpperCase
+valueOf,property,29389,valueOf
+<symbol Symbol.iterator>,property,29391,[Symbol.iterator]
+__proto__,property,25329,{constructor, __defineGetter__, __defineSetter__, …, get __proto__, set __proto__, toLocaleString}
+properties,internal,29393,system / PropertyArray
+map,internal,25577,system / Map
+1,hidden,71,
+Showing 1-56 of 56 (Page 1 of 1).
+`;
+
exports[`memory > get_heapsnapshot_retainers > with valid nodeId 1`] = `
## Heap Snapshot Data
name,type,nodeId,nodeName
diff --git a/tests/tools/memory.test.ts b/tests/tools/memory.test.ts
index 4c46d95b..67fa36b3 100644
--- a/tests/tools/memory.test.ts
+++ b/tests/tools/memory.test.ts
@@ -19,6 +19,7 @@ import {
getHeapSnapshotRetainers,
closeHeapSnapshot,
getHeapSnapshotRetainingPaths,
+ getHeapSnapshotEdges,
} from '../../src/tools/memory.js';
import {withMcpContext} from '../utils.js';
@@ -280,4 +281,56 @@ describe('memory', () => {
});
});
});
+
+ describe('get_heapsnapshot_edges', () => {
+ it('with valid nodeId', async t => {
+ await withMcpContext(async (response, context) => {
+ const filePath = join(
+ process.cwd(),
+ 'tests/fixtures/example.heapsnapshot',
+ );
+
+ await getHeapSnapshotEdges.handler(
+ {params: {filePath, nodeId: 25341}},
+ response,
+ context,
+ );
+
+ const responseData = await response.handle(
+ getHeapSnapshotEdges.name,
+ context,
+ );
+ const output = responseData.content
+ .map(c => (c.type === 'text' ? c.text : ''))
+ .join('\n');
+
+ t.assert.snapshot(output);
+ });
+ });
+
+ it('with pagination', async t => {
+ await withMcpContext(async (response, context) => {
+ const filePath = join(
+ process.cwd(),
+ 'tests/fixtures/example.heapsnapshot',
+ );
+
+ await getHeapSnapshotEdges.handler(
+ {params: {filePath, nodeId: 25341, pageSize: 2}},
+ response,
+ context,
+ );
+
+ const responseData = await response.handle(
+ getHeapSnapshotEdges.name,
+ context,
+ );
+ const output = responseData.content
+ .map(c => (c.type === 'text' ? c.text : ''))
+ .join('\n');
+
+ t.assert.snapshot(output);
+ });
+ });
+ });
});