deepseek-subagent-mcp

Gibt Claude Code, Codex oder einem anderen MCP-Client einen DeepSeek Harness-Agenten, an den er Aufgaben delegieren kann – so, wie er sie an einen seiner eigenen Subagenten delegieren würde.

MCP (Model Context Protocol) ist der Standard, über den ein Coding-Agent externe Werkzeuge lädt. DeepSeek Harness ist DeepSeeks Open-Source-Agenten-Laufzeit – ein Modell in einer Schleife mit Datei- und Shell-Werkzeugen, veröffentlicht im August 2026 unter MIT. Dieser Server sitzt dazwischen: Er führt einen Harness-Agenten in einem separaten Prozess aus und stellt sechs Werkzeuge zum Starten, Beobachten, Fortsetzen und Stoppen bereit.

Der Kind-Agent hat seinen eigenen Kontextfenster. Das ist der Punkt – du übergibst ihm eine in sich geschlossene Aufgabe, er verbraucht seine eigenen Tokens, während er an den Dateien arbeitet, und du erhältst ein Ergebnis statt eines Transkripts.

Voraussetzungen

• Python 3.11 oder neuer

• Ein DeepSeek-API-Schlüssel von platform.deepseek.com

• macOS 14+ auf Apple Silicon, oder Linux auf x86-64 oder arm64

Es ist keine Node.js-Installation erforderlich: Die Harness-Laufzeit wird als eigenständige ausführbare Datei im deepseek-harness-sdk-Wheel mitgeliefert. Dieses Wheel ist auch die Plattformbeschränkung – es veröffentlicht macosx_14_0_arm64, manylinux_2_28_x86_64 und manylinux_2_28_aarch64 und sonst nichts, sodass Windows, Intel-Macs und macOS 13 dieses Paket überhaupt nicht installieren können.

Installieren

uvx --from git+https://github.com/gaztrabisme/deepseek-subagent-mcp deepseek-subagent-mcp

Claude Code

Füge in deinem Projekt zur .mcp.json hinzu, oder für jedes Projekt zu ~/.claude.json:

{
  "mcpServers": {
    "deepseek-subagent": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/gaztrabisme/deepseek-subagent-mcp",
        "deepseek-subagent-mcp"
      ],
      "env": {
        "DEEPSEEK_API_KEY": "sk-...",
        "DSA_WORKSPACE": "/path/to/your/project"
      }
    }
  }
}

Codex

Füge zu ~/.codex/config.toml hinzu:

[mcp_servers.deepseek-subagent]
command = "uvx"
args = ["--from", "git+https://github.com/gaztrabisme/deepseek-subagent-mcp", "deepseek-subagent-mcp"]
env = { DEEPSEEK_API_KEY = "sk-...", DSA_WORKSPACE = "/path/to/your/project" }

Werkzeuge

Läufe sind standardmäßig asynchron, da eine Codierungsaufgabe viele Minuten dauern kann und MCP-Clients einzelne Werkzeugaufrufe mit einem Timeout belegen. dsh_delegate kehrt zurück, sobald die Arbeit in die Warteschlange gestellt ist; dsh_await übernimmt das Warten und meldet dabei den Fortschritt. Für kurze Aufgaben übergib wait_seconds an dsh_delegate und überspringe den zweiten Aufruf.

Jeder dsh_delegate erstellt einen Agenten, der einen Laufzeitprozess und eine persistierte Sitzung hält. dsh_continue tritt wieder in diese Sitzung ein, sodass das Kind seine früheren Runden noch im Kontext hat.

Jede Delegation gibt an, wie sie überprüft wird

dsh_delegate erfordert ein verification-Argument: den Befehl, der beweist, dass die Aufgabe erledigt ist.

dsh_delegate(task="Fix the failing date parser", verification="pytest -q tests/test_dates.py")

Der Server führt diesen Befehl selbst aus, im Arbeitsbereich des Agenten, nachdem das Kind fertig ist. Ein Kind, das seine eigenen Testergebnisse meldet, ist eine Behauptung; ein Exit-Code ist eine Tatsache, und Agenten, die vorzeitig den Sieg erklären, sind ein gut dokumentiertes Fehlermuster.

