mcp-demo

Ein minimaler Python-MCP-Server, der in Phasen aufgebaut ist, sodass jeder Commit ein Konzept vermittelt. Endzustand: Claude Code kann lokale Ollama-Modelle (gemma3:4b / 3:12b) als Tool aufrufen, um Aufgaben mit geringer Priorität von der API auf das Homelab auszulagern.

Was ist MCP eigentlich?

Das Model Context Protocol ist ein standardisiertes JSON-RPC 2.0-Protokoll, das es einem LLM-Client (Claude Code, Claude Desktop, Cursor) ermöglicht, Tools zu entdecken und aufzurufen, Ressourcen abzurufen und Prompt-Vorlagen aus separaten Prozessen, den sogenannten MCP-Servern, zu laden. MCP verhält sich zu LLM-Tooling wie LSP zur Sprachunterstützung in IDEs: ein Protokoll, viele interoperable Implementierungen.

Die beweglichen Teile

    ┌───────────────────┐  stdio / HTTP   ┌──────────────────┐
    │  MCP Client       │ ◄──JSON-RPC──► │  MCP Server      │
    │  (Claude Code)    │                │  (this repo)     │
    └───────────────────┘                └──────────────────┘
            │                                     │
            │ spawns as child                     │ hits
            │ process (stdio)                     │ localhost:11434
            ▼                                     ▼
     your shell env                        Ollama / gemma3

• Client — eingebettet in die LLM-App

• Server — jeder Prozess, der MCP spricht

• Transport — stdio (Client startet Server als Kindprozess, leitet JSON-RPC weiter) oder streamable-http (Server ist ein Webdienst). Dieses Repository verwendet stdio.

Drei Primitive, die ein MCP-Server bereitstellt

Phasenfortschritt

Jede Phase ist ein Commit — git log zeigt die Entwicklung.

1. ✅ scaffold — pyproject, README, .gitignore.

2. ✅ hello-world server — ein echo-Tool + Smoke-Test-Client. Beweist den vollständigen Lebenszyklus: Client-Start → Handshake → Tool-Erkennung → Tool-Aufruf.

3. ✅ ollama_ask tool — asynchrones Tool, das per POST an localhost:11434/api/generate sendet und Gemmas Antwort zurückgibt.

4. ✅ polish — fügt den system-Parameter zu ollama_ask hinzu und stellt eine Ressource unter ollama://models bereit (Liste der geladenen Modelle).

Installation & Ausführung

python3 -m venv .venv
source .venv/bin/activate
pip install -e .
# Phase 2+ only: run the server by hand to smoke-test
python -m mcp_demo.server

Der Server liest JSON-RPC von stdin und schreibt nach stdout — wenn Sie ihn direkt in einem Terminal ausführen, wartet er einfach auf Eingaben. Das ist erwartet. Der Client (Claude Code) ist das, was ihn tatsächlich füttert.

Registrierung bei Claude Code

Fügen Sie dies zu ~/.claude/settings.json hinzu:

{
  "mcpServers": {
    "mcp-demo": {
      "command": "/home/booty/mcp-demo/.venv/bin/python",
      "args": ["-m", "mcp_demo.server"]
    }
  }
}

Starten Sie Claude Code neu. Die Tools erscheinen als mcp__mcp-demo__<tool_name>.

Weiterführende Literatur

• Spezifikation: https://modelcontextprotocol.io/specification

• Python SDK: https://github.com/modelcontextprotocol/python-sdk

• Inspector (eine Debug-UI zum Testen jedes MCP-Servers): npx @modelcontextprotocol/inspector