# Sovereign MCP

### AI Infrastructure You Can Verify.

Every decision. Signed. Recorded. Provable.

---

<div align="center">

```
         Your Request
              │
       Sovereign Router
              │
       ┌──────┼──────┐
       │      │      │
   Bedrock  Groq  Ollama
       │      │      │
       └──────┼──────┘
              │
        ERE Verification
        (deterministic gate)
              │
         Ed25519 Sign
              │
         WORM Receipt
         (append-only)
              │
          Response
```

</div>

---

## What It Does

Your AI provider can change pricing tomorrow, shut down your model, read every prompt, or refuse your workload. You have no recourse.

Sovereign MCP fixes this:

- **Provider independent** — Swap from Claude to Llama to Ollama with zero code changes. If one goes down, the next catches it automatically.
- **Deterministically verified** — Every output passes 5 verification gates before it ships. No stubs. No placeholders. No "TODO: implement."
- **Cryptographically signed** — Ed25519 signature on every response. Prove what the AI said, when, and to whom.
- **Append-only audit trail** — WORM-style receipts. Tamper-evident. Permanent. If it happened, you can prove it.
- **Self-hosted** — Runs on your hardware, your network, your rules. No cloud dependency required.

---

## Quick Start

```bash
# stdio mode (Claude Code / VSCode)
node sovereign-mcp.mjs

# HTTP mode (BobIDE / Android / any client)
node sovereign-mcp.mjs --http
```

Configure providers in `.env.local`:

```env
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret
AWS_REGION=us-east-1
BEDROCK_MODEL_ID=us.anthropic.claude-haiku-4-5-20251001-v1:0
GROQ_API_KEY=your-groq-key
OLLAMA_URL=http://localhost:11434
```

Any provider you don't configure is skipped. The router uses what's available.

---

## Tools

| Tool | What it does |
|---|---|
| `compute_route` | Route queries through the best available provider with automatic failover |
| `ere_verify` | Deterministic 5-pass verification — catches stubs, placeholders, secrets, broken code |
| `magma_seal` | WORM-seal any content with verification hash + Ed25519 signature |
| `agent_dispatch` | Route tasks to specialized agents or registered proxy services |
| `magma_exec` | Execute composable instruction pipelines with `§VERB:AGENT:ACTION{payload}` syntax |
| `proxy_register` | Register external services as callable tools |
| `proxy_list` | List registered proxy integrations |
| `governor_pubkey` | Export Ed25519 public key for external signature verification |

---

## Verification Gates (ERE)

Every output is checked by 5 deterministic passes before it leaves the system:

| Pass | What it catches |
|---|---|
| P1 | Empty or trivial responses |
| P2 | "Not implemented" stubs, TODO placeholders |
| P3 | Crypto operations in wrong language boundary |
| P4 | Hardcoded secrets, unauthorized AI dependencies |
| P5 | Structural integrity (unbalanced delimiters) |

If any pass fails, the output is BLOCKED. Not logged and forwarded — blocked. The gate is fail-closed.

---

## Instruction Language (Magma)

Composable instructions with pipeline support:

```
§COMPUTE:FORGE:BUILD{query:"build a WORM handler in Rust"}
```

Pipeline — chain operations:

```
§QUERY:ORACLE:SEARCH{q:"find auth patterns"} >> §SEAL:SENTINEL:ANCHOR{data:_prev}
```

Verbs: `COMPUTE` (paid model) · `QUERY` (fast/free) · `SEAL` (sign + log) · `DISPATCH` (route to agent) · `NULLIFY` (void an action)

Every instruction is audit-logged with timestamp, executor, and signature.

---

## Agent Routing

Define specialized agents with system prompts. Route tasks to the right expert:

```javascript
const AGENT_PROMPTS = {
  forge:    "Production-grade builder. TypeScript, Rust, Haskell. Never stubs.",
  oracle:   "Knowledge graph. Citations. Never hallucinate sources.",
  sentinel: "Zero-trust security. Hard verdicts: APPROVED or BLOCKED.",
  vault:    "Treasury. Basis points, yield curves, capital efficiency.",
}
```

Add your own. Remove ours. The architecture doesn't care what agents you define — it cares that their output is verified and signed.

---

## Provider Cascade

```
1. Bedrock (sovereign, paid, AWS credentials)
      │ fails?
      ▼
2. Groq (fast, free tier)
      │ fails?
      ▼
3. Ollama (local, bare metal, zero cost)
      │ fails?
      ▼
   Hard error — no silent degradation
```

No unverified fallback. No quiet failure. If all providers are down, you know immediately.

---

## Integration

### Claude Code / VSCode

Add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "sovereign": {
      "command": "node",
      "args": ["path/to/sovereign-mcp.mjs"]
    }
  }
}
```

### HTTP Client (any language)

```bash
curl -X POST http://localhost:7071 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"compute_route","arguments":{"agent":"forge","query":"build a REST API"}}}'
```

### Verify Signatures Externally

```javascript
import { verify } from 'crypto'

const pubkey = await fetch('http://localhost:7071', {
  method: 'POST',
  body: JSON.stringify({jsonrpc:'2.0',id:1,method:'tools/call',params:{name:'governor_pubkey',arguments:{}}})
}).then(r => r.json())

// Use pubkey to verify any response signature
```

---

## Architecture

```
sovereign-mcp/
├── sovereign-mcp.mjs     Server (stdio + HTTP)
├── .env.example           Provider configuration template
├── LICENSE                [Your license here]
└── README.md
```

Single file. No build step. No dependencies beyond `@aws-sdk/client-bedrock-runtime` (optional — only if you use Bedrock).

---

## Who This Is For

- **Teams** that need to prove what their AI said and when
- **Enterprises** that can't send data to a third party
- **Developers** building multi-model systems that don't break when one provider goes down
- **Anyone** who thinks AI infrastructure should be auditable, not just "hopefully correct"

---

## The Question

If your AI made a decision that cost you $10M, could you prove exactly what it said, when, and why?

If not, you don't have AI infrastructure. You have a hope and a prayer.

---

<div align="center">

**AI Infrastructure You Can Verify.**

---

## License

[Functional Source License 1.1](LICENSE) — Ahmad Ali Parr / Bel Esprit D'Accord Trust

**Change Date:** 2030-07-24 · **Change License:** Apache 2.0

Use it. Build on it. Don't compete with it for 4 years.

---

SnapKitty Collective · 2026

</div>