Sherpa (Local Coder MCP Server)

A lightweight, zero-dependency Python-based Model Context Protocol (MCP) server that offloads code generation, deterministic compiler validation, sandboxed testing, and self-healing to local hardware (Apple Silicon via Metal or NVIDIA GPUs via CUDA/Ollama), immediately freeing memory and context after every invocation.

🎯 The Philosophy: "Blind Orchestrator" Pattern

Frontier cloud models (Claude, Gemini, GPT-4) serve as Architects—defining interfaces, contracts, and orchestrating execution. Implementation code generation, compiler syntax checks, contract validation, and sandboxed test execution run locally on your own hardware.

Only compact telemetry receipts (bytes written, duration, compiler error lines, test pass/fail) return to the cloud model's context window. File contents never enter orchestrator context unless explicitly requested, eliminating quadratic context window compounding ("multi-turn context tax") and reducing cloud token costs by up to 90%.

Related MCP server: OmniBridge MCP Server

🚀 Key Features

1. Instant Memory Eviction (keep_alive: 0):

   • Every inference request to Ollama automatically sends an eviction hook to guarantee zero lingering VRAM on GPUs or unified memory on Apple Silicon.

2. Zero-Token Deterministic Compiler Gates:

   • Native language parsers and compilers (cargo check & rustc for Rust, go vet for Go, py_compile for Python, node --check for JS/TS, g++ for C++) validate code in under 20ms with zero token cost.

3. Contract-Driven Hallucination Detection (code_contract_check):

   • Deterministic AST scanner that checks generated code against a contract.json manifest before tests are run, catching forbidden/hallucinated fields, missing required fields, or deprecated framework patterns.

4. Binary Compilation & Contract Reflection (code_build & code_schema):

   • Builds native binaries directly with cargo build, returns terse compiler diagnostics on error, and reflects public struct, enum, and function contracts from source or --schema CLI binaries.

5. Autonomous Recursive Self-Healing (code_fix) & STOP Protocol:

   • Executes multi-turn generation → validation → contract check → test cycles entirely on local compute without frontier model intervention. Halts and emits a structured decision_required: true STOP signal when design choices require human judgment.

6. Zero Third-Party Runtime Dependencies:

   • Implements standard MCP JSON-RPC 2.0 over stdio using only the Python standard library. Starts in milliseconds.

🛠️ The 7 MCP Tools

💻 Hardware & Model Support

Works identically across Apple Silicon (M-Series M1–M4 with Unified Memory) and Linux / Windows (NVIDIA CUDA):

• 16 GB Mac / 10 GB RTX 3080: qwen2.5-coder:14b-instruct-q4_k_m (Standard)

• 24 GB – 48 GB Mac (M4 Pro / Max) / 24 GB GPU: qwen2.5-coder:32b-instruct-q4_k_m (Best reasoning)

• 8 GB Mac / 8 GB GPU: qwen2.5-coder:7b-instruct-q8_0 (Fast boilerplate)

See SETUP.md for full manual model installation and custom Modelfile instructions.

⚙️ Configuration

Sherpa features a hierarchical configuration engine (CLI args > Environment variables > Project sherpa.json > Global user ~/.config/sherpa/config.json > Defaults).

Using the Config CLI:

# View active configuration
python3 -m coder.config show

# Set the global model
python3 -m coder.config set model qwen2.5-coder:14b-instruct-q4_k_m

# Set remote Ollama host
python3 -m coder.config set ollama_host http://localhost:11434

Client Setup (Antigravity CLI / Claude Desktop):

Add to your mcp_config.json:

{
  "mcpServers": {
    "sherpa": {
      "command": "python3",
      "args": ["/path/to/coder/server.py"],
      "env": {
        "SHERPA_MODEL": "qwen2.5-coder:14b-instruct-q4_k_m"
      }
    }
  }
}

🧠 Agent Skill & Orchestration Guide

Sherpa ships with a ready-to-use agent skill definition in skills/local-coder/SKILL.md designed for Antigravity, Claude Code, and agentic workflows.

It instructs frontier orchestrators on:

• The Granularity Boundary Rule: Slicing tasks into micro-contracts (<40 lines) to achieve near-100% compiler pass rates on local 14B models.

• The STOP Protocol: Structured human-in-the-loop decision checkpoints when self-healing attempts are exhausted or design ambiguities are detected.

• Contract Manifests (contract.json): Pre-defining data structures and route schemas so code_contract_check can eliminate hallucinations prior to test runs.

🧪 Running Tests

Run the complete test suite (67 tests, pure stdlib):

python3 -m unittest discover -s tests -p "test_*.py" -v

📜 License

MIT License. See LICENSE for details.