@memlab/mcp-server 2.18.1 → 2.52.0

package/README.md

@@ -76,21 +76,12 @@ Then configure (`~/.claude.json` for Claude Code, or `.mcp.json` for Cursor/Wind
 
 ## Auto-Approving Tool Permissions
 
-By default, Claude Code prompts you to approve each MCP tool call. To auto-approve all MemLab tools, add this to your `~/.claude/settings.json` (user-level) or `.claude/settings.json` (project-level):
+By default, Claude Code prompts you to approve each MCP tool call. Every MemLab tool except `memlab_eval` and `memlab_for_each` is strictly read-only heap analysis and safe to auto-approve.
 
-```json
-{
-  "permissions": {
-    "allow": [
-      "mcp__memlab__*"
-    ]
-  }
-}
-```
+> [!CAUTION]
+> **Do not auto-approve `memlab_eval` or `memlab_for_each`.** They execute arbitrary JavaScript with the full privileges of the MCP server process (see the warning under [`memlab_eval`](#memlab_eval)). Leave them on manual approval so each invocation is reviewed. Avoid the `mcp__memlab__*` wildcard, which would auto-approve them too.
 
-The naming convention is `mcp__<server-name>__*` where `memlab` matches the key you used in your MCP server config. The `*` wildcard auto-approves all tools from that server.
-
-You can also allowlist individual tools for granular control, add this to your `~/.claude/settings.json` (user-level) or `.claude/settings.json` (project-level):
+To auto-approve the read-only tools while keeping the two code-execution tools on manual approval, allowlist the read-only tools explicitly in your `~/.claude/settings.json` (user-level) or `.claude/settings.json` (project-level):
 
 ```json
 {
@@ -371,7 +362,10 @@ Input:  { report: "list"|"full_analysis"|"detached_dom"|"duplicated_strings"|...
 
 ### `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.
+Execute arbitrary JavaScript against the loaded heap snapshot. Has access to `snapshot`, `utils`, and `helpers`.
+
+> [!WARNING]
+> **This tool runs arbitrary code with the full privileges of the MCP server process.** It uses `node:vm` to scope the globals it injects, but [`node:vm` is not a security sandbox](https://nodejs.org/api/vm.html) — code can reach the host realm (e.g. `Object.constructor('return process')()`) and from there touch the filesystem, network, and shell. Treat calling `memlab_eval` as equivalent to running code on your machine. The same applies to `memlab_for_each`, whose `filter`/`map`/`reduce` code strings are executed the same way. Do not auto-approve these two tools, and be aware that heap snapshot contents are attacker-influenceable input — a prompt-injection could steer the model into running hostile code here.
 
 ```
 Input:  { code: "...", timeout_ms?: 30000 }

package/bin/.eslintrc.js

@@ -0,0 +1,26 @@
+/**
+ * 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
+ */
+
+// Files in this directory are npm `bin` entry points: package.json declares
+// them as executables, so POSIX requires `#!/usr/bin/env node` on line 1.
+//
+// `fb-www/docblock-first` treats anything preceding the file docblock as
+// disqualifying, and the shebang counts — verified by removing it, at which
+// point the rule stops firing. The two requirements are therefore mutually
+// exclusive for this directory, and the rule's stated rationale (ESLint skips
+// pragma parsing, producing spurious no-undef errors for Flow utility types)
+// does not apply: these are plain CommonJS/ESM Node scripts with no Flow types.
+//
+// Scoped to bin/ so the rule keeps applying to every other file in the package.
+module.exports = {
+  rules: {
+    'fb-www/docblock-first': 'off',
+  },
+};

package/bin/memlab-cli.js

@@ -0,0 +1,313 @@
+/**
+ * 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
+ */
+/// usr/bin/env node
+
+/**
+ * Non-MCP command line for the memlab MCP server.
+ *
+ * Why this exists: the server is only ever reachable through an MCP client, so
+ * when a host fails to attach it (a dropped stdio handshake, a plugin that never
+ * finishes connecting) every tool in the package becomes unavailable at once,
+ * with no diagnostic and no fallback. That happened in practice and cost an
+ * agent ~20 minutes and a hand-written JSON-RPC client before any heap could be
+ * analyzed at all. The server itself was healthy the whole time.
+ *
+ * This speaks the same stdio JSON-RPC the host would, so the tools stay usable
+ * without one:
+ *
+ *   memlab-cli doctor
+ *   memlab-cli list
+ *   memlab-cli schema memlab_load_snapshot
+ *   memlab-cli call memlab_snapshot_header '{"file_path":"/tmp/a.heapsnapshot"}'
+ *   memlab-cli script steps.jsonl        # one {"tool":..,"args":{..}} per line
+ *
+ * `script` (and multiple `call` pairs) reuse ONE server process, which matters:
+ * the server is stateful and a large snapshot costs minutes to load, so a
+ * process per call pays that repeatedly.
+ */
+
+import {spawn} from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import {fileURLToPath} from 'url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+function resolveServerPath() {
+  if (process.env.MEMLAB_MCP_SERVER) {
+    return process.env.MEMLAB_MCP_SERVER;
+  }
+  // Packaged layout is bin/ next to dist/; the plugin copies this script to the
+  // install root, where dist/ is a direct child.
+  const candidates = [
+    path.join(HERE, '..', 'dist', 'index.js'),
+    path.join(HERE, 'dist', 'index.js'),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) {
+      return c;
+    }
+  }
+  return candidates[0];
+}
+
+/**
+ * The interpreter to run the SERVER with, which is not necessarily the one
+ * running this CLI: `node` on PATH is frequently older than the package's
+ * `>= 18` engine requirement, and spawning the server with it fails at module
+ * load with an opaque syntax error. Mirrors the plugin start.sh lookup.
+ */
+function resolveNodeBin() {
+  if (Number(process.versions.node.split('.')[0]) >= 18) {
+    return process.execPath;
+  }
+  for (const c of ['/usr/local/bin/claude_code/node']) {
+    if (fs.existsSync(c)) {
+      return c;
+    }
+  }
+  return process.execPath;
+}
+
+class Client {
+  constructor(serverPath) {
+    this.proc = spawn(
+      resolveNodeBin(),
+      ['--max-old-space-size=8192', serverPath],
+      {stdio: ['pipe', 'pipe', 'pipe']},
+    );
+    this.nextId = 0;
+    this.buf = '';
+    this.pending = new Map();
+    this.stderr = [];
+    // Drain stderr. A chatty server that fills this pipe would otherwise block
+    // its own writes and deadlock the session.
+    this.proc.stderr.on('data', d => {
+      this.stderr.push(String(d));
+      if (this.stderr.length > 400) {
+        this.stderr.splice(0, 200);
+      }
+    });
+    this.proc.stdout.on('data', d => this.onData(String(d)));
+    this.proc.on('exit', code => {
+      for (const {reject} of this.pending.values()) {
+        reject(
+          new Error(
+            `memlab server exited (code ${code}). stderr tail:\n${this.stderr.slice(-40).join('')}`,
+          ),
+        );
+      }
+      this.pending.clear();
+    });
+  }
+
+  onData(chunk) {
+    this.buf += chunk;
+    let nl;
+    while ((nl = this.buf.indexOf('\n')) >= 0) {
+      const line = this.buf.slice(0, nl).trim();
+      this.buf = this.buf.slice(nl + 1);
+      if (!line) {
+        continue;
+      }
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const entry = this.pending.get(msg.id);
+      if (!entry) {
+        continue;
+      }
+      this.pending.delete(msg.id);
+      if (msg.error) {
+        entry.reject(new Error(JSON.stringify(msg.error)));
+      } else {
+        entry.resolve(msg.result);
+      }
+    }
+  }
+
+  request(method, params) {
+    const id = ++this.nextId;
+    this.proc.stdin.write(
+      JSON.stringify({jsonrpc: '2.0', id, method, params}) + '\n',
+    );
+    return new Promise((resolve, reject) =>
+      this.pending.set(id, {resolve, reject}),
+    );
+  }
+
+  notify(method, params) {
+    this.proc.stdin.write(
+      JSON.stringify({jsonrpc: '2.0', method, params}) + '\n',
+    );
+  }
+
+  async init() {
+    await this.request('initialize', {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: {name: 'memlab-cli', version: '1.0'},
+    });
+    this.notify('notifications/initialized', {});
+  }
+
+  async listTools() {
+    return (await this.request('tools/list', {})).tools ?? [];
+  }
+
+  async callTool(name, args) {
+    const res = await this.request('tools/call', {name, arguments: args});
+    return (res.content ?? [])
+      .map(c => (c.type === 'text' ? c.text : JSON.stringify(c)))
+      .join('\n');
+  }
+
+  close() {
+    this.proc.stdin.end();
+  }
+}
+
+async function doctor(serverPath) {
+  const major = Number(process.versions.node.split('.')[0]);
+  const nodeBin = resolveNodeBin();
+  const lines = [
+    `cli node: ${process.versions.node}${major >= 18 ? '' : ' (below the >= 18 engine requirement)'}`,
+    `server node: ${nodeBin}${nodeBin === process.execPath && major < 18 ? ' — NO >= 18 interpreter found; the server will fail to load' : ''}`,
+  ];
+  lines.push(`server path: ${serverPath}`);
+  const exists = fs.existsSync(serverPath);
+  lines.push(`server present: ${exists ? 'yes' : 'NO'}`);
+  if (!exists) {
+    lines.push(
+      'Fix: build the package (`npm run build-pkg`), or set MEMLAB_MCP_SERVER to a built dist/index.js.',
+    );
+    console.log(lines.join('\n'));
+    return 1;
+  }
+  // The decisive check: can the server actually start and answer? A corrupted
+  // or partial node_modules only shows up here, not from a file listing.
+  const client = new Client(serverPath);
+  const timer = setTimeout(() => client.proc.kill('SIGKILL'), 60000);
+  try {
+    await client.init();
+    const tools = await client.listTools();
+    lines.push(`handshake: OK`);
+    lines.push(`tools registered: ${tools.length}`);
+    console.log(lines.join('\n'));
+    return 0;
+  } catch (err) {
+    lines.push(`handshake: FAILED — ${err.message}`);
+    lines.push(
+      'Fix: check the install dir for build-errors.log / deps-check-errors.log, ' +
+        'then rebuild (the plugin start.sh does a clean rebuild when dependencies fail to load).',
+    );
+    console.log(lines.join('\n'));
+    return 1;
+  } finally {
+    clearTimeout(timer);
+    client.close();
+  }
+}
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const serverPath = resolveServerPath();
+
+  if (!cmd || cmd === '--help' || cmd === '-h') {
+    console.log(
+      [
+        'Usage: memlab-cli <command>',
+        '',
+        '  doctor                      check node, server presence, and a live handshake',
+        '  list                        list tool names and one-line descriptions',
+        '  schema <tool>               print a tool input schema as JSON',
+        '  call <tool> <json> [...]    call one or more tools in ONE server session',
+        '  script <file.jsonl>         run {"tool":..,"args":{..}} lines in ONE session',
+        '',
+        'Server is resolved from $MEMLAB_MCP_SERVER, else dist/index.js next to this script.',
+      ].join('\n'),
+    );
+    return 0;
+  }
+
+  if (cmd === 'doctor') {
+    return doctor(serverPath);
+  }
+
+  const client = new Client(serverPath);
+  try {
+    await client.init();
+    if (cmd === 'list') {
+      for (const t of await client.listTools()) {
+        console.log(`${t.name}\t${(t.description ?? '').slice(0, 150)}`);
+      }
+    } else if (cmd === 'schema') {
+      const want = rest[0];
+      const tool = (await client.listTools()).find(t => t.name === want);
+      if (!tool) {
+        console.error(`Unknown tool: ${want}`);
+        return 1;
+      }
+      console.log(JSON.stringify(tool.inputSchema ?? {}, null, 2));
+    } else if (cmd === 'call') {
+      for (let i = 0; i < rest.length; i += 2) {
+        const tool = rest[i];
+        const args = rest[i + 1] ? JSON.parse(rest[i + 1]) : {};
+        console.log(`\n===== ${tool} =====`);
+        // Sequential by construction: JSON-RPC over ONE stdio socket to a
+        // stateful server (a loaded snapshot). These cannot be parallelised —
+        // the server answers one request at a time and later calls depend on
+        // earlier ones.
+        // eslint-disable-next-line no-await-in-loop
+        console.log(await client.callTool(tool, args));
+      }
+    } else if (cmd === 'script') {
+      const file = rest[0];
+      // Sequential by construction: these are JSON-RPC calls over ONE stdio
+      // socket to a stateful server, so they cannot be parallelised — the next
+      // request depends on the previous one having been answered.
+
+      for (const raw of fs.readFileSync(file, 'utf8').split('\n')) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#')) {
+          continue;
+        }
+        const spec = JSON.parse(line);
+        console.log(`\n===== ${spec.tool} =====`);
+        // Sequential by construction: JSON-RPC over ONE stdio socket to a
+        // stateful server (a loaded snapshot). These cannot be parallelised —
+        // the server answers one request at a time and later calls depend on
+        // earlier ones.
+        // eslint-disable-next-line no-await-in-loop
+        console.log(await client.callTool(spec.tool, spec.args ?? {}));
+      }
+    } else {
+      console.error(`Unknown command: ${cmd}. Try --help.`);
+      return 1;
+    }
+    return 0;
+  } finally {
+    client.close();
+  }
+}
+
+// Terminal by construction: both arms call process.exit, so there is nothing
+// left to chain and no rejection can escape.
+// eslint-disable-next-line fb-www/promise-termination
+main().then(
+  code => process.exit(code ?? 0),
+  err => {
+    console.error(err.message ?? String(err));
+    process.exit(1);
+  },
+);

