Local Coder MCP Agent

Dieses Projekt bündelt einen Workflow für einen lokalen Coding-Agenten:

1. Ein Qwen-Coding-Modell läuft lokal hinter einer OpenAI-kompatiblen /v1/chat/completions-API.

2. Ein Python-Worker kommuniziert mit dieser lokalen API über das OpenAI SDK.

3. Ein local-coder-MCP-Server macht delegate_to_local_coder für Codex verfügbar.

4. Codex delegiert Implementierungsaufgaben an den lokalen Worker und prüft Tests und Diffs anschließend selbst.

Es sind keine Modellgewichte enthalten. Verwenden Sie Ihr eigenes lokales Modellverzeichnis über MODEL_DIR.

Architektur

Codex
  -> MCP tool: delegate_to_local_coder(task, workspace, max_steps)
    -> mcp_servers.local_coder.server
      -> workers.coding.worker.CodingWorker
        -> OpenAI-compatible local model server
        -> restricted file/test/git tools inside the requested workspace

Der Worker kann Dateien auflisten, Dateien lesen, Dateien schreiben, exakten Text patchen, pytest ausführen, eine kleine Whitelist von Befehlen ausführen, Text durchsuchen, den Git-Status anzeigen und den Git-Diff anzeigen. Er verweigert Pfade außerhalb des ausgewählten Arbeitsbereichs.

Related MCP server: Codex Workspace Bridge

Installation

git clone <your-repo-url>
cd local-coder-mcp-agent
python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev,mlx]"
cp .env.example .env

Lesen Sie die Datei .env:

MODEL_DIR=${HOME}/models/Qwen3-Coder-30B-A3B-Instruct-4bit
ALLOWED_WORKSPACE_ROOT=${HOME}/AI/projects
LOCAL_CODER_BASE_URL=http://127.0.0.1:8080/v1
LOCAL_CODER_MODEL=default_model
LOCAL_CODER_API_KEY=local

ALLOWED_WORKSPACE_ROOT ist der Verzeichnisbaum, den der Worker bearbeiten darf. Für mehrere Wurzelverzeichnisse verwenden Sie ALLOWED_WORKSPACE_ROOTS, getrennt durch : unter macOS/Linux.

Modellserver starten

Für ein MLX-Modell auf Apple Silicon:

source .venv/bin/activate
./scripts/start_qwen3_coder_server.sh

Das Skript startet:

python -m mlx_lm.server \
  --model "${MODEL_DIR}" \
  --host 127.0.0.1 \
  --port 8080 \
  --max-tokens 4096 \
  --temp 0

Jeder OpenAI-kompatible Server funktioniert, wenn er http://127.0.0.1:8080/v1/chat/completions bereitstellt oder wenn Sie LOCAL_CODER_BASE_URL aktualisieren.

MCP-Server manuell starten

source .venv/bin/activate
./scripts/start_local_coder_mcp.sh

Normalerweise startet Codex den MCP-Server für Sie über config.toml.

Codex MCP konfigurieren

Kopieren Sie den local-coder-Block aus config.example.toml in Ihre Codex-config.toml und ersetzen Sie dann die Platzhalter durch lokale Werte:

[mcp_servers.local-coder]
enabled = true
command = "${PROJECT_ROOT}/.venv/bin/python"
args = ["-m", "mcp_servers.local_coder.server"]
cwd = "${PROJECT_ROOT}"

[mcp_servers.local-coder.env]
LOCAL_CODER_BASE_URL = "http://127.0.0.1:8080/v1"
LOCAL_CODER_MODEL = "default_model"
LOCAL_CODER_API_KEY = "local"
ALLOWED_WORKSPACE_ROOT = "${ALLOWED_WORKSPACE_ROOT}"

Verwenden Sie reale lokale Pfade nur in Ihrer privaten Codex-Konfiguration, niemals in committeten Dateien.

Eine Aufgabe von Codex delegieren

Beispiel-Prompt an Codex:

Use the local-coder MCP server and specifically call delegate_to_local_coder.

Workspace:
${ALLOWED_WORKSPACE_ROOT}/sandbox

Task:
Add multiply(a: int, b: int) -> int to calculator.py.

Requirements:
- Do not change add(), subtract(), or divide().
- Add pytest coverage for multiply().
- Run all tests.
- Inspect git diff before finishing.

After the local worker completes the task, review its changes yourself.
Do not implement the change yourself unless the local worker fails.

Der enthaltene Ordner examples/sandbox ist ein kleines pytest-Projekt für Smoke-Tests.

Häufige Fehler

Der Arbeitsbereich liegt nicht in einem erlaubten Wurzelverzeichnis

Setzen Sie ALLOWED_WORKSPACE_ROOT oder ALLOWED_WORKSPACE_ROOTS so, dass der angeforderte Arbeitsbereich in einem zulässigen Verzeichnis liegt. Das ist beabsichtigt: Der Worker soll keine beliebigen lokalen Dateien bearbeiten können.

Der Worker hat die maximale Anzahl an Schritten überschritten

Erhöhen Sie max_steps für größere Aufgaben oder teilen Sie die Aufgabe in kleinere Schritte auf. Gute Aufgaben für den lokalen Worker sind spezifisch und überprüfbar.

Das Modell hat keine brauchbare Antwort geliefert

Der lokale Modellserver hat eine Antwort ohne brauchbaren content, reasoning_content, reasoning oder thinking zurückgegeben. Versuchen Sie Folgendes:

• Verifizieren Sie, dass der Server OpenAI-kompatible Chat-Completions implementiert.

• Setzen Sie LOCAL_CODER_ENABLE_THINKING=false.

• Reduzieren Sie die Aufgabengröße.

• Testen Sie den Server mit einer direkten /v1/chat/completions-Anfrage.

Verbindung fehlgeschlagen

Stellen Sie sicher, dass der Modellserver läuft, der Port zu LOCAL_CODER_BASE_URL passt und keine Firewall und kein Proxy den localhost-Verkehr abfängt.

Sicherheit

• Committen Sie keine .env, keine private Codex-Konfiguration, keine Modellgewichte, keine Logs, keine Schlüssel und keine generierten Caches.

• Halten Sie ALLOWED_WORKSPACE_ROOT eng begrenzt.

• Der lokale Worker kann Dateien bearbeiten und in erlaubten Arbeitsbereichen begrenzte Befehle ausführen. Prüfen Sie jeden Diff, bevor Sie Änderungen übernehmen.

• Lassen Sie den Server an 127.0.0.1 gebunden, es sei denn, Sie haben einen separaten Netzwerksicherheitsplan.

• Dieses Repository verwendet absichtlich Platzhalter wie ${HOME}, ${MODEL_DIR}, ${PROJECT_ROOT} und ${ALLOWED_WORKSPACE_ROOT}.

Prüfungen ausführen

python -m pytest -q
python -m py_compile \
  mcp_servers/local_coder/server.py \
  workers/coding/client.py \
  workers/coding/parser.py \
  workers/coding/tools.py \
  workers/coding/worker.py