MCP • RAG • IoT

MCP Server

The Synoema MCP server implements the Model Context Protocol (MCP 2024-11-05) over stdio. It integrates the Synoema compiler, evaluator, type checker, and RAG retrieval layer into any MCP-compatible client — Claude Desktop, Cursor, Zed, or a custom agent.

Core Language Tools

Error JSON shape — every error from eval, typecheck, and run follows a machine-readable schema that LLMs can parse and act on:

{
  "code": "unbound_variable",
  "severity": "error",
  "message": "Undefined variable: foo",
  "span": {"line": 4, "col": 8, "end_line": 4, "end_col": 11},
  "llm_hint": "Variable 'foo' is not defined. Did you mean 'bar'?",
  "fixability": "easy",
  "did_you_mean": "bar",
  "source_origin": "user"
}

source_origin distinguishes user code ("user"), imported modules ("import:<path>"), and prelude bugs ("prelude"). Every error carries an llm_hint — a sentence written for the model, not the human.

Dev Intelligence Tools

Seven tools expose a live index of the Synoema compiler source, powered by syn AST parsing. Line numbers and API surfaces are always current — no stale docs.

All budgets are ≤500 tokens for compatibility with small context models (8K–32K). Available recipes: add_operator, add_builtin, add_type, fix_from_error.

RAG Retrieval Tools

Five tools perform semantic retrieval over the installed RAG index. See the RAG section for index details.

All retrieval tools degrade gracefully when the RAG index is absent — they return a structured error and the server continues serving all other tools without restart.

Auto-Injection for Small Models

Models ≤7B often cannot reliably emit structured search_* tool-use actions, but still benefit from retrieval context. The MCP server can auto-inject a retrieval_context field into responses from typecheck, run, and feedback_loop — transparent to the model, no protocol changes needed.

Enable in ~/.sno/config.toml:

[rag.auto_inject]
enabled = true
scopes = ["traces", "corpus"]  # any of corpus, docs, skills, traces, sno
top_k = 3
max_chunk_chars = 800

# Per-tool override:
[rag.auto_inject.per_tool.typecheck]
top_k = 2
scopes = ["traces"]

When the tool response contains an error, the middleware appends:

{
  "error": "Type mismatch: expected Int, found String",
  "retrieval_context": {
    "query": "Type mismatch: expected Int, found String",
    "hits": [
      {"scope": "traces", "source": "trace/t42.json", "score": 0.82, "text": "..."},
      {"scope": "corpus", "source": "corpus/add.sno",  "score": 0.78, "text": "..."}
    ],
    "auto_injected": true,
    "top_k": 3
  }
}

The middleware silently skips injection if the RAG index is missing. Clients that ignore retrieval_context see no behavioral change.

RAG Index Auto-Watch (per-project)

The MCP server can watch the project directory and rebuild the RAG index automatically when *.sno files change. Configure per-project via SNO_RAG_WATCH=true in your .mcp.json — no global config needed, no external tools required.

# .mcp.json in your project root
{
  "mcpServers": {
    "synoema": {
      "command": "/path/to/synoema-mcp",
      "args": [],
      "env": {
        "SNO_RAG_WATCH": "true"
      }
    }
  }
}

When SNO_RAG_WATCH=true the server builds the index on startup, polls all files recursively (skipping target/, .git/, node_modules/), and rebuilds 3 seconds after the last change. Each project writes to its own ~/.sno/rag-index/<project-name>/ — no collisions when multiple projects are open simultaneously.

Session & State Tools

Package Discovery Tools

Self-Report Tools (LLM → author feedback)

Four tools let the LLM record gaps, contradictions, or ambiguities it encounters. These feed the research/llm-failures/ channel — not for end users, but for improving the language and docs.

Telemetry is off by default. Enable local-only collection in ~/.sno/config.toml:

[telemetry]
llm_failures = "local-only"

MCP Installation & Connection

Step 1 — install the binary

sno mcp-install                  # recommended: auto-detects local build or downloads
sno mcp-install --from-source    # build from source (requires repo clone)
sno mcp-install --local ./mcp/target/release/synoema-mcp

Step 2 — configure your IDE

sno setup claude --binary    # Claude Desktop
sno setup cursor --binary    # Cursor
sno setup cline              # Cline (VS Code) — binary path auto-detected

