feat(cmp-server): Improve MCP server cache/growth/duplicate-string detectors

Summary:
Three detector improvements to the MemLab MCP server, based on recurring gaps hit while analyzing real Node.js server heap snapshots. Source of truth is edited in `www/scripts/webspeed/memory_lab/packages/mcp-server/src/` and synced to the internal Claude plugin copy under `fbcode/claude-templates/components/plugins/memlab/memlab-server/` via `sync-mcp-to-plugin.sh`.

**1. Recognize the `{<array>, timestamp/loadedAt, map}` TTL-cache shape (`cache-analysis`).** The object-cache detector already matched `hasDataProp && hasTimestampProp`, but its `DATA_PROPS` set lacked `entries` and its `TIMESTAMP_PROPS` set lacked `loadedAt`, so the two most common in-process Nest cache shapes — `{entries, timestamp, map}` and `{items, loadedAt}` — were classified as "plain collection" instead of "cache-like." Added `entries`/`records`/`nodes`/`list`/`cache` to the data-property set and `loadedAt`/`loaded_at`/`cached_at`/`fetchedAt`/`fetched_at`/`lastFetched`/`lastLoaded`/`lastUpdated` to the timestamp set.

**2. Stop flagging load-once TTL caches as unbounded growth (`growth-signals`).** A large `Array` held by a `{…, loadedAt/timestamp}` wrapper is a point-in-time snapshot refreshed wholesale, not append-only growth, yet it was reported as an "append-only candidate." Added a shared `hasFreshnessTimestampSibling()` helper and skip such arrays, reporting a count of how many were excluded so the heuristic stays transparent.

**3. Detect cached failure payloads (`duplicated-strings`).** Added `looksLikeFailurePayload()` and a callout when heavily-duplicated strings look like cached error/failure responses (JSON-ish payloads carrying markers such as `UNKNOWN_FAILURE`, `"status":"…FAILURE"`, or a non-null `"error"`). These are both wasted memory and a strong signal that an upstream dependency is failing and its failures are being cached — linking a memory finding to a likely correctness bug.

New shared helpers (`FRESHNESS_TIMESTAMP_PROPS`, `hasFreshnessTimestampSibling`, `looksLikeFailurePayload`) live in `utils.ts`. All three changes are additive and backward-compatible; package/plugin versions bumped accordingly (mcp-server 2.1.2→2.2.0, internal server 2.0.6→2.1.0, plugin 1.7.0→1.8.0).

Reviewed By: boujeepossum

Differential Revision: D107701087

fbshipit-source-id: f6270b7cd9f0892758d0f53e59bdb1a75e519329

Author: JacksonGL

packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memlab/mcp-server",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "license": "MIT",
   "description": "MCP server for MemLab heap snapshot analysis — gives AI coding assistants tools to explore JavaScript heap snapshots, find memory leaks, and identify optimization opportunities",
   "author": "Liang Gong <lgong@meta.com>",

packages/mcp-server/src/tools/cache-analysis.ts

