Local Worker MCP

Lokaler, client-unabhängiger MCP. Frontier plant, delegiert und überprüft. Local erledigt die schwere, mechanische und überprüfbare Arbeit.

Ziel ist es, den Tokenverbrauch kostenpflichtiger KI zu reduzieren, ohne die Rohdaten in deren Kontext zu laden.

Codex / Claude / Gemini / Grok
              │
              ▼
       Local Worker MCP
              │
       ┌──────┴───────────────┐
       ▼                      ▼
 Gemma 4 12B QAT          arquivos / PDF
 via Ollama               extração + evidências
       │
       ▼
 resultado compacto e verificável
       │
       ▼
 Frontier revisa

Dies ersetzt nicht die Haupt-KI und ist kein Model-Router. Es handelt sich um echte Arbeitsdelegation.

LOCAL DISPONÍVEL?          NÃO
      │                     │
      ▼                     ▼
   DELEGA                NÃO INSISTE
      │                     │
      ▼                     ▼
   COMPRIME            FRONTIER ASSUME
      │
      ▼
 FRONTIER REVISA

Gemma ist eine Optimierung. Sie darf niemals zum Single Point of Failure werden.

Prinzip

Delegieren, wenn die Aufgabe mechanisch, repetitiv, überprüfbar oder kontextintensiv ist: PDF, Logs, CSV, Code, Extraktion, Klassifikation, Zusammenfassung.

In der Frontier belassen: Architekturentscheidungen, Sicherheit, kritische Änderungen, subjektive Beurteilung, mehrdeutige Anforderungen.

Wenn der lokale Worker offline ist, arbeitet die Frontier weiter. Der MCP gibt schnell unavailable zurück und empfiehlt einen Fallback. Der Client kann protokollieren:

Worker local indisponível; executei diretamente.

Erfordert keinen Benutzereingriff.

Related MCP server: ollama-handoff

Anforderungen

• Python 3.10+

• Ollama auf demselben PC oder einem anderen im LAN

• Ein lokales Modell (empfohlen: Gemma 4 12B QAT)

Installation

git clone https://github.com/CaioAllgayer/Local-Worker-MCP.git
cd Local-Worker-MCP
python -m pip install -e ".[dev]"
copy .env.example .env

Ollama + Gemma

1. Ollama installieren und starten.

2. Modell herunterladen. Der Name ist nicht fest codiert — verwenden Sie den tatsächlichen Namen in Ihrem ollama list:

ollama list
ollama pull <nome-real-do-gemma>

3. Wenn LOCAL_LLM_MODEL leer bleibt, versucht der Worker, ein Modell zu erkennen, dessen Name gemma enthält. Andernfalls wird das erste gelistete Modell verwendet.

4. Endpunkt testen:

curl http://127.0.0.1:11434/api/tags
local-worker status

5. MCP starten:

local-worker-mcp

Gleicher PC

LOCAL_LLM_PROVIDER=ollama
LOCAL_LLM_BASE_URL=http://127.0.0.1:11434
LOCAL_LLM_MODEL=

local vs. lan wird anhand des Hostnamens erkannt. 127.0.0.1, localhost und ::1 sind lokal.

Notebook mit Desktop

Der Worker geht nicht von localhost aus. Das Backend kann sich auf einem anderen PC im LAN befinden.

Auf dem Notebook:

LOCAL_LLM_PROVIDER=ollama
LOCAL_LLM_BASE_URL=http://192.168.x.x:11434

Ersetzen Sie 192.168.x.x durch die aktuelle IP des Desktops (ipconfig unter Windows, ip a unter Linux). Es gibt keine feste IP im Projekt.

Das Verhalten ist dasselbe: Fail-Fast, Circuit Breaker, Cache, Komprimierung.

Auf dem Desktop muss Ollama Verbindungen aus dem LAN akzeptieren (Variable OLLAMA_HOST=0.0.0.0 und Firewall, die Port 11434 freigibt).

OpenAI-kompatibel

LM Studio, llama.cpp server, vLLM und ähnliche:

LOCAL_LLM_PROVIDER=openai_compatible
LOCAL_LLM_BASE_URL=http://127.0.0.1:1234/v1
LOCAL_LLM_MODEL=...
LOCAL_LLM_API_KEY=

Fail-Fast und Circuit Breaker

Standardeinstellungen:

LOCAL_LLM_CONNECT_TIMEOUT_SECONDS=2
LOCAL_LLM_REQUEST_TIMEOUT_SECONDS=45
LOCAL_LLM_MAX_RETRIES=0
LOCAL_LLM_CIRCUIT_BREAKER_FAILURES=2
LOCAL_LLM_CIRCUIT_BREAKER_COOLDOWN_SECONDS=60