Then restart your IDE (or Developer: Reload Window in VS Code for Cline).

Manual config reference

# Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "synoema": { "command": "/Users/you/.sno/bin/synoema-mcp" }
  }
}

# Cursor — .cursor/mcp.json
{ "synoema": { "command": "/Users/you/.sno/bin/synoema-mcp" } }

# Cline — cline_mcp_settings.json (mcpServers section)
{
  "synoema": {
    "disabled": false, "timeout": 60, "type": "stdio",
    "command": "/Users/you/.sno/bin/synoema-mcp",
    "args": [], "env": { "SNO_RAG_WATCH": "true" }
  }
}

# Zed — settings.json
{
  "context_servers": {
    "synoema": { "command": { "path": "/Users/you/.sno/bin/synoema-mcp", "args": [] } }
  }
}

Verify connection

Ask your agent: "Use the eval tool to compute 2 + 3". If you see 5 : Int, MCP is connected.

Traffic logging

# Enable logging for one run
SYNOEMA_MCP_TRAFFIC=1 synoema-mcp

# Or in ~/.sno/config.toml
[logging]
enabled = true
level = "errors"   # all | errors | tools
dir = "~/.sno/mcp-traffic"

RAG — Retrieval-Augmented Generation

RAG gives LLMs a local knowledge base they can search before generating code. Synoema's RAG stack is Rust-native, offline-first, and opt-in. No Python, no external vector database. It ships as part of the sno CLI and the MCP server.

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                     OFFLINE (build phase)                        │
│                                                                  │
│   source tree          sno build-index          vector index     │
│   ┌───────────┐   ──────────────────────▶   ┌──────────────┐    │
│   │ corpus    │        5 chunkers            │ chunks.jsonl │    │
│   │ docs/     │        potion-base-8M        │ vectors.bin  │    │
│   │ skills/   │        256-dim bundled       │ MANIFEST.json│    │
│   │ traces/   │                              └──────────────┘    │
│   │ .sno files│                                                  │
│   └───────────┘                                                  │
└──────────────────────────────────────────────────────────────────┘
                                   │
                           sno rag install
                                   │
                                   ▼
┌──────────────────────────────────────────────────────────────────┐
│                    RUNTIME (MCP server)                          │
│                                                                  │
│   ┌────────────────────────────────────────────────────────┐    │
│   │ synoema-mcp  ──  search_corpus / search_docs /         │    │
│   │                  search_skills / search_traces /        │    │
│   │                  search_unified                         │    │
│   └─────────────────────┬─────────────────────┬────────────┘    │
│                         │                     │                  │
│          ┌──────────────▼──┐       ┌─────────▼──────────────┐  │
│          │  sno fix         │       │  auto_inject           │  │
│          │  --with-rag      │       │  middleware             │  │
│          │  (ReAct loop)    │       │  (transparent for       │  │
│          │  explicit search │       │  small models)          │  │
│          └──────────────────┘       └────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘

Five Scopes

Embedder

Default embedder: potion-base-8M (Model2Vec static embedder — 8M parameters, 256-dim output, ~29 MB). Pure Rust, no ONNX runtime, no network I/O. Bundled directly into the binary via include_bytes! — RAG works out-of-the-box on every platform without a separate install step.

Default builds ship a deterministic StubEmbedder so that cargo test --all stays hermetic. The bundled real embedder is active by default in all release builds.

Index format

Brute-force cosine similarity over the full vector set. On the current corpus (~13k chunks) a single query takes ~50 ms on a 2023 M2 laptop. HNSW is deferred until the corpus exceeds ~20k chunks or query rate exceeds 50 qps — the dependency cost is not justified yet.

Three retrieval modes

ReAct retrieval trace example

Thought: I see a non-exhaustive case error. Let me search traces for similar fixes.
Action: search_traces
Arguments: {"query": "exhaustiveness case Nothing", "k": 3}
Observation: [
  {"source": "traces/t42.json", "score": 0.82, "text": "case opt of\n  Just x -> …\n  Nothing -> 0"}
]
Thought: Found the pattern. Adding the missing branch.
Action: apply_patch
Arguments: {"file": "broken.sno", "patch": "…"}

RAG Installation & Usage

Install

# Fastest: install Synoema with RAG in one command
curl -fsSL https://synoema.tech/install.sh | sh -s -- --with-rag

