MCP server: omnimcode-mcp exposes OMC as a runtime to LLM clients

RandomCoder-lab · claude · RandomCoder-lab · commit 51aaef31c949 · 2026-05-16T10:38:04.000-05:00
New crate omnimcode-mcp implements the MCP protocol over stdin/stdout
JSON-RPC so any MCP client (Claude Desktop, Cursor, etc.) can drive
OMC programmatically. The intent: turn OMC from "an LLM can write
this if you hand it the manual" into "an LLM treats OMC as a callable
runtime the way it treats Python via REPL."

Tools exposed:
  omc_eval(code)             — evaluate OMC source, return result
  omc_help(name)             — signature/description/example for builtin
  omc_list_builtins(cat?)    — enumerate documented builtins
  omc_categories()           — list categories
  omc_unique_builtins()      — the OMC-only surface (substrate / autograd /
                               lazy generators / harmonic ops)
  omc_explain_error(message) — 259-pattern catalog lookup with fix
  omc_did_you_mean(name)     — typo suggestions

Implementation notes:
  - Each tools/call spins a fresh Interpreter to keep the server
    stateless. Sessions can layer on top.
  - omc_eval returns the last top-level expression value via the new
    Interpreter::take_last_expression_value() hook.
  - Display format collapses Rust's Debug{...} noise into compact
    LLM-readable strings; HInt surfaces value + φ-resonance + HIM
    so substrate metadata is visible in tool output.

New OMC-side helpers:
  Interpreter::take_return_value()           — top-level returns
  Interpreter::take_last_expression_value()  — REPL-style result capture

examples/demos/llm_showcase.omc — the canonical "this is OMC" demo
running every OMC-unique primitive that an LLM would reach for OMC
over NumPy: substrate-typed integers, substrate-preserving matmul,
substrate-distance attention, autograd with substrate-annotated
forward values, lazy Fibonacci streams. Bottom-line numbers from the
showcase: 100 builtins documented, 13 OMC-unique, 259 error patterns
curated, 14 categories.

OMC_REFERENCE.md regenerated (1085 lines) to reflect the docs change
(`resonance` → `res` to match the actual builtin name).

Claude Desktop config example included in omnimcode-mcp/README.md.

Co-Authored-By: Claude Opus 4.7 &lt;noreply@anthropic.com&gt;
diff --git a/Cargo.toml b/Cargo.toml
@@ -6,6 +6,7 @@ members = [
     "omnimcode-lsp",
     "omnimcode-codegen",
     "omnimcode-cli",
+    "omnimcode-mcp",
 ]
 # omnimcode-python kept around but excluded from the default workspace.
 # It was the "Python embeds OMC" wrapper (extension-module mode); now
diff --git a/OMC_REFERENCE.md b/OMC_REFERENCE.md
@@ -2,7 +2,7 @@
 
 Auto-generated from `omnimcode-core/src/docs.rs`. Run `omc --gen-docs > OMC_REFERENCE.md` to regenerate.
 
-**Total documented builtins**: 97
+**Total documented builtins**: 100
 
 **OMC-unique**: 13 (no direct Python/NumPy equivalent — these are why you reach for OMC over numpy)
 
@@ -23,7 +23,7 @@ Auto-generated from `omnimcode-core/src/docs.rs`. Run `omc --gen-docs > OMC_REFE
 - [json](#json) (2 builtins)
 - [stdlib](#stdlib) (8 builtins)
 - [exceptions](#exceptions) (1 builtins)
-- [introspection](#introspection) (5 builtins)
+- [introspection](#introspection) (8 builtins)
 
 ---
 
@@ -535,14 +535,14 @@ Position in Fibonacci sequence (-1 if not an attractor).
 fibonacci_index(13)  // 7  ; fibonacci_index(14)  // -1
 ```
 
-### `resonance` 🔱 *OMC-unique*
+### `res` 🔱 *OMC-unique*
 
 **Signature**: `(n: int) -> float`
 
-φ-resonance of a single value.
+φ-resonance of a single value (0..1, 1=on Fibonacci attractor).
 
 ```omc
-resonance(8)  // 1.0  ; resonance(7)  // <1.0
+res(8)  // 1.0  ; res(7)  // <1.0
 ```
 
 ### `harmony` 🔱 *OMC-unique*