Verweigerte Verbindung wird nicht wiederholt. Nach N Fehlern öffnet sich der Stromkreis und die nächsten Aufrufe geben sofort unavailable zurück. Nach der Abkühlphase ist ein Versuch erlaubt.

{
  "status": "unavailable",
  "fallback_recommended": true,
  "reason": "Local LLM endpoint unreachable"
}

MCP-Tools

Der rohe Dateiinhalt muss nicht in den Kontext der kostenpflichtigen KI gelangen. Der Worker liest, komprimiert und gibt überprüfbare Belege zurück (Seite, Zeile, Ausschnitt).

Sicherheit

Standard: SECURITY_MODE=READ_ONLY, ENABLE_SHELL=false.

SECURITY_MODE=READ_ONLY
ALLOWED_PATHS=C:\Projects,D:\Research
ENABLE_SHELL=false

• READ_ONLY — nur Lesen in autorisierten Pfaden; Schreiben und Shell blockiert

• WORKSPACE_WRITE — Lesen/Schreiben in autorisierten Pfaden; Shell nur wenn ENABLE_SHELL=true

• FULL_LOCAL — großzügiger; blockiert dennoch destruktive Befehle

Path Traversal wird blockiert. rm, del, format usw. werden abgelehnt.

Cache und Logs

Persistenter Cache in ~/.local-worker-mcp/cache, selbstreinigend:

CACHE_TTL_DAYS=30
CACHE_MAX_SIZE_GB=10
CACHE_CLEANUP_THRESHOLD_PERCENT=90
CACHE_TARGET_USAGE_PERCENT=80
CACHE_CLEANUP_INTERVAL_HOURS=6

Einträge sind standardmäßig verwertbar. persistent=true bewahrt wichtige Artefakte.

Logs rotieren und verfallen:

LOG_RETENTION_DAYS=14
LOG_MAX_SIZE_MB=250

Das Log speichert nicht den vollständigen Dateiinhalt.

Benchmark

local-worker benchmark arquivo.pdf

Ausgabe:

Arquivo: arquivo.pdf
Worker: gemma4:12b-qat
Backend: ollama
Endpoint: LAN/local
Tamanho: ...
Tokens originais estimados: ...
Tokens processados localmente: ...
Resultado para frontier: ...
Compressão: ...
Tempo: ...
Cache: HIT/MISS

Codex

~/.codex/config.toml oder das JSON des Clients:

{
  "mcpServers": {
    "local-worker": {
      "command": "local-worker-mcp",
      "env": {
        "LOCAL_LLM_PROVIDER": "ollama",
        "LOCAL_LLM_BASE_URL": "http://127.0.0.1:11434",
        "ALLOWED_PATHS": "C:\\Projects"
      }
    }
  }
}

Siehe examples/codex.json.

Claude Code

claude mcp add local-worker --scope user -- local-worker-mcp

Oder fügen Sie examples/claude_code.json in ~/.claude.json ein.

In der CLAUDE.md / AGENTS.md des Projekts lehren Sie die Richtlinie:

Mechanische Aufgaben und das Lesen großer Dateien gehen an delegate_pdf / delegate_file / delegate_task. Wenn local_status oder das Tool unavailable zurückgibt, führen Sie direkt aus und machen Sie weiter.

Andere MCP-Clients

Jeder stdio-Client funktioniert. Generisches Beispiel in examples/generic.json:

{
  "mcpServers": {
    "local-worker": {
      "command": "local-worker-mcp",
      "env": {
        "LOCAL_LLM_PROVIDER": "ollama",
        "LOCAL_LLM_BASE_URL": "http://127.0.0.1:11434"
      }
    }
  }
}

Beispiele

• examples/pdf.md — Paper / langes PDF

• examples/code.md — Erstes Lesen eines Repositorys

• examples/logs.md — Fehlerextraktion

Tests

python -m pip install -e ".[dev]"
pytest
ruff check src tests

Die Suite hängt nicht von echten Ollama/Gemma ab. Alles wird gemockt.

Was nicht in dieses MVP gehört

Windows-GUI-Automatisierung, Playwright, komplexer Multi-Agent, vektorielles RAG, Dashboard, Kubernetes, ML-Router.

Die Architektur lässt Platz für delegate_repo, delegate_git, delegate_browser usw. in der nächsten Phase.

Lizenz

MIT.