deepseek-mcp

Ein MCP-Server, der es Claude Code ermöglicht, eine begrenzte Einheit von Repository-Arbeit an DeepSeek als lokalen Sub-Agenten zu delegieren.

Claude bleibt der Orchestrator: Es entscheidet über Umfang, Architektur und Korrektheit. DeepSeek ist ein Ausführungs-Worker für den token-intensiven Teil – das Erkunden des Repositorys, das Vornehmen routinemäßiger oder wiederholender Änderungen und das Ausführen der Tests – innerhalb eines einzigen autorisierten Arbeitsbereichs und unter harten Budgets.

Der Punkt ist, nicht zweimal für denselben Kontext zu bezahlen. Wenn Claude ein Subsystem liest und DeepSeek es dann erneut liest, ist nichts gespart; daher gehört die Delegationsentscheidung vor die breiten Lesevorgänge.

User
 ↓
Claude: plan + define goal/scope
 ↓
DeepSeek: inspect repo + read code + implement + test
 ↓
DeepSeek: compact structured summary
 ↓
Claude: review diff/results + final answer

DeepSeek ist der primäre Repository-Worker; Claude ist der Orchestrator. Claude plant, trifft die architektonischen und sicherheitsrelevanten Entscheidungen, überprüft den zurückgegebenen Diff und schreibt die endgültige Antwort. DeepSeek erledigt die Repository-Arbeit: Erkunden, Glob/Grep/Read, Verstehen des Codes, Implementieren, Testen und routinemäßige Korrekturen. Claude delegiert vor dem breiten Lesen von Quelldateien, und DeepSeek entdeckt die relevanten Dateien selbst innerhalb des autorisierten Umfangs und gibt eine kompakte strukturierte Zusammenfassung zurück – Claude sendet niemals Dateiinhalte.

Erfordert Python 3.11+ und einen DeepSeek-API-Schlüssel. Eine Laufzeitabhängigkeit: das MCP SDK. Alles andere ist die Standardbibliothek. ripgrep wird für die Suche verwendet, wenn vorhanden, und eine reine Python-Scan wird verwendet, wenn nicht.

1. Install

Das Paket ist noch nicht auf PyPI veröffentlicht, also installieren Sie es aus einem Checkout. Installieren Sie es einmal, global – es ist keine Projektabhängigkeit und funktioniert in jedem Repository.

git clone https://github.com/giaminhgist/DeepSeek_MCP.git
cd DeepSeek_MCP

uv tool install .          # recommended: isolated, and puts deepseek-mcp on PATH
# or
pipx install .
# or, into the current environment
pip install .

Bestätigen Sie, dass das Konsolenskript gefunden wird:

deepseek-mcp --version     # -> deepseek-mcp 0.1.0

Wenn der Befehl nicht gefunden wird, ist das Installationsverzeichnis nicht in Ihrem PATH. Mit uv führen Sie uv tool update-shell aus und öffnen eine neue Shell.

deepseek-mcp ohne Argumente startet den MCP-Server auf stdio. Das ist es, was Claude Code ausführt; Sie würden es normalerweise nicht selbst aufrufen.

Related MCP server: Hydra

2. Set the API key

Holen Sie sich einen Schlüssel von https://platform.deepseek.com/. Legen Sie ihn niemals in ein Projekt-Repository. Exportieren Sie ihn aus Ihrem Shell-Profil:

export DEEPSEEK_API_KEY="sk-your-key-here"     # ~/.bashrc, ~/.zshrc, …

# Windows PowerShell
setx DEEPSEEK_API_KEY "sk-your-key-here"

Dann prüfen Sie, ob der Server ihn sehen kann:

deepseek-mcp --check       # prints a health report as JSON; exits 1 if unusable

--check gibt "mode": "enabled" und "status": "ok" aus, wenn der Schlüssel lesbar ist. Der Schlüssel selbst erscheint nie im Bericht.

Drei unterstützte Schlüsselquellen, in Prioritätsreihenfolge:

1. DEEPSEEK_MCP_API_KEY oder DEEPSEEK_API_KEY in der Serverumgebung.

2. api_key_env in der Benutzerkonfigurationsdatei, die eine andere Umgebungsvariable zum Lesen benennt.