# PowerShell (Windows)
.\install.ps1 -WithRag

# Add RAG to an existing install
sno rag install

# Check what is installed
sno rag status
# → Installed: 2026-04-18, 12840 chunks across 5 scopes, ~179 MB

# Update when a new pack is published
sno rag update

# Remove everything
sno rag remove

sno rag install downloads the pack manifest, verifies SHA-256, extracts to ~/.sno/models/embed/<date>/, and flips an atomic symlink at ~/.sno/models/embed/current/ — in-flight tools never see a half-updated index.

Troubleshooting

Run sno doctor for a single-command health report across all components including the RAG pack, embedder path, and index integrity.

IoT Platform

Synoema's IoT platform enables LLM-generated automation rules to run on embedded hardware — from bare Cortex-M MCUs to Raspberry Pi — through a 3-tier device model and a WASM-first compilation strategy.

Three Deployment Tiers

Tier 0: Bare MCU              Tier 1: RTOS / wasm3            Tier 2: Linux Edge
──────────────────            ────────────────────────        ──────────────────
Cortex-M0/M3, <64 KB         ESP32, STM32, ≥128 KB           RPi, aarch64 SBC

sno wasm → .wasm              sno wasm → .wasm                sno build --native
     │                             │                               │
C host + wasm3 embed          wasm3 on-device                 Cranelift ObjectModule
integer-only rules            floats + contracts              full language

aot_thumbv7m.rs (partial)    wasm_codegen.rs v2+v3           aot_aarch64.rs
→ blocked: Cranelift ARM32    + wasm_runtime.rs               → shipped

Target hardware:              Target hardware:                Target hardware:
RP2040, STM32F0/F1            ESP32, STM32F4/H7               Raspberry Pi (all)
nRF5340 (Zephyr)              nRF5340, Arduino                Jetson, BeagleBone
<64 KiB flash                 ≥128 KiB flash                  x86/aarch64 Linux

WASM v3 Feature Matrix

Contracts at compile time

requires and ensures clauses compile to WebAssembly unreachable traps — violations are caught at runtime before they propagate. This mirrors the JIT contract enforcement via Cranelift trapif:

-- Synoema rule with safety contracts
rule_overpressure : Int -> Bool
  requires pressure > 0
  ensures result == (pressure > 800)
rule_overpressure pressure = pressure > 800

; WASM output (simplified)
;; requires check: trap if pressure <= 0
i64.const 0
call $__int_unbox
i64.gt_s
i64.eqz
if unreachable end

;; function body…
;; ensures check: trap if result != (pressure > 800)
…

Six Vertical MVPs

Wave 2 aggregate: 30/30 check (100%) • 29/30 WASM (96.7%) • mean 200 B. Known failure: rule_flow_min_alarm — Nil list pattern not yet registered in WASM v3 ctor_tags; deferred to wasm-host-imports.

LLM → IoT Pipeline

The complete pipeline from natural language prompt to WASM artifact on hardware:

Natural language prompt
       │
       ▼ LLM (constrained by synoema-iot-rules.gbnf)
Synoema IoT rule (.sno)
       │
       ├── sno check  →  parse + typecheck  →  PASS / FAIL + structured errors
       │
       └── sno wasm   →  WASM v3 codegen   →  .wasm artifact
                           │
                           ├── Tier 0: C host + wasm3 embed  (MCU)
                           ├── Tier 1: on-device wasm3       (RTOS/ESP32)
                           └── sno build --native            (Linux edge ELF)
                               --target aarch64-linux

GBNF-constrained generation

The LLM generates IoT rules constrained by lang/tools/constrained/synoema-iot-rules.gbnf — a GBNF grammar that limits output to valid Synoema rule syntax. This eliminates hallucinated syntax and reduces parse failures on first generation.

# Rule example generated within the GBNF constraint
rule_fan_control : Int -> Bool
  requires temp > -50
  ensures result == (temp > 30)
rule_fan_control temp = temp > 30

Two LLM backends

Reference pipeline: cloud_compile.py

# Cloud path (requires ANTHROPIC_API_KEY)
python3 lang/tools/llm/cloud_compile.py \
  --prompt "turn on fan when temperature exceeds 30°C" \
  --target rpi