@@ -397,6 +397,14 @@ export function registerCacheAnalysis(server: McpServer): void {
             'value',
             'response',
             'payload',
+            // Common collection-property names on Nest/in-process TTL caches
+            // that were missed before (e.g. `{entries, timestamp, map}`,
+            // `{records, loadedAt}`). Feedback round 4 §B.
+            'entries',
+            'records',
+            'nodes',
+            'list',
+            'cache',
           ]);
           const TIMESTAMP_PROPS = new Set([
             'timestamp',
@@ -408,6 +416,17 @@ export function registerCacheAnalysis(server: McpServer): void {
             'ttlMs',
             'expiry',
             'createdAt',
+            // Freshness markers used by load-once warm caches. `loadedAt` in
+            // particular is a very common Nest pattern that was missed before.
+            // Feedback round 4 §B.
+            'loadedAt',
+            'loaded_at',
+            'cached_at',
+            'fetchedAt',
+            'fetched_at',
+            'lastFetched',
+            'lastLoaded',
+            'lastUpdated',
           ]);
           const CONFIG_PROPS = new Set([
             'ttlMs',

packages/mcp-server/src/tools/duplicated-strings.ts

@@ -11,7 +11,12 @@
 import type {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js';
 import {z} from 'zod';
 import {getSnapshot} from '../heap-state.js';
-import {formatBytes, errorResult, toolResult} from '../utils.js';
+import {
+  formatBytes,
+  errorResult,
+  toolResult,
+  looksLikeFailurePayload,
+} from '../utils.js';
 
 export function registerDuplicatedStrings(server: McpServer): void {
   server.tool(
@@ -181,8 +186,32 @@ export function registerDuplicatedStrings(server: McpServer): void {
               : '';
           return `${i + 1}. "${val}" x ${d.count} copies, ${d.total_size_formatted} total${savingsLabel}${actionLabel}${nodeIdsPart}${context}`;
         });
+        // Cached failure payloads: duplicated JSON-ish strings carrying an
+        // explicit failure/error marker. These are both wasted memory and a
+        // signal that an upstream dependency is failing (and that failures are
+        // being cached). Feedback round 4 §D.
+        const failurePayloads = duplicated.filter(d =>
+          looksLikeFailurePayload(d.value),
+        );
+
         const hasHeavyDups = duplicated.some(d => d.count >= 1000);
         const suggestions: string[] = [];
+        if (failurePayloads.length > 0) {
+          const totalFailureCopies = failurePayloads.reduce(
+            (sum, d) => sum + d.count,
+            0,
+          );
+          const failureBytes = failurePayloads.reduce(
+            (sum, d) => sum + d.total_size,
+            0,
+          );
+          suggestions.push(
+            `⚠️ **Cached failure payloads detected:** ${failurePayloads.length} of the duplicated strings look like cached error/failure responses ` +
+              `(${totalFailureCopies.toLocaleString('en-US')} copies, ${formatBytes(failureBytes)}). ` +
+              'This usually means an upstream dependency is failing AND those failures are being cached. ' +
+              'Check the upstream call (permissions, timeouts, bad input) and avoid caching error responses (or cache them with a short TTL).',
+          );
+        }
         if (hasHeavyDups) {
           suggestions.push(
             '**Suggested action:** Heavily duplicated strings often come from `JSON.parse()` or API responses. ' +

packages/mcp-server/src/tools/growth-signals.ts

@@ -18,6 +18,7 @@ import {
   markdownTable,
   errorResult,
   toolResult,
+  hasFreshnessTimestampSibling,
 } from '../utils.js';
 
 type KeyPattern = 'sequential-int' | 'timestamp' | 'monotonic-string' | 'mixed';
@@ -118,6 +119,10 @@ export function registerGrowthSignals(server: McpServer): void {
         const meta = getSnapshotMetadata();
         const totalSize = meta?.totalSize ?? 0;
         const candidates: GrowthCandidate[] = [];
+        // Count of large arrays skipped because they are the data side of a
+        // load-once `{entries, loadedAt}`-style TTL cache (a point-in-time
+        // snapshot, not append-only growth). Feedback round 4 §C.
+        let excludedLoadOnce = 0;
 
         const insert = (c: GrowthCandidate) => {
           let i = 0;
@@ -164,6 +169,13 @@ export function registerGrowthSignals(server: McpServer): void {
           } else if (node.name === 'Array') {
             const count = node.edge_count;
             if (count < min_entries) return;
+            // A large array held by a `{..., loadedAt/timestamp}` cache wrapper
+            // is a load-once snapshot refreshed wholesale, not append-only
+            // growth — don't flag it as a growth signal. Feedback round 4 §C.
+            if (hasFreshnessTimestampSibling(node)) {
+              excludedLoadOnce++;
+              return;
+            }
             // Heuristic: large dense arrays are append-only growth candidates.
             insert({
               nodeId: node.id,
@@ -176,9 +188,14 @@ export function registerGrowthSignals(server: McpServer): void {
           }
         });
 
+        const loadOnceNote =
+          excludedLoadOnce > 0
+            ? ` (${formatNumber(excludedLoadOnce)} large array(s) held by a \`{…, loadedAt/timestamp}\` cache wrapper were excluded as load-once snapshots, not append-only growth)`
+            : '';
+
         if (candidates.length === 0) {
           return toolResult(
-            `No growth signals found (no timestamp/sequentially-keyed collections or large arrays >= ${formatNumber(min_entries)} entries and >= ${formatBytes(min_retained_size)}). This is a single-snapshot heuristic — capture a second snapshot later and use memlab_diff_snapshots to confirm actual growth.`,
+            `No growth signals found (no timestamp/sequentially-keyed collections or large arrays >= ${formatNumber(min_entries)} entries and >= ${formatBytes(min_retained_size)})${loadOnceNote}. This is a single-snapshot heuristic — capture a second snapshot later and use memlab_diff_snapshots to confirm actual growth.`,
           );
         }
 
@@ -209,6 +226,7 @@ export function registerGrowthSignals(server: McpServer): void {
           '',
           markdownTable(headers, rows, rightCols),
           '',
+          ...(loadOnceNote ? [`_Note:${loadOnceNote}_`, ''] : []),
           '_Heuristic only — timestamp/sequential keys and large dense arrays *suggest* append-only growth but do not prove it. Confirm by capturing a later snapshot and running `memlab_diff_snapshots`, or trace one with `memlab_retainer_trace` to see what keeps it alive._',
         ];
 

packages/mcp-server/src/utils.ts

@@ -222,6 +222,72 @@ export function isNodeWorthInspecting(node: IHeapNode): boolean {
   return true;
 }
 
+/**
+ * Property names that mark a "freshness" timestamp on a TTL/warm cache wrapper
+ * object (e.g. `{entries, loadedAt}`, `{items, timestamp}`). Their presence next
+ * to a large array/Map means the collection was loaded as a point-in-time
+ * snapshot, not appended to over time. Shared by cache-analysis (to recognize
+ * the cache shape) and growth-signals (to suppress the append-only
+ * false-positive on load-once caches). Feedback round 4 §B/§C.
+ */
+export const FRESHNESS_TIMESTAMP_PROPS: ReadonlySet<string> = new Set([
+  'timestamp',
+  'loadedAt',
+  'loaded_at',
+  'ts',
+  'cachedAt',
+  'cached_at',
+  'fetchedAt',
+  'fetched_at',
+  'lastFetched',
+  'lastLoaded',
+  'lastUpdated',
+  'updatedAt',
+  'expiresAt',
+  'expiry',
+]);
+
+/**
+ * True when `node` (typically a large Array/Map) is held by a wrapper object
+ * that also carries a freshness-timestamp sibling property — i.e. it is the data
+ * side of a `{entries, loadedAt}`-style TTL/warm cache, loaded once rather than
+ * grown unboundedly.
+ */
+export function hasFreshnessTimestampSibling(node: IHeapNode): boolean {
+  for (const ref of node.referrers) {
+    if (ref.type !== 'property') continue;
+    const parent = ref.fromNode;
+    if (!parent) continue;
+    for (const edge of parent.references) {
+      if (
+        edge.type === 'property' &&
+        FRESHNESS_TIMESTAMP_PROPS.has(String(edge.name_or_index))
+      ) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Heuristic: does a (JSON-ish) string look like a cached *failure* response?
+ * Cached error payloads are both wasted memory and a signal that an upstream
+ * dependency is failing — surfacing them links a memory finding to a likely
+ * correctness bug. Conservative: requires a JSON-object/array head plus an
+ * explicit failure marker. Feedback round 4 §D.
+ */
+export function looksLikeFailurePayload(value: string): boolean {
+  const head = value.length > 4096 ? value.slice(0, 4096) : value;
+  const trimmed = head.trimStart();
+  if (!(trimmed.startsWith('{') || trimmed.startsWith('['))) return false;
+  return (
+    /\bUNKNOWN_FAILURE\b/.test(head) ||
+    /"status"\s*:\s*"[^"]*(?:FAILURE|FAILED|ERROR)/i.test(head) ||
+    /"error"\s*:\s*"(?!null)[^"]+/i.test(head)
+  );
+}
+
 export function filterLargestObjects(
   snapshot: IHeapSnapshot,
   filter: (node: IHeapNode) => boolean,