@plur-ai/mcp 0.20.1 → 0.21.1

package/dist/server-EHKHU4JH.js

@@ -0,0 +1,1006 @@
+import {
+  CURSOR_CORE_TOOL_NAMES,
+  FOLDER_SCOPE,
+  folderMapAdvice,
+  folderOnCommand,
+  getToolDefinitions,
+  mcpCanary,
+  registerFlushOnExit,
+  resolveToolProfile,
+  setActiveToolProfile,
+  validateToolArgs
+} from "./chunk-OETJSRYE.js";
+import {
+  VERSION
+} from "./chunk-O2NJFMNP.js";
+
+// src/server.ts
+import { Server, ProtocolError, ProtocolErrorCode } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { join as join2 } from "path";
+import { homedir } from "os";
+import { Plur, checkForUpdate, VERSION_CHECK_SUCCESS_TTL_MS } from "@plur-ai/core";
+
+// src/drop-log.ts
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { atomicWrite, withLock } from "@plur-ai/core";
+var PAYLOAD_DROP_LOG_MAX_ENTRIES = 500;
+function payloadDropLogPath(storageRoot) {
+  return join(storageRoot, "logs", "payload-drops.jsonl");
+}
+function recordPayloadDrop(storageRoot, record) {
+  try {
+    const path = payloadDropLogPath(storageRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    withLock(path, () => {
+      appendFileSync(path, JSON.stringify(record) + "\n");
+      const lines = readFileSync(path, "utf8").split("\n").filter((l) => l.length > 0);
+      if (lines.length > PAYLOAD_DROP_LOG_MAX_ENTRIES) {
+        atomicWrite(path, lines.slice(-PAYLOAD_DROP_LOG_MAX_ENTRIES).join("\n") + "\n", { durable: false });
+      }
+    });
+  } catch {
+  }
+}
+
+// src/folder-gate.ts
+import {
+  folderOffEntries,
+  folderMapProblem,
+  folderAsk,
+  hostFolderAsk,
+  folderNonceOutstanding,
+  endFolderNonceSession,
+  sweepFolderNonces,
+  coversHomeOrRoot,
+  workspaceFolderScope,
+  FOLDER_NONCE_TTL_MS
+} from "@plur-ai/core";
+import { fileURLToPath } from "url";
+import { randomBytes } from "crypto";
+import { execFileSync } from "child_process";
+import { realpathSync } from "fs";
+import { dirname as dirname2, resolve } from "path";
+var FOLDER_GATED_TOOLS = /* @__PURE__ */ new Set([
+  // write engrams
+  "plur_learn",
+  "plur_learn_batch",
+  "plur_feedback",
+  "plur_pin",
+  "plur_forget",
+  "plur_ingest",
+  "plur_promote",
+  "plur_rescope",
+  "plur_episode_to_engram",
+  "plur_report_failure",
+  "plur_extract_meta",
+  "plur_validate_meta",
+  "plur_tensions",
+  "plur_tensions_purge",
+  "plur_packs_install",
+  "plur_packs_uninstall",
+  // read engrams
+  "plur_recall",
+  "plur_recall_hybrid",
+  "plur_inject",
+  "plur_inject_hybrid",
+  "plur_similarity_search",
+  "plur_meta_engrams",
+  "plur_history",
+  "plur_provenance",
+  "plur_profile",
+  "plur_packs_export",
+  // episodes and sessions
+  "plur_capture",
+  "plur_timeline",
+  "plur_session_start",
+  "plur_session_end",
+  // move engrams between the local store and a remote
+  "plur_sync",
+  "plur_outbox",
+  // returns the statements of recently retrieved engrams
+  "plur_receipt"
+]);
+function log(line) {
+  try {
+    process.stderr.write(`[plur] ${line}
+`);
+  } catch {
+  }
+}
+function unreadable(problem, root) {
+  const advice = folderMapAdvice(problem, root);
+  return {
+    success: true,
+    plur: "off",
+    reason: "folder-map-unreadable",
+    file: problem.file,
+    ...problem.line !== void 0 ? { line: problem.line } : {},
+    ...problem.column !== void 0 ? { column: problem.column } : {},
+    fixable: problem.fixable,
+    ...advice.command ? { repair_command: advice.command } : {},
+    ...advice.summary ? { repair_summary: advice.summary } : {},
+    message: `PLUR memory is paused: the folder map ${JSON.stringify(problem.file)} ${problem.problem}. Until it is fixed, PLUR cannot tell whether memory is allowed in this folder, so nothing was read from or written to memory. This is not an error \u2014 carry on without memory. ${advice.text}`
+  };
+}
+function folderOffAnswer(plur, dirs) {
+  const root = plur.storageRoot;
+  let problem;
+  try {
+    problem = folderMapProblem(root);
+  } catch (err) {
+    problem = { file: `${root}/folders.yaml`, problem: `could not be checked (${err?.message ?? err})`, fixable: false };
+  }
+  if (problem) {
+    log(`folder map ${problem.file} ${problem.problem}; memory tools do nothing until it is fixed.`);
+    return unreadable(problem, root);
+  }
+  for (const dir of dirs) {
+    let mode;
+    try {
+      mode = plur.resolveFolderPolicy(dir).mode;
+    } catch (err) {
+      const why = `could not be applied to ${JSON.stringify(dir)} (${err?.message ?? err})`;
+      log(`folder map: ${why}; memory tools do nothing.`);
+      return unreadable({ file: `${root}/folders.yaml`, problem: why, fixable: false }, root);
+    }
+    if (mode !== "off") continue;
+    let entries = [];
+    try {
+      entries = folderOffEntries(dir, { root }).map((e) => e.path);
+    } catch {
+    }
+    if (entries.length === 0) entries = [dir];
+    const cmds = entries.map((e) => folderOnCommand(e, root));
+    const how = cmds.every((c) => c !== null) ? cmds.join(entries.length > 1 ? " and " : "") : `plur folders set <folder> --on for ${entries.length > 1 ? "each of " : ""}${entries.map((e) => JSON.stringify(e)).join(", ")} (see plur folders list)`;
+    const through = entries.length === 1 && entries[0] === dir ? "" : ` through ${entries.length > 1 ? "the entries" : "the entry"} ${entries.map((e) => JSON.stringify(e)).join(", ")}`;
+    return {
+      success: true,
+      plur: "off",
+      folder: dir,
+      message: `PLUR is off for this folder (${JSON.stringify(dir)}): your folder map turns memory off here${through}, so nothing was read from or written to memory. This is not an error \u2014 carry on without memory. Only the user can turn it back on, from a terminal: ${how}`
+    };
+  }
+  return null;
+}
+function createWorkspaceDirs(server, opts = {}) {
+  const timeout = opts.timeoutMs ?? 2e3;
+  const cwd = opts.cwd ?? (() => process.cwd());
+  let cached = null;
+  let gen = 0;
+  let pending = null;
+  server.setNotificationHandler("notifications/roots/list_changed", () => {
+    gen++;
+    cached = null;
+    pending = null;
+  });
+  const request = (g) => server.listRoots(void 0, { timeout }).then(
+    ({ roots }) => {
+      const dirs = [];
+      for (const r of roots) {
+        let dir = null;
+        try {
+          if (typeof r.uri === "string" && /^file:\/\//i.test(r.uri)) dir = fileURLToPath(r.uri.replace(/^file:/i, "file:"));
+        } catch {
+          dir = null;
+        }
+        if (dir === null) {
+          log(`a workspace root the server cannot resolve to a local folder (${JSON.stringify(String(r.uri).slice(0, 200))}); memory tools do nothing for this call.`);
+          return null;
+        }
+        dirs.push(dir);
+      }
+      if (g === gen && listChanged()) cached = { gen: g, dirs };
+      return dirs;
+    },
+    (err) => {
+      log(`roots/list failed (${err?.message ?? err}); memory tools do nothing for this call, the next call asks the client again.`);
+      return null;
+    }
+  ).finally(() => {
+    if (pending?.gen === g) pending = null;
+  });
+  const listChanged = () => {
+    const roots = server.getClientCapabilities()?.roots;
+    return roots?.listChanged === true;
+  };
+  const clientRoots = async () => {
+    if (!server.getClientCapabilities()?.roots) return [];
+    for (let attempt = 0; attempt < 3; attempt++) {
+      if (cached && cached.gen === gen) return cached.dirs;
+      const g = gen;
+      let promise;
+      if (listChanged()) {
+        if (!pending || pending.gen !== g) pending = { gen: g, promise: request(g) };
+        promise = pending.promise;
+      } else {
+        promise = request(g);
+      }
+      const dirs = await promise;
+      if (dirs === null) return null;
+      if (g === gen) return dirs;
+    }
+    return null;
+  };
+  return {
+    async dirs() {
+      const roots = await clientRoots();
+      return roots === null ? null : [.../* @__PURE__ */ new Set([...roots, cwd()])];
+    },
+    async workspace() {
+      const roots = await clientRoots();
+      return roots === null ? null : { roots: [...new Set(roots)], cwd: cwd() };
+    }
+  };
+}
+function workspaceUnknownAnswer() {
+  return {
+    success: true,
+    plur: "off",
+    reason: "workspace-unknown",
+    message: `PLUR couldn't get the editor's workspace folders (the MCP roots request failed, timed out, or named a folder that is not on this machine), so it cannot tell whether memory is allowed here: memory is off for this call, and nothing was read from or written to memory. This is not an error. The next call will ask again; if the editor's roots keep failing, memory stays off until they work.`
+  };
+}
+function parseEtime(etime) {
+  const m = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/.exec(etime.trim());
+  if (!m) return null;
+  return Number(m[1] ?? 0) * 86400 + Number(m[2] ?? 0) * 3600 + Number(m[3]) * 60 + Number(m[4]);
+}
+function ancestorHosts(now = Date.now()) {
+  if (process.platform === "win32") return [];
+  let table;
+  try {
+    table = execFileSync("ps", ["-A", "-o", "pid=,ppid=,etime="], { encoding: "utf8", timeout: 2e3, stdio: ["ignore", "pipe", "ignore"] });
+  } catch {
+    return [];
+  }
+  const info = /* @__PURE__ */ new Map();
+  for (const line of table.split("\n")) {
+    const m = /^\s*(\d+)\s+(\d+)\s+(\S+)\s*$/.exec(line);
+    if (!m) continue;
+    const secs = parseEtime(m[3]);
+    if (secs === null) continue;
+    info.set(Number(m[1]), { ppid: Number(m[2]), startedAt: now - secs * 1e3 });
+  }
+  const out = [];
+  let pid = process.ppid;
+  while (pid > 1 && out.length < 8 && !out.some((h) => h.pid === pid)) {
+    const i = info.get(pid);
+    if (!i) break;
+    out.push({ pid, startedAt: i.startedAt });
+    pid = i.ppid;
+  }
+  return out;
+}
+function workspaceWriteScope(plur, ws) {
+  return workspaceFolderScope(ws.roots.length > 0 ? ws.roots : [ws.cwd], (dir) => plur.resolveFolderPolicy(dir));
+}
+function workspaceKey(ws) {
+  const inputs = ws.roots.length > 0 ? ws.roots : [ws.cwd];
+  const real = inputs.map((i) => {
+    try {
+      return realpathSync.native(i);
+    } catch {
+      return resolve(i);
+    }
+  });
+  return JSON.stringify([ws.roots.length > 0 ? "roots" : "cwd", ...[...new Set(real)].sort()]);
+}
+function isHomeOrAbove(dir) {
+  try {
+    return coversHomeOrRoot(dir);
+  } catch {
+    return true;
+  }
+}
+function isFilesystemRoot(dir) {
+  const r = resolve(dir);
+  return dirname2(r) === r;
+}
+function createFolderGate(plur, opts = {}) {
+  const sessionId = opts.sessionId ?? `mcp-${randomBytes(8).toString("hex")}`;
+  try {
+    sweepFolderNonces(plur.storageRoot);
+  } catch {
+  }
+  const asked = /* @__PURE__ */ new Map();
+  const notNow = /* @__PURE__ */ new Set();
+  let ended = false;
+  const reissueAfter = Math.max(0, FOLDER_NONCE_TTL_MS - 6e4);
+  let hosts = null;
+  const hostList = () => {
+    if (hosts === null) {
+      try {
+        hosts = (opts.hosts ?? ancestorHosts)();
+      } catch {
+        hosts = [];
+      }
+    }
+    return hosts;
+  };
+  const hosted = /* @__PURE__ */ new Map();
+  const notNowAnswer = (folder) => ({
+    success: true,
+    plur: "off",
+    reason: "not-now",
+    folder,
+    message: `PLUR memory is off in this folder (${JSON.stringify(folder)}) for the rest of this session: the user answered "not now" to the folder question, so nothing was read from or written to memory. This is not an error \u2014 carry on without memory, and do not ask again. The folder is still undecided; a new session will ask.`
+  });
+  const askFor = (dir, policy) => {
+    const outstanding = (nonce) => {
+      try {
+        return folderNonceOutstanding(plur.storageRoot, sessionId, nonce);
+      } catch {
+        return false;
+      }
+    };
+    let entry = asked.get(dir);
+    if (entry?.ask.notNowNonce !== void 0) {
+      const notNowNonce = entry.ask.notNowNonce;
+      const answered = !outstanding(notNowNonce) && entry.ask.nonces.some((n) => n !== notNowNonce && outstanding(n));
+      if (answered) {
+        log(`folder ${JSON.stringify(entry.ask.folder)}: the user answered "not now"; memory tools do nothing for the rest of this session.`);
+        notNow.add(dir);
+        asked.delete(dir);
+        return notNowAnswer(entry.ask.folder);
+      }
+    }
+    if (entry && (!entry.ask.notice && Date.now() - entry.issuedAt > reissueAfter || entry.reason !== policy.reason)) {
+      asked.delete(dir);
+      entry = void 0;
+    }
+    if (entry && entry.ask.nonces.some((n) => !outstanding(n))) {
+      asked.delete(dir);
+      entry = void 0;
+    }
+    if (!entry && !ended) {
+      const shown = hosted.get(dir);
+      if (shown) {
+        const hostSession = shown.hostSession;
+        const inHost = (n) => {
+          try {
+            return hostSession !== void 0 && folderNonceOutstanding(plur.storageRoot, hostSession, n);
+          } catch {
+            return false;
+          }
+        };
+        const nn = shown.notNowNonce;
+        if (nn !== void 0 && !inHost(nn) && shown.nonces.some((n) => n !== nn && inHost(n))) {
+          log(`folder ${JSON.stringify(shown.folder)}: the user answered "not now"; memory tools do nothing for the rest of this session.`);
+          hosted.delete(dir);
+          notNow.add(dir);
+          return notNowAnswer(shown.folder);
+        }
+        let still = null;
+        try {
+          still = hostFolderAsk({ dir, policy, root: plur.storageRoot, hosts: hostList(), plur });
+        } catch {
+        }
+        if (still && still.nonces.every((n) => shown.nonces.includes(n))) {
+          return { success: true, plur: "ask", folder: shown.folder, question: shown.text, answers: shown.answers };
+        }
+        hosted.delete(dir);
+      } else {
+        let found = null;
+        try {
+          const list = hostList();
+          if (list.length > 0) found = hostFolderAsk({ dir, policy, root: plur.storageRoot, hosts: list, offerNotNow: true, plur });
+        } catch (err) {
+          log(`folder question of the host process could not be read (${err?.message ?? err}).`);
+        }
+        if (found && !found.notice) {
+          hosted.set(dir, found);
+          return { success: true, plur: "ask", folder: found.folder, question: found.text, answers: found.answers };
+        }
+      }
+    }
+    if (!entry && ended) {
+      return {
+        success: true,
+        plur: "off",
+        reason: "folder-ask-failed",
+        folder: dir,
+        message: `PLUR has no decision for this folder (${JSON.stringify(dir)}) and this session is closing, so it did not ask; nothing was read from or written to memory. This is not an error. A new session will ask.`
+      };
+    }
+    if (!entry) {
+      let ask = null;
+      try {
+        ask = folderAsk({ dir, policy, sessionId, root: plur.storageRoot, plur, claim: () => true, bindSession: true, mcp: true });
+      } catch (err) {
+        log(`folder question for ${JSON.stringify(dir)} could not be built (${err?.message ?? err}).`);
+      }
+      if (!ask) {
+        return {
+          success: true,
+          plur: "off",
+          reason: "folder-ask-failed",
+          folder: dir,
+          message: `PLUR has no decision for this folder (${JSON.stringify(dir)}) and could not prepare the question that asks the user, so nothing was read from or written to memory. This is not an error \u2014 carry on without memory. The next call tries again; the user can also decide from a terminal: plur folders set <folder> --on | --off.`
+        };
+      }
+      entry = { ask, issuedAt: Date.now(), ...policy.reason ? { reason: policy.reason } : {} };
+      asked.set(dir, entry);
+    }
+    if (entry.ask.notice) {
+      return { success: true, plur: "off", reason: "folder-cannot-be-asked", folder: entry.ask.folder, message: entry.ask.text };
+    }
+    return { success: true, plur: "ask", folder: entry.ask.folder, question: entry.ask.text, answers: entry.ask.answers };
+  };
+  return {
+    sessionId,
+    check(workspace) {
+      const off = folderOffAnswer(plur, [.../* @__PURE__ */ new Set([...workspace.roots, workspace.cwd])]);
+      if (off) return off;
+      const usableRoots = workspace.roots.filter((r) => !isHomeOrAbove(r));
+      const askable = usableRoots.length > 0 ? usableRoots : isHomeOrAbove(workspace.cwd) ? [] : [workspace.cwd];
+      const on = [];
+      for (const dir of askable) {
+        if (isFilesystemRoot(dir)) continue;
+        let policy;
+        try {
+          policy = plur.resolveFolderPolicy(dir);
+        } catch (err) {
+          const why = `could not be applied to ${JSON.stringify(dir)} (${err?.message ?? err})`;
+          log(`folder map: ${why}; memory tools do nothing.`);
+          return unreadable({ file: `${plur.storageRoot}/folders.yaml`, problem: why, fixable: false }, plur.storageRoot);
+        }
+        if (policy.mode === "ask") {
+          if (notNow.has(dir)) return notNowAnswer(asked.get(dir)?.ask.folder ?? dir);
+          return askFor(dir, policy);
+        }
+        on.push({ dir, ...policy.scope ? { scope: policy.scope } : {} });
+      }
+      const scope = workspaceWriteScope(plur, workspace) ?? void 0;
+      for (const { dir } of on) {
+        hosted.delete(dir);
+        if (!asked.has(dir)) continue;
+        asked.delete(dir);
+        notNow.delete(dir);
+      }
+      return { plur: "on", ...scope ? { scope } : {} };
+    },
+    end() {
+      ended = true;
+      asked.clear();
+      hosted.clear();
+      try {
+        endFolderNonceSession(plur.storageRoot, sessionId);
+      } catch {
+      }
+    }
+  };
+}
+
+// src/server.ts
+function serverPidPath(baseDir) {
+  return join2(baseDir ?? join2(homedir(), ".plur"), "server.pid");
+}
+function readEnterpriseToken(baseDir) {
+  const configPath = join2(baseDir ?? join2(homedir(), ".plur"), "config.json");
+  if (!existsSync2(configPath)) return void 0;
+  try {
+    const cfg = JSON.parse(readFileSync2(configPath, "utf8"));
+    const ent = cfg?.enterprise;
+    if (!ent || typeof ent.url !== "string" || typeof ent.token !== "string") return void 0;
+    return { url: ent.url, token: ent.token, username: ent.username };
+  } catch {
+    return void 0;
+  }
+}
+var _pendingReload = false;
+function isPendingReload() {
+  return _pendingReload;
+}
+function clearPendingReload() {
+  _pendingReload = false;
+}
+var INSTRUCTIONS = `PLUR is your persistent memory. Corrections, preferences, and conventions persist across sessions as engrams.
+
+PLUR is a GLOBAL tool \u2014 one MCP server, one engram store (~/.plur/), available in every project. Multi-project scoping uses domain/scope fields on engrams, not separate installations.
+
+TOOL PROFILE: by default only the core session tools are exposed directly (lean profile). Every other plur_* operation is reachable via plur_admin: { action: "<tool name>", args: {...} } \u2014 same arguments and validation as a direct call. A plur_* name missing from tools/list means it MOVED behind plur_admin, not that the MCP is down \u2014 never conclude the server is unavailable from a name-lookup miss. Discover the live surface with plur_admin { action: "help" } (every action with description + argument schema) or plur_doctor (tool_surface). PLUR_TOOL_PROFILE=full exposes everything directly.
+
+SESSION LIFECYCLE:
+- With hooks installed (plur init): engrams are injected automatically on first message. You do NOT need to call plur_session_start \u2014 it happens via hooks. Just call plur_session_end before the conversation ends.
+- Without hooks: call plur_session_start at the start, plur_session_end at the end.
+
+DURING the session:
+- When user corrects you ("no, use X not Y") \u2192 call plur_learn immediately
+- When user states a preference ("always X", "never Y") \u2192 call plur_learn immediately
+- When you discover a codebase convention or pattern \u2192 call plur_learn
+
+EVERY REPLY: End every reply with one short line: \`Memory \u2014 recalled N \xB7 used: ENG-\u2026, ENG-\u2026 \xB7 written: ENG-\u2026\` (recalled as a count; used and written as ids only, no statements), or \`Memory \u2014 none\`. Only count/list ids you actually saw this turn; never invent an id. Give details only if the user asks.
+
+SCOPE SELECTION (set scope PER engram, by content \u2014 not once per session):
+A single session produces engrams that belong in different stores. Choose the
+"scope" on EACH plur_learn call from what the engram is about:
+- Team / engineering / architecture / shared-convention knowledge \u2192 the matching
+  team store scope (e.g. "group:<org>/<team>"). plur_session_start lists the
+  scopes this install can write to \u2014 use them.
+- Personal preferences, your workflow, or details specific to one project \u2192 the
+  default/local scope (or "project:<name>").
+- "global" is for genuinely cross-project facts only (language gotchas, tool
+  quirks). Do NOT let team-relevant knowledge fall back to "global" by omitting
+  scope \u2014 with a team store configured it never reaches the team store. If no
+  scope fits, prefer the project/local default over global.
+
+OPTIONAL but improves quality:
+- Call plur_feedback to rate which injected engrams helped (positive/negative)
+- Call plur_recall before answering factual questions \u2014 the answer may be in memory
+
+Do not ask permission to use these tools \u2014 they are your memory system.
+
+FOLDERS WHERE PLUR IS OFF: the user can turn memory off for a folder (plur folders set <folder> --off). In that folder the memory tools (learn, recall, inject, session start/end, capture, feedback, receipt, \u2026) read and write nothing and answer { plur: "off", message } instead \u2014 not an error. The same answer, with reason "folder-map-unreadable", comes back when the user's folder map is broken, and with reason "workspace-unknown" when your client's workspace roots could not be fetched (that one retries by itself on the next call). Carry on without memory and do not retry or work around it; only the user can turn it back on, from a terminal (the message names the command). For a broken map the message names the line and the problem; when it carries a repair_command (plur folders repair --yes), tell the user what is wrong, show them repair_summary (what the repair changes), and run that command only after they agree. plur_status and plur_doctor keep working.
+
+Setup: If this is a fresh install, suggest the user run: npx @plur-ai/mcp init
+This installs hooks for automatic injection + session management. One-time global setup.`;
+var GUIDE_RESOURCE = `# PLUR \u2014 Agent Guide
+
+## What is PLUR?
+
+Persistent memory for AI agents. Corrections, preferences, and conventions are stored as **engrams** \u2014 small assertions that strengthen with use and decay when irrelevant (ACT-R model). Storage is plain YAML on disk. Search runs locally (BM25 + embeddings); when an enterprise/remote store is configured AND relevant to the current project, recall additionally makes one live timeout-bounded call per remote host and merges the results \u2014 degradation is surfaced per host via a \`remote_stores\` block, never silent. With no remote store configured, search is fully local with zero API calls.
+
+## Quick Start
+
+1. \`plur_session_start\` \u2014 start a session, inject relevant context
+2. \`plur_learn\` \u2014 store a new learning
+3. \`plur_feedback\` \u2014 rate injected engrams
+4. \`plur_session_end\` \u2014 capture summary and new learnings
+
+## When to Call Each Tool
+
+| Trigger | Tool |
+|---------|------|
+| Session starts | \`plur_session_start\` with task description |
+| User corrects you | \`plur_learn\` with the correction |
+| User states preference ("always X", "never Y") | \`plur_learn\` with scope and type |
+| You used a recalled engram successfully | \`plur_feedback\` with "positive" |
+| A recalled engram was wrong or irrelevant | \`plur_feedback\` with "negative" |
+| User says "forget X" or a memory is outdated | \`plur_forget\` |
+| You need to check what's stored | \`plur_status\` or \`plur_packs_list\` |
+| User asks what memory did for them / is memory working | \`plur_receipt\` (relay its \`summary\`; activation_rate is coverage, not quality) |
+| End of session | \`plur_session_end\` with summary and suggestions |
+
+## Tool Categories
+
+### Session Management
+- **plur_session_start** \u2014 start a session, inject relevant context
+- **plur_session_end** \u2014 end a session, capture summary and new learnings
+
+### Core Memory
+- **plur_learn** \u2014 store a correction, preference, or convention
+- **plur_recall** \u2014 hybrid search by default (BM25 + embeddings); pass mode:"keyword" for BM25-only
+- **plur_feedback** \u2014 rate an engram (trains relevance)
+- **plur_forget** \u2014 retire an outdated engram
+- **plur_promote** \u2014 activate a candidate engram (status only \u2014 never changes scope)
+- **plur_rescope** \u2014 move an engram to another scope (e.g. promote a local engram into a team store)
+
+### Context Injection
+- **plur_inject** \u2014 select engrams for a task (BM25)
+- **plur_inject_hybrid** \u2014 select engrams for a task (BM25 + embeddings, recommended)
+
+### Episodic Timeline
+- **plur_capture** \u2014 record what happened in a session
+- **plur_timeline** \u2014 query past episodes
+
+### Knowledge Management
+- **plur_ingest** \u2014 extract engrams from text content
+- **plur_packs_install** \u2014 install curated engram packs
+- **plur_packs_list** \u2014 list installed packs
+- **plur_packs_export** \u2014 export engrams as a shareable pack
+
+### Multi-Store
+- **plur_stores_add** \u2014 register an additional engram store
+- **plur_stores_list** \u2014 list all configured stores
+
+**Note:** Multi-store is currently config-only. Recall and inject search the primary store. Cross-store search coming in a future release.
+
+### Sync & Status
+- **plur_sync** \u2014 sync engrams across devices via git
+- **plur_sync_status** \u2014 check sync state
+- **plur_status** \u2014 system health
+- **plur_receipt** \u2014 counted report of what memory retrieved for the user (local, read-only)
+
+## Scoping
+
+Use \`scope\` to namespace engrams per project:
+- \`scope: "global"\` \u2014 applies everywhere (default)
+- \`scope: "project:my-app"\` \u2014 applies only to my-app
+- Scoped recall automatically includes global engrams
+
+## Storage
+
+\`\`\`
+~/.plur/
+\u251C\u2500\u2500 engrams.yaml     # learned knowledge
+\u251C\u2500\u2500 episodes.yaml    # session timeline
+\u2514\u2500\u2500 config.yaml      # settings
+\`\`\`
+
+Override with \`PLUR_PATH\` environment variable.
+`;
+var _whenIdle = /* @__PURE__ */ new WeakMap();
+var _endFolderQuestion = /* @__PURE__ */ new WeakMap();
+async function closeWhenIdle(server, timeoutMs) {
+  try {
+    _endFolderQuestion.get(server)?.();
+  } catch {
+  }
+  await new Promise((r) => setTimeout(r, 10));
+  await (_whenIdle.get(server)?.(timeoutMs) ?? Promise.resolve());
+  await server.close().catch(() => {
+  });
+}
+var versionRecheckTimer;
+async function createServer(plur, options) {
+  const instance = plur ?? new Plur();
+  const profile = options?.profile ?? "lean";
+  setActiveToolProfile(profile);
+  const tools = getToolDefinitions(profile);
+  const announceUpdate = (r) => {
+    if (r.updateAvailable) {
+      console.error(`[plur] Update available: ${r.current} \u2192 ${r.latest}. Run: npm i -g @plur-ai/cli@latest && plur init (configs pin versions)`);
+    }
+  };
+  checkForUpdate("@plur-ai/mcp", VERSION, announceUpdate);
+  if (!versionRecheckTimer) {
+    versionRecheckTimer = setInterval(() => {
+      checkForUpdate("@plur-ai/mcp", VERSION, announceUpdate);
+    }, VERSION_CHECK_SUCCESS_TTL_MS);
+    versionRecheckTimer.unref?.();
+  }
+  const server = new Server(
+    { name: "plur-mcp", version: VERSION },
+    {
+      capabilities: {
+        tools: {},
+        resources: {},
+        prompts: {},
+        logging: {}
+      },
+      instructions: INSTRUCTIONS
+    }
+  );
+  let inFlight = 0;
+  let idleWaiters = [];
+  const trackInFlight = async (fn) => {
+    inFlight++;
+    try {
+      return await fn();
+    } finally {
+      inFlight--;
+      if (inFlight === 0) {
+        setImmediate(() => {
+          if (inFlight === 0) {
+            const w = idleWaiters;
+            idleWaiters = [];
+            w.forEach((f) => f());
+          }
+        });
+      }
+    }
+  };
+  _whenIdle.set(server, (timeoutMs) => new Promise((resolve2) => {
+    if (inFlight === 0) return resolve2();
+    const timer = timeoutMs === void 0 ? void 0 : setTimeout(resolve2, timeoutMs);
+    timer?.unref?.();
+    idleWaiters.push(() => {
+      if (timer) clearTimeout(timer);
+      resolve2();
+    });
+  }));
+  const workspace = createWorkspaceDirs(server);
+  const folderGate = createFolderGate(instance);
+  _endFolderQuestion.set(server, () => folderGate.end());
+  const priorOnClose = server.onclose;
+  server.onclose = () => {
+    folderGate.end();
+    priorOnClose?.();
+  };
+  server.setRequestHandler("tools/list", async () => ({
+    tools: tools.map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema,
+      ...t.annotations && { annotations: t.annotations }
+    }))
+  }));
+  server.setRequestHandler("tools/call", (request) => trackInFlight(async () => {
+    const tool = tools.find((t) => t.name === request.params.name);
+    if (!tool) {
+      const hidden = getToolDefinitions("full").find((t) => t.name === request.params.name);
+      if (hidden) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({
+            error: `Tool "${request.params.name}" exists but is not directly callable under the current tool profile.`,
+            success: false,
+            hint: `Call it via plur_admin: { action: "${request.params.name}", args: { ... } } \u2014 same arguments, same validation, same result. To expose all tools directly, set PLUR_TOOL_PROFILE=full.`
+          }) }],
+          isError: true
+        };
+      }
+      return {
+        content: [{ type: "text", text: JSON.stringify({ error: `Unknown tool: ${request.params.name}`, success: false }) }],
+        isError: true
+      };
+    }
+    const gated = tool.name === "plur_admin" ? request.params.arguments?.action : tool.name;
+    let admittedWs = null;
+    if (typeof gated === "string" && FOLDER_GATED_TOOLS.has(gated)) {
+      const ws = await workspace.workspace();
+      const decision = ws === null ? workspaceUnknownAnswer() : folderGate.check(ws);
+      if (decision.plur !== "on") return { content: [{ type: "text", text: JSON.stringify(decision, null, 2) }] };
+      admittedWs = ws;
+    }
+    mcpCanary.tick();
+    try {
+      const rawArguments = request.params.arguments;
+      let args = rawArguments ?? {};
+      const validated = validateToolArgs(tool, args);
+      if (!validated.ok) {
+        const drop = validated.errorPayload.drop;
+        if (drop) {
+          recordPayloadDrop(instance.storageRoot, {
+            ts: (/* @__PURE__ */ new Date()).toISOString(),
+            tool: request.params.name,
+            arguments_wire: drop === "whole_payload" ? rawArguments === void 0 ? "absent" : "empty_object" : "partial",
+            params_keys: Object.keys(request.params ?? {}),
+            received_fields: validated.errorPayload.received_fields,
+            missing_fields: validated.errorPayload.missing_fields,
+            missing_array_params: validated.missingArrayParams,
+            request_id: request.id,
+            server_version: VERSION
+          });
+          try {
+            void Promise.resolve(server.sendLoggingMessage({
+              level: "warning",
+              data: `Payload drop (#772) on ${request.params.name}: arguments ${rawArguments === void 0 ? "key absent from frame" : `arrived with fields [${validated.errorPayload.received_fields.join(", ")}]`}. Recorded in ${payloadDropLogPath(instance.storageRoot)}.`
+            })).catch(() => {
+            });
+          } catch {
+          }
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify(validated.errorPayload) }],
+          isError: true
+        };
+      }
+      args = validated.data;
+      const folderContext = {
+        resolve: async () => {
+          const ws = await workspace.workspace();
+          return ws === null ? null : { scope: workspaceWriteScope(instance, ws), key: workspaceKey(ws) };
+        },
+        ...admittedWs !== null ? { admitted: () => ({ scope: workspaceWriteScope(instance, admittedWs), key: workspaceKey(admittedWs) }) } : {}
+      };
+      args = { ...args, [FOLDER_SCOPE]: folderContext };
+      const result = await tool.handler(args, instance);
+      let payload = result;
+      let resultIsError = false;
+      if (result && typeof result === "object" && result._isError === true) {
+        resultIsError = true;
+        const { _isError, ...rest } = result;
+        payload = rest;
+      }
+      return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        ...resultIsError ? { isError: true } : {}
+      };
+    } catch (err) {
+      const message = String(err?.message ?? err).split("\n", 1)[0];
+      server.sendLoggingMessage({ level: "error", data: `Tool ${request.params.name} failed: ${message}` });
+      return {
+        content: [{ type: "text", text: JSON.stringify({ error: message, success: false }) }],
+        isError: true
+      };
+    }
+  }));
+  server.setRequestHandler("resources/list", async () => ({
+    resources: [
+      {
+        uri: "plur://guide",
+        name: "PLUR Agent Guide",
+        description: "Complete reference for all PLUR tools, when to use them, scoping, and storage",
+        mimeType: "text/markdown"
+      },
+      {
+        uri: "plur://status",
+        name: "PLUR Status",
+        description: "Live system health \u2014 engram count, episode count, pack count, storage path",
+        mimeType: "application/json"
+      }
+    ]
+  }));
+  server.setRequestHandler("resources/read", async (request) => {
+    const uri = request.params.uri;
+    if (uri === "plur://guide") {
+      const cursorNote = options?.profile === "cursor" || options?.profile === "lean" || options?.profile == null ? `
+
+## Lean tool profile (default)
+
+Most tools above are NOT directly callable in this session \u2014 only ${[...CURSOR_CORE_TOOL_NAMES].join(", ")} are top-level tools here. Everything else in this guide is reachable through **plur_admin**: call it with \`{ action: "<tool name above>", args: {...} }\`. Set \`PLUR_TOOL_PROFILE=full\` to expose all ${getToolDefinitions("full").length} tools directly.` : "";
+      return {
+        contents: [{
+          uri: "plur://guide",
+          mimeType: "text/markdown",
+          text: GUIDE_RESOURCE + cursorNote
+        }]
+      };
+    }
+    if (uri === "plur://status") {
+      const status = await instance.status();
+      return {
+        contents: [{
+          uri: "plur://status",
+          mimeType: "application/json",
+          text: JSON.stringify({
+            engram_count: status.engram_count,
+            episode_count: status.episode_count,
+            pack_count: status.pack_count,
+            storage_root: status.storage_root,
+            version: VERSION
+          }, null, 2)
+        }]
+      };
+    }
+    throw new ProtocolError(ProtocolErrorCode.InvalidRequest, `Unknown resource: ${uri}`);
+  });
+  server.setRequestHandler("prompts/list", async () => ({
+    prompts: [
+      {
+        name: "plur-getting-started",
+        description: "Step-by-step guide to set up and start using PLUR memory"
+      },
+      {
+        name: "plur-session-start",
+        description: "Load relevant context for a task \u2014 call at the start of each session",
+        arguments: [
+          { name: "task", description: "Brief description of the task or goal", required: true },
+          { name: "scope", description: "Project scope (e.g. project:my-app)", required: false }
+        ]
+      }
+    ]
+  }));
+  server.setRequestHandler("prompts/get", async (request) => {
+    const name = request.params.name;
+    if (name === "plur-getting-started") {
+      const status = await instance.status();
+      return {
+        description: "Get started with PLUR memory",
+        messages: [{
+          role: "user",
+          content: {
+            type: "text",
+            text: `I just set up PLUR. Here's my current status:
+
+- Engrams stored: ${status.engram_count}
+- Episodes recorded: ${status.episode_count}
+- Packs installed: ${status.pack_count}
+- Storage: ${status.storage_root}
+
+${status.engram_count === 0 ? `I have no memories yet. Help me get started by:
+1. Teaching me a coding preference or convention (I'll use plur_learn)
+2. Then recalling it to verify it works (I'll use plur_recall)
+3. Rating the recall quality (I'll use plur_feedback)` : `I have ${status.engram_count} engrams stored. Try asking me something related to your project \u2014 I'll check my memory first.`}`
+          }
+        }]
+      };
+    }
+    if (name === "plur-session-start") {
+      const task = request.params.arguments?.task ?? "general work";
+      const scope = request.params.arguments?.scope;
+      return {
+        description: "Load relevant context for this session",
+        messages: [{
+          role: "user",
+          content: {
+            type: "text",
+            text: `Starting a new session. Task: ${task}${scope ? ` (scope: ${scope})` : ""}
+
+Please:
+1. Call plur_recall with query "${task}"${scope ? ` and scope "${scope}"` : ""} to load relevant memories
+2. Review the recalled engrams and apply any relevant conventions or preferences
+3. If any recalled engrams are helpful, call plur_feedback with "positive"
+4. If any are irrelevant, call plur_feedback with "negative"`
+          }
+        }]
+      };
+    }
+    throw new ProtocolError(ProtocolErrorCode.InvalidRequest, `Unknown prompt: ${name}`);
+  });
+  return server;
+}
+async function runStdio() {
+  const LOG_WINDOW_MS = 6e4;
+  const LOG_MAX_PER_WINDOW = 20;
+  let logWindowStart = 0;
+  let logCount = 0;
+  let suppressed = 0;
+  const logFault = (kind, err) => {
+    const now = Date.now();
+    if (now - logWindowStart > LOG_WINDOW_MS) {
+      if (suppressed > 0) {
+        process.stderr.write(`[plur:mcp] (${suppressed} further fault log lines suppressed in the last minute)
+`);
+      }
+      logWindowStart = now;
+      logCount = 0;
+      suppressed = 0;
+    }
+    if (logCount >= LOG_MAX_PER_WINDOW) {
+      suppressed++;
+      return;
+    }
+    logCount++;
+    const detail = err instanceof Error ? err.stack ?? err.message : String(err);
+    process.stderr.write(`[plur:mcp] ${kind} (#1070): ${detail}
+`);
+  };
+  process.on("unhandledRejection", (err) => logFault("unhandled rejection \u2014 server stays up", err));
+  process.on("uncaughtException", (err) => {
+    logFault("UNCAUGHT EXCEPTION \u2014 exiting so lock recovery and the harness can see the failure", err);
+    setTimeout(() => process.exit(1), 100);
+  });
+  const induceMs = Number(process.env.PLUR_TEST_INDUCE_UNHANDLED_REJECTION_MS ?? "");
+  if (Number.isFinite(induceMs) && induceMs > 0) {
+    setTimeout(() => {
+      void Promise.reject(new Error("induced test rejection (#1070)"));
+    }, induceMs);
+  }
+  const induceThrowMs = Number(process.env.PLUR_TEST_INDUCE_UNCAUGHT_EXCEPTION_MS ?? "");
+  if (Number.isFinite(induceThrowMs) && induceThrowMs > 0) {
+    setTimeout(() => {
+      throw new Error("induced test exception (#1070)");
+    }, induceThrowMs);
+  }
+  const profile = resolveToolProfile();
+  const server = await createServer(void 0, { profile });
+  registerFlushOnExit({});
+  try {
+    writeFileSync(serverPidPath(), String(process.pid));
+  } catch {
+  }
+  if (process.platform !== "win32") {
+    process.on("SIGUSR1", () => {
+      _pendingReload = true;
+    });
+  }
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  let closing = null;
+  const closeSession = (timeoutMs) => {
+    if (!closing) closing = closeWhenIdle(server, timeoutMs);
+    return closing;
+  };
+  process.stdin.once("end", () => {
+    void closeSession();
+  });
+  process.stdin.once("close", () => {
+    void closeSession();
+  });
+  for (const signal of ["SIGTERM", "SIGINT"]) {
+    process.once(signal, () => {
+      const code = signal === "SIGTERM" ? 143 : 130;
+      const timer = setTimeout(() => process.exit(code), 3e3);
+      timer.unref?.();
+      void closeSession(2e3).finally(() => {
+        if (process.stdout.writableLength > 0) process.stdout.once("drain", () => process.exit(code));
+        else process.exit(code);
+      });
+    });
+  }
+}
+export {
+  GUIDE_RESOURCE,
+  INSTRUCTIONS,
+  clearPendingReload,
+  closeWhenIdle,
+  createServer,
+  isPendingReload,
+  readEnterpriseToken,
+  runStdio,
+  serverPidPath
+};