@memlab/mcp-server 2.18.1 → 2.86.0

package/dist/tools/tools-index.js

@@ -0,0 +1,492 @@
+/**
+ * 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 { listToolNames } from '../tool-registry.js';
+import { errorResult, makeNamePatternTest, textResult } from '../utils.js';
+const GROUPS = [
+    {
+        question: 'What is this heap actually made of?',
+        tools: [
+            [
+                'memlab_script_census',
+                'How much of the heap is retained JS SOURCE TEXT — and whether the same bundle is retained twice.',
+            ],
+            [
+                'memlab_property_names',
+                'Which property names exist at all; the cheapest way to confirm a field is present before probing for it.',
+            ],
+            [
+                'memlab_async_census',
+                'Pending async work: scheduler task queues (live vs cancelled), timer closures, unsettled Promises.',
+            ],
+            [
+                'memlab_app_heap',
+                'START HERE on an unfamiliar app: splits the heap into application data vs bundle source vs V8 machinery. On one app this showed ~55% of the heap was JS bundle source, which reframed every number that followed.',
+            ],
+            [
+                'memlab_quick_diagnosis',
+                'One call for summary + biggest objects + class histogram + duplicated strings.',
+            ],
+            [
+                'memlab_snapshot_summary',
+                'Node/edge counts and totals, when you only need the shape of the capture.',
+            ],
+            [
+                'memlab_class_histogram',
+                'Counts and sizes per class; `name_pattern` answers "is class X present?" in one row.',
+            ],
+            ['memlab_largest_objects', 'The single biggest retainers, ranked.'],
+            [
+                'memlab_shape_histogram',
+                'Groups plain objects by their property set — finds record types the class name hides behind `Object`.',
+            ],
+            [
+                'memlab_identify',
+                'Name a minified structure from its property shape — listener record, LRU node, React update record, undo entry.',
+            ],
+            [
+                'memlab_object_cost_breakdown',
+                'Where one class’s bytes actually go (self vs properties vs elements).',
+            ],
+            [
+                'memlab_what_if',
+                'If this set were freed, how many bytes actually come back — dominator-deduped, no double counting.',
+            ],
+            [
+                'memlab_trace_all',
+                'Retainer-trace an ENTIRE population and cluster the paths server-side — finds the minority path a 10-instance sample cannot.',
+            ],
+            [
+                'memlab_retainer_diff',
+                'Did the population grow along the same retention path, or did a NEW owner appear? The question a count diff cannot answer.',
+            ],
+            [
+                'memlab_identity_diff',
+                'Same objects, or just the same count? Matches a population across two captures by CONTENT — churn and retention need different fixes.',
+            ],
+            [
+                'memlab_next_measurement',
+                'What the loaded snapshots cannot support, and which capture would fix it. Run it before writing a conclusion.',
+            ],
+            [
+                'memlab_app_config',
+                'Read the feature flags the app was actually running with, out of the capture — "was the fix even enabled here?" without circular inference.',
+            ],
+            [
+                'memlab_metric',
+                'Record a measurement under a name and keep it ACROSS sessions — the only way a number measured today survives to be compared next week.',
+            ],
+            [
+                'memlab_unit_cost',
+                'Retained bytes per instance, AVERAGE and MARGINAL — the number a cap, an LRU size or an eviction policy is sized against.',
+            ],
+        ],
+    },
+    {
+        question: 'Is anything growing — and is it a leak?',
+        tools: [
+            [
+                'memlab_ladder_probe',
+                'ONE numeric probe across an ordered ladder, with the per-cycle rate and a linear fit — the cheapest way to test a metric, since each rung loads once for all probes.',
+            ],
+            [
+                'memlab_census_diff',
+                'Detached-DOM and listener census at TWO rungs, diffed per class and per callback in one call.',
+            ],
+            [
+                'memlab_leak_report',
+                'The ladder verdict: per-class growth across an ordered set of snapshots.',
+            ],
+            [
+                'memlab_sequence_analysis',
+                'Per-class trend across a ladder, with artifact families flagged.',
+            ],
+            [
+                'memlab_collection_trend',
+                'Entry counts of NAMED collections across a ladder, with growth per interaction cycle.',
+            ],
+            [
+                'memlab_population_diff',
+                'Whether two snapshots hold the same POPULATION or just the same count — equal totals are not identity.',
+            ],
+            [
+                'memlab_react_update_queues',
+                'The React eager-bailout family in one call: queue BREADTH vs chain LENGTH vs owning component. The breadth/length split is what separates a leak from "more hooks mounted".',
+            ],
+            [
+                'memlab_settle_check',
+                'Backlog or leak? Compares a busy rung against one captured after idle + GC — growth that comes back was work in flight.',
+            ],
+            [
+                'memlab_growth_signals',
+                'Single-snapshot signals that something is accumulating.',
+            ],
+            [
+                'memlab_diff_snapshots',
+                'Raw per-class deltas between two resident snapshots.',
+            ],
+            [
+                'memlab_hypothesis',
+                'State a leak hypothesis and have it checked against the ladder instead of arguing it.',
+            ],
+            [
+                'memlab_verify_fix',
+                'Did the fix work? Compares per-cycle growth RATES between a before ladder and an after ladder — from two sets of snapshot FILES, so no runtime gate is needed and an ungated or build-only fix is verified the same way.',
+            ],
+            [
+                'memlab_ladder',
+                'Name a ladder once and reference it as `ladder:<name>` from every trend tool.',
+            ],
+        ],
+    },
+    {
+        question: 'Who owns the growth / why is X retained?',
+        tools: [
+            [
+                'memlab_react_owners',
+                'Name the React COMPONENT behind a population of plain `Object`s. Fibers and hooks are all `Object` in a production bundle, so every class-name heuristic — including `helpers.owner` — walks past them.',
+            ],
+            [
+                'memlab_population_vs_owners',
+                'STRUCTURAL or ACCUMULATING? One record per live owner is a baseline; many records per owner is a leak.',
+            ],
+            [
+                'memlab_chain_walk',
+                'Walk a repeated linked structure (`.next` update queues, `.prev` closure chains, LRU lists) and report how deep it goes — use this instead of a hand-written loop, which cannot tell a cycle from a hop cap.',
+            ],
+            [
+                'memlab_module_attribution',
+                'Attribute bytes to the MODULE that owns them, by walking dominators up to the nearest module-registry export.',
+            ],
+            [
+                'memlab_explain_delta',
+                'WHERE a heap grew, attributed to the object that owns the new bytes rather than to what they are.',
+            ],
+            [
+                'memlab_dominator_chain',
+                'From one node up to the accountable application object.',
+            ],
+            [
+                'memlab_dominator_attribution',
+                'Given several candidate retainers, how much each one actually dominates — a zero refutes a hypothesis.',
+            ],
+            ['memlab_retainer_trace', 'The shortest retainer path for one node.'],
+            [
+                'memlab_retainer_summary',
+                'Retainer paths across many instances, clustered by shape.',
+            ],
+            ['memlab_referrer_summary', 'Who points at this, grouped by edge.'],
+            [
+                'memlab_pinch_points',
+                'Single objects whose release would free the most.',
+            ],
+            ['memlab_dominator_subtree', 'What one object holds, expanded downward.'],
+            [
+                'memlab_retainer_layers',
+                'The retention structure around a node, layer by layer.',
+            ],
+            ['memlab_trace_dominators', 'Dominator path for a set of nodes at once.'],
+        ],
+    },
+    {
+        question: 'Is it real, or a measurement artifact?',
+        tools: [
+            [
+                'memlab_artifact_budget',
+                'ONE number for how much of the heap is not the application — and, with a baseline, how much of the GROWTH was the app. `app_delta` is the number that should lead a report.',
+            ],
+            [
+                'memlab_replicate',
+                'Does the effect REPRODUCE across independently-driven runs? Refuses to call it real until it does — the guard against filing a one-off.',
+            ],
+            [
+                'memlab_dev_artifacts',
+                'Memory retained ONLY by dev/automation roots — DevTools, extensions, React Fast Refresh, the a11y cache. Run before calling anything a production leak.',
+            ],
+            [
+                'memlab_explain_delta',
+                'Counts the OTHER artifact family — V8 JIT warmup — which dev_artifacts does not. Read both.',
+            ],
+            [
+                'memlab_check_health',
+                'Prioritized triage that separates likely-real from likely-noise.',
+            ],
+        ],
+    },
+    {
+        question: 'Detached DOM and event listeners',
+        tools: [
+            [
+                'memlab_dom_audit',
+                'Budget the ATTACHED DOM and rank surfaces worth virtualizing. An OPTIMIZATION tool — these elements are correctly retained, there are simply too many.',
+            ],
+            [
+                'memlab_detached_dom',
+                'Detached nodes, with a pinned-vs-GC-eligible split; `group_by:"dominator"` groups by what a fix would actually free.',
+            ],
+            ['memlab_event_listener_leaks', 'Listeners that outlived their target.'],
+            ['memlab_event_registry', 'What is registered on what.'],
+        ],
+    },
+    {
+        question: 'Collections and caches',
+        tools: [
+            [
+                'memlab_collection_diff',
+                'WHICH collections grew across a ladder, without being told their names — censuses every Map/Set/Array and keys each by a stable `<Owner>.<property>` signature.',
+            ],
+            [
+                'memlab_weakref_census',
+                'Every WeakRef, split LIVE vs EMPTY, grouped by the shape of the holder.',
+            ],
+            [
+                'memlab_cache_analysis',
+                'Unbounded or oversized caches in one snapshot.',
+            ],
+            [
+                'memlab_sparse_elements',
+                'Integer-keyed objects and arrays whose elements backing store is mostly holes — waste charged to no class, so a histogram cannot see it.',
+            ],
+            [
+                'memlab_id_space_audit',
+                'Separate integer-keyed structures indexed by the SAME sparse id space — several small sparse findings that are really one re-keying fix.',
+            ],
+            [
+                'memlab_stale_collections',
+                'Collections holding entries nothing else references.',
+            ],
+            [
+                'memlab_collection_trend',
+                'The same collections tracked ACROSS a ladder.',
+            ],
+            [
+                'memlab_map_entries',
+                'Enumerate a Map/Set correctly (SMI gaps and browser slot typing handled).',
+            ],
+            ['memlab_weakmap_entries', 'Enumerate a WeakMap.'],
+            [
+                'memlab_array_group_by',
+                'Group an array’s elements by a property to see what is piling up.',
+            ],
+            [
+                'memlab_property_distribution',
+                'Cardinality and top values of one property across instances.',
+            ],
+        ],
+    },
+    {
+        question: 'Strings and duplication',
+        tools: [
+            [
+                'memlab_intern_opportunities',
+                'What an intern pool would actually reclaim, grouped by property x parent shape. Start here for an interning decision.',
+            ],
+            ['memlab_duplicated_strings', 'The raw per-value duplication table.'],
+            [
+                'memlab_string_patterns',
+                'Group strings by prefix to find families (URLs, ids, payloads).',
+            ],
+            ['memlab_sliced_strings', 'Substrings pinning huge parents.'],
+            [
+                'memlab_duplicate_objects',
+                'The same question for objects rather than strings.',
+            ],
+            ['memlab_search_strings', 'Find a string value in the heap.'],
+            ['memlab_get_string', 'Read one string node’s value.'],
+        ],
+    },
+    {
+        question: 'Inspect or find specific objects',
+        tools: [
+            [
+                'memlab_find_nodes_by_class',
+                'By exact class name, or by `name_pattern` regex/substring.',
+            ],
+            ['memlab_search_nodes', 'By name/type/size predicates.'],
+            ['memlab_find_by_property', 'By a property name/value.'],
+            ['memlab_find_by_shape', 'By property set.'],
+            ['memlab_match_object', 'By a structural pattern.'],
+            ['memlab_get_node', 'One node’s details.'],
+            ['memlab_object_shape', 'One object’s properties and their sizes.'],
+            ['memlab_get_references', 'Outgoing edges.'],
+            ['memlab_get_referrers', 'Incoming edges.'],
+            ['memlab_get_property', 'One property of one object.'],
+            ['memlab_get_value', 'A scalar value, where the format allows it.'],
+            [
+                'memlab_closure_inspection',
+                'What a closure captured, and what that costs.',
+            ],
+            ['memlab_global_variables', 'What is hanging off the global object.'],
+            ['memlab_aggregate', 'Sum/count over a node set.'],
+            ['memlab_for_each', 'Run one tool over many nodes.'],
+        ],
+    },
+    {
+        question: 'None of the above — ask the heap directly',
+        tools: [
+            [
+                'memlab_eval',
+                'Arbitrary JS over the snapshot, with indexed helpers (`byClass`, `iterByType`, `classCounts`, `entries`, `dominates`, `pathBetween`). Use `mode:"describe_env"` for the calling convention. This is the escape hatch when no fixed-shape tool matches the question.',
+            ],
+            [
+                'memlab_eval_across',
+                'The same eval program run against several snapshots at once — comparative questions without the switch-and-diff.',
+            ],
+            [
+                'memlab_auto_investigate',
+                'When you do not yet have a question: runs the standard deep-dive and reports what it found.',
+            ],
+            [
+                'memlab_tools',
+                'This index. Filter it with `question` or look a tool up with `tool`.',
+            ],
+        ],
+    },
+    {
+        question: 'Sharing a capture outside its trust boundary',
+        tools: [
+            [
+                'memlab_anonymize_snapshot',
+                'Rewrite a capture so it can be attached to a task or handed to a model, keeping it analyzable — and reporting the identifier-shaped text it could NOT classify. Also audits a capture someone else anonymized: one such file still carried 26,303 account handles as property names.',
+            ],
+        ],
+    },
+    {
+        question: 'Session, batching and write-ups',
+        tools: [
+            [
+                'memlab_round_digest',
+                'The verdict table for a finished round and nothing else — the audit verdict, the ladder shape, and the per-metric rate/fit/verdict rows, without the ~30 KB of prose.',
+            ],
+            [
+                'memlab_round_audit',
+                'Read a round’s run.json BEFORE analysing it, so a broken bring-up is caught before its numbers travel into a write-up.',
+            ],
+            [
+                'memlab_load_snapshot',
+                'Load a local path, a manifold:// URL, or a bare Nest filename.',
+            ],
+            [
+                'memlab_snapshots',
+                'List / switch / unload resident snapshots; set session output controls.',
+            ],
+            [
+                'memlab_batch',
+                'Several tools against ONE load — the load is the expensive part.',
+            ],
+            [
+                'memlab_snapshot_header',
+                'Node/edge counts WITHOUT loading the snapshot.',
+            ],
+            [
+                'memlab_server_status',
+                'Confirm the server is alive; returns instantly.',
+            ],
+            [
+                'memlab_finding_index',
+                'Record findings as you go so the write-up is not reconstructed from memory.',
+            ],
+            ['memlab_reports', 'Render the findings.'],
+            ['memlab_hunt_report', 'Render a leak-hunt run.'],
+            [
+                'memlab_analyze_run',
+                'Point at a run.json and get the WHOLE analysis protocol — trend, owner attribution, population diff, artifact classification, caveats — in one call.',
+            ],
+        ],
+    },
+];
+export function registerToolsIndex(server) {
+    server.tool('memlab_tools', 'Index of every memlab tool, grouped by the QUESTION it answers ("what is this heap made of", "is anything growing", "why is X retained", "is it real or an artifact", …). Call this first when you are not sure which tool fits, or when you suspect the server has something better than the one you were about to use — it costs one call and lists tools whose schemas have not been fetched yet, which is otherwise impossible to discover under deferred tool loading. Pass `question` to filter to matching groups, or `tool` to find which group a tool belongs to.', {
+        question: z
+            .string()
+            .optional()
+            .describe('Filter to groups matching this text (case-insensitive regex, substring fallback) — e.g. "growing", "retained", "artifact", "string".'),
+        tool: z
+            .string()
+            .optional()
+            .describe('Show the group(s) containing this tool name (with or without the memlab_ prefix).'),
+    }, async ({ question, tool }) => {
+        try {
+            const registered = new Set(listToolNames());
+            const wanted = tool
+                ? tool.startsWith('memlab_')
+                    ? tool
+                    : `memlab_${tool}`
+                : null;
+            const matchesQuestion = makeNamePatternTest(question);
+            const indexed = new Set(GROUPS.flatMap(g => g.tools.map(([n]) => n)));
+            const uncategorized = [...registered].filter(n => !indexed.has(n));
+            let groups = GROUPS;
+            if (wanted != null) {
+                groups = groups.filter(g => g.tools.some(([n]) => n === wanted));
+                if (groups.length === 0) {
+                    // This branch returns immediately, so the uncategorized list has to
+                    // be rendered HERE. Pointing at the drift-guard section further
+                    // down sent the reader to output this call never produces.
+                    const parts = [
+                        `\`${wanted}\` is not in the index${registered.has(wanted) ? ' (but it IS registered — the index is missing an entry)' : ' and is not a registered tool'}.`,
+                    ];
+                    if (uncategorized.length > 0) {
+                        parts.push(`Registered but not categorized: ${uncategorized.map(n => `\`${n}\``).join(', ')}.`);
+                    }
+                    parts.push(`Registered tools: ${[...registered].join(', ')}`);
+                    return textResult(parts.join('\n\n'));
+                }
+            }
+            if (question != null) {
+                groups = groups.filter(g => matchesQuestion(g.question) ||
+                    g.tools.some(([n, w]) => matchesQuestion(n) || matchesQuestion(w)));
+            }
+            const lines = [
+                `# memlab tools by question (${registered.size} registered)`,
+                '',
+            ];
+            if (groups.length === 0) {
+                // Name BOTH filters when both were passed: `tool` narrows first, so
+                // "no group matches <question>" alone describes the wrong search and
+                // suggests re-running with no arguments when dropping one would do.
+                const filterDesc = wanted != null && question != null
+                    ? `\`${wanted}\` and "${question}" together`
+                    : question != null
+                        ? `"${question}"`
+                        : 'that filter';
+                lines.push(`No group matches ${filterDesc}. ` +
+                    (wanted != null && question != null
+                        ? `\`${wanted}\` is in the index, but not in a group matching "${question}" — drop one of the two, or call \`memlab_tools\` with no arguments for the full index.`
+                        : 'Call `memlab_tools` with no arguments for the full index.'));
+                return textResult(lines.join('\n'));
+            }
+            for (const g of groups) {
+                lines.push(`## ${g.question}`, '');
+                for (const [name, when] of g.tools) {
+                    // A name in the index that is no longer registered is worse than a
+                    // missing one: it sends the caller after a tool that will fail.
+                    const missing = registered.has(name) ? '' : ' _(not registered)_';
+                    lines.push(`- \`${name}\`${missing} — ${when}`);
+                }
+                lines.push('');
+            }
+            // Drift guard. The index is hand-written for usefulness, so a newly
+            // added tool would otherwise be invisible here — which is the exact
+            // failure this tool exists to fix, reproduced one level up.
+            if (question == null && wanted == null) {
+                if (uncategorized.length > 0) {
+                    lines.push('## Not yet categorized', '', `These are registered but missing from the index above: ${uncategorized.map(n => `\`${n}\``).join(', ')}. Their own descriptions are the only documentation.`, '');
+                }
+            }
+            lines.push('_A tool listed under several questions is genuinely useful for each. Where a group is ordered, the first entry is the one to try first._');
+            return textResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=tools-index.js.map

package/dist/tools/tools-index.js.map

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

package/dist/tools/trace-all.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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';
+import type { IHeapNode, IHeapSnapshot } from '@memlab/core';
+import { type TraceStep } from './retainer-summary.js';
+export interface TraceCluster {
+    key: string;
+    steps: TraceStep[];
+    count: number;
+    selfSize: number;
+    exampleIds: number[];
+    ids: number[];
+    idsTruncated: boolean;
+}
+/**
+ * Render a cluster's chain. When a path was truncated for grouping, its last
+ * step still carries the edge leading to the next hop, and that edge IS part
+ * of the grouping key — so suppressing it (which is correct for a complete
+ * path, whose last node is the target) renders two distinct clusters
+ * byte-identically. Show it, with a marker for the hops beyond.
+ */
+export declare function renderClusterChain(steps: TraceStep[]): string;
+export declare function selectPopulation(snapshot: IHeapSnapshot, sel: {
+    nodeIds?: number[];
+    className?: string;
+    shape?: string[];
+}): IHeapNode[];
+export declare function clusterByRetainerPath(nodes: IHeapNode[], frameworkFilter: boolean, maxTrace: number, maxDepth?: number): {
+    clusters: TraceCluster[];
+    traced: number;
+    noPath: number;
+    truncated: boolean;
+};
+export declare function registerTraceAll(server: McpServer): void;
+//# sourceMappingURL=trace-all.d.ts.map

package/dist/tools/trace-all.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-all.d.ts","sourceRoot":"","sources":["../../src/tools/trace-all.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AACvE,OAAO,KAAK,EAAC,SAAS,EAAE,aAAa,EAAC,MAAM,cAAc,CAAC;AAI3D,OAAO,EAIL,KAAK,SAAS,EACf,MAAM,uBAAuB,CAAC;AAiB/B,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,EAAE,CAAC;IAGrB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,YAAY,EAAE,OAAO,CAAC;CACvB;AAID;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,CAI7D;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,aAAa,EACvB,GAAG,EAAE;IAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CAAC,GAC9D,SAAS,EAAE,CA0Bb;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,SAAS,EAAE,EAClB,eAAe,EAAE,OAAO,EACxB,QAAQ,EAAE,MAAM,EAKhB,QAAQ,CAAC,EAAE,MAAM,GAChB;IACD,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;CACpB,CA0CA;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAoOxD"}