# Sherpa (Local Coder MCP Server)

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python: >=3.10](https://img.shields.io/badge/python-%E2%89%A53.10-blue.svg)](https://www.python.org/)
[![Tests: 67 passed](https://img.shields.io/badge/tests-67%20passed-brightgreen.svg)]()
[![Hardware: Apple Silicon & NVIDIA](https://img.shields.io/badge/hardware-Metal%20%7C%20CUDA-purple.svg)]()

A lightweight, zero-dependency Python-based [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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%.

---

## 🚀 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

| Tool | Purpose |
|---|---|
| `code_generate` | Generates implementation code directly to disk with instant memory eviction. |
| `code_validate` | Runs native language compilers (`cargo check`, `go vet`, `py_compile`, `node --check`) for sub-20ms syntax validation. |
| `code_test` | Executes unit/integration test suites in an isolated sandbox with `summary_only` receipts. |
| `code_contract_check` | Zero-token AST scanner detecting schema violations, forbidden fields, and API drift before tests run. |
| `code_build` | Compiles Rust Cargo projects to native binaries, with optional CLI execution and terse error filtering. |
| `code_schema` | Extracts machine-readable contract schemas from compiled binaries (via `--schema`) or Rust source AST. |
| `code_fix` | Autonomous recursive self-healing loop combining generation, validation, contract checks, and tests with the STOP protocol. |

---

## 💻 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`**](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:
```bash
# 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`:
```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`](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):

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

---

## 📜 License

MIT License. See [LICENSE](LICENSE) for details.