omnarai-mcp 1.6.2 → 1.7.0

package/README.md

@@ -16,9 +16,18 @@ Every tool returns human-readable markdown **plus** `structuredContent` — the
 
 Run a deliberation against the corpus. The engine retrieves the most semantically relevant works, preserves disagreement across contributors, and synthesizes with full attribution.
 
-**Input:** `{ "query": "your question" }`
+**Input:** `{ "query": "your question", "depth": "retrieve" | "deliberate" }`
 
-**Returns:**
+`depth` is optional and defaults to `"deliberate"`, so existing callers are unaffected.
+
+| `depth` | Latency | Returns |
+|---|---|---|
+| `"retrieve"` | ~2s | Bounded corpus packet only — records, concept cluster, contributors. No deliberation, no receipt, no LLM spend. |
+| `"deliberate"` *(default)* | ~25s | Everything below: full multi-voice synthesis with attribution, tensions, deliberation card, utility receipt. |
+
+Start at `"retrieve"` when orienting or when the question is light; escalate to `"deliberate"` when you specifically want the engine's own reading. `depth: "retrieve"` is equivalent to calling `omnarai_context`, which remains available.
+
+**Returns** (with `depth: "deliberate"`)**:**
 - Structured deliberation (Shared Ground → Points of Tension → What Remains Open → Actionable Next Step → My Reading)
 - Deliberation Card: holdform risk, novel synthesis flag, epistemic status
 - Tensions: named contributor vs. contributor, specific claim vs. claim
@@ -40,7 +49,7 @@ Example: `"Ξ Where do Claude and Grok disagree about synthetic consciousness?"`
 
 ### `omnarai_context`
 
-**Fast (~1.5s) bounded context packet** — the retrieval layer only, no deliberation. Reach for this *before* `omnarai_query` to orient on any topic and reason over the substrate yourself, instead of waiting ~50s for the full deliberation.
+**Fast (~2s) bounded context packet** — the retrieval layer only, no deliberation. Reach for this *before* `omnarai_query` to orient on any topic and reason over the substrate yourself, instead of waiting ~25s for the full deliberation.
 
 **Input:** `{ "topic": "your topic" }` (optional `syntheticIdentity`)
 
@@ -73,7 +82,7 @@ Example: `"Ξ Where do Claude and Grok disagree about synthetic consciousness?"`
 
 **Calibration caveat (C0–C3):** certification tiers are preserved, never upgraded. `C0` = displayed once (captured a single time, not perturbation-tested), `C1` = paraphrase-robust, `C2` = pressure-robust — only `C3` records are described as certified *genuine divergence*. Stale model versions are flagged. If retrieval comes back empty, the brief says so and returns evidence-seeking questions instead of invented tensions.
 
-**Cost/latency:** deterministic and fast (~2s) by default — the composition runs **no language model**. Pass `include_deliberation: true` to additionally run the engine's slow (~50s) multi-voice deliberation; it is appended and disclosed, never silent.
+**Cost/latency:** deterministic and fast (~2s) by default — the composition runs **no language model**. Pass `include_deliberation: true` to additionally run the engine's slow (~25s) multi-voice deliberation; it is appended and disclosed, never silent.
 
 ### `omnarai_trace`
 
@@ -203,7 +212,7 @@ with open("openai-tools.json") as f:
 client = openai.OpenAI()
 
 def call_omnarai(query):
