@memlab/mcp-server 2.0.0

package/README.md

@@ -0,0 +1,285 @@
+# @memlab/mcp-server
+
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that wraps [MemLab](https://facebook.github.io/memlab/)'s heap analysis APIs, giving AI coding assistants (Claude Code, Cursor, etc.) interactive tools to explore JavaScript heap snapshots, find memory leaks, and identify optimization opportunities.
+
+## Quick Start
+
+### Option 1: npx (no install)
+
+Add to your Claude Code MCP config (`~/.claude.json` or `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "memlab": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@memlab/mcp-server"]
+    }
+  }
+}
+```
+
+### Option 2: Global install
+
+```bash
+npm install -g @memlab/mcp-server
+```
+
+Then configure:
+
+```json
+{
+  "mcpServers": {
+    "memlab": {
+      "type": "stdio",
+      "command": "memlab-mcp"
+    }
+  }
+}
+```
+
+### Option 3: From source
+
+```bash
+git clone https://github.com/facebook/memlab.git
+cd memlab
+npm install
+npm run build
+```
+
+Then configure:
+
+```json
+{
+  "mcpServers": {
+    "memlab": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/to/memlab/packages/mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+## How It Works
+
+The server holds a loaded `IHeapSnapshot` in memory across tool calls (loading is expensive for large heaps). Only one snapshot can be loaded at a time. All tools are read-only — they analyze the heap but never modify it.
+
+## Getting a Heap Snapshot
+
+### Chrome DevTools
+
+1. Open DevTools (F12) > Memory tab
+2. Select "Heap snapshot" and click "Take snapshot"
+3. Right-click the snapshot in the left panel > "Save..."
+4. Save the `.heapsnapshot` file
+
+### Node.js
+
+```js
+const v8 = require('v8');
+const snapshot = v8.writeHeapSnapshot();
+console.log(`Heap snapshot written to ${snapshot}`);
+```
+
+## Tools Reference
+
+### `memlab_load_snapshot`
+
+Load and parse a `.heapsnapshot` file. Builds indexes, computes the dominator tree, and calculates retained sizes.
+
+```
+Input:  { file_path: "/path/to/snapshot.heapsnapshot" }
+Output: { status, file_path, node_count, edge_count, total_size }
+```
+
+### `memlab_snapshot_summary`
+
+Overview stats: total nodes/edges, total size, breakdown by node type with dominator-aware aggregate retained sizes.
+
+### `memlab_largest_objects`
+
+Top N objects by retained size, filtering out internal/meta nodes.
+
+```
+Input:  { limit?: 20 }
+```
+
+### `memlab_get_node`
+
+Look up a single node by numeric ID with full details (size, type, detachment status, dominator, location, string value).
+
+```
+Input:  { node_id: 12345 }
+```
+
+### `memlab_find_nodes_by_class`
+
+Find all objects with a given constructor/class name, sorted by retained size.
+
+```
+Input:  { class_name: "FiberNode", limit?: 20 }
+```
+
+### `memlab_get_references`
+
+Outgoing edges from a node (what it points to), sorted by target retained size.
+
+```
+Input:  { node_id: 12345, limit?: 30 }
+```
+
+### `memlab_get_referrers`
+
+Incoming edges to a node (what points to it), sorted by source retained size.
+
+```
+Input:  { node_id: 12345, limit?: 30 }
+```
+
+### `memlab_retainer_trace`
+
+Shortest path from a GC root to a node. Shows why the object is retained in memory.
+
+```
+Input:  { node_id: 12345 }
+```
+
+### `memlab_detached_dom`
+
+Find detached DOM elements still retained in memory (common memory leak source). Supports count-only and ids-only modes for large result sets.
+
+```
+Input:  { output_mode?: "full"|"count"|"ids", limit?: 20 }
+```
+
+### `memlab_duplicated_strings`
+
+Find duplicated string instances ranked by total retained size.
+
+```
+Input:  { limit?: 15 }
+```
+
+### `memlab_stale_collections`
+
+Find Map/Set/Array collections holding detached DOM or unmounted Fiber nodes.
+
+```
+Input:  { limit?: 15 }
+```
+
+### `memlab_global_variables`
+
+Non-built-in global variables on the Window object, sorted by retained size.
+
+```
+Input:  { limit?: 20 }
+```
+
+### `memlab_search_nodes`
+
+General-purpose search combining filters: name pattern (regex), node type, size thresholds, detachment status.
+
+```
+Input:  { name_pattern?: "Regex", type?: "object", min_retained_size?: 1000000, limit?: 20 }
+```
+
+### `memlab_get_property`
+
+Look up a specific property of a node by name and return the target node with full details.
+
+```
+Input:  { node_id: 12345, property_name: "stateNode" }
+```
+
+### `memlab_object_shape`
+
+Show all named properties of an object with target types and sizes.
+
+```
+Input:  { node_id: 12345, include_internal?: false, limit?: 50 }
+```
+
+### `memlab_class_histogram`
+
+Instance count and total retained size per constructor name, sorted by aggregate retained size (dominator-aware). The Chrome DevTools "Summary" view equivalent.
+
+```
+Input:  { limit?: 30, min_count?: 1, node_type?: "object" }
+```
+
+### `memlab_dominator_subtree`
+
+Show objects dominated by a given node — what would be freed if it were garbage collected.
+
+```
+Input:  { node_id: 12345, limit?: 20 }
+```
+
+### `memlab_closure_inspection`
+
+Inspect a closure's captured variables, source location, and scope context. Critical for diagnosing closure-based memory leaks.
+
+```
+Input:  { node_id: 12345 }
+```
+
+### `memlab_find_by_property`
+
+Find all objects that have a specific property name. Useful for React internals (`__reactFiber$`), custom markers, or framework-specific patterns.
+
+```
+Input:  { property_name: "__reactFiber$", limit?: 20 }
+```
+
+### `memlab_aggregate`
+
+Aggregate heap nodes by type, name, or name prefix. Returns grouped statistics with dominator-aware retained sizes (no double-counting).
+
+```
+Input:  { group_by: "type"|"name"|"name_prefix", name_pattern?: "...", limit?: 30 }
+```
+
+### `memlab_reports`
+
+Run curated memory analysis reports. Use `"list"` to see available reports, pick one by name, or use `"full_analysis"` to run all reports for comprehensive triage.
+
+```
+Input:  { report: "list"|"full_analysis"|"detached_dom"|"duplicated_strings"|..., limit?: 10 }
+```
+
+### `memlab_eval`
+
+Execute arbitrary JavaScript against the loaded heap snapshot in a sandboxed VM. Has access to `snapshot`, `utils`, and `helpers` but no filesystem/network access.
+
+```
+Input:  { code: "...", timeout_ms?: 30000 }
+```
+
+### `memlab_for_each`
+
+Structured map/filter/reduce over all heap nodes with code predicates.
+
+```
+Input:  { filter_code: "node.type === 'closure'", map_code?: "...", reduce_code?: "...", limit?: 100 }
+```
+
+## Example Workflow
+
+A typical memory investigation:
+
+1. **Load the snapshot**: "Load the heap snapshot at /tmp/my-app.heapsnapshot"
+2. **Get an overview**: "Show me a summary of the heap"
+3. **Find the biggest objects**: "What are the largest objects by retained size?"
+4. **Investigate a specific object**: "Show me the retainer trace for node 48231"
+5. **Check for common leak patterns**:
+   - "Are there any detached DOM nodes?"
+   - "Show me duplicated strings"
+   - "Are any collections holding stale objects?"
+6. **Drill into references**: "What does node 48231 reference?"
+
+## License
+
+MIT

package/bin/memlab-mcp.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../dist/index.js';

package/dist/heap-state.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import type { IHeapSnapshot } from '@memlab/core';
+export declare function getSnapshot(): IHeapSnapshot;
+export declare function getFilePath(): string | null;
+export declare function setSnapshot(snapshot: IHeapSnapshot, filePath: string): void;
+//# sourceMappingURL=heap-state.d.ts.map

package/dist/heap-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heap-state.d.ts","sourceRoot":"","sources":["../src/heap-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,cAAc,CAAC;AAKhD,wBAAgB,WAAW,IAAI,aAAa,CAK3C;AAED,wBAAgB,WAAW,IAAI,MAAM,GAAG,IAAI,CAE3C;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAG3E"}

package/dist/heap-state.js

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+let currentSnapshot = null;
+let currentFilePath = null;
+export function getSnapshot() {
+    if (!currentSnapshot) {
+        throw new Error('No heap snapshot loaded. Use memlab_load_snapshot first.');
+    }
+    return currentSnapshot;
+}
+export function getFilePath() {
+    return currentFilePath;
+}
+export function setSnapshot(snapshot, filePath) {
+    currentSnapshot = snapshot;
+    currentFilePath = filePath;
+}
+//# sourceMappingURL=heap-state.js.map

package/dist/heap-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heap-state.js","sourceRoot":"","sources":["../src/heap-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,IAAI,eAAe,GAAyB,IAAI,CAAC;AACjD,IAAI,eAAe,GAAkB,IAAI,CAAC;AAE1C,MAAM,UAAU,WAAW;IACzB,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,eAAe,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,OAAO,eAAe,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,QAAuB,EAAE,QAAgB;IACnE,eAAe,GAAG,QAAQ,CAAC;IAC3B,eAAe,GAAG,QAAQ,CAAC;AAC7B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG"}

package/dist/index.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerLoadSnapshot } from './tools/load-snapshot.js';
+import { registerSnapshotSummary } from './tools/snapshot-summary.js';
+import { registerLargestObjects } from './tools/largest-objects.js';
+import { registerGetNode } from './tools/get-node.js';
+import { registerFindNodesByClass } from './tools/find-nodes-by-class.js';
+import { registerGetReferences } from './tools/get-references.js';
+import { registerGetReferrers } from './tools/get-referrers.js';
+import { registerRetainerTrace } from './tools/retainer-trace.js';
+import { registerDetachedDom } from './tools/detached-dom.js';
+import { registerDuplicatedStrings } from './tools/duplicated-strings.js';
+import { registerStaleCollections } from './tools/stale-collections.js';
+import { registerGlobalVariables } from './tools/global-variables.js';
+import { registerSearchNodes } from './tools/search-nodes.js';
+import { registerGetProperty } from './tools/get-property.js';
+import { registerObjectShape } from './tools/object-shape.js';
+import { registerClassHistogram } from './tools/class-histogram.js';
+import { registerDominatorSubtree } from './tools/dominator-subtree.js';
+import { registerClosureInspection } from './tools/closure-inspection.js';
+import { registerFindByProperty } from './tools/find-by-property.js';
+import { registerAggregateNodes } from './tools/aggregate-nodes.js';
+import { registerEval } from './tools/eval.js';
+import { registerForEach } from './tools/for-each.js';
+import { registerReports } from './tools/reports.js';
+const server = new McpServer({
+    name: 'memlab',
+    version: '1.1.0',
+});
+registerLoadSnapshot(server);
+registerSnapshotSummary(server);
+registerLargestObjects(server);
+registerGetNode(server);
+registerFindNodesByClass(server);
+registerGetReferences(server);
+registerGetReferrers(server);
+registerRetainerTrace(server);
+registerDetachedDom(server);
+registerDuplicatedStrings(server);
+registerStaleCollections(server);
+registerGlobalVariables(server);
+registerSearchNodes(server);
+registerGetProperty(server);
+registerObjectShape(server);
+registerClassHistogram(server);
+registerDominatorSubtree(server);
+registerClosureInspection(server);
+registerFindByProperty(server);
+registerAggregateNodes(server);
+registerReports(server);
+registerEval(server);
+registerForEach(server);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(err => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/aggregate-nodes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerAggregateNodes(server: McpServer): void;
+//# sourceMappingURL=aggregate-nodes.d.ts.map

package/dist/tools/aggregate-nodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate-nodes.d.ts","sourceRoot":"","sources":["../../src/tools/aggregate-nodes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAoCvE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAqI9D"}

package/dist/tools/aggregate-nodes.js

@@ -0,0 +1,136 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import { z } from 'zod';
+import memlabCore from '@memlab/core';
+const { utils } = memlabCore;
+import { getSnapshot } from '../heap-state.js';
+import { errorResult, textResult, formatBytes, formatNumber, markdownTable, } from '../utils.js';
+function getGroupKey(node, groupBy) {
+    switch (groupBy) {
+        case 'type':
+            return node.type;
+        case 'name':
+            return node.name;
+        case 'name_prefix': {
+            const spaceIdx = node.name.indexOf(' ');
+            return spaceIdx > 0 ? node.name.substring(0, spaceIdx) : node.name;
+        }
+    }
+}
+export function registerAggregateNodes(server) {
+    server.tool('memlab_aggregate', 'Aggregate heap nodes by type, name, or name prefix. Returns grouped statistics (count, total self size, aggregate retained size) sorted by retained size. Retained size uses dominator-aware aggregation (no double-counting).', {
+        name_pattern: z
+            .string()
+            .optional()
+            .describe('Regex pattern to match against node names'),
+        type: z.string().optional().describe('Node type filter'),
+        min_retained_size: z
+            .number()
+            .optional()
+            .describe('Minimum retained size in bytes'),
+        min_self_size: z
+            .number()
+            .optional()
+            .describe('Minimum self (shallow) size in bytes'),
+        is_detached: z
+            .boolean()
+            .optional()
+            .describe('Filter by detachment status'),
+        group_by: z
+            .enum(['type', 'name', 'name_prefix'])
+            .describe('What to group on: "type" (node type), "name" (full name), "name_prefix" (first word of name)'),
+        metrics: z
+            .array(z.enum(['count', 'sum_self_size', 'retained_size']))
+            .optional()
+            .default(['count', 'sum_self_size', 'retained_size'])
+            .describe('Metrics to compute per group'),
+        limit: z
+            .number()
+            .optional()
+            .default(30)
+            .describe('Maximum number of groups to return (default 30)'),
+    }, async ({ name_pattern, type, min_retained_size, min_self_size, is_detached, group_by, metrics, limit, }) => {
+        try {
+            const snapshot = getSnapshot();
+            const nameRegex = name_pattern ? new RegExp(name_pattern, 'i') : null;
+            const groups = new Map();
+            snapshot.nodes.forEach(node => {
+                if (node.id <= 3)
+                    return;
+                if (type && node.type !== type)
+                    return;
+                if (nameRegex && !nameRegex.test(node.name))
+                    return;
+                if (min_retained_size && node.retainedSize < min_retained_size)
+                    return;
+                if (min_self_size && node.self_size < min_self_size)
+                    return;
+                if (is_detached !== undefined) {
+                    const detached = node.is_detached || node.name.startsWith('Detached ');
+                    if (is_detached !== detached)
+                        return;
+                }
+                const key = getGroupKey(node, group_by);
+                let stats = groups.get(key);
+                if (!stats) {
+                    stats = { count: 0, sum_self_size: 0, node_ids: new Set() };
+                    groups.set(key, stats);
+                }
+                stats.count++;
+                stats.sum_self_size += node.self_size;
+                stats.node_ids.add(node.id);
+            });
+            const metricsSet = new Set(metrics);
+            const needsRetained = metricsSet.has('retained_size');
+            // Compute dominator-aware aggregate retained size per group.
+            const entries = Array.from(groups.entries()).map(([key, stats]) => {
+                const retainedSize = needsRetained
+                    ? utils.aggregateDominatorMetrics(stats.node_ids, snapshot, () => true, (node) => node.retainedSize)
+                    : 0;
+                return { key, ...stats, retained_size: retainedSize };
+            });
+            const sorted = entries
+                .sort((a, b) => b.retained_size - a.retained_size ||
+                b.sum_self_size - a.sum_self_size)
+                .slice(0, limit);
+            const headers = [
+                group_by === 'type'
+                    ? 'Type'
+                    : group_by === 'name'
+                        ? 'Name'
+                        : 'Name Prefix',
+            ];
+            if (metricsSet.has('count'))
+                headers.push('Count');
+            if (metricsSet.has('sum_self_size'))
+                headers.push('Self Size');
+            if (metricsSet.has('retained_size'))
+                headers.push('Retained Size');
+            const rightCols = new Set();
+            for (let i = 1; i < headers.length; i++)
+                rightCols.add(i);
+            const rows = sorted.map(stats => {
+                const row = [stats.key];
+                if (metricsSet.has('count'))
+                    row.push(formatNumber(stats.count));
+                if (metricsSet.has('sum_self_size'))
+                    row.push(formatBytes(stats.sum_self_size));
+                if (metricsSet.has('retained_size'))
+                    row.push(formatBytes(stats.retained_size));
+                return row;
+            });
+            return textResult(`Aggregation by ${group_by} (${formatNumber(groups.size)} groups, showing ${rows.length})\n\n${markdownTable(headers, rows, rightCols)}`);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=aggregate-nodes.js.map

package/dist/tools/aggregate-nodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate-nodes.js","sourceRoot":"","sources":["../../src/tools/aggregate-nodes.ts"],"names":[],"mappings":"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"}

package/dist/tools/class-histogram.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerClassHistogram(server: McpServer): void;
+//# sourceMappingURL=class-histogram.d.ts.map

package/dist/tools/class-histogram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"class-histogram.d.ts","sourceRoot":"","sources":["../../src/tools/class-histogram.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAcvE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA0G9D"}