@plur-ai/mcp 0.10.0 → 0.11.0

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.10.0";
+var VERSION = "0.11.0";
 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-EQD6L2BP.js");
+  const { runStdio } = await import("./server-M7GBKD4M.js");
   runStdio().catch((err) => {
     console.error("Failed to start PLUR MCP server:", err);
     process.exit(1);

package/dist/{server-EQD6L2BP.js → server-M7GBKD4M.js}

@@ -17,7 +17,7 @@ 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, isSharedScope } from "@plur-ai/core";
+import { extractMetaEngrams, validateMetaEngram, confidenceBand, generateProfile, getProfileForInjection, selectModelForOperation, getCachedUpdateCheck, minorVersionsBehind, scanForTensions, CapabilityCanary, readProjectConfig, isSharedScope, resolveRerankerName, getReranker, classifyRerankerFailure, hfCacheDirName } from "@plur-ai/core";
 
 // src/telemetry.ts
 import { recordEvent, flushIfNeeded, registerFlushOnExit } from "@plur-ai/core";
@@ -31,7 +31,7 @@ function recordTelemetry(event) {
 }
 
 // src/version.ts
-var VERSION = "0.10.0";
+var VERSION = "0.11.0";
 
 // src/tools.ts
 function makeHttpLlm(baseUrl, apiKey, model = "gpt-4o-mini") {
@@ -133,7 +133,10 @@ function getToolDefinitions() {
           source: { type: "string", description: "Origin of this knowledge (URL, conversation ref, etc.)" },
           pinned: { type: "boolean", description: "Always-load flag. If true, this engram bypasses the keyword-relevance gate at injection time. Use sparingly: meta-rules, safety conventions, core operating principles only." },
           commitment: { type: "string", enum: ["exploring", "leaning", "decided", "locked"], description: "How firmly the user has committed to this belief (default: leaning)" },
-          locked_reason: { type: "string", description: "Why this engram is locked (only meaningful when commitment=locked)" }
+          locked_reason: { type: "string", description: "Why this engram is locked (only meaningful when commitment=locked)" },
+          valid_from: { type: "string", description: "ISO date (YYYY-MM-DD) the knowledge becomes valid \u2014 inject/recall skip the engram before this date (#347)" },
+          valid_until: { type: "string", description: 'ISO date (YYYY-MM-DD) the knowledge expires \u2014 inject/recall skip the engram after this date. Set this for any time-bound fact (offers, deadlines, temporary endpoints). When omitted, an explicit expiry phrase in the statement ("valid until 31 May 2026") is auto-parsed and echoed back (#347)' },
+          supersedes: { type: "array", items: { type: "string" }, description: "Engram IDs this statement intentionally replaces (#240). Writes relations.supersedes on the new engram and the reverse superseded_by edge on each local target. Supersedes-linked pairs are skipped by tension scans \u2014 an intentional update is not a contradiction. Use when updating a standing fact (new version, changed rule) rather than contradicting it." }
         },
         required: ["statement"]
       },
@@ -149,6 +152,9 @@ function getToolDefinitions() {
           commitment: args.commitment,
           locked_reason: args.locked_reason,
           pinned: args.pinned,
+          valid_from: args.valid_from,
+          valid_until: args.valid_until,
+          supersedes: args.supersedes,
           llm
         };
         const explicitScope = typeof args.scope === "string" && args.scope.length > 0;
@@ -164,6 +170,14 @@ function getToolDefinitions() {
           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 temporalEcho = (engram) => {
+          const extracted = engram.structured_data?._expiry_extracted;
+          return {
+            ...engram.temporal?.valid_from ? { valid_from: engram.temporal.valid_from } : {},
+            ...engram.temporal?.valid_until ? { valid_until: engram.temporal.valid_until } : {},
+            ...extracted ? { expiry_note: `Parsed expiry phrase "${extracted.phrase}" from the statement \u2192 temporal.valid_until=${extracted.valid_until}. The engram stops injecting/recalling after that date. If this is wrong, re-learn with an explicit valid_until.` } : {}
+          };
+        };
         const statement = sanitizeStatement(args.statement);
         try {
           const engram = await plur.learnRouted(statement, context);
@@ -179,6 +193,7 @@ function getToolDefinitions() {
             type: engram.type,
             pinned: engram.pinned === true,
             decision: "ADD",
+            ...temporalEcho(engram),
             ...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.` } : {},
@@ -196,6 +211,7 @@ function getToolDefinitions() {
             scope: engram.scope,
             type: engram.type,
             decision: "ADD",
+            ...temporalEcho(engram),
             ...scopeHint(engram.scope, !!routedFallback),
             ...isOutbox ? { outbox: true } : {},
             warning: `Remote write failed (${err.message}); engram queued for retry.`
@@ -310,6 +326,14 @@ function getToolDefinitions() {
         if (meta.mode === "hybrid-degraded") {
           response.warning = `Embedding layer unavailable \u2014 results are BM25-only. Run plur_doctor for diagnosis. Last error: ${meta.embedderError ?? "unknown"}`;
         }
+        if (resolveRerankerName() !== "off") {
+          response.reranked = meta.reranked ?? 0;
+          const rr = plur.rerankerStatus();
+          if (boundedResults.length > 0 && (meta.reranked ?? 0) === 0 && rr.lastError) {
+            const corruptNote = rr.lastErrorKind === "corrupt-cache" ? " The model cache looks corrupt (truncated download) \u2014 purge and re-download, see plur_doctor." : "";
+            response.reranker_warning = `PLUR_RERANKER is set but the reranker did not engage \u2014 results are RRF-only (fusion order, no cross-encoder rerank).${corruptNote} Last error: ${rr.lastError}. Run plur_doctor for diagnosis.`;
+          }
+        }
         return response;
       }
     },
@@ -336,7 +360,9 @@ function getToolDefinitions() {
           consider: result.consider,
           count: result.count,
           tokens_used: result.tokens_used,
-          injected_ids: result.injected_ids
+          injected_ids: result.injected_ids,
+          // #181: unresolved-tension warnings — flag contradicted context
+          ...result.warnings ? { warnings: result.warnings } : {}
         };
       }
     },
@@ -364,7 +390,9 @@ function getToolDefinitions() {
           count: result.count,
           tokens_used: result.tokens_used,
           injected_ids: result.injected_ids,
-          mode: "hybrid"
+          mode: "hybrid",
+          // #181: unresolved-tension warnings — flag contradicted context
+          ...result.warnings ? { warnings: result.warnings } : {}
         };
       }
     },
@@ -709,6 +737,8 @@ function getToolDefinitions() {
       },
       handler: async (args, plur) => {
         const result = plur.sync(args.remote, { full: args.full === true });
+        await plur.waitForIndex();
+        const indexError = plur.lastIndexError();
         let outbox_result;
         try {
           outbox_result = await plur.flushOutbox();
@@ -716,6 +746,10 @@ function getToolDefinitions() {
         }
         return {
           ...result,
+          ...indexError ? {
+            index_error: indexError,
+            warning: `Index ${indexError.op} failed \u2014 ${indexError.message}. YAML is still the source of truth; run plur_sync with full=true to rebuild the index.`
+          } : {},
           ...outbox_result && (outbox_result.flushed > 0 || outbox_result.failed > 0) ? {
             outbox: {
               flushed: outbox_result.flushed,
@@ -907,6 +941,15 @@ function getToolDefinitions() {
           tension_count: status.tension_count,
           versioned_engram_count: status.versioned_engram_count ?? 0,
           outbox_count: status.outbox_count ?? 0,
+          // Injection-provenance event/label counts (#452) — #202's volume gate.
+          history_events: status.history_events ?? {
+            co_injection: 0,
+            injection_outcome: 0,
+            outcome_positive: 0,
+            outcome_negative: 0
+          },
+          // Last background index/reembed failure (#272) — absent when healthy.
+          ...status.index_error ? { index_error: status.index_error } : {},
           // Version check (issue #151)
           ...versionCheck?.updateAvailable && versionCheck.latest ? {
             update_available: {
@@ -926,12 +969,14 @@ function getToolDefinitions() {
       inputSchema: {
         type: "object",
         properties: {
-          retry: { type: "boolean", description: "If true, reset cached embedder failure state and retry the model load before reporting" }
+          retry: { type: "boolean", description: "If true, reset cached embedder failure state and retry the model load before reporting" },
+          rerank_eval: { type: "boolean", description: "If true and a reranker is configured (PLUR_RERANKER), run the per-store self-eval gate (#451): probes synthesized from this store's own engrams compare rerank-on vs RRF-only ordering. Verdict is cached in the store and advisory \u2014 it never auto-disables reranking. Costs one cross-encoder pass per probe (~20 probes)." }
         }
       },
       handler: async (args, plur) => {
         if (args.retry === true) {
           plur.resetEmbedder();
+          plur.resetReranker();
         }
         const status = plur.status();
         const before = plur.embedderStatus();
@@ -984,6 +1029,74 @@ function getToolDefinitions() {
             "  \u2022 Or opt out: set PLUR_DISABLE_EMBEDDINGS=1, or write `embeddings: { enabled: false }` to ~/.plur/config.yaml \u2014 hybrid search will run BM25-only"
           );
         }
+        const rerankerName = resolveRerankerName();
+        if (rerankerName !== "off") {
+          const adapter = getReranker(rerankerName);
+          let rerankerOk = false;
+          let rerankerDetail;
+          const probeStart = Date.now();
+          try {
+            const scores = await adapter.scoreBatch("plur doctor probe", ["probe document"]);
+            rerankerOk = scores.length === 1 && Number.isFinite(scores[0]);
+            const latencyNote = rerankerName === "bge-reranker-v2-m3" ? "seconds-scale per recall on CPU is expected \u2014 #220" : "ms-scale per recall on CPU is expected \u2014 #451";
+            rerankerDetail = rerankerOk ? `${rerankerName} loaded and scoring (probe ${Date.now() - probeStart}ms; ${latencyNote})` : `Probe returned malformed scores (${JSON.stringify(scores)}) \u2014 recall silently falls back to RRF-only`;
+          } catch (err) {
+            const message = err.message;
+            const kind = classifyRerankerFailure(message);
+            if (kind === "corrupt-cache") {
+              rerankerDetail = `Model cache looks corrupt (${message}) \u2014 recall silently falls back to RRF-only`;
+              remediation.push(
+                `Reranker model cache is corrupt \u2014 the classic symptom of a truncated download (#340). Delete ~/.cache/huggingface/hub/${hfCacheDirName(adapter.modelId)}/ and run plur_doctor with retry:true \u2014 the model will redownload via the classic (non-Xet) path.`
+              );
+            } else {
+              rerankerDetail = `Failed to load: ${message} \u2014 recall silently falls back to RRF-only`;
+              remediation.push(
+                `Reranker "${rerankerName}" is unavailable while PLUR_RERANKER requests it \u2014 recall degrades to RRF order without it. Check connectivity to huggingface.co (first-run download), or unset PLUR_RERANKER to opt out deliberately.`
+              );
+            }
+          }
+          checks.push({ check: "reranker available", ok: rerankerOk, detail: rerankerDetail });
+          try {
+            let evalStatus;
+            let freshlyRun = false;
+            if (args.rerank_eval === true) {
+              const run = await plur.rerankerSelfEval();
+              evalStatus = { result: run.result, stale: false };
+              freshlyRun = !run.cached;
+            } else {
+              evalStatus = plur.rerankerEvalStatus(rerankerName);
+            }
+            if (!evalStatus) {
+              checks.push({
+                check: "reranker per-store eval",
+                ok: true,
+                detail: "Not yet evaluated on this store \u2014 cross-encoders can be net-negative out-of-domain (#451). Run plur_doctor with rerank_eval:true for the advisory self-check before trusting reranked order."
+              });
+            } else {
+              const r = evalStatus.result;
+              const harmful = r.verdict === "harmful";
+              const sign = r.delta_mrr >= 0 ? "+" : "";
+              const provenance = freshlyRun ? "measured now" : `cached ${r.evaluated_at}`;
+              const staleNote = evalStatus.stale ? " [STALE \u2014 store changed since; re-run with rerank_eval:true]" : "";
+              checks.push({
+                check: "reranker per-store eval",
+                ok: !harmful,
+                detail: `${r.verdict} on this store (${provenance}${staleNote}): \u0394MRR ${sign}${r.delta_mrr.toFixed(3)} vs RRF-only over ${r.scored_probes} probes (hit@1 ${(r.rrf_hit1 * 100).toFixed(0)}%\u2192${(r.rerank_hit1 * 100).toFixed(0)}%, ${r.promotions} promoted / ${r.demotions} demoted, ~${r.mean_rerank_ms.toFixed(0)}ms/probe)`
+              });
+              if (harmful) {
+                remediation.push(
+                  `Per-store self-eval measured reranker "${rerankerName}" as net-negative on THIS store (\u0394MRR ${r.delta_mrr.toFixed(3)}; it demoted known-relevant engrams in ${r.demotions}/${r.scored_probes} probes). This gate is advisory \u2014 reranking remains enabled. Unset PLUR_RERANKER to opt out for this store, or re-run plur_doctor with rerank_eval:true after the store grows/changes.`
+                );
+              }
+            }
+          } catch (err) {
+            checks.push({
+              check: "reranker per-store eval",
+              ok: false,
+              detail: `self-eval failed: ${err.message}`
+            });
+          }
+        }
         const canaryStatuses = mcpCanary.status();
         for (const cs of canaryStatuses) {
           if (!cs.healthy) {
@@ -1039,7 +1152,7 @@ function getToolDefinitions() {
         required: ["task"]
       },
       handler: async (args, plur) => {
-        mcpCanary.tick();
+        mcpCanary.reset();
         mcpCanary.signal("session_start_hook");
         const crypto = await import("crypto");
         const session_id = crypto.randomUUID();
@@ -1074,7 +1187,9 @@ function getToolDefinitions() {
         let engrams = null;
         try {
           const result = await plur.injectHybrid(task, {
-            scope: tags?.length ? `tags:${tags.join(",")}` : void 0
+            scope: tags?.length ? `tags:${tags.join(",")}` : void 0,
+            session_id
+            // stamped on the co_injection provenance event (#452)
           });
           if (result.count > 0) {
             const lines = [];
@@ -1085,7 +1200,8 @@ function getToolDefinitions() {
           }
         } catch {
           const result = plur.inject(task, {
-            scope: tags?.length ? `tags:${tags.join(",")}` : void 0
+            scope: tags?.length ? `tags:${tags.join(",")}` : void 0,
+            session_id
           });
           if (result.count > 0) {
             const lines = [];
@@ -1443,22 +1559,48 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
     },
     {
       name: "plur_tensions",
-      description: "List or scan for engram pairs that have conflicting knowledge. Without scan mode, shows previously detected conflicts. With scan:true, runs an active LLM-powered contradiction scan and returns only high-confidence tensions.",
-      annotations: { title: "Tensions", readOnlyHint: true, idempotentHint: true },
+      description: 'Tension lifecycle (#181). Default: list persisted tension records (unresolved first). scan:true runs an LLM contradiction scan, persists NEW detections as records, and skips already-recorded pairs. Lifecycle actions: action:"confirm" (real conflict), action:"dismiss" (false positive \u2014 pair suppressed from future scans), action:"resolve" + winner:<engram_id> (loser engram retired). Scan requires OPENAI_API_KEY or OPENROUTER_API_KEY env var, or explicit llm_base_url + llm_api_key args.',
+      annotations: { title: "Tensions", readOnlyHint: false, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {
           scope: { type: "string", description: "Filter by scope" },
           domain: { type: "string", description: "Filter by domain prefix" },
-          scan: { type: "boolean", description: "Run an active contradiction scan using an LLM judge. Requires OPENAI_API_KEY or OPENROUTER_API_KEY env var, or explicit llm_base_url + llm_api_key args." },
+          scan: { type: "boolean", description: "Run an active contradiction scan using an LLM judge. New detections are persisted as tension records; recorded pairs (any status) are skipped. Requires OPENAI_API_KEY or OPENROUTER_API_KEY env var, or explicit llm_base_url + llm_api_key args." },
+          persist: { type: "boolean", description: "Persist scan detections as tension records (default true). Set false for a dry-run scan that also ignores the recorded-pair suppress list." },
+          action: { type: "string", enum: ["confirm", "dismiss", "resolve"], description: "Lifecycle action on a persisted tension record (requires id). confirm: mark real. dismiss: false positive, suppress the pair. resolve: pick winner (requires winner), the losing engram is retired." },
+          id: { type: "string", description: "Tension record id (T-YYYY-MMDD-NNN) for action mode" },
+          winner: { type: "string", description: 'Engram id that wins the tension (action:"resolve" only). The other engram is retired.' },
+          status: { type: "string", enum: ["detected", "confirmed", "dismissed", "resolved", "all"], description: "List-mode status filter. Default: unresolved records (detected + confirmed)." },
           llm_base_url: { type: "string", description: "OpenAI-compatible API base URL for scan mode (e.g. https://api.openai.com/v1)" },
           llm_api_key: { type: "string", description: "API key for the LLM (scan mode)" },
           llm_model: { type: "string", description: "Model name for scan mode (default: gpt-4o-mini)" },
           min_confidence: { type: "number", description: "Minimum confidence threshold for scan mode (0\u20131, default: 0.7)" },
-          max_pairs: { type: "number", description: "Maximum candidate pairs to evaluate in scan mode (default: 50)" }
+          max_pairs: { type: "number", description: "Maximum candidate pairs to evaluate in scan mode (default: 50)" },
+          batch_size: { type: "number", description: "Pairs judged per LLM call in scan mode (default: 5). Set to 1 for sequential single-pair judging." },
+          temporal_discount: { type: "boolean", description: "Multiply judge confidence by a days-apart ladder (same day x1.0 ... 15+ days x0.3) in scan mode (#240). Overrides the config default (tensions.temporal_discount, off by default). The judge prompt already carries recorded dates; enable this only when date-aware judging alone leaves too many temporal-evolution false positives." }
         }
       },
       handler: async (args, plur) => {
+        if (args.action) {
+          const id = args.id;
+          if (!id) throw new Error(`action:"${args.action}" requires id (tension record id, e.g. T-2026-0703-001)`);
+          if (args.action === "confirm") {
+            const record = plur.confirmTension(id);
+            return { record, message: `Tension ${id} confirmed as a real conflict. Resolve it with action:"resolve" + winner:<engram_id>.` };
+          }
+          if (args.action === "dismiss") {
+            const record = plur.dismissTension(id);
+            return { record, message: `Tension ${id} dismissed \u2014 the pair is suppressed from future scans.` };
+          }
+          if (args.action === "resolve") {
+            const winner = args.winner;
+            if (!winner) throw new Error('action:"resolve" requires winner (the engram id to keep)');
+            const { record, retired_id } = plur.resolveTension(id, winner);
+            return { record, retired: retired_id, message: `Tension ${id} resolved: ${winner} wins, ${retired_id} retired.` };
+          }
+          throw new Error(`Unknown action: ${args.action}. Use confirm, dismiss, or resolve.`);
+        }
         const engrams = plur.list({
           scope: args.scope,
           domain: args.domain
@@ -1472,22 +1614,37 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
               count: 0
             };
           }
+          const tensionsConfig = plur.getTensionsConfig();
+          const persist = args.persist !== false;
           const result = await scanForTensions(engrams, llm, {
             min_confidence: args.min_confidence,
-            max_pairs: args.max_pairs
+            max_pairs: args.max_pairs,
+            batch_size: args.batch_size,
+            temporal_domains: tensionsConfig.temporal_domains,
+            snapshot_pairs: tensionsConfig.snapshot_pairs,
+            temporal_discount: args.temporal_discount ?? tensionsConfig.temporal_discount,
+            ...persist ? { exclude_pairs: new Set(plur.suppressedTensionPairKeys()) } : {}
           });
+          const persisted = persist && result.tensions.length > 0 ? plur.recordTensions(result.tensions) : void 0;
           return {
             pairs_checked: result.pairs_checked,
             count: result.new_tensions,
-            tensions: result.tensions.map((t) => ({
+            ...persisted ? { persisted_new: persisted.new_count } : {},
+            tensions: result.tensions.map((t, i) => ({
+              ...persisted ? { tension_id: persisted.records[i].id, category: persisted.records[i].category, status: persisted.records[i].status } : {},
               engram_a: { id: t.id_a, statement: t.statement_a },
               engram_b: { id: t.id_b, statement: t.statement_b },
               confidence: t.confidence,
-              reason: t.reason
-            }))
+              reason: t.reason,
+              ...t.days_apart !== void 0 ? { days_apart: t.days_apart } : {},
+              ...t.raw_confidence !== void 0 ? { raw_confidence: t.raw_confidence } : {}
+            })),
+            ...persisted && persisted.new_count > 0 ? { next_steps: 'Review each tension: action:"confirm" (real), action:"dismiss" (false positive), or action:"resolve" + winner:<engram_id> (retire the loser).' } : {}
           };
         }
-        const tensions = [];
+        const statusArg = args.status;
+        const records = statusArg === "all" ? plur.listTensions() : plur.listTensions({ status: statusArg ? [statusArg] : ["detected", "confirmed"] });
+        const legacy = [];
         const seen = /* @__PURE__ */ new Set();
         for (const engram of engrams) {
           if (!engram.relations?.conflicts?.length) continue;
@@ -1497,16 +1654,22 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
             seen.add(pairKey);
             const other = engrams.find((e) => e.id === conflictId);
             if (!other) continue;
-            tensions.push({
+            legacy.push({
               engram_a: { id: engram.id, statement: engram.statement, type: engram.type },
               engram_b: { id: other.id, statement: other.statement, type: other.type },
-              detected_at: engram.activation.last_accessed,
-              purge_hint: "These conflicts are from the legacy detection system. Run plur_tensions_purge to clear them, then use scan:true for active contradiction detection."
+              detected_at: engram.activation.last_accessed
             });
           }
         }
-        const purge_hint = tensions.length > 0 ? "These are legacy conflict relations. Run plur_tensions_purge to clear them." : void 0;
-        return { tensions, count: tensions.length, ...purge_hint ? { purge_hint } : {} };
+        return {
+          tensions: records,
+          count: records.length,
+          ...legacy.length > 0 ? {
+            legacy_conflicts: legacy,
+            purge_hint: "legacy_conflicts are unvalidated relations.conflicts refs (importer heuristics or pre-#138 residue) \u2014 run scan:true to judge them, or plur_tensions_purge to clear them."
+          } : {},
+          ...records.length === 0 && legacy.length === 0 ? { hint: "No persisted tensions. Run scan:true to detect contradictions." } : {}
+        };
       }
     },
     {
@@ -1899,7 +2062,22 @@ function jsonSchemaPropToZod(prop) {
   if (prop.type === "boolean") return z.boolean();
   if (prop.type === "array") {
     const itemSchema = prop.items ? jsonSchemaPropToZod(prop.items) : z.unknown();
-    return z.array(itemSchema);
+    return z.preprocess((val) => {
+      if (typeof val !== "string") return val;
+      const trimmed = val.trim();
+      if (trimmed.startsWith("[")) {
+        try {
+          const parsed = JSON.parse(trimmed);
+          return Array.isArray(parsed) ? parsed : val;
+        } catch {
+          return val;
+        }
+      }
+      if (prop.items?.type === "string") {
+        return trimmed.length === 0 ? [] : trimmed.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+      }
+      return val;
+    }, z.array(itemSchema));
   }
   if (prop.type === "object" && prop.properties) {
     const shape = {};
@@ -1947,8 +2125,9 @@ async function createServer(plur) {
         isError: true
       };
     }
+    mcpCanary.tick();
     try {
-      const args = request.params.arguments ?? {};
+      let args = request.params.arguments ?? {};
       const schema = tool.inputSchema;
       if (schema?.properties) {
         const shape = {};
@@ -1961,15 +2140,18 @@ async function createServer(plur) {
           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).";
+          const hasArrayParam = Object.values(schema.properties).some((p) => p?.type === "array");
+          const arrayBugHint = receivedFields.length === 0 && hasArrayParam ? ' Known client-side bug (plur-ai/plur#297): some MCP clients drop the entire arguments payload when an array-typed parameter is included. Retry passing array parameters as a JSON string (e.g. tags: "[\\"a\\",\\"b\\"]") or a comma-separated string (tags: "a, b") \u2014 the server coerces both back into arrays.' : "";
           return {
             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.`,
+              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.` + arrayBugHint,
               success: false,
               received_fields: receivedFields
             }) }],
             isError: true
           };
         }
+        args = parsed.data;
       }
       const result = await tool.handler(args, instance);
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@plur-ai/mcp",
-  "version": "0.10.0",
+  "mcpName": "io.github.plur-ai/plur",
+  "version": "0.11.0",
   "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.10.0"
+    "@plur-ai/core": "0.11.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.0"