@plur-ai/mcp 0.9.13 → 0.10.1

package/dist/index.js

@@ -5,7 +5,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSy
 import { join } from "path";
 import { fileURLToPath } from "url";
 import { homedir, platform } from "os";
-var VERSION = "0.9.13";
+var VERSION = "0.10.1";
 var HELP = `plur-mcp v${VERSION} \u2014 persistent memory for AI agents
 
 Usage:
@@ -279,7 +279,7 @@ if (arg === "init") {
   process.exit(0);
 }
 if (arg === "serve" || arg === void 0) {
-  const { runStdio } = await import("./server-O2CC7LEL.js");
+  const { runStdio } = await import("./server-XG6IEACO.js");
   runStdio().catch((err) => {
     console.error("Failed to start PLUR MCP server:", err);
     process.exit(1);

package/dist/{server-O2CC7LEL.js → server-XG6IEACO.js}

@@ -17,10 +17,21 @@ import { Plur as Plur2, checkForUpdate } from "@plur-ai/core";
 import { existsSync, unlinkSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
-import { extractMetaEngrams, validateMetaEngram, confidenceBand, generateProfile, getProfileForInjection, selectModelForOperation, getCachedUpdateCheck, minorVersionsBehind, scanForTensions, CapabilityCanary, readProjectConfig } from "@plur-ai/core";
+import { extractMetaEngrams, validateMetaEngram, confidenceBand, generateProfile, getProfileForInjection, selectModelForOperation, getCachedUpdateCheck, minorVersionsBehind, scanForTensions, CapabilityCanary, readProjectConfig, isSharedScope } from "@plur-ai/core";
+
+// src/telemetry.ts
+import { recordEvent, flushIfNeeded, registerFlushOnExit } from "@plur-ai/core";
+function recordTelemetry(event) {
+  try {
+    const rolledOver = recordEvent(event);
+    if (rolledOver) void flushIfNeeded({}).catch(() => {
+    });
+  } catch {
+  }
+}
 
 // src/version.ts
-var VERSION = "0.9.13";
+var VERSION = "0.10.1";
 
 // src/tools.ts
 function makeHttpLlm(baseUrl, apiKey, model = "gpt-4o-mini") {
@@ -104,7 +115,7 @@ function getToolDefinitions() {
   return [
     {
       name: "plur_learn",
-      description: "Create an engram \u2014 record a reusable learning, preference, or correction",
+      description: "Create an engram \u2014 record a reusable learning, preference, or correction. Multi-agent note: in an orchestration that spawns subagents, have the PARENT session own plur_learn writes \u2014 spawned subagents should return their findings as text for the parent to persist, rather than each calling plur_learn (tool availability is not guaranteed in every subagent context). See plur-ai/plur#281.",
       annotations: { title: "Learn", destructiveHint: false, idempotentHint: false },
       inputSchema: {
         type: "object",
@@ -140,11 +151,27 @@ function getToolDefinitions() {
           pinned: args.pinned,
           llm
         };
+        const explicitScope = typeof args.scope === "string" && args.scope.length > 0;
+        const scopeHint = (engramScope, wasRouted) => {
+          if (explicitScope || wasRouted || isSharedScope(engramScope)) return {};
+          let remote = [];
+          try {
+            remote = plur.getWritableRemoteScopes();
+          } catch {
+            return {};
+          }
+          if (remote.length === 0) return {};
+          const scopes = remote.map((s) => `"${s.scope}"`).join(", ");
+          return { scope_hint: `Stored at "${engramScope}" because no scope was passed, but a team store is configured (${scopes}). If this is team/engineering knowledge, re-learn it with an explicit scope so it reaches the shared store; keep genuinely personal notes at the default scope.` };
+        };
         const statement = sanitizeStatement(args.statement);
         try {
           const engram = await plur.learnRouted(statement, context);
           const isOutbox = !!engram.structured_data?._outbox;
+          const demoted = engram.structured_data?._demoted;
+          const routed = engram.structured_data?._routed;
           mcpCanary.signal("learn_activity");
+          recordTelemetry("learn");
           return {
             id: engram.id,
             statement: engram.statement,
@@ -152,18 +179,24 @@ function getToolDefinitions() {
             type: engram.type,
             pinned: engram.pinned === true,
             decision: "ADD",
-            ...isOutbox ? { outbox: true, warning: "Remote write failed; engram queued locally for retry on next session start or plur_sync." } : {}
+            ...scopeHint(engram.scope, !!routed),
+            ...isOutbox ? { outbox: true, warning: "Remote write failed; engram queued locally for retry on next session start or plur_sync." } : {},
+            ...demoted ? { demoted: true, requested_scope: demoted.from, warning: `Sensitive content (${demoted.patterns}) detected \u2014 stored at "${demoted.to}"/private instead of the requested shared scope "${demoted.from}". If this is a false positive, re-scope deliberately.` } : {},
+            ...routed ? { routed: { scope: routed.scope, confidence: routed.confidence, reason: routed.reason }, info: `No scope was provided; auto-routed to "${routed.scope}" (confidence ${routed.confidence}) because its content matched that scope's covers. Pass an explicit scope to override.` } : {}
           };
         } catch (err) {
           const engram = plur.learn(statement, context);
           const isOutbox = !!engram.structured_data?._outbox;
+          const routedFallback = engram.structured_data?._routed;
           mcpCanary.signal("learn_activity");
+          recordTelemetry("learn");
           return {
             id: engram.id,
             statement: engram.statement,
             scope: engram.scope,
             type: engram.type,
             decision: "ADD",
+            ...scopeHint(engram.scope, !!routedFallback),
             ...isOutbox ? { outbox: true } : {},
             warning: `Remote write failed (${err.message}); engram queued for retry.`
           };
@@ -172,7 +205,7 @@ function getToolDefinitions() {
     },
     {
       name: "plur_recall",
-      description: "Query engrams by BM25 keyword matching \u2014 use plur_recall_hybrid for semantic similarity",
+      description: "Query engrams by BM25 keyword matching \u2014 use plur_recall_hybrid for semantic similarity. Note: a project-scope filter also returns personal-family engrams (local, global, user:*, agent:*); an explicit scope=global recall returns ALL personal-family engrams \u2014 wider than scope=global INJECT, which is targeted to the global namespace only.",
       annotations: { title: "Recall (BM25)", readOnlyHint: true, idempotentHint: true },
       inputSchema: {
         type: "object",
@@ -230,6 +263,7 @@ function getToolDefinitions() {
           domain: args.domain,
           limit: effectiveLimit
         });
+        recordTelemetry("recall");
         const results = meta.engrams;
         let truncated = false;
         let boundedResults = results;
@@ -658,7 +692,7 @@ function getToolDefinitions() {
     },
     {
       name: "plur_sync",
-      description: "Sync engrams via git \u2014 initializes repo on first call, commits and pushes/pulls on subsequent calls. Provide a remote URL on first call to enable cross-device sync.",
+      description: "Sync engrams via git AND refresh the derived index from YAML. Initializes repo on first call, commits and pushes/pulls on subsequent calls. Provide a remote URL on first call to enable cross-device sync. Pass full=true to drop-and-rebuild the index from YAML (recovery path; YAML stays untouched).",
       annotations: { title: "Sync", openWorldHint: true, destructiveHint: false, idempotentHint: true },
       inputSchema: {
         type: "object",
@@ -666,11 +700,15 @@ function getToolDefinitions() {
           remote: {
             type: "string",
             description: "Git remote URL (e.g. git@github.com:user/plur-engrams.git). Only needed on first call to set up remote."
+          },
+          full: {
+            type: "boolean",
+            description: "Full reindex: drop the derived index (PGLite/SQLite) and rebuild from YAML. YAML is never modified. Use to recover from an out-of-sync index."
           }
         }
       },
       handler: async (args, plur) => {
-        const result = plur.sync(args.remote);
+        const result = plur.sync(args.remote, { full: args.full === true });
         let outbox_result;
         try {
           outbox_result = await plur.flushOutbox();
@@ -883,7 +921,7 @@ function getToolDefinitions() {
     },
     {
       name: "plur_doctor",
-      description: "Diagnose the PLUR install. Reports whether the embedding model loaded, whether hybrid search is fully operational, and what to do if it is degraded. Run this first when recall feels off.",
+      description: 'Diagnose the PLUR install. Reports whether the embedding model loaded, whether hybrid search is fully operational, and \u2014 for any configured enterprise/remote store \u2014 whether its auth is valid (probes /api/v1/me and decodes token expiry), so a dead or soon-to-expire token surfaces instead of hiding behind a "healthy" report. Run this first when recall feels off or team engrams stop syncing.',
       annotations: { title: "Doctor", readOnlyHint: false, idempotentHint: false },
       inputSchema: {
         type: "object",
@@ -953,6 +991,28 @@ function getToolDefinitions() {
             if (cs.warning) remediation.push(cs.warning);
           }
         }
+        try {
+          const remotes = await plur.checkRemoteHealth({ timeoutMs: 5e3 });
+          for (const h of remotes) {
+            const expiresNote = typeof h.tokenExpiresInDays === "number" ? ` \u2014 token ${h.tokenExpiresInDays < 0 ? `expired ${-h.tokenExpiresInDays}d ago` : `expires in ${h.tokenExpiresInDays}d`}` : "";
+            if (h.status === "ok") {
+              const soon = typeof h.tokenExpiresInDays === "number" && h.tokenExpiresInDays <= 7;
+              checks.push({
+                check: `remote store: ${h.url}`,
+                ok: !soon,
+                detail: soon ? `Reachable, but token expires in ${h.tokenExpiresInDays}d \u2014 reauth soon` : `Reachable, auth valid${expiresNote}`
+              });
+              if (soon) remediation.push(`Remote ${h.url}: token expires in ${h.tokenExpiresInDays}d \u2014 mint a new token (<host>/me/api-keys), update ~/.plur/config.yaml, restart.`);
+            } else if (h.status === "auth_expired") {
+              checks.push({ check: `remote store: ${h.url}`, ok: false, detail: `AUTH FAILED${expiresNote} \u2014 team-scoped writes are queuing to the outbox, not syncing. (${h.reason ?? ""})` });
+              remediation.push(`Remote ${h.url}: re-authenticate \u2014 open <host>/auth/github (or <host>/me/api-keys) in a browser, paste the token into ~/.plur/config.yaml, then restart Claude/MCP so it reloads. Queued engrams flush on next session_start.`);
+            } else {
+              checks.push({ check: `remote store: ${h.url}`, ok: false, detail: `Unreachable (${h.reason ?? "network error"}) \u2014 writes queue locally until it recovers.` });
+              remediation.push(`Remote ${h.url}: unreachable \u2014 check connectivity/VPN. Reads fall back to local; writes queue in the outbox.`);
+            }
+          }
+        } catch {
+        }
         return {
           ok: checks.every((c) => c.ok),
           checks,
@@ -990,7 +1050,14 @@ function getToolDefinitions() {
           outbox_result = await plur.flushOutbox();
         } catch {
         }
-        const remote_scopes = plur.getWritableRemoteScopes();
+        const remote_scopes = plur.getWritableRemoteScopes().map((s) => {
+          const md = plur.getScopeMetadata(s.scope);
+          return {
+            ...s,
+            ...md?.description ? { description: md.description } : {},
+            ...md?.covers && md.covers.length > 0 ? { covers: md.covers } : {}
+          };
+        });
         const projectConfig = readProjectConfig();
         const explicit_default_scope = args.default_scope ?? null;
         const default_scope = explicit_default_scope ?? projectConfig.scope ?? null;
@@ -1059,15 +1126,58 @@ Auto-detected project scope: "${default_scope}" (from .plur.yaml in the current
         } else if (scope_source === "none") {
           guide += `
 
-\u26A0\uFE0F No project scope detected. plur_learn calls without explicit scope will be tagged "global" and will appear in EVERY project's future sessions. To avoid context bleed across projects, create a .plur.yaml in this project's root with: scope: "project:<your-project-name>"`;
+\u26A0\uFE0F No project scope detected. plur_learn calls without explicit scope will be tagged "global" and will appear in EVERY project's future sessions. Create a .plur.yaml NOW to prevent this: scope: "project:<your-project-name>". (This is every project's PERSONAL recall context, NOT team shared stores \u2014 use an explicit shared scope like project:/group: to reach a team store.) Note: an explicit scope=global RECALL surfaces all your personal engrams, but scope=global INJECT is targeted to the global namespace only \u2014 don't be surprised if a local engram a global recall finds is absent from a global inject.`;
         }
         if (remote_scopes.length > 0) {
-          const scopeList = remote_scopes.map((s) => `"${s.scope}"`).join(", ");
+          const safe = (x) => String(x ?? "").replace(/\s+/g, " ").trim().slice(0, 200);
+          const scopeList = remote_scopes.map((s) => {
+            const detail = [
+              s.description ? `\u2014 ${safe(s.description)}` : "",
+              s.covers && s.covers.length > 0 ? `(covers: ${s.covers.map(safe).join(", ")})` : ""
+            ].filter(Boolean).join(" ");
+            return detail ? `"${safe(s.scope)}" ${detail}` : `"${safe(s.scope)}"`;
+          }).join("; ");
           guide += default_scope ? `
 
 Session default scope is set to "${default_scope}". To route an engram to a remote enterprise store instead, pass scope explicitly to plur_learn (available remote scopes: ${scopeList}).` : `
 
-Remote store scopes available: ${scopeList}. When an engram is relevant to the team (engineering patterns, architecture decisions, project conventions), set scope to the matching remote scope in plur_learn. Personal preferences, local project details, and corrections specific to your workflow should stay at default scope (local).`;
+Remote store scopes available: ${scopeList}. Set scope PER ENGRAM by content: when an engram is relevant to the team (engineering patterns, architecture decisions, project conventions), set scope to the matching remote scope in plur_learn. Personal preferences, local project details, and corrections specific to your workflow can be left unscoped (they land at the unscoped default, "global" \u2014 the cross-project personal namespace). Do NOT let TEAM knowledge fall back to "global" \u2014 without an explicit scope it will, and it will never reach the shared store.`;
+          try {
+            const discoveries = await plur.discoverRemoteScopes({ timeoutMs: 3e3 });
+            const failures = discoveries.filter((d) => !d.ok);
+            if (failures.length > 0) {
+              const authExpired = failures.some((f) => /\b40[13]\b/.test(f.error ?? ""));
+              const pending = outbox_result?.failed ?? 0;
+              const urls = [...new Set(failures.map((f) => f.url))].join(", ");
+              guide += authExpired ? `
+
+\u26A0\uFE0F ENTERPRISE STORE AUTH FAILED (token expired/invalid): ${urls}. Team-scoped engrams are NOT syncing` + (pending > 0 ? ` \u2014 ${pending} queued in the outbox` : "") + `. Reauth: open <host>/auth/github (or <host>/me/api-keys) in a browser, paste the token into ~/.plur/config.yaml, then restart Claude/MCP. Queued engrams flush on the next session_start.` : `
+
+\u26A0\uFE0F ENTERPRISE STORE UNREACHABLE: ${urls}. Reads fall back to local; team-scoped writes queue in the outbox` + (pending > 0 ? ` (${pending} pending)` : "") + ` until it recovers. Check connectivity/VPN.`;
+            }
+            const unregistered = [...new Set(discoveries.filter((d) => d.ok).flatMap((d) => d.unregistered))];
+            if (unregistered.length > 0) {
+              const list = unregistered.map((s) => `"${safe(s)}"`).join(", ");
+              guide += `
+
+\u{1F50E} Your token is authorized for ${unregistered.length} more scope(s) not yet registered: ${list}. Call plur_scopes_discover with register:true to add them all in one step.`;
+            }
+          } catch {
+          }
+          try {
+            for (const t of plur.remoteTokenExpiries()) {
+              if (t.expired) {
+                guide += `
+
+\u26A0\uFE0F Enterprise token for ${t.url} EXPIRED ${t.expiresAt ?? ""}. Reauth and restart to resume team sync.`;
+              } else if (typeof t.expiresInDays === "number" && t.expiresInDays <= 7) {
+                guide += `
+
+\u23F3 Enterprise token for ${t.url} expires in ${t.expiresInDays}d. Mint a fresh one (<host>/me/api-keys) before it lapses.`;
+              }
+            }
+          } catch {
+          }
         }
         return {
           session_id,
@@ -1186,7 +1296,7 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
     },
     {
       name: "plur_stores_add",
-      description: "Register an additional engram store. Either filesystem (path) or remote (url+token, e.g. PLUR Enterprise).",
+      description: 'Register an additional engram store. Either filesystem (path) or remote (url+token, e.g. PLUR Enterprise). One remote URL can host multiple scopes \u2014 call once per team scope you are authorized for; each registers independently. Returns status: "added" or "already_registered".',
       annotations: { title: "Add store", destructiveHint: false, idempotentHint: true },
       inputSchema: {
         type: "object",
@@ -1206,23 +1316,32 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
         const token = args.token;
         if (!path && !url) return { error: "Either path or url must be provided" };
         if (path && url) return { error: "Provide path OR url, not both" };
-        plur.addStore(path ?? "", args.scope, {
+        const requestedScope = args.scope;
+        const result = plur.addStore(path ?? "", requestedScope, {
           shared: args.shared,
           readonly: args.readonly,
           url,
           token
         });
+        const scopeDropped = result.status === "already_registered" && result.scope !== requestedScope;
         return {
-          success: true,
+          success: !scopeDropped,
+          status: result.status,
           ...path ? { path } : { url },
-          scope: args.scope,
+          // On already_registered this is the EXISTING entry's scope — for
+          // local stores (path-only identity) it may differ from the request.
+          scope: result.scope,
+          ...scopeDropped ? {
+            requested_scope: requestedScope,
+            note: `This path is already registered under scope "${result.scope}". A local store is keyed by its path, so the requested scope "${requestedScope}" was NOT added. Use a separate store file for a different scope, or remove the existing entry first.`
+          } : {},
           kind: url ? "remote" : "filesystem"
         };
       }
     },
     {
       name: "plur_stores_list",
-      description: "List all configured engram stores with their scope, path, and engram count",
+      description: "List all configured engram stores with their scope, path, and engram count. When a store declares self-describing scope metadata, its description and covers (topics the scope is the home for) are included so you can pick the right scope.",
       annotations: { title: "List stores", readOnlyHint: true, idempotentHint: true },
       inputSchema: { type: "object", properties: {} },
       handler: async (_args, plur) => {
@@ -1235,6 +1354,53 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
         };
       }
     },
+    {
+      name: "plur_suggest_scope",
+      description: 'Suggest which registered scope(s) an engram belongs in, ranked by fit. Deterministic \u2014 no LLM, no network. Scores the statement keywords, optional domain (a dotted namespace like "plur.core.security"), and tags against the covers[] each scope declares. ADVISORY ONLY: this does not route or store anything; pass the chosen scope to plur_learn yourself. Returns candidates sorted by confidence (empty when nothing matches).',
+      annotations: { title: "Suggest scope", readOnlyHint: true, idempotentHint: true },
+      inputSchema: {
+        type: "object",
+        properties: {
+          statement: { type: "string", description: "The engram statement to route" },
+          domain: { type: "string", description: 'Optional dotted namespace for the engram (e.g. "plur.core.security") \u2014 strongest routing signal' },
+          tags: { type: "array", items: { type: "string" }, description: "Optional tags on the engram" }
+        },
+        required: ["statement"]
+      },
+      handler: async (args, plur) => {
+        const candidates = plur.suggestScope({
+          statement: args.statement,
+          domain: args.domain,
+          tags: args.tags
+        });
+        return { candidates, count: candidates.length };
+      }
+    },
+    {
+      name: "plur_scopes_discover",
+      description: "Discover which scopes your remote token is authorized for via the enterprise server (GET /api/v1/me), and which of those are not yet registered locally. Read-only by default; pass register:true to register all authorized-but-unregistered scopes in one step. Only shared-family scopes (group:/project:/space:/team:/org:/public) are auto-registered \u2014 personal-family scopes (global/local/user:*/agent:*) advertised by /me are skipped and surfaced in the result. Use this when you have access to multiple team scopes on one server.",
+      annotations: { title: "Discover scopes", readOnlyHint: false, idempotentHint: true },
+      inputSchema: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "Limit discovery to this remote URL (default: all configured remote stores)" },
+          register: { type: "boolean", description: "Register all authorized-but-unregistered scopes (default false \u2014 discovery is read-only)" }
+        }
+      },
+      handler: async (args, plur) => {
+        const url = args.url;
+        const register = args.register === true;
+        const discoveries = await plur.discoverRemoteScopes({ url });
+        if (discoveries.length === 0) {
+          return { discovered: [], note: "No remote stores configured. Register one scope first with plur_stores_add, then discover the rest." };
+        }
+        if (!register) {
+          return { discovered: discoveries };
+        }
+        const registered = await plur.registerDiscoveredScopes({ url });
+        return { discovered: discoveries, registered };
+      }
+    },
     {
       name: "plur_promote",
       description: "Activate candidate engrams so they appear in injection results",
@@ -1616,6 +1782,19 @@ DURING the session:
 - 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
 
+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_hybrid before answering factual questions \u2014 the answer may be in memory
@@ -1779,9 +1958,15 @@ async function createServer(plur) {
         }
         const parsed = z.object(shape).passthrough().safeParse(args);
         if (!parsed.success) {
-          const details = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join(", ");
+          const receivedFields = Object.keys(args);
+          const details = parsed.error.issues.map((i) => `${i.path.join(".") || "root"}: ${i.message}`).join(", ");
+          const receivedNote = receivedFields.length > 0 ? `Received fields: [${receivedFields.join(", ")}].` : "Received no fields (the arguments object was empty).";
           return {
-            content: [{ type: "text", text: JSON.stringify({ error: `Invalid arguments: ${details}`, success: false }) }],
+            content: [{ type: "text", text: JSON.stringify({
+              error: `Invalid arguments: ${details}. ${receivedNote} The call reached the server \u2014 this is a malformed-arguments error, not a transport failure. Fix the field(s) named above and retry; do not abandon the call.`,
+              success: false,
+              received_fields: receivedFields
+            }) }],
             isError: true
           };
         }
@@ -1909,10 +2094,12 @@ Please:
 }
 async function runStdio() {
   const server = await createServer();
+  registerFlushOnExit({});
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
 export {
+  INSTRUCTIONS,
   createServer,
   runStdio
 };

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@plur-ai/mcp",
-  "version": "0.9.13",
+  "mcpName": "io.github.plur-ai/plur",
+  "version": "0.10.1",
   "type": "module",
   "bin": {
     "plur-mcp": "dist/index.js"
@@ -13,7 +14,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.23.0",
-    "@plur-ai/core": "0.9.13"
+    "@plur-ai/core": "0.10.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.0"