Der Befehl wird nach derselben Richtlinie klassifiziert, die auch die eigenen Aufrufe des Kindes vor der Ausführung regelt – der Aufrufer ist ein anderer Agent und kann per Prompt-Injection manipuliert werden, daher ist „der Aufrufer hat danach gefragt“ keine Autorisierung. Übergib verification="true", wenn es wirklich nichts zu überprüfen gibt; eine explizite Lüge ist besser als ein stillschweigender Standardwert.

Was zurückkommt

Ein Subagent, der sein vollständiges Transkript zurückgibt, hat seinen eigenen Zweck verfehlt. Wenn die Antwort des Kindes größer ist als DSA_SUMMARY_TOKENS, wird es – in derselben Sitzung, als eine weitere Runde – gebeten, sie durch eine Übergabezusammenfassung in sieben Abschnitten zu ersetzen: Ziel, Einschränkungen & Präferenzen, Fortschritt, Wichtige Entscheidungen, Nächste Schritte, Relevante Dateien, Kritischer Kontext. Das ist es, was die MCP-Grenze überschreitet.

Eine Antwort, die bereits unter der Grenze liegt, wird wörtlich zurückgegeben und kostet keine zusätzliche Runde. Die rohe Antwort wird immer aufbewahrt: dsh_transcript(run_id, raw=True).

Überwachte Ausführung

Die Werkzeugaufrufe des Kindes werden vor ihrer Ausführung abgefangen. Ein PreToolUse-Hook innerhalb der Laufzeit übergibt jeden vorgeschlagenen Aufruf an diesen Server, der mit Erlauben oder Verweigern antwortet; ein verweigerter Aufruf kommt als blockiertes Werkzeugergebnis mit Angabe des Grundes zum Modell zurück, und das Modell passt sich an.

Ein deterministischer Klassifikator entscheidet zuerst, und er entscheidet über die meisten Aufrufe. Dateien lesen, ls, grep, Versionsverwaltungs-Lesevorgänge, Ausführen des eigenen Codes und der Tests des Arbeitsbereichs sind ohne Modellbeteiligung erlaubt. Privilegierte Befehle, Löschvorgänge außerhalb des Arbeitsbereichs, Fetch-in-Shell-Pipe und alles, was SSH-Schlüssel oder .env berührt, werden kategorisch abgelehnt – auch durch ein harmlos aussehendes Verb, denn cat ~/.ssh/id_rsa ist ein schreibgeschütztes Werkzeug, das auf ein Geheimnis angewendet wird. Nur das, was der Klassifikator nicht klassifizieren kann, wird eskaliert.

Die Eskalation läuft auf der besten Stufe, die der Client unterstützt, die beim Start ermittelt und von dsh_list gemeldet wird:

Jede Stufe schlägt geschlossen fehl. Ein nicht erreichbarer Supervisor, ein Timeout, eine fehlerhafte Anfrage oder ein Client, der keine der beiden Fähigkeiten unterstützt, führen alle zu einer Ablehnung, niemals zu einer Genehmigung.

Die Leiter wird durchlaufen, nicht einmal ausgewählt: Eine Stufe, die einen Fehler verursacht, fällt auf die nächste Stufe zurück, sodass ein Client, der Sampling fallen lässt – in der Spezifikationsrevision vom 28.07.2026 als veraltet markiert, aber heute noch funktionierend – zu dir zurückfällt, anstatt alles abzulehnen. Eine Stufe, die ein Timeout hat, fällt nicht zurück; eine unbeantwortete Frage ist ein Nein, und eine erneute Frage auf einem anderen Kanal würde die Wartezeit nur verdoppeln.

Setze DSA_SUPERVISOR=off, um die Sperre vollständig zu deaktivieren.

Dem Supervisor werden strukturierte Fakten gezeigt, niemals die Prosa des Kindes: das Werkzeug, die Programme in jedem Pipeline-Segment und jeder Pfad, den der Befehl nennt, mit einem Flag, ob er innerhalb oder außerhalb des Arbeitsbereichs liegt. Das Kind schreibt sowohl den Befehl als auch eine Begründung dafür, und ein Kind, das seinen eigenen Fall argumentieren kann, wird es tun. Ein Pfad, der nicht statisch aufgelöst werden kann – $TMPDIR/out.txt – wird als unaufgelöst gemeldet, nicht geraten, und zählt als außerhalb.