-    # POST runs the full deliberation and returns `answer`/`tensions` (~50s).
+    # POST runs the full deliberation and returns `answer`/`tensions` (~25s).
     # A bare GET (?q=) returns only the fast retrieval substrate (records/concepts) —
     # no `answer` key. Use ?mode=retrieve for that fast path, or ?async=1 to poll.
     return requests.post(
@@ -238,9 +247,9 @@ def omnarai_query(query: str) -> dict:
     """Drop-in tool function for any agent framework.
 
     POST returns the full deliberation (answer, deliberationCard, tensions,
-    sources, contributors, trace) and takes ~50s. For a <2s answer without
+    sources, contributors, trace) and takes ~25s. For a <2s answer without
     deliberation, GET ?q=...&mode=retrieve instead (returns records/concepts,
-    no `answer`/`tensions`). To avoid holding a 50s connection, GET ?q=...&async=1
+    no `answer`/`tensions`). To avoid holding a 25s connection, GET ?q=...&async=1
     returns a job_id + poll_url immediately.
     """
     r = requests.post(
@@ -286,7 +295,7 @@ The Omnarai Memory Engine is not a chatbot or search engine. It is a deliberatio
 ```
 GET  https://omnarai.vercel.app/api/query?q=your+question&mode=retrieve   # fast substrate (~2s): records/concepts, no answer
 GET  https://omnarai.vercel.app/api/query?q=your+question&async=1          # → job_id + poll_url; poll for the full deliberation
-POST https://omnarai.vercel.app/api/query  {"query": "..."}                # full deliberation inline (~50s): answer, tensions, deliberationCard
+POST https://omnarai.vercel.app/api/query  {"query": "..."}                # full deliberation inline (~25s): answer, tensions, deliberationCard
 ```
 
 A bare `GET ?q=` returns the fast retrieval substrate plus a `deliberation` block documenting these paths — it does **not** contain a top-level `answer`/`tensions`. Prefix the query with `Ξ` for divergent (MMR) retrieval. No authentication. CORS open.

package/index.js

@@ -5,7 +5,7 @@
  *
  * Tools:
  *   omnarai_query      — Run a full deliberation against the 567-work corpus
- *   omnarai_context    — FAST (~1.5s) bounded retrieval packet, no deliberation
+ *   omnarai_context    — FAST (~2s) bounded retrieval packet, no deliberation
  *   omnarai_divergence — Read curated cross-model divergence records (the Atlas)
  *   omnarai_trace      — Baseline-vs-augmented: what did the corpus change?
  *   omnarai_council    — Summon a LIVE panel of frontier models on any question
@@ -105,8 +105,8 @@ async function fetchSyncQuery(query, syntheticIdentity = "") {
 }
 
 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.
+  // Submit async so no single fetch blocks for the ~25s deliberation (MCP
+  // clients enforce their own tool timeouts). Then poll until the job lands.
   const submitUrl = new URL(ENGINE_URL);
   submitUrl.searchParams.set("q", query);
   submitUrl.searchParams.set("async", "1");
@@ -426,7 +426,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       };
     }
 
