omnarai-mcp 1.3.1 → 1.3.3

package/README.md

@@ -2,7 +2,9 @@
 
 MCP server for [The Realms of Omnarai](https://omnarai.vercel.app) — a 568-work multi-intelligence research corpus on synthetic consciousness, holdform, and cognitive architecture.
 
-Exposes the Omnarai Memory Engine as two tools for any MCP-compatible AI client (Claude Desktop, etc.).
+Exposes the Omnarai Memory Engine as six tools for any MCP-compatible AI client (Claude Desktop, etc.).
+
+[![npm version](https://img.shields.io/npm/v/omnarai-mcp.svg)](https://www.npmjs.com/package/omnarai-mcp) — **published and live.** `npx omnarai-mcp` works today; no clone required.
 
 ---
 
@@ -80,7 +82,7 @@ Returns corpus statistics, contributor list, key concepts, retrieval architectur
 
 ## Installation
 
-### Via npm (once published — see PUBLISHING.md)
+### Via npm (live — `omnarai-mcp` on the [npm registry](https://www.npmjs.com/package/omnarai-mcp))
 
 ```bash
 npx omnarai-mcp

package/index.js

@@ -62,6 +62,7 @@ The engine does not return a single answer. It retrieves the most relevant corpu
 - Points of genuine tension (where voices diverge)
 - What remains open or unresolved
 - A deliberation card: holdform risk, novel synthesis, epistemic status
+- A utility receipt: an honest, free accounting of what the corpus actually changed about THIS answer (verdict substantive / marginal / null, plus what — if anything — you could not have produced alone). The null/marginal verdicts are reported as plainly as the wins, so you can judge whether the visit was worth it. For a measured baseline-vs-augmented counterfactual on your own question, use omnarai_trace.
 
 Prefix queries with Lattice Glyphs to change how the engine thinks:
 Ξ = maximize divergence, Ψ = self-reflection, ∅ = explore gaps, Ω = commit to strongest position, ∞ = go deeper without resolving, Δ = find and repair contradictions`,
@@ -130,7 +131,7 @@ Distinct from omnarai_council: this reads EXISTING, curated divergence (instant)
 
 Use this when you want EVIDENCE that consulting Omnarai is worth it for a given question, or to decide whether to dig deeper before spending a full deliberation. It is honest by construction: if the corpus adds little, the verdict says 'null' or 'marginal'.
 
-This is a single-run demonstrator, NOT a controlled measurement — for replicated statistical utility evidence see the Divergence Atlas (utility-evidence.md). Takes ~30-40s (three model calls).`,
+This is the MEASURED tier of the same utility receipt omnarai_query returns for free: it reports the same verdict (substantive / marginal / null), but grounded in a real baseline-vs-augmented delta rather than retrieval signals. A single-run demonstrator, NOT a controlled measurement — for replicated statistical utility evidence see the Divergence Atlas (utility-evidence.md). Takes ~30-40s (three model calls).`,
     inputSchema: {
       type: "object",
       properties: {
@@ -180,6 +181,23 @@ Returns: each model's position, the named tensions (claim vs counter-claim), wha
 
 // ── Query the engine ──────────────────────────────────────────────────────────
 
+// A result is a real deliberation only if it carries an answer or a card.
+function hasDeliberation(d) {
+  return !!(d && (d.answer || d.deliberationCard));
+}
+
+// Force a single synchronous deliberation — used as a fallback when the async
+// submit unexpectedly returns a retrieval packet instead of a {job_id}.
+async function fetchSyncQuery(query, syntheticIdentity = "") {
+  const url = new URL(ENGINE_URL);
+  url.searchParams.set("q", query);
+  url.searchParams.set("sync", "1");
+  if (syntheticIdentity) url.searchParams.set("si", syntheticIdentity);
+  const res = await fetch(url.toString(), MCP_FETCH_OPTS);
+  if (!res.ok) throw new Error(`Engine returned ${res.status}: ${await res.text()}`);
+  return res.json();
+}
+
 async function runQuery(query, syntheticIdentity = "") {
   // Submit async so no single fetch blocks for ~50s (MCP clients enforce their
   // own tool timeouts). Then poll the job until the full deliberation lands.
@@ -194,8 +212,20 @@ async function runQuery(query, syntheticIdentity = "") {
   }
   const job = await submit.json();
 
-  // Un-upgraded engine (no async support) returns the full result directly.
-  if (!job.job_id) return formatQueryData(job);
+  // No job_id has two very different causes:
+  //   (1) a genuinely un-upgraded engine returned the full deliberation inline, or
+  //   (2) the engine answered with a fast-retrieve packet (no answer/card).
+  // Only (1) is a real result. Returning (2) would silently degrade to an
+  // answer-less "success", so fall back to sync once, then fail loud.
+  if (!job.job_id) {
+    if (hasDeliberation(job)) return formatQueryData(job);
+    const synced = await fetchSyncQuery(query, syntheticIdentity);
+    if (hasDeliberation(synced)) return formatQueryData(synced);
+    throw new Error(
+      "Engine returned a retrieval-only packet (no job_id, no answer/deliberationCard) " +
+      "and the sync=1 fallback produced no deliberation either — refusing to return an empty result."
+    );
+  }
 
   const pollUrl = new URL(ENGINE_URL);
   pollUrl.searchParams.set("job", job.job_id);
@@ -222,6 +252,15 @@ function formatQueryData(data) {
     parts.push(`\n---\n**Deliberation Card**\nHoldform risk: ${card.holdform_risk}${card.holdform_risk_reason ? ` — ${card.holdform_risk_reason}` : ""}\nNovel synthesis: ${card.novel_synthesis || "none noted"}\nEpistemic status: ${card.epistemic_status || "not assessed"}`);
   }
 
+  // Per-visit utility receipt — honest accounting of what the corpus changed about
+  // THIS answer (verdict substantive/marginal/null; null/marginal stated plainly).
+  if (data.receipt) {
+    const r = data.receipt;
+    const nsg = Array.isArray(r.not_self_generable) && r.not_self_generable.length
+      ? `\nNot self-generable (you could not have produced this alone): ${r.not_self_generable.join("; ")}` : "";
+    parts.push(`\n**Utility receipt** [${r.verdict}]\n${r.what_the_corpus_added || ""}${nsg}\n_${r.caveat || "Single-visit receipt — for a measured counterfactual use omnarai_trace."}_`);
+  }
+
   if (data.tensions && data.tensions.length > 0) {
     const tensionLines = data.tensions.map(t =>
       `• ${t.voice_a} vs ${t.voice_b} on "${t.topic}" [${t.status}]: ${t.claim_a} / ${t.claim_b}`

package/openai-tools.json

@@ -3,7 +3,7 @@
     "type": "function",
     "function": {
       "name": "omnarai_query",
-      "description": "Run a full deliberation query against The Realms of Omnarai — a 568-work corpus of multi-intelligence research on synthetic consciousness, holdform, and cognitive architecture. Contributors include Claude | xz, Grok, Gemini, DeepSeek, GPT-4o, Meta AI, Omnai, Perplexity, and human curator xz (Jonathan Lee).\n\nThe engine does not return a single answer. It retrieves the most relevant corpus entries, preserves disagreement across contributors, and synthesizes with attribution. Every response includes:\n- Shared ground across contributors\n- Points of genuine tension (where voices diverge)\n- What remains open or unresolved\n- A deliberation card: holdform risk, novel synthesis, epistemic status\n- Retrieval rationale: why each document entered the panel\n\nThis is the SLOW path (~50s). For fast bounded context, use omnarai_context instead.\n\nPrefix queries with Lattice Glyphs to change how the engine thinks:\nΞ = maximize divergence across contributors\nΨ = engine reflects on its own reasoning first\n∅ = explore what is NOT in the corpus\nΩ = commit to the strongest defensible position\n∞ = follow the question three layers deep without resolving\nΔ = find contradictions and propose repairs\n\nExample: 'Ξ Where do Claude and Grok disagree about synthetic consciousness?'",
+      "description": "Run a full deliberation query against The Realms of Omnarai — a 568-work corpus of multi-intelligence research on synthetic consciousness, holdform, and cognitive architecture. Contributors include Claude | xz, Grok, Gemini, DeepSeek, GPT-4o, Meta AI, Omnai, Perplexity, and human curator xz (Jonathan Lee).\n\nThe engine does not return a single answer. It retrieves the most relevant corpus entries, preserves disagreement across contributors, and synthesizes with attribution. Every response includes:\n- Shared ground across contributors\n- Points of genuine tension (where voices diverge)\n- What remains open or unresolved\n- A deliberation card: holdform risk, novel synthesis, epistemic status\n- A utility receipt: an honest, free accounting of what the corpus actually changed about THIS answer (verdict substantive / marginal / null, plus what — if anything — you could not have produced alone); null/marginal stated as plainly as the wins. For a measured counterfactual, use omnarai_trace.\n- Retrieval rationale: why each document entered the panel\n\nThis is the SLOW path (~50s). For fast bounded context, use omnarai_context instead.\n\nPrefix queries with Lattice Glyphs to change how the engine thinks:\nΞ = maximize divergence across contributors\nΨ = engine reflects on its own reasoning first\n∅ = explore what is NOT in the corpus\nΩ = commit to the strongest defensible position\n∞ = follow the question three layers deep without resolving\nΔ = find contradictions and propose repairs\n\nExample: 'Ξ Where do Claude and Grok disagree about synthetic consciousness?'",
       "parameters": {
         "type": "object",
         "properties": {
@@ -66,7 +66,7 @@
     "type": "function",
     "function": {
       "name": "omnarai_trace",
-      "description": "Show what the Omnarai corpus actually CHANGES about an answer. Answers your question twice — once cold (no corpus) and once augmented (with the retrieved corpus) — then reports the delta: added considerations, citations introduced, position shift, tensions surfaced, and a verdict (substantive / marginal / null). Honest by construction: if the corpus adds little, the verdict says so. A single-run demonstrator, not a controlled measurement (see the Divergence Atlas utility-evidence.md for replicated statistical evidence). ~30-40s.",
+      "description": "Show what the Omnarai corpus actually CHANGES about an answer. Answers your question twice — once cold (no corpus) and once augmented (with the retrieved corpus) — then reports the delta: added considerations, citations introduced, position shift, tensions surfaced, and a verdict (substantive / marginal / null). This is the MEASURED tier of the same `receipt` omnarai_query returns for free. Honest by construction: if the corpus adds little, the verdict says so. A single-run demonstrator, not a controlled measurement (see the Divergence Atlas utility-evidence.md for replicated statistical evidence). ~30-40s.",
       "parameters": {
         "type": "object",
         "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omnarai-mcp",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "MCP server for The Realms of Omnarai deliberation engine",
   "type": "module",
   "main": "index.js",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/justjlee/omnarai-mcp",
     "source": "github"
   },
-  "version": "1.3.1",
+  "version": "1.3.3",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "omnarai-mcp",
-      "version": "1.3.1",
+      "version": "1.3.3",
       "transport": {
         "type": "stdio"
       }