feat: Add get_heapsnapshot_dominators MCP tool (#2215)

Adding the get_heapsnapshot_dominators MCP tool to show the dominators
for a given node. In combination with get_heapsnapshot_retaining_paths
this should help understand what keeps an object reachable and thus
alive.

Co-authored-by: Dominik Inführ <dinfuehr@chromium.org>
Co-authored-by: Nicholas Roscino <nroscino@google.com>

Author: 3 people

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** (8 tools)
+- **Memory** (9 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_dominators`](docs/tool-reference.md#get_heapsnapshot_dominators)
   - [`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)

docs/tool-reference.md

@@ -39,11 +39,12 @@
   - [`take_snapshot`](#take_snapshot)
   - [`screencast_start`](#screencast_start)
   - [`screencast_stop`](#screencast_stop)
-- **[Memory](#memory)** (8 tools)
+- **[Memory](#memory)** (9 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_dominators`](#get_heapsnapshot_dominators)
   - [`get_heapsnapshot_edges`](#get_heapsnapshot_edges)
   - [`get_heapsnapshot_retainers`](#get_heapsnapshot_retainers)
   - [`get_heapsnapshot_retaining_paths`](#get_heapsnapshot_retaining_paths)
@@ -493,6 +494,17 @@ in the DevTools Elements panel (if any).
 
 ---
 
+### `get_heapsnapshot_dominators`
+
+**Description:** Loads a memory heapsnapshot and returns the dominator chain for a specific node ID. This helps to identify which objects are keeping the target node alive. (requires flag: --memoryDebugging=true)
+
+**Parameters:**
+
+- **filePath** (string) **(required)**: A path to a .heapsnapshot file to read.
+- **nodeId** (number) **(required)**: The node ID to get the dominator chain for.
+
+---
+
 ### `get_heapsnapshot_edges`
 
 **Description:** Loads a memory heapsnapshot and returns outgoing edges (references) for a specific node ID. (requires flag: --memoryDebugging=true)

package-lock.json

@@ -63,7 +63,7 @@
     "@types/yargs": "^17.0.33",
     "@typescript-eslint/eslint-plugin": "^8.43.0",
     "@typescript-eslint/parser": "^8.43.0",
-    "chrome-devtools-frontend": "1.0.1642845",
+    "chrome-devtools-frontend": "1.0.1645245",
     "core-js": "3.49.0",
     "debug": "4.4.3",
     "eslint": "^9.35.0",

package.json

@@ -148,6 +148,18 @@ export class HeapSnapshotManager {
     );
   }
 
+  async getDominatorsOf(
+    filePath: string,
+    nodeId: number,
+  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.DominatorChain> {
+    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.getDominatorsOf(nodeIndex);
+  }
+
   async getEdges(
     filePath: string,
     nodeId: number,

src/HeapSnapshotManager.ts

@@ -945,6 +945,13 @@ export class McpContext implements Context {
     );
   }
 
+  async getHeapSnapshotDominators(
+    filePath: string,
+    nodeId: number,
+  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.DominatorChain> {
+    return await this.#heapSnapshotManager.getDominatorsOf(filePath, nodeId);
+  }
+
   async loadResource(path: string): Promise<string> {
     const url = new URL(path);
 

src/McpContext.ts

@@ -223,6 +223,7 @@ export class McpResponse implements Response {
     staticData?: DevTools.HeapSnapshotModel.HeapSnapshotModel.StaticData | null;
     nodes?: DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange;
     retainingPaths?: DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainingPaths;
+    dominators?: DevTools.HeapSnapshotModel.HeapSnapshotModel.DominatorChain;
   };
   #networkRequestsOptions?: {
     include: boolean;
@@ -489,6 +490,16 @@ export class McpResponse implements Response {
     };
   }
 
+  setHeapSnapshotDominators(
+    dominators: DevTools.HeapSnapshotModel.HeapSnapshotModel.DominatorChain,
+  ) {
+    this.#heapSnapshotOptions = {
+      ...this.#heapSnapshotOptions,
+      include: true,
+      dominators,
+    };
+  }
+
   attachImage(value: ImageContentData): void {
     this.#images.push(value);
   }
@@ -819,6 +830,7 @@ export class McpResponse implements Response {
       heapSnapshotData?: object[];
       heapSnapshotNodes?: readonly object[];
       heapSnapshotRetainingPaths?: object;
+      heapSnapshotDominators?: readonly object[];
       extensionServiceWorkers?: object[];
       extensionPages?: object[];
       errorMessage?: string;
@@ -1133,6 +1145,16 @@ Call ${handleDialog.name} to handle it before continuing.`);
         structuredContent.heapSnapshotRetainingPaths =
           retainingPaths as unknown as object;
       }
+      const dominators = this.#heapSnapshotOptions.dominators;
+      if (dominators) {
+        response.push('### Dominator Chain');
+        if (dominators.length === 0) {
+          response.push('No dominators found.');
+        } else {
+          response.push(HeapSnapshotFormatter.formatDominators(dominators));
+        }
+        structuredContent.heapSnapshotDominators = dominators;
+      }
     }
 
     if (data.detailedNetworkRequest) {

src/McpResponse.ts

@@ -360,6 +360,25 @@ export const commands: Commands = {
       },
     },
   },
+  get_heapsnapshot_dominators: {
+    description:
+      'Loads a memory heapsnapshot and returns the dominator chain for a specific node ID. This helps to identify which objects are keeping the target node alive. (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 the dominator chain for.',
+        required: true,
+      },
+    },
+  },
   get_heapsnapshot_edges: {
     description:
       'Loads a memory heapsnapshot and returns outgoing edges (references) for a specific node ID. (requires flag: --memoryDebugging=true)',

src/bin/chrome-devtools-cli-options.ts

@@ -104,6 +104,19 @@ export class HeapSnapshotFormatter {
     return lines.join('\n');
   }
 
+  static formatDominators(
+    dominators: DevTools.HeapSnapshotModel.HeapSnapshotModel.DominatorChain,
+  ): string {
+    const lines: string[] = [];
+    lines.push('nodeId,nodeName,selfSize,retainedSize');
+    for (const node of dominators) {
+      lines.push(
+        `${node.nodeId},${node.nodeName},${DevTools.I18n.ByteUtilities.formatBytesToKb(node.selfSize)},${DevTools.I18n.ByteUtilities.formatBytesToKb(node.retainedSize)}`,
+      );
+    }
+    return lines.join('\n');
+  }
+
   #getSortedAggregates(): AggregatedInfoWithId[] {
     return Object.values(this.#aggregates).sort((a, b) => b.maxRet - a.maxRet);
   }

src/formatters/HeapSnapshotFormatter.ts

@@ -797,5 +797,18 @@
         "argType": "number"
       }
     ]
+  },
+  {
+    "name": "get_heapsnapshot_dominators",
+    "args": [
+      {
+        "name": "file_path_length",
+        "argType": "number"
+      },
+      {
+        "name": "node_id",
+        "argType": "number"
+      }
+    ]
   }
 ]