# Mock mode — fully hermetic, no API key
python3 lang/tools/llm/cloud_compile.py \
  --mock \
  --prompt "turn on fan when temp > 30" \
  --target rpi

# Industrial rules with contracts
python3 lang/tools/llm/cloud_compile.py \
  --prompt "shut off pump when pressure > 800 PSI" \
  --vertical industrial \
  --target stm32

Wave-2 Training Corpus

1,177 unique (prompt, rule) pairs across 5 verticals × 7 rule kinds × 3 difficulty tiers:

Rule kinds:   threshold / hysteresis / counter / timer /
              interlock / safety / pattern-match
Verticals:    home / industrial / wearable / automotive / agriculture
Difficulty:   simple / medium / hard
Splits:       946 train / 104 val / 127 test  (hash-mod-10 deterministic)
Token stats:  mean 89.5 / median 87 / p95 139 (cl100k_base)

Training script: research/finetune/train_iot_rules_small.py (Qwen2.5-Coder-3B, QLoRA 4-bit, AMD RX 7900 GRE + unsloth + ROCm).

How MCP + RAG + IoT Fit Together

The three layers are independent but designed to compose:

Claude Desktop / Cursor / custom agent
           │
           │ MCP 2024-11-05 (stdio JSON-RPC)
           │
    ┌──────▼──────────────────────────────────────────────┐
    │               synoema-mcp                           │
    │                                                      │
    │  eval / typecheck / run / feedback_loop             │
    │       │                │                             │
    │       │  auto_inject   │  search_* tools             │
    │       │  middleware     │  (when agent calls them)   │
    │       │       │         │                             │
    │       │       └────┬────┘                             │
    │       │            │                                  │
    │       │     ┌──────▼──────────────────┐              │
    │       │     │  RAG index              │              │
    │       │     │  ~/.sno/models/embed/   │              │
    │       │     │  potion-base-8M         │              │
    │       │     │  5 scopes, ~13k chunks  │              │
    │       │     └─────────────────────────┘              │
    └───────┼──────────────────────────────────────────────┘
            │
            │  sno check / sno wasm / sno build --native
            │
    ┌───────▼────────────────────────────────────────────┐
    │          IoT Compilation Pipeline                   │
    │                                                     │
    │  .sno rule  →  WASM v3 codegen  →  .wasm artifact │
    │                                        │            │
    │                             ┌──────────┴──┐         │
    │                        Tier 0        Tier 1/2       │
    │                        wasm3 MCU     Linux ELF      │
    └────────────────────────────────────────────────────┘

Typical LLM agent workflow

1. Agent opens session — MCP server creates a ULID session, warms the AST cache.
2. Agent calls get_context — receives phase-appropriate reference docs (≤1800 tok).
3. Agent generates a rule — calls typecheck with the draft. If there is an error, the auto-inject middleware attaches relevant search_traces hits automatically.
4. Agent calls run — executes the rule to verify output. If it fails again, the ReAct loop (sno fix --with-rag) activates and searches the corpus for idiomatic fixes.
5. Agent compiles to WASM — calls sno wasm rule.sno via the run tool or the CLI. Gets a .wasm artifact ready for the target tier.
6. Agent deploys — via cloud_compile.py for the full pipeline, or manually for custom hardware.

Specialized models in the MCP pipeline

The MCP server uses two fine-tuned models for specific sub-tasks where a small specialist outperforms a large generalist:

What we dropped and why: general-purpose coder-7B fine-tunes were tried and abandoned — 8.7% compile rate on IoT tasks vs. 97.1% for a domain-specific 0.5B. Models <30B parameters lack the semantic capacity for open-ended code generation; the right answer for those tasks is a large frontier model (Claude, GPT-4o) via API, not a small fine-tune. Small models win only when the task is narrow, the input space is structured, and the verifier (compiler) is perfect.

Key measured numbers

Further reading

• LLM Integration Hub — MCP, RAG, Constrained Decoding, Skills, and ReAct in one page
• IoT Platform page — hero section, tier diagrams, vertical demos
• Package Manager — sno-http and the package registry
• GitHub repository — source for MCP server, RAG crate, IoT examples
• Language Reference — syntax, types, builtins, stdlib
• Zero to 41% — fine-tuning a 3B model from scratch
• sno code — Synoema Mode — AI agent with MCP tools, RAG retrieval, type-aware edits, contract verification