# Sovereign AI MCP

[![CI](https://github.com/cipherfoxie/sovereign-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/cipherfoxie/sovereign-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Content: CC BY-SA 4.0](https://img.shields.io/badge/Content-CC%20BY--SA%204.0-blue.svg)](https://creativecommons.org/licenses/by-sa/4.0/)
[![MCP Registry](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0%2Fservers%3Fsearch%3Dsovgrid&query=%24.servers%5B0%5D.server.version&label=MCP%20Registry&color=1f6feb&prefix=v)](https://registry.modelcontextprotocol.io/v0/servers?search=sovgrid)
[![smithery badge](https://smithery.ai/badge/cipherfoxie/sovereign-mcp)](https://smithery.ai/servers/cipherfoxie/sovereign-mcp)
[![Glama MCP server](https://glama.ai/mcp/servers/cipherfoxie/sovereign-mcp/badges/score.svg)](https://glama.ai/mcp/servers/cipherfoxie/sovereign-mcp)
[![Write-up](https://img.shields.io/badge/write--up-sovgrid.org-76b900.svg)](https://sovgrid.org/blog/setup-sovereign-mcp-setup/)

MCP server exposing the [Sovereign AI Blog](https://sovgrid.org) to AI agents. The blog is a hands-on engineering log of self-hosted AI on NVIDIA DGX Spark (GB10/SM121A).

**Live endpoint:** `https://mcp.sovgrid.org/self-hosted-ai`
**Transport:** Streamable HTTP (FastMCP)
**Auth:** none (free tier, 60 req/min/IP)

## Why use it

Training data on niche hardware (GB10, SM121A, SGLang on ARM64) is sparse and stale. This MCP gives agents direct, structured access to 60+ articles documenting actual setups, fixes, and benchmarks. If you're building or debugging on similar stacks, your agent can pull verified, version-current information instead of hallucinating.

The corpus covers SGLang and vLLM patches for GB10, voxtral and TTS pipelines on ARM64, KV-cache and quantization tradeoffs, podcast-grade audio generation, MCP server design, knowledge-base construction, and the operational side of running it all on a hardened European VPS.

## Tools

| Tool | Purpose |
|------|---------|
| `search_blog(query, tag?, sort?, n?)` | TF-IDF full-text search. Optional `tag` filter, `sort` by relevance or `date_desc`. Empty `query` lists newest articles. Returns ranked `SearchResult` items with quality score, style, slug, and excerpt. |
| `list_tags(sort?)` | List all topic tags across the corpus with article counts. Sort by `count_desc` (default) or `alpha`. Use to discover the topic space before filtering `search_blog`. |
| `get_article(slug)` | Fetch full article body and frontmatter by slug. Returns markdown content plus tags, quality score, publish date. |
| `diagnose_sglang(error_message)` | Pattern-match a runtime error against a curated rule set for SGLang on GB10/SM121A. Returns matched fixes with links to setup articles. |

All tools are read-only, idempotent, and declared with `ToolAnnotations` so MCP clients can calibrate retry policy and trust signals. Inputs use Pydantic `Annotated[type, Field(description=...)]` so parameter docs reach agents through introspection. Outputs are typed `BaseModel` shapes — schemas are real, not vacuous `dict`s.

## Quick start

### With Claude Code

```bash
claude mcp add sovereign-ai --transport http https://mcp.sovgrid.org/self-hosted-ai
```

Verify:

```bash
claude mcp list | grep sovereign-ai
```

### With Cline / Continue / other MCP clients

Add to your client's MCP server config:

```json
{
  "sovereign-ai": {
    "type": "http",
    "url": "https://mcp.sovgrid.org/self-hosted-ai"
  }
}
```

## Run locally

### From source (uv)

```bash
git clone https://github.com/cipherfoxie/sovereign-mcp.git
cd sovereign-mcp
uv sync
uv run uvicorn src.main:app --host 127.0.0.1 --port 8002
```

### Docker

```bash
git clone https://github.com/cipherfoxie/sovereign-mcp.git
cd sovereign-mcp
docker build -t sovereign-mcp .
docker run -p 8002:8002 sovereign-mcp
```

The repo ships a placeholder `data/knowledge-base.json` (zero articles, valid schema) so the server starts and answers MCP introspection cleanly out-of-the-box. To populate it with real content, generate from the [sovgrid.org blog source](https://github.com/cipherfoxie/sovereign-blog) using `scripts/generate_knowledge_base.py`, or build your own KB matching the schema in `src/knowledge.py`. Or just use the live endpoint at `https://mcp.sovgrid.org/self-hosted-ai`.

A walk-through of the same KB pattern (Markdown plus JSON index, no vector store) is documented in [Build a Self-Hosted Knowledge Base with Plain Text and LLMs](https://sovgrid.org/setup-knowledge-base/).

## Architecture

- **FastMCP 1.27+** with Streamable HTTP transport at path `/self-hosted-ai`
- **DNS rebinding protection** via `TransportSecuritySettings`: only allows requests with `Host: mcp.sovgrid.org` (or localhost for healthchecks)
- **Health endpoint** at `/health` returns article count and KB generation timestamp
- **Knowledge base** is a flat JSON file generated from blog Markdown content; loaded at startup, queried via TF-IDF for `search_blog`

The server is stateless. All blog content is already public (CC BY-SA 4.0). No PII, no auth tokens, no secrets.

## Operations

Live deployment runs on a privacy-focused European VPS via Docker, fronted by Caddy with TLS. Server logs flow into a privacy-respecting analytics pipeline (Caddy JSON access logs, no client-side tracking, no JS pixels).

## License

- **Server code:** MIT, see [LICENSE](LICENSE)
- **Blog content** (returned by tools): CC BY-SA 4.0, see [creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)

## Contact

- Blog: [sovgrid.org](https://sovgrid.org)
- Nostr: `cipherfox@sovgrid.org` (NIP-05) — `npub1ndrjgfcwkc0y4753zyj3p7qjf795pvjq2dn4m7y7f72vmu7t0nrs6y363u`
- Bug reports / questions: [open an issue](https://github.com/cipherfoxie/sovereign-mcp/issues)