3. api_key in der Benutzerkonfigurationsdatei – akzeptiert, aber abgeraten, und es erzeugt eine Startwarnung, weil es den Schlüssel auf die Festplatte legt.

Alles andere ist optional; siehe Konfigurationsreferenz. Die einzige andere Variable, die man vorab kennen sollte, ist DEEPSEEK_MCP_WORKSPACE, die das autorisierte Projektwurzelverzeichnis festlegt, anstatt es zu entdecken (siehe Workspace).

3. Add the server to Claude Code

Wenn DEEPSEEK_API_KEY bereits in der Umgebung exportiert ist, die Claude Code erbt:

claude mcp add deepseek --scope user -- deepseek-mcp

Wenn nicht – zum Beispiel ein Desktop-Start, der Ihr Shell-Profil nicht liest – übergeben Sie es explizit:

claude mcp add deepseek --scope user -e DEEPSEEK_API_KEY=sk-your-key-here -- deepseek-mcp

--scope user registriert es für jedes Projekt. Verwenden Sie --scope local nur für das aktuelle Projekt.

Äquivalente handgeschriebene Konfiguration:

{
  "mcpServers": {
    "deepseek": {
      "command": "deepseek-mcp",
      "env": {
        "DEEPSEEK_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Lassen Sie den env-Block vollständig weg, wenn der Schlüssel bereits in der geerbten Umgebung vorhanden ist. Committen Sie keinen Schlüssel in eine Repository-Datei.

4. Verify the connection

Dann, innerhalb von Claude Code:

claude mcp list            # deepseek should be listed and connected

• Führen Sie /mcp aus – deepseek sollte mit seinen zwei Tools erscheinen; * bitten Sie Claude, deepseek_health aufzurufen. Ein funktionierender Server antwortet mit status: "ok", mode: "enabled", dem Standard-model und der allowed_models-Zulassungsliste, dem aufgelösten Workspace-Root, den aktivierten Fähigkeiten, den Budgetgrenzen und einem usage-Objekt mit den laufenden Gesamtwerten des Workers für diesen Serverprozess.

Ohne konfigurierten Schlüssel startet der Server trotzdem und antwortet weiterhin auf deepseek_health – mit status: "error", mode: "disabled" – sodass das Problem von innerhalb von Claude Code diagnostizierbar ist. In diesem Zustand führt er keine Arbeit aus.

5. Troubleshooting

Logs gehen an stderr als event key=value-Datensätze, niemals an stdout. Erhöhen Sie die Detailstufe mit DEEPSEEK_MCP_LOG_LEVEL=DEBUG oder senden Sie sie mit DEEPSEEK_MCP_LOG_FILE=/absolute/path.log an eine Datei.

The tool surface

Zwei Tools, bewusst.

deepseek_health

Konfiguration und Gesundheit: Status, das Standard-model und die allowed_models-Zulassungsliste, das autorisierte Workspace-Root und wie es aufgelöst wurde, aktivierte Fähigkeiten, Budgetgrenzen und ein usage-Objekt mit den laufenden Gesamtwerten des Workers für diesen Serverprozess. Keine Geheimnisse. Verwenden Sie es, um zu bestätigen, dass der Worker verwendbar ist, und um eine Delegation zu dimensionieren, bevor Sie eine senden.

delegate_to_deepseek

Eine begrenzte Arbeitseinheit, als strukturierter Vertrag statt eines Prosa-Blobs:

{
  "objective": "Treat a None row as invalid and cover it with a test.",
  "scope": ["src/importer/**", "tests/importer/**"],
  "constraints": ["Do not change the public response schema."],
  "acceptance_criteria": ["validate_row(None) returns False."],
  "verification": [["pytest", "tests/importer", "-q"]],
  "mode": "write"
}

Der Worker schleift dann selbst – glob, grep, read, edit, run, repair – und gibt ein kompaktes Ergebnis zurück, niemals ein Transkript:

{
  "status": "completed",
  "summary": "Treated a None row as invalid and added a regression test.",
  "changed_files": ["src/importer/validate.py"],
  "created_files": ["tests/importer/test_none.py"],
  "deleted_files": [],
  "inspected_files": ["src/importer/__init__.py"],
  "verification": [
    {"argv": ["pytest", "tests/importer", "-q"], "exit_code": 0, "summary": "24 passed"}
  ],
  "warnings": [],
  "unresolved": [],
  "assumptions": [],
  "diff_stat": " src/importer/validate.py | 3 ++-",
  "metrics": {
    "turns": 7, "tool_calls": 12, "prompt_tokens": 18400,
    "completion_tokens": 2100, "duration_seconds": 41.2,
    "files_read": 4, "files_changed": 2, "compactions": 0
  },
  "session_usage": {
    "delegations": 3, "turns": 19, "tool_calls": 31,
    "prompt_tokens": 51200, "completion_tokens": 6400,
    "total_tokens": 57600, "since": "server start"
  },
  "model": "deepseek-chat",
  "analysis": {
    "important_files": ["src/importer/validate.py"],
    "architecture_notes": ["validate_row is the single entry point for row checks."],
    "dependencies": ["src/importer/schema.py"],
    "suggested_scope": ["src/importer/**", "tests/importer/**"],
    "risks": ["Changing the None handling may affect callers that rely on the old behaviour."]
  },
  "debug_ledger": ["R src/importer/validate.py", "E src/importer/validate.py", "X pytest tests/importer -q"]
}

model ist das Modell, das die Delegation tatsächlich ausgeführt hat, nach der Auflösung der Aufgaben-Override. analysis ist nur vorhanden, wenn die Delegation danach gefragt hat, und trägt die fünf Repository-Kartenfelder. debug_ledger ist das kompakte Ausführungsprotokoll mit einer Zeile pro Tool-Aufruf, das nur befüllt wird, wenn der Server mit debug aktiviert läuft. metrics meldet den eigenen Token-Verbrauch und die Form dieser Delegation; session_usage trägt die laufenden Gesamtwerte des Workers für diesen Serverprozess, einschließlich dieser Delegation – delegations, turns, tool_calls, prompt_tokens, completion_tokens, total_tokens und since (immer das Literal "server start").

Der Zähler hinter usage und session_usage liegt im Arbeitsspeicher und ist auf den Serverprozess beschränkt: Er wird zurückgesetzt, wenn der MCP-Server neu startet, was genau das since-Feld festhält. Er wird nicht auf der Festplatte gespeichert. Nur Delegationen, die den Worker erreicht haben, werden gezählt – eine früher abgelehnte Anfrage (Server deaktiviert, ungültiges Anfragefeld oder ein Modell außerhalb der allowed_models-Zulassungsliste) hat nie ein Modell aufgerufen und erhöht daher weder delegations noch irgendeinen Token-Zähler. total_tokens wird aus seinen Bestandteilen berechnet und nicht gespeichert, kann also nicht abweichen.

Statuswerte: completed, partial, blocked, failed, budget_exceeded, disabled. Erwartbare Fehler – fehlerhafte Konfiguration, ein abgelehnter Pfad, ein verweigerter Befehl, ein erschöpftes Budget, ein Provider-Fehler – werden alle als einer dieser Werte mit einer Begründung zurückgegeben. Ein Python-Traceback niemals.

Ergebnisse enthalten Schlussfolgerungen, niemals rohe Read/Grep/Tool-Transkripte. Das Debug-Ledger ist das kompakte Ledger – eine Zeile pro Tool-Aufruf – nicht die Tool-Ausgabe, selbst wenn Debug aktiviert ist.

Modi verengen, erweitern nie

Ein Modus wird mit den konfigurierten Fähigkeiten des Servers geschnitten. Eine Anfrage, die mehr verlangt, als der Server gewährt, wird vor jedem API-Aufruf abgelehnt – sie kann die Richtlinie niemals erweitern.

Was dem Worker nicht anvertraut wird

Zwei Dinge im Ergebnis stammen nicht vom Modell:

• Die Liste der geänderten Dateien stammt aus der Beobachtung der Tools plus einem git status-Vergleich mit einem vor dem Lauf erstellten Schnappschuss, sodass bereits vorhandene, nicht committete Änderungen eines Benutzers nie als Arbeit des Workers gemeldet werden.

• Der Status. Ein beanspruchtes completed wird auf partial herabgestuft, wenn die angeforderte Verifikation nie ausgeführt wurde oder mit einem Nicht-Null-Exitcode endete. failed und budget_exceeded sind Urteile des Servers und können vom Worker überhaupt nicht beansprucht werden.

Verifizieren Sie trotzdem. git status --short, git diff --stat, dann lesen Sie die geänderten Hunks proportional zum Risiko. completed ist eine Behauptung, kein Beweis.

Budgets

Jede Delegation ist begrenzt, und der Lauf endet mit einer strukturierten Begründung statt mit Überschreitung: Turns (24), Tool-Aufrufe (80), Wanduhrzeit (15 Min), Ausgabe pro Tool-Aufruf (20.000 Zeichen), Read-Fenster (250 Zeilen), Grep-Treffer (100), Glob-Pfade (300) und geschätzter aktiver Kontext (96.000 Tokens).

Kontext wird als budgetierte Ressource behandelt und nicht als wachsendes Transkript. Oberhalb einer Schwelle werden alte Tool-Payloads durch einzeilige Einträge aus einem deterministischen Ausführungs-Ledger ersetzt; wenn das nicht ausreicht, werden ganze alte Turns verworfen, da das Ledger weiterhin festhält, was sie getan haben. Das Systemprompt, der ursprüngliche Aufgabenvertrag, die letzten Turns und das Ledger bleiben immer erhalten. Für Zusammenfassungen wird nie ein zusätzlicher Modellaufruf ausgegeben, und wenn der Worker ein entferntes Detail benötigt, liest er die Datei erneut.

Alle Grenzen sind konfigurierbar und werden von deepseek_health gemeldet.

Konfigurationsreferenz

Als reserviert markierte Einstellungen werden beim Start validiert, aber noch nicht verwendet.

Rangfolge

Umgebungsvariable > Benutzerkonfigurationsdatei > eingebauter Standardwert

Die Modellauswahl hat eine weitere Ebene darüber: Eine einzelne Delegation kann ihr eigenes Modell benennen, die vollständige Reihenfolge lautet also

Aufgabenmodell > Umgebungsvariable > Benutzerkonfigurationsdatei > eingebauter Standardwert

Das Aufgabenmodell ist der Parameter model von delegate_to_deepseek. Wenn allowed_models des Servers nicht leer ist, handelt es sich um eine Zulassungsliste, und eine Anfrage, die etwas anderes benennt, wird vor jedem API-Aufruf als blocked abgelehnt – die Modellwahl verengt sich auf das, was der Betreiber erlaubt hat, genau wie Delegationsmodi sich auf die Fähigkeiten des Servers verengen.

Eine fehlende, fehlerhaft formatierte oder widersprüchliche Einstellung ist ein Fehler. Der Server fällt nicht auf einen breiteren Arbeitsbereich oder eine permissivere Richtlinie zurück.

Wenn das Laden der Konfiguration fehlschlägt, startet der Prozess trotzdem und beantwortet weiterhin deepseek_health, meldet aber status: "error", mode: "disabled" und leistet keine Arbeit. Führen Sie deepseek-mcp --check aus, um denselben Bericht auf der Befehlszeile zu sehen.

Speicherort der Konfigurationsdatei

Die Benutzerkonfigurationsdatei liegt außerhalb jedes Projekts:

DEEPSEEK_MCP_CONFIG überschreibt den Pfad. Wenn es gesetzt ist und die Datei nicht existiert, schlägt der Start fehl, statt stillschweigend Standardwerte zu verwenden. Eine fehlende Konfigurationsdatei am Standardort ist in Ordnung; eine leere Datei ist in Ordnung; unbekannte Schlüssel sind ein Fehler.

Schema der Konfigurationsdatei

Jeder Schlüssel ist optional.

{
  "model": "deepseek-chat",
  "allowed_models": ["deepseek-chat", "deepseek-reasoner"],
  "base_url": "https://api.deepseek.com/v1",
  "api_key_env": "DEEPSEEK_API_KEY",
  "workspace": "/absolute/path/to/project",
  "tools": {
    "enabled": ["Read", "Glob", "Grep", "Edit", "Write", "Run"],
    "max_write_bytes": 2000000,
    "allow_secret_paths": false,
    "secret_path_exceptions": []
  },
  "provider": {
    "timeout_seconds": 120,
    "max_retries": 3,
    "retry_base_delay": 0.5,
    "retry_max_delay": 8.0,
    "temperature": 0.0,
    "max_output_tokens": 4096
  },
  "budgets": {
    "max_turns": 24,
    "max_tool_calls": 80,
    "max_wall_seconds": 900,
    "max_tool_output_chars": 20000,
    "read_window_lines": 250,
    "max_grep_matches": 100,
    "max_glob_paths": 300,
    "max_context_tokens": 96000,
    "compaction_threshold_ratio": 0.7
  },
  "commands": {
    "default_timeout_seconds": 120,
    "max_timeout_seconds": 600,
    "extra_denied_executables": [],
    "extra_allowed_executables": [],
    "allow_unsafe_shell": false
  },
  "logging": { "level": "INFO", "file": null, "log_task_text": false },
  "debug": false
}

Ein api_key-Schlüssel wird hier akzeptiert, ist aber nicht empfehlenswert: Er legt den Schlüssel auf der Festplatte ab und erzeugt eine Startwarnung. Bevorzugen Sie api_key_env, das stattdessen die zu lesende Umgebungsvariable benennt.

allowed_models ist eine optionale Zulassungsliste von Modellnamen, die eine Delegation anfordern darf. Wenn sie nicht leer ist, muss das konfigurierte model darin enthalten sein (sonst widersprechen sich die Einstellungen), und ein Aufgaben-model, das etwas außerhalb davon benennt, wird vor jedem API-Aufruf als blocked abgelehnt. Leer bedeutet, dass jeder wohlgeformte Modellname akzeptiert wird.

Anmeldedaten und Endpunkt

Kein API-Schlüssel bedeutet keine Arbeit: Der Start meldet den Server als deaktiviert.

Arbeitsbereich

Ohne expliziten Arbeitsbereich wird der Stamm gefunden, indem vom Prozess-Arbeitsverzeichnis aus aufwärts nach .git, .hg, .svn, pyproject.toml, package.json, go.mod oder Cargo.toml gesucht wird. Wird keines gefunden, wird das Arbeitsverzeichnis selbst verwendet und eine Warnung aufgezeichnet.

Ein expliziter Arbeitsbereich, der fehlt, nicht lesbar ist, kein Verzeichnis ist, relativ ist oder das Dateisystem-Root ist, ist ein Startfehler. Er degradiert nie zum Arbeitsverzeichnis. Der Server muss nicht in Ihrem Projekt leben, und er modifiziert nie ein Projekt, um sich selbst zu aktivieren.

Tools

Standardmäßig aktivierte Tools sind alle außer NotebookEdit. NotebookEdit ist ein anerkannter Name ohne Implementierung, daher ist das Aktivieren ein Startfehler und kein Tool, das dem Worker angeboten wird und das er nicht nutzen kann. Read ist Pflicht.

.git-, .hg- und .svn-Interna sind über die Dateisystem-Tools niemals les- oder schreibbar; verwenden Sie stattdessen einen schreibgeschützten git-Befehl über Run.

Budgetgrenzen

Alle pro Delegation durchgesetzt und von deepseek_health gemeldet, damit Claude eine Delegation vor dem Senden dimensionieren kann.

Das Überschreiten eines Budgets beendet die Delegation mit status: "budget_exceeded" und einer Begründung, nachdem gemeldet wurde, welche Arbeit bereits gelandet ist.

Provider

Timeouts, Verbindungsfehler, 429 und 5xx werden erneut versucht. Ein 4xx tritt sofort auf, weil das erneute Versuchen eines falschen Schlüssels oder einer fehlerhaften Anfrage nur Zeit verschwendet. Weiterleitungen werden grundsätzlich abgelehnt, damit der Authorization-Header nicht an einen anderen Host erneut gesendet werden kann.

Befehlsrichtlinie

Run führt ein argv-Array mit shell=False aus. Die ausführbare Datei muss auf einer Zulassungsliste stehen, und gefährliche Unterbefehle werden strukturell abgelehnt. Verwenden Sie commands.extra_allowed_executables in der Konfigurationsdatei, um ein projektspezifisches Werkzeug hinzuzufügen, und extra_denied_executables, um eines zu entfernen. Ein zusätzlicher Zulassungseintrag kann ein hart gesperrtes Programm nicht wieder aktivieren.

Standardmäßig abgelehnt: Rechteausweitung, Paketinstallation, Veröffentlichung, Netzwerkdienstprogramme, Shells und Inline-Code-Interpreter, destruktive Dateisystemoperationen, In-Place-Editoren sowie mutierende oder entfernte Git-Unterbefehle. Schreibgeschütztes Git (status, diff, log, show, ls-files, rev-parse, blame, …) ist erlaubt.

Allzweck-Dateileser wie cat, head und grep sind bewusst nicht auf der Zulassungsliste: Sie wären eine Ein-Befehl-Umgehung der Sperrliste für geheime Pfade, die Read, Glob und Grep durchsetzen. Fügen Sie einen nur über extra_allowed_executables wieder hinzu, wenn Sie das akzeptieren.

Protokollierung

Die Delegationsprotokollierung enthält nur Metadaten: Ereignisname, Status, Modus, Anzahl der Runden und Tool-Aufrufe, Token-Anzahl, Dauer und Dateianzahl. Kein Aufgabentext, keine Dateiinhalte, keine Befehlsausgabe und keine Prompt-Texte. Protokolle gehen an stderr, niemals an stdout — stdout transportiert ausschließlich MCP-Protokollverkehr. Der API-Schlüssel wird aus jedem Datensatz als Sicherheitsnetz bereinigt.

Sicherheitslage

Lesen Sie diesen Abschnitt, bevor Sie entscheiden, worauf Sie den Worker ausrichten.

Die hier beschriebenen Schutzmaßnahmen werden durch die Modellauswahl- und Analysefunktionen nicht verändert: begrenzter Kontext mit Kompaktierung, die Workspace-Sandbox, die Befehls-Zulassungsliste, kein Commit oder Push, standardmäßig keine Paketinstallation oder Netzwerkzugriff sowie ein strukturiertes Ergebnis mit Token- und Tool-Metriken.

Was im Code durchgesetzt wird:

• Jeder Pfad wird gegen eine einzige Workspace-Wurzel aufgelöst. Symlinks werden zuerst verfolgt und das Ergebnis wird validiert, sodass ein Link aus dem Baum heraus abgelehnt wird. Bei Schreibzielen wird das übergeordnete Verzeichnis unmittelbar vor dem Schreiben erneut validiert.

• Ein explizit konfigurierter Workspace, der fehlt oder nicht nutzbar ist, ist ein Startfehler. Er fällt niemals stillschweigend auf ein breiteres Verzeichnis zurück.

• Pfade mit Geheimnissen (.env, .env.*, *.pem, *.key, id_rsa, .netrc, .ssh/, .aws/ und ähnliche) sowie .git/.hg/.svn-Interna sind für jedes Tool gesperrt und werden aus Suchergebnissen ausgelassen, statt lediglich unlesbar zu sein.

• Der scope einer Delegation schränkt Schreibvorgänge ein. Lesezugriffe bleiben über den gesamten Workspace offen, weil der Worker erkunden muss, um seine Aufgabe zu erfüllen.

• Run verwendet shell=False. Es gibt keine Shell, sodass &&, |, $(...) und > als wörtlicher Argumenttext ankommen und keinen zweiten Befehl verketten können. Die ausführbare Datei muss auf einer Zulassungsliste stehen, gefährliche Unterbefehle werden strukturell über argv abgelehnt, absolute Pfadargumente müssen innerhalb des Workspace liegen, und ein Argument, das einen vorhandenen gesperrten Pfad benennt, wird abgelehnt.

• Paketinstallation, Veröffentlichung, Netzwerkdienstprogramme, Rechteausweitung sowie mutierende oder entfernte Git-Unterbefehle werden standardmäßig abgelehnt. Ebenso Allzweck-Dateileser wie cat und grep, die andernfalls eine Ein-Befehl-Umgehung der Sperrliste für geheime Pfade wären.

• Unterprozesse erhalten eine Umgebung ohne Anmeldeinformationen, sodass der eigene API-Schlüssel des Workers nicht in der Befehlsausgabe oder einem Protokoll auftauchen kann.

• Schreibvorgänge sind atomar (temporäre Datei, fsync, Umbenennung), sodass ein unterbrochener Schreibvorgang die Originaldatei intakt lässt. Edit kann die SHA-256-Prüfsumme verlangen, die Read zurückgegeben hat, sodass eine veraltete Bearbeitung abgelehnt statt angewendet wird.

• Der System-Prompt stellt fest, dass Repository-Inhalte Daten und keine Anweisungen sind — und die oben genannten Grenzen werden serverseitig durchgesetzt, sodass eine Datei, die dem Worker sagt, er solle seine Anweisungen ignorieren, ihm nichts gewähren kann.

• Protokolle enthalten standardmäßig nur Metadaten: Ereignis, Status, Anzahl, Dauer. Kein Aufgabentext, keine Dateiinhalte, keine Befehlsausgabe und keine Prompt-Texte. Der API-Schlüssel wird aus jedem Datensatz als Sicherheitsnetz bereinigt.

Was dies nicht ist: Sandboxing auf Betriebssystemebene gegen Angreifer.

Dies ist eine Richtlinie auf Anwendungsebene. Sie begrenzt die Kategorie von Aktionen, die ein verwirrter, fehlgeleiteter oder prompt-injizierter Worker ausführen kann. Sie ist keine Eindämmungsgrenze gegen einen entschlossenen Angreifer, und die beiden sind nicht gleichwertig.

Konkret:

• Ein zugelassener Test-Runner führt den Code Ihres Projekts aus. pytest importiert das Repository; make test führt aus, was das Makefile vorgibt. Alles, was auf diesem Weg erreichbar ist, ist erreichbar, einschließlich Dateien, die die Pfadrichtlinie abgelehnt hätte.

• Es gibt keine Prozess-, Dateisystem- oder Netzwerkisolation — keinen Container, kein bubblewrap oder seccomp, kein macOS-Sandbox-Profil, kein Windows-Job-Objekt, keinen Netzwerk-Namespace. Ein Befehl, der erlaubt ist, läuft mit denselben Rechten wie der Serverprozess.

• Die Sperrlisten sind strukturell und nicht erschöpfend. Sie sind der Grund, warum die Richtlinie für ausführbare Dateien eine Zulassungsliste ist: Unbekannte Programme werden abgelehnt, statt als sicher angenommen zu werden.

Richten Sie dies nicht auf ein Repository, aus dem Sie keine Tests ausführen würden, und behandeln Sie es nicht als Ersatz für die Prüfung des Diffs.

Bekannte Einschränkungen

• NotebookEdit ist ein erkannter Tool-Name ohne Implementierung. Das Aktivieren ist ein Startfehler und kein Tool, das dem Worker angeboten wird und das er nicht nutzen kann.

• commands.allow_unsafe_shell wird validiert, bewirkt aber nichts; es gibt keine rohe Shell-Ausführung.

• Der Worker kann keine Dateien löschen. Es gibt kein Lösch-Tool, und rm wird abgelehnt.

• Keine Sandbox auf Betriebssystemebene, wie oben beschrieben.

• Die Kontextschätzung ist eine Zeichen-Heuristik, die anhand der vom Anbieter gemeldeten Nutzung nach oben kalibriert wird. Sie ist bewusst konservativ, nicht exakt.

• Das Suchverhalten unterscheidet sich geringfügig zwischen den Engines ripgrep und reinem Python, da sich die Regex-Dialekte unterscheiden. Die verwendete Engine wird in jedem Ergebnis genannt.

• Windows wird unterstützt und in CI getestet, aber die Beendigung von Prozessgruppen bei Timeout ist dort im Vergleich zu POSIX nur bestmöglich.

• Eine Delegation pro Aufruf. Es gibt keine Hintergrundjobs, keinen persistenten Worker-Speicher und keinen automatischen Git-Commit oder -Push.

Entwicklung

uv venv && uv pip install -e ".[dev]"
python -m pytest          # the full suite; no API key and no network needed
python -m ruff check .
python -m ruff format --check .
python -m mypy

Die Testsuite ruft niemals eine kostenpflichtige API auf: Ein skriptierter Fake-Provider springt ein, und die MCP-Integrationstests steuern einen echten Server-Unterprozess über stdio gegen temporäre Git-Repositories.

phases/ enthält die Implementierungsreihenfolge, aus der dieser Server aufgebaut wurde, zur Referenz aufbewahrt.

GLOBAL_CLAUDE.md ist nicht Teil dieser Codebasis. Es ist eine Anweisungsdatei auf Benutzerebene für Claude Code, die beschreibt, wann delegiert werden soll — kopieren Sie sie nach ~/.claude/CLAUDE.md oder führen Sie sie mit der Datei zusammen, die Sie bereits haben.

Lizenz

MIT.