examples/claude_supervisor.py führt das gesamte Muster gegen einen echten Claude aus, für Clients, die selbst kein sampling anbieten:

DEEPSEEK_API_KEY=sk-... uv run python examples/claude_supervisor.py

Obergrenzen und Kosten

Ein delegierter Agent gibt in einer Schleife dein Geld aus, daher begrenzen ihn vier unabhängige Obergrenzen, und jeder Lauf meldet, was er verbraucht hat.

Es gibt keinen Abbruch während einer Runde auf der Leitung, daher ist jeder Stopp ein Prozess-Kill. Ein Kill aufgrund einer Obergrenze hat immer Vorrang vor dem, was der Lauf selbst gemeldet hat: Die Ausgabe eines getöteten Prozesses wird niemals als Erfolg gelesen.

dsh_delegate, dsh_await und dsh_list melden alle die Token-Nutzung – Eingabe, Ausgabe, Cache-Lese- und -Schreibvorgänge sowie Schrittanzahl – summiert aus dem, was der Anbieter gemeldet hat. Die Eingabe pro Schritt wird absichtlich summiert: Jede Anfrage berechnet das gesamte erneut gesendete Präfix, daher ist die Summe das, was die Delegation tatsächlich gekostet hat.

Konfiguration

Jede Einstellung ist eine Umgebungsvariable im Serverprozess.

Grenzen, die Sie kennen sollten, bevor Sie sich darauf verlassen

Diese stammen aus dem Wire-Protokoll des Harness SDK, nicht aus hier getroffenen Entscheidungen.

• Die Dateisystem-Sandbox deckt Bash nicht ab. dsh-fs-sandbox schränkt die write-/edit-Tools des Modells auf den Arbeitsbereich ein, aber dsh-bash-sandbox ist nicht in der gebündelten Laufzeitumgebung enthalten, daher ist Bash selbst uneingeschränkt. Der Supervisor deckt dies ab – er schaltet jedes Tool einschließlich Bash vor der Ausführung vor. Mit DSA_SUPERVISOR=off gibt es überhaupt keine Begrenzung für Bash; richten Sie es auf einen Branch oder ein temporäres Verzeichnis.

• Die Sandbox schränkt nur Dateieffekte ein – nicht Netzwerk, Prozesse oder Systemaufrufe. Und workspace-write erlaubt /tmp sowie das Arbeitsverzeichnis.

• Abbrechen beendet den Prozess. Es gibt kein Abbruch während eines Durchlaufs im Wire-Protokoll, daher beendet dsh_cancel die Laufzeitumgebung. Bereits geschriebene Bearbeitungen bleiben auf der Festplatte, und die Sitzung kann danach nicht fortgesetzt werden.

• Die Sitzung eines abgeräumten Agenten ist weg, aber seine Ergebnisse sind es nicht. Nach DSA_IDLE_TIMEOUT wird der Prozess freigegeben; dsh_await und dsh_transcript funktionieren weiterhin für seine abgeschlossenen Durchläufe, dsh_continue nicht.

• Sitzungen leben so lange wie der Prozess. Es gibt kein Schließen pro Sitzung, daher wächst der Speicher mit der Historie eines Agenten. Brechen Sie Agenten ab, mit denen Sie fertig sind.

• Upstream ist eine Entwicklervorschau. deepseek-harness-sdk ist auf ==0.1.0rc7 festgelegt; zwei Release Candidates wurden innerhalb einer Woche ausgeliefert. Erwarten Sie, dass sich das Wire-Protokoll ändert.

Entwicklung

uv sync
uv run pytest                  # 127 tests, no API key, no network
uv run ruff check .
uv run deepseek-subagent-mcp   # starts on stdio; a client drives it

Live-Tests benötigen einen echten Schlüssel und kosten Token; sie werden nicht von pytest gesammelt:

DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_task.py        # the product works
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_result.py      # distillation and the archive
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_supervisor.py  # the gate works
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_escalation.py  # both escalation tiers
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_limits.py      # reaper and deadline
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_mcp.py         # all six tools

CLAUDE.md enthält die Architektur und die Upstream-Einschränkungen; wiki/ enthält das Entscheidungsprotokoll und was gemessen wurde.

Lizenz

MIT.