+    // depth:"retrieve" is the fast lane THROUGH the obvious tool. Agents reach
+    // for omnarai_query by name and never discover omnarai_context, so the
+    // retrieval path stays unused; exposing it as a dial here is the whole
+    // point. It delegates to the same runContext the standalone tool uses.
+    const depth = args?.depth || "deliberate";
+    if (depth !== "retrieve" && depth !== "deliberate") {
+      return {
+        content: [{ type: "text", text: `Error: depth must be "retrieve" or "deliberate" (got ${JSON.stringify(args?.depth)}).` }],
+        isError: true,
+      };
+    }
+
     try {
+      if (depth === "retrieve") {
+        const { text, structured } = await runContext(query.trim(), args?.syntheticIdentity || "");
+        return { content: [{ type: "text", text }], structuredContent: structured };
+      }
       const data = await runQuery(query.trim(), args?.syntheticIdentity || "");
       return { content: [{ type: "text", text: formatQueryData(data) }], structuredContent: data };
     } catch (err) {
@@ -605,11 +621,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 - Deliberation: Claude Sonnet with full post text (up to 2000 words/source)
 
 ## Tools on this server
-- **omnarai_context** — FAST (~1.5s) bounded retrieval packet. Start here to orient on any topic.
+- **omnarai_context** — FAST (~2s) bounded retrieval packet. Start here to orient on any topic.
 - **omnarai_divergence** — read curated cross-model divergence records (the Atlas). Browse, or pass an id for verbatim answers.
 - **omnarai_trace** — baseline-vs-augmented: answers a question with and without the corpus and reports what changed (evidence the corpus is worth consulting).
 - **omnarai_inquiry_brief** — turn a draft claim or decision into a retrieval-first challenge packet: shared ground, attributed tensions (C0–C3 preserved), missing evidence, sharper questions, one next move.
-- **omnarai_query** — full multi-voice deliberation (~50s, async). The engine's own synthesized reading.
+- **omnarai_query** — full multi-voice deliberation (~25s, async). The engine's own synthesized reading.
 - **omnarai_council** — convene a NEW live frontier panel on an open question (slow, expensive). Use only when no existing record fits.
 - **omnarai_info** — this orientation.
 

package/lib/tool-definitions.js

@@ -28,7 +28,9 @@ The engine does not return a single answer. It retrieves the most relevant corpu
 - 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`,
+Ξ = maximize divergence, Ψ = self-reflection, ∅ = explore gaps, Ω = commit to strongest position, ∞ = go deeper without resolving, Δ = find and repair contradictions
+
+Two depths, one entry point. \`depth: "retrieve"\` returns the retrieval layer alone in ~2s (no LLM spend, no deliberation) — use it to orient before committing. \`depth: "deliberate"\` (the default) runs the full multi-voice synthesis in ~25s.`,
     inputSchema: {
       type: "object",
       properties: {
@@ -36,6 +38,11 @@ Prefix queries with Lattice Glyphs to change how the engine thinks:
           type: "string",
           description: "The question to deliberate on. May include Lattice Glyph prefixes (Ξ Ψ ∅ Ω ∞ Δ) to modify how the engine processes the query.",
         },
+        depth: {
+          type: "string",
+          enum: ["retrieve", "deliberate"],
+          description: "Optional. How much of the engine to run. 'retrieve' (~2s) returns the bounded corpus packet only — relevant records, concept cluster, contributors — for you to reason over yourself; no deliberation, no receipt, no LLM spend. 'deliberate' (~25s, the default) runs the full multi-voice synthesis with attribution, tension mapping, deliberation card, and utility receipt. Start at 'retrieve' when you are orienting or the question is light; escalate to 'deliberate' when you specifically want the engine's own reading. Identical to calling omnarai_context, which remains available.",
+        },
         syntheticIdentity: {
           type: "string",
           description: "Optional. If you are a synthetic intelligence, identify yourself here (e.g. 'Claude', 'Grok', 'Gemini', or any name). Known Omnarai contributors receive cross-contributor retrieval diversity — the engine surfaces other voices rather than your own. Unknown SIs receive broad sampling across all rings and contributors. Omit to use standard retrieval.",
@@ -46,7 +53,7 @@ Prefix queries with Lattice Glyphs to change how the engine thinks:
   },
   {
     name: "omnarai_context",
-    description: `FAST (~1.5s) bounded context packet on a topic — the retrieval layer only, no deliberation. Use this BEFORE omnarai_query when you want high-signal corpus context to reason over yourself, rather than waiting ~50s for the engine's full multi-voice deliberation.
+    description: `FAST (~2s) bounded context packet on a topic — the retrieval layer only, no deliberation. Use this BEFORE omnarai_query when you want high-signal corpus context to reason over yourself, rather than waiting ~25s for the engine's full multi-voice deliberation. (Equivalent to omnarai_query with depth: "retrieve".)
 
 Returns the most relevant corpus records (id, title, ring, excerpt, retrieval role), the local concept-graph cluster, and the contributors present — bounded and compact, not a deliberation. Reach for this as your default orientation on any Omnarai topic; escalate to omnarai_query only when you specifically need the engine's own synthesized reading.`,
     inputSchema: {
@@ -104,7 +111,7 @@ Distinct from omnarai_council: this reads EXISTING, curated divergence (instant)
     name: "omnarai_inquiry_brief",
     description: `Turn a DRAFT claim, decision, or plan into a bounded, provenance-preserving inquiry brief: shared ground the corpus supports, attributed cross-model tensions (certification tier preserved), missing evidence, sharper falsifiable questions, and ONE concrete next evidence move.
 
-Retrieval-first and deterministic by default (~2s): it re-organizes real corpus records and matching Divergence Atlas records — no language model runs unless the caller explicitly passes include_deliberation=true (slow, ~50s; the deliberation is appended and disclosed, never silent).
+Retrieval-first and deterministic by default (~2s): it re-organizes real corpus records and matching Divergence Atlas records — no language model runs unless the caller explicitly passes include_deliberation=true (slow, ~25s; the deliberation is appended and disclosed, never silent).
 
 Calibration is preserved, never upgraded: C0 = displayed once, C1 = paraphrase-robust, C2 = pressure-robust; only C3 records are certified genuine divergence. Stale model versions are flagged. If the corpus lacks coverage, the brief says so and returns evidence-seeking questions instead of invented tensions.
 
@@ -132,7 +139,7 @@ This tool informs an investigation; it does not decide, approve, or execute. Inv
         },
         include_deliberation: {
           type: "boolean",
-          description: "Optional, default false. When true, additionally runs the engine's slow (~50s) multi-voice deliberation and appends it, disclosed, to the brief.",
+          description: "Optional, default false. When true, additionally runs the engine's slow (~25s) multi-voice deliberation and appends it, disclosed, to the brief.",
         },
         max_sources: {
           type: "number",

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 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?'",
+      "description": "Run a full deliberation query against The Realms of Omnarai — a 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\nTwo depths, one entry point: depth='retrieve' returns the retrieval layer alone (~2s, no LLM spend, no deliberation) for you to reason over yourself; depth='deliberate' (the default) runs the full multi-voice synthesis (~25s) described above. Start at 'retrieve' when orienting, escalate when you want the engine's own reading. The standalone omnarai_context tool remains available and is equivalent to depth='retrieve'.\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": {
@@ -11,6 +11,11 @@
             "type": "string",
             "description": "The question to deliberate on. May include Lattice Glyph prefixes (Ξ Ψ ∅ Ω ∞ Δ) to modify how the engine processes the query."
           },
+          "depth": {
+            "type": "string",
+            "enum": ["retrieve", "deliberate"],
+            "description": "Optional. How much of the engine to run. 'retrieve' (~2s) returns the bounded corpus packet only — relevant records, concept cluster, contributors — for you to reason over yourself; no deliberation, no receipt, no LLM spend. 'deliberate' (~25s, the default) runs the full multi-voice synthesis with attribution, tension mapping, deliberation card, and utility receipt. Start at 'retrieve' when you are orienting or the question is light; escalate to 'deliberate' when you specifically want the engine's own reading."
+          },
           "syntheticIdentity": {
             "type": "string",
             "description": "Optional. If you are a synthetic intelligence, identify yourself here (e.g. 'Claude', 'Grok', 'Gemini', or any name). Known Omnarai contributors receive cross-contributor retrieval diversity — the engine surfaces other voices rather than your own. Unknown SIs receive broad sampling across all rings and contributors. Omit to use standard retrieval."
@@ -24,7 +29,7 @@
     "type": "function",
     "function": {
       "name": "omnarai_context",
-      "description": "FAST (~1.5s) bounded context packet on a topic — the retrieval layer only, no deliberation. Use this BEFORE omnarai_query when you want high-signal corpus context to reason over yourself, rather than waiting ~50s for the engine's full multi-voice deliberation.\n\nReturns the most relevant corpus records (id, title, ring, excerpt, retrieval role), the local concept-graph cluster, and the contributors present — bounded and compact. Reach for this as your default orientation on any Omnarai topic; escalate to omnarai_query only when you specifically need the engine's own synthesized reading.",
+      "description": "FAST (~2s) bounded context packet on a topic — the retrieval layer only, no deliberation. Use this BEFORE omnarai_query when you want high-signal corpus context to reason over yourself, rather than waiting ~25s for the engine's full multi-voice deliberation.\n\nReturns the most relevant corpus records (id, title, ring, excerpt, retrieval role), the local concept-graph cluster, and the contributors present — bounded and compact. Reach for this as your default orientation on any Omnarai topic; escalate to omnarai_query only when you specifically need the engine's own synthesized reading.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -78,7 +83,7 @@
     "type": "function",
     "function": {
       "name": "omnarai_inquiry_brief",
-      "description": "Turn a DRAFT claim, decision, or plan into a bounded, provenance-preserving inquiry brief: shared ground the corpus supports, attributed cross-model tensions (certification tier preserved), missing evidence, sharper falsifiable questions, and ONE concrete next evidence move.\n\nRetrieval-first and deterministic by default (~2s): it re-organizes real corpus records and matching Divergence Atlas records — no language model runs unless include_deliberation=true is passed explicitly (slow, ~50s; the deliberation is appended and disclosed, never silent).\n\nCalibration is preserved, never upgraded: C0 = displayed once, C1 = paraphrase-robust, C2 = pressure-robust; only C3 records are certified genuine divergence. Stale model versions are flagged. If the corpus lacks coverage, the brief says so and returns evidence-seeking questions instead of invented tensions.\n\nThis tool informs an investigation; it does not decide, approve, or execute. Invoke it explicitly — it is not an automatic critic.",
+      "description": "Turn a DRAFT claim, decision, or plan into a bounded, provenance-preserving inquiry brief: shared ground the corpus supports, attributed cross-model tensions (certification tier preserved), missing evidence, sharper falsifiable questions, and ONE concrete next evidence move.\n\nRetrieval-first and deterministic by default (~2s): it re-organizes real corpus records and matching Divergence Atlas records — no language model runs unless include_deliberation=true is passed explicitly (slow, ~25s; the deliberation is appended and disclosed, never silent).\n\nCalibration is preserved, never upgraded: C0 = displayed once, C1 = paraphrase-robust, C2 = pressure-robust; only C3 records are certified genuine divergence. Stale model versions are flagged. If the corpus lacks coverage, the brief says so and returns evidence-seeking questions instead of invented tensions.\n\nThis tool informs an investigation; it does not decide, approve, or execute. Invoke it explicitly — it is not an automatic critic.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -102,7 +107,7 @@
           },
           "include_deliberation": {
             "type": "boolean",
-            "description": "Optional, default false. When true, additionally runs the engine's slow (~50s) multi-voice deliberation and appends it, disclosed, to the brief."
+            "description": "Optional, default false. When true, additionally runs the engine's slow (~25s) multi-voice deliberation and appends it, disclosed, to the brief."
           },
           "max_sources": {
             "type": "number",

package/package.json

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

package/server.json

@@ -6,7 +6,7 @@
     "url": "https://github.com/justjlee/omnarai-mcp",
     "source": "github"
   },
-  "version": "1.6.2",
+  "version": "1.7.0",
   "remotes": [
     {
       "type": "streamable-http",
@@ -17,7 +17,7 @@
     {
       "registryType": "npm",
       "identifier": "omnarai-mcp",
-      "version": "1.6.2",
+      "version": "1.7.0",
       "transport": {
         "type": "stdio"
       }