@@ -1051,5 +1051,35 @@ Builtins flagged as unique to OMC (no clean Python equivalent).
 omc_unique_builtins()  // [is_attractor, arr_substrate_attention, ...]
 ```
 
+### `omc_explain_error`
+
+**Signature**: `(msg: string) -> dict`
+
+Pattern-match an error message against the curated catalog. Returns {matched, pattern, category, explanation, typical_cause, fix}.
+
+```omc
+try { arr_softmx([1.0]); } catch e { print(dict_get(omc_explain_error(e), "fix")); }
+```
+
+### `omc_error_categories`
+
+**Signature**: `() -> string[]`
+
+All distinct error categories in the catalog.
+
+```omc
+omc_error_categories()  // [dispatch, arrays, linalg, ...]
+```
+
+### `omc_error_count`
+
+**Signature**: `() -> int`
+
+Number of curated error patterns. The knowledge base size.
+
+```omc
+omc_error_count()  // 42+
+```
+
 ---
 
diff --git a/examples/demos/llm_showcase.omc b/examples/demos/llm_showcase.omc
@@ -0,0 +1,112 @@
+# The OMC-unique surface: things an LLM would reach for OMC for that
+# Python/NumPy/JAX simply can't do.
+#
+# Each section starts with a one-line "why this is OMC-only" so an LLM
+# reading the output understands the differentiator.
+
+fn show(label, v) {
+    print(concat_many(label, " = ", to_string(v)));
+}
+
+fn main() {
+    print("=== OMC unique-primitive showcase ===");
+    print("Run via: omc examples/demos/llm_showcase.omc");
+    print("");
+
+    # ----------------------------------------------------------------
+    # 1. Substrate metadata on every integer.
+    #    Python's i64 is a raw value. OMC's HInt carries φ-resonance
+    #    and HIM scores reflecting Fibonacci-attractor alignment.
+    # ----------------------------------------------------------------
+    print("[1] Substrate metadata on integers (no NumPy equivalent)");
+    show("  is_attractor(8)            ", is_attractor(8));    # 1 (Fib)
+    show("  is_attractor(7)            ", is_attractor(7));    # 0
+    show("  attractor_distance(7)      ", attractor_distance(7));  # 1
+    show("  res(8)                     ", res(8));       # 1.0
+    show("  res(7)                     ", res(7));       # < 1.0
+    print("");
+
+    # ----------------------------------------------------------------
+    # 2. Substrate-typed array library. Resonance/HIM survive every op.
+    # ----------------------------------------------------------------
+    print("[2] Substrate-typed array ops");
+    h fib = [0, 1, 2, 3, 5, 8, 13, 21];
+    show("  arr_resonance_vec(fib)    ", arr_resonance_vec(fib));
+    show("  arr_fold_all([7,100,9,22])", arr_fold_all([7, 100, 9, 22]));
+    print("");
+
+    # ----------------------------------------------------------------
+    # 3. Matrix multiplication preserves substrate metadata.
+    #    Every output cell of an int matmul carries its own resonance.
+    # ----------------------------------------------------------------
+    print("[3] Substrate-preserving matmul");
+    h A = [[1, 2], [3, 5]];   # Fibonacci-shaped
+    h B = [[2, 3], [5, 8]];
+    h C = arr_matmul(A, B);   # 2x2 result, each cell HInt
+    show("  A @ B[0]                  ", arr_get(C, 0));
+    show("  A @ B[1]                  ", arr_get(C, 1));
+    print("");
+
+    # ----------------------------------------------------------------
+    # 4. Substrate-distance attention. The attention KERNEL itself
+    #    uses Fibonacci-distance scoring instead of dot products.
+    # ----------------------------------------------------------------
+    print("[4] Substrate-distance attention");
+    h Q = [[1, 2]];                       # single query
+    h K = [[1, 2], [100, 200]];           # close key + far key
+    h V = [[5.0, 5.0], [99.0, 99.0]];     # close V + far V
+    h out = arr_substrate_attention(Q, K, V);
+    show("  attention(Q,K,V)[0]       ", arr_get(out, 0));
+    print("  → strongly weighted toward V[0] because Q matches K[0] in substrate-space");
+    print("");
+
+    # ----------------------------------------------------------------
+    # 5. Reverse-mode autograd that preserves substrate metadata on
+    #    forward values. Python autograd hands you plain f64.
+    # ----------------------------------------------------------------
+    print("[5] Autograd that keeps substrate metadata on forward path");
+    tape_reset();
+    h x = tape_var(3);
+    h y = tape_var(5);
+    h s = tape_add(x, y);     # 8 — Fibonacci attractor
+    h sq = tape_mul(s, s);    # 64 — close to 55 attractor
+    tape_backward(sq);
+    show("  forward value at s        ", tape_value(s));   # substrate-annotated 8
+    show("  forward value at sq       ", tape_value(sq));
+    show("  d(sq)/dx                  ", tape_grad(x));    # 2*8 = 16
+    show("  d(sq)/dy                  ", tape_grad(y));    # 2*8 = 16
+    print("");
+
+    # ----------------------------------------------------------------
+    # 6. Lazy substrate Fibonacci generator — streams forever in O(1)
+    #    memory. Each yielded value already carries resonance=1.0.
+    # ----------------------------------------------------------------
+    print("[6] Lazy substrate Fibonacci stream (O(1) memory)");
+    h collected = [];
+    gen_substrate_fib(
+        fn(v) {
+            arr_push(collected, v);
+            return 1;
+        },
+        100
+    );
+    show("  Fibs <= 100               ", collected);
+    print("");
+
+    # ----------------------------------------------------------------
+    # 7. The introspection layer itself. LLMs read this at runtime.
+    # ----------------------------------------------------------------
+    print("[7] Self-describing runtime");
+    show("  builtin count             ", arr_len(omc_list_builtins()));
+    show("  category count            ", arr_len(omc_categories()));
+    show("  OMC-unique builtin count  ", arr_len(omc_unique_builtins()));
+    show("  curated error pattern count", omc_error_count());
+    print("");
+    print("  An LLM can call omc_help(\"<name>\") for any of these.");
+    print("  Errors come with did_you_mean suggestions + omc_explain_error.");
+
+    print("");
+    print("=== These are the primitives Python/NumPy cannot replicate. ===");
+}
+
+main();
diff --git a/omnimcode-core/src/docs.rs b/omnimcode-core/src/docs.rs
@@ -388,10 +388,10 @@ pub const BUILTINS: &[BuiltinDoc] = &[
         unique_to_omc: true,
     },
     BuiltinDoc {
-        name: "resonance", category: "substrate",
+        name: "res", category: "substrate",
         signature: "(n: int) -> float",
-        description: "φ-resonance of a single value.",
-        example: "resonance(8)  // 1.0  ; resonance(7)  // <1.0",
+        description: "φ-resonance of a single value (0..1, 1=on Fibonacci attractor).",
+        example: "res(8)  // 1.0  ; res(7)  // <1.0",
         unique_to_omc: true,
     },
     BuiltinDoc {
diff --git a/omnimcode-core/src/interpreter.rs b/omnimcode-core/src/interpreter.rs
@@ -44,6 +44,11 @@ pub struct Interpreter {
     /// `tape_value(id)` to get the substrate-annotated forward value
     /// alongside `tape_grad(id)` for the derivative.
     autograd_tape: Vec<TapeNode>,
+    /// Value of the most recently evaluated top-level
+    /// `Statement::Expression`. The MCP server and any REPL frontend
+    /// read this to surface "what did the last line evaluate to"
+    /// without re-running side effects.
+    last_expression_value: Option<Value>,
     /// Stack of yield callbacks for LAZY generators. When set, the
     /// active generator's yield statements invoke the topmost callback
     /// with the yielded value rather than appending to a Vec. Memory
@@ -144,9 +149,16 @@ impl Interpreter {
             autograd_tape: Vec::new(),
             yield_callbacks: Vec::new(),
             gen_stop_requested: false,
+            last_expression_value: None,
         }
     }
 
+    /// Read (and clear) the most recent top-level expression value.
+    /// Used by the MCP server to return the result of `omc_eval`.
+    pub fn take_last_expression_value(&mut self) -> Option<Value> {
+        self.last_expression_value.take()
+    }
+
     /// Register a host-side builtin that OMC code can call by name.
     /// The closure receives the evaluated argument values and returns
     /// either a Value (success) or an error message that propagates
@@ -877,6 +889,14 @@ impl Interpreter {
         }
     }
 
+    /// Take ownership of the current top-level return value. Used by
+    /// the MCP server (and tooling) to read what the last `return`
+    /// produced after `execute` finished. None when the program didn't
+    /// return — equivalent to "no expression result".
+    pub fn take_return_value(&mut self) -> Option<Value> {
+        self.return_value.take()
+    }
+
     pub fn execute(&mut self, statements: Vec<Statement>) -> Result<(), String> {
         for stmt in statements {
             self.execute_stmt(&stmt)?;
@@ -1356,7 +1376,12 @@ impl Interpreter {
                 Ok(())
             }
             Statement::Expression(expr) => {
-                self.eval_expr(expr)?;
+                // Save the result so the MCP / REPL paths can read
+                // "what did the last top-level expression evaluate to"
+                // without re-running. Empty/silent expressions still
+                // leave the prior value in place.
+                let v = self.eval_expr(expr)?;
+                self.last_expression_value = Some(v);
                 Ok(())
             }
             Statement::VarDecl {
diff --git a/omnimcode-mcp/Cargo.toml b/omnimcode-mcp/Cargo.toml
@@ -0,0 +1,16 @@
+[package]
+name = "omnimcode-mcp"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+license.workspace = true
+description = "MCP server exposing OMC eval / introspection / error explainer to LLM clients."
+
+[[bin]]
+name = "omnimcode-mcp"
+path = "src/main.rs"
+
+[dependencies]
+omnimcode-core = { path = "../omnimcode-core", default-features = false }
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
diff --git a/omnimcode-mcp/README.md b/omnimcode-mcp/README.md
@@ -0,0 +1,90 @@
+# omnimcode-mcp
+
+MCP server for OMC. Lets an LLM client (Claude Desktop, Cursor, any
+JSON-RPC capable agent) call OMC as a runtime — eval code, look up
+builtins, get structured error explanations.
+
+Built so an LLM can write idiomatic OMC without it being in training
+data: the introspection + error catalog tools give it everything it
+needs to discover the language at runtime.
+
+## Tools exposed
+
+- `omc_eval(code)` — evaluate OMC source, return result value
+- `omc_help(name)` — signature + description + example for a builtin
+- `omc_list_builtins(category?)` — enumerate documented builtins
+- `omc_categories()` — list builtin categories
+- `omc_unique_builtins()` — OMC-only primitives (no NumPy equivalent)
+- `omc_explain_error(message)` — pattern-match an error against the
+  259-entry knowledge base; returns explanation + cause + fix
+- `omc_did_you_mean(name)` — typo suggestions over the known surface
+
+## Build
+
+```bash
+cargo build --release -p omnimcode-mcp
+# Binary lands at target/release/omnimcode-mcp
+```
+
+## Claude Desktop config
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or the equivalent on your platform:
+
+```json
+{
+  "mcpServers": {
+    "omc": {
+      "command": "/absolute/path/to/target/release/omnimcode-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The LLM can now call `omc_eval`, `omc_help`,
+etc. directly.
+
+## Why this matters for LLMs
+
+OMC has ~200+ builtins, many added recently. Without a discoverable
+surface, an LLM will hallucinate `numpy.dot` or invent `arr_multiply`.
+With the MCP server wired in, the LLM:
+
+1. Calls `omc_categories()` to see what's available
+2. Calls `omc_list_builtins("substrate")` to find OMC-unique primitives
+3. Calls `omc_help("arr_substrate_attention")` for signature + example
+4. Writes code, calls `omc_eval`
+5. On error, calls `omc_explain_error(msg)` for a one-line fix
+
+The OMC-unique primitives — substrate-typed arrays, autograd that
+preserves φ-resonance, native lazy generators, harmonic ops — are
+the reason an LLM would pick OMC over NumPy/PyTorch. The MCP server
+makes those discoverable.
+
+## Protocol
+
+Line-delimited JSON-RPC 2.0 over stdin/stdout. Implements:
+- `initialize` (returns server info + capabilities)
+- `tools/list` (returns the tool catalog above)
+- `tools/call` (dispatches to a tool by name)
+
+Notifications (no `id` field) are accepted silently. Anything else
+gets a "Method not found" error.
+
+## Example manual session
+
+```
+$ ./target/release/omnimcode-mcp
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
+{"jsonrpc":"2.0","id":2,"method":"tools/list"}
+{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"omc_eval","arguments":{"code":"is_attractor(8);"}}}
+```
+
+Returns:
+
+```json
+{"jsonrpc":"2.0","id":3,"result":{"content":[{"text":"HInt { value: 1, resonance: 1.000, him: 0.382 }","type":"text"}],"isError":false}}
+```
+
+Notice the substrate metadata in the response — that's the part Python
+can't give you.
diff --git a/omnimcode-mcp/src/main.rs b/omnimcode-mcp/src/main.rs

Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,7 @@ members = [`
`6`	`6`	`"omnimcode-lsp",`
`7`	`7`	`"omnimcode-codegen",`
`8`	`8`	`"omnimcode-cli",`
	`9`	`+ "omnimcode-mcp",`
`9`	`10`	`]`
`10`	`11`	`# omnimcode-python kept around but excluded from the default workspace.`
`11`	`12`	`# It was the "Python embeds OMC" wrapper (extension-module mode); now`