@memlab/mcp-server 2.0.0

package/dist/tools/largest-objects.js

@@ -0,0 +1,32 @@
+/**
+ * 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 { getSnapshot } from '../heap-state.js';
+import { isNodeWorthInspecting, filterLargestObjects, serializeNodeSummary, formatNodeSummaryTable, errorResult, textResult, } from '../utils.js';
+export function registerLargestObjects(server) {
+    server.tool('memlab_largest_objects', 'Find the top N objects by retained size in the loaded heap snapshot. Filters out internal/meta objects.', {
+        limit: z
+            .number()
+            .optional()
+            .default(20)
+            .describe('Maximum number of objects to return (default 20)'),
+    }, async ({ limit }) => {
+        try {
+            const snapshot = getSnapshot();
+            const nodes = filterLargestObjects(snapshot, isNodeWorthInspecting, limit);
+            const summaries = nodes.map(serializeNodeSummary);
+            return textResult(`Top ${summaries.length} objects by retained size\n\n${formatNodeSummaryTable(summaries)}`);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=largest-objects.js.map

package/dist/tools/largest-objects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"largest-objects.js","sourceRoot":"","sources":["../../src/tools/largest-objects.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AACtB,OAAO,EAAC,WAAW,EAAC,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,WAAW,EACX,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,MAAM,UAAU,sBAAsB,CAAC,MAAiB;IACtD,MAAM,CAAC,IAAI,CACT,wBAAwB,EACxB,yGAAyG,EACzG;QACE,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,OAAO,CAAC,EAAE,CAAC;aACX,QAAQ,CAAC,kDAAkD,CAAC;KAChE,EACD,KAAK,EAAE,EAAC,KAAK,EAAC,EAAE,EAAE;QAChB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;YAC/B,MAAM,KAAK,GAAG,oBAAoB,CAChC,QAAQ,EACR,qBAAqB,EACrB,KAAK,CACN,CAAC;YACF,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;YAClD,OAAO,UAAU,CACf,OAAO,SAAS,CAAC,MAAM,gCAAgC,sBAAsB,CAAC,SAAS,CAAC,EAAE,CAC3F,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/load-snapshot.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 registerLoadSnapshot(server: McpServer): void;
+//# sourceMappingURL=load-snapshot.d.ts.map

package/dist/tools/load-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-snapshot.d.ts","sourceRoot":"","sources":["../../src/tools/load-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAOvE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA+B5D"}

package/dist/tools/load-snapshot.js

@@ -0,0 +1,39 @@
+/**
+ * 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 memlabHeapAnalysis from '@memlab/heap-analysis';
+const { getFullHeapFromFile } = memlabHeapAnalysis;
+import { setSnapshot } from '../heap-state.js';
+import { formatBytes, formatNumber, errorResult, textResult } from '../utils.js';
+export function registerLoadSnapshot(server) {
+    server.tool('memlab_load_snapshot', 'Load and parse a .heapsnapshot file. This builds indexes, computes the dominator tree, and calculates retained sizes. Only one snapshot can be loaded at a time.', {
+        file_path: z.string().describe('Absolute path to a .heapsnapshot file'),
+    }, async ({ file_path }) => {
+        try {
+            const snapshot = await getFullHeapFromFile(file_path);
+            setSnapshot(snapshot, file_path);
+            let nodeCount = 0;
+            let edgeCount = 0;
+            let totalSize = 0;
+            snapshot.nodes.forEach(node => {
+                nodeCount++;
+                totalSize += node.self_size;
+            });
+            snapshot.edges.forEach(() => {
+                edgeCount++;
+            });
+            return textResult(`Loaded ${file_path}: ${formatNumber(nodeCount)} nodes, ${formatNumber(edgeCount)} edges, ${formatBytes(totalSize)}`);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=load-snapshot.js.map

package/dist/tools/load-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-snapshot.js","sourceRoot":"","sources":["../../src/tools/load-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AACtB,OAAO,kBAAkB,MAAM,uBAAuB,CAAC;AACvD,MAAM,EAAC,mBAAmB,EAAC,GAAG,kBAAkB,CAAC;AACjD,OAAO,EAAC,WAAW,EAAC,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAC,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAC,MAAM,aAAa,CAAC;AAE/E,MAAM,UAAU,oBAAoB,CAAC,MAAiB;IACpD,MAAM,CAAC,IAAI,CACT,sBAAsB,EACtB,kKAAkK,EAClK;QACE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;KACxE,EACD,KAAK,EAAE,EAAC,SAAS,EAAC,EAAE,EAAE;QACpB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,SAAS,CAAC,CAAC;YACtD,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;YAEjC,IAAI,SAAS,GAAG,CAAC,CAAC;YAClB,IAAI,SAAS,GAAG,CAAC,CAAC;YAClB,IAAI,SAAS,GAAG,CAAC,CAAC;YAClB,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE;gBAC5B,SAAS,EAAE,CAAC;gBACZ,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC;YAC9B,CAAC,CAAC,CAAC;YACH,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE;gBAC1B,SAAS,EAAE,CAAC;YACd,CAAC,CAAC,CAAC;YAEH,OAAO,UAAU,CACf,UAAU,SAAS,KAAK,YAAY,CAAC,SAAS,CAAC,WAAW,YAAY,CAAC,SAAS,CAAC,WAAW,WAAW,CAAC,SAAS,CAAC,EAAE,CACrH,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/object-shape.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 registerObjectShape(server: McpServer): void;
+//# sourceMappingURL=object-shape.d.ts.map

package/dist/tools/object-shape.d.ts.map

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

package/dist/tools/object-shape.js

@@ -0,0 +1,86 @@
+/**
+ * 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 { getSnapshot } from '../heap-state.js';
+import { formatBytes, formatNumber, formatNodeInline, markdownTable, errorResult, textResult, } from '../utils.js';
+export function registerObjectShape(server) {
+    server.tool('memlab_object_shape', 'Show the shape/structure of a heap object: all its named properties with target node types and sizes. Filters out internal/hidden edges to show only user-visible properties. Use this to understand what an object contains at a glance.', {
+        node_id: z.number().describe('The numeric ID of the heap node'),
+        include_internal: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Include internal/hidden edges (default false)'),
+        limit: z
+            .number()
+            .optional()
+            .default(50)
+            .describe('Maximum number of properties to return (default 50)'),
+    }, async ({ node_id, include_internal, limit }) => {
+        try {
+            const snapshot = getSnapshot();
+            const node = snapshot.getNodeById(node_id);
+            if (!node) {
+                return errorResult(`Node with id ${node_id} not found`);
+            }
+            const userEdgeTypes = new Set([
+                'property',
+                'element',
+                'context',
+                'shortcut',
+            ]);
+            const filteredEdges = node.references
+                .filter(edge => include_internal || userEdgeTypes.has(edge.type))
+                .sort((a, b) => b.toNode.retainedSize - a.toNode.retainedSize)
+                .slice(0, limit);
+            const totalEdges = node.references.length;
+            const hiddenCount = include_internal
+                ? 0
+                : totalEdges -
+                    node.references.filter(e => userEdgeTypes.has(e.type)).length;
+            const lines = [
+                `**${formatNodeInline(node.id, node.name, node.type)}** — ${formatNumber(totalEdges)} edges total${hiddenCount > 0 ? `, ${formatNumber(hiddenCount)} internal hidden` : ''}`,
+                '',
+            ];
+            const headers = [
+                'Name',
+                'Edge Type',
+                'Target',
+                'Target Type',
+                'Retained',
+            ];
+            const rightCols = new Set([4]);
+            const rows = filteredEdges.map(edge => {
+                const target = edge.toNode;
+                let targetLabel = `@${target.id} ${target.name}`;
+                if (target.isString) {
+                    const strNode = target.toStringNode();
+                    if (strNode) {
+                        const val = strNode.stringValue;
+                        targetLabel = `@${target.id} "${val.length > 60 ? val.slice(0, 60) + '...' : val}"`;
+                    }
+                }
+                return [
+                    String(edge.name_or_index),
+                    edge.type,
+                    targetLabel,
+                    target.type,
+                    formatBytes(target.retainedSize),
+                ];
+            });
+            lines.push(markdownTable(headers, rows, rightCols));
+            return textResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=object-shape.js.map

package/dist/tools/object-shape.js.map

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

package/dist/tools/reports.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 registerReports(server: McpServer): void;
+//# sourceMappingURL=reports.d.ts.map

package/dist/tools/reports.d.ts.map

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