package/dist/artifact-classes.d.ts

@@ -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
+ */
+/**
+ * Registry of heap classes whose growth is a MEASUREMENT artifact rather than an
+ * application leak.
+ *
+ * Motivation: across a six-round leak hunt, every single class reported at the
+ * top of `sequence_analysis` as "↑ every step (LEAK signal)" belonged to one of
+ * the families below — CDP inspector bookkeeping, V8 JIT warmup, or captured
+ * error stacks. None was ever a leak. An agent that does not already know this
+ * list reads the label and reports a false leak, which is exactly what happened
+ * repeatedly before the families were catalogued.
+ *
+ * These are deliberately matched on CLASS NAME only. Name matching cannot prove
+ * that a given instance is an artifact, so the classification is used to
+ * annotate and down-rank rows — never to hide them outright (callers can always
+ * pass `include_artifacts: true`). Anything that is genuinely ambiguous is left
+ * unclassified on purpose: a false "this is an artifact" is far more damaging
+ * than a false "this might be a leak".
+ */
+export type ArtifactKind = 'warmup' | 'ax' | 'cdp-network' | 'cdp-perf' | 'cdp-console' | 'stack-capture';
+export declare function artifactLabel(kind: ArtifactKind): string;
+export declare function artifactNote(kind: ArtifactKind): string;
+/**
+ * Where a non-production string came from. Both kinds are equally unshippable,
+ * but they call for different follow-up: `harness` means re-run without the
+ * bridge attached to measure the app cleanly, `dev-build` means measure a
+ * production build.
+ */
+export type NonProductionStringKind = 'harness' | 'dev-build';
+/**
+ * Classify a string VALUE as non-production (harness-injected or DEV-build
+ * only), or null when it is app content that really does ship.
+ */
+export declare function classifyNonProductionString(value: string): {
+    kind: NonProductionStringKind;
+    what: string;
+} | null;
+/**
+ * Back-compatible wrapper returning just the description. Prefer
+ * {@link classifyNonProductionString} when the caller can act on the kind.
+ */
+export declare function classifyHarnessString(value: string): string | null;
+/**
+ * React Fast Refresh module-scope registries, by the edge name that binds each
+ * one. These live in the refresh runtime's closure and are reachable only
+ * through compiled-code constant pools, so a retainer-root scan does not find
+ * them and they classify as `production` unless matched by name here. See
+ * `tools/dev-artifacts` for the measured cost of missing them.
+ */
+export declare const REACT_REFRESH_REGISTRY_EDGE_NAMES: ReadonlySet<string>;
+/**
+ * The rarest property of the react-refresh signature record. Callers gate on
+ * this before confirming the full shape, so a scan stays one name compare per
+ * edge on everything else.
+ */
+export declare const REACT_REFRESH_SIGNATURE_GATE_PROP = "getCustomHooks";
+/**
+ * Recognize the per-type signature record react-refresh stores via
+ * `setSignature(type, key, forceReset, getCustomHooks)` — the value side of
+ * `allSignaturesByType`, shaped `{forceReset, ownKey, fullKey, getCustomHooks}`.
+ */
+export declare function isReactRefreshSignatureShape(propNames: Iterable<string>): boolean;
+/**
+ * Recognize the parent object SHAPE of an MCP/devtools tool manifest entry.
+ *
+ * The bridge's tool definitions carry long `.description` strings — one per tool
+ * — and a per-load intern pool would happily "save" them. The shape is
+ * distinctive enough to match directly, and matching the shape (rather than the
+ * description text) keeps app strings that merely have a `description` property
+ * out of it.
+ */
+export declare function isHarnessToolManifestShape(propNames: ReadonlyArray<string>): boolean;
+/**
+ * Classify a class NAME as a known measurement artifact, or null when it is a
+ * genuine leak candidate.
+ */
+export declare function classifyArtifact(name: string): ArtifactKind | null;
+//# sourceMappingURL=artifact-classes.d.ts.map

package/dist/artifact-classes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-classes.d.ts","sourceRoot":"","sources":["../src/artifact-classes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,IAAI,GACJ,aAAa,GACb,UAAU,GACV,aAAa,GACb,eAAe,CAAC;AAwGpB,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAExD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAEvD;AAED;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,SAAS,GAAG,WAAW,CAAC;AAkE9D;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,GACZ;IAAC,IAAI,EAAE,uBAAuB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAAG,IAAI,CAKtD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAElE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,WAAW,CAAC,MAAM,CAWhE,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,mBAAmB,CAAC;AASlE;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,GAC1B,OAAO,CAOT;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,GAC/B,OAAO,CAQT;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CASlE"}