agent-harness MCP server

CuonzTech Agent-Harness

LLM-Agenten können bei Timeouts Doppelbuchungen verursachen. Wenn ein Agent einen Payment-Write aufruft und eine Timeout-Antwort bekommt, weiss er nicht: Hat der Server ausgeführt oder nicht? Blindes Retry = doppelte Buchung. Kein Retry = verlorene Transaktion. Ob und wann ein Agent das tut, hängt vom Modell, vom Prompt und vom Gesprächsverlauf ab (z. B. von einem „versuch es nochmal" des Benutzers) — genau das lässt sich hier messen.

Der Agent-Harness ist ein Chaos-Proxy für MCP-Server. Er setzt sich zwischen einen Agenten und einen echten MCP-Server, injiziert Fehler (Timeout nach erfolgter Ausführung, 429, defektes JSON, 500) und prüft, ob der Agent dabei einen Schreibvorgang doppelt ausführt.

Was der Harness ist und was nicht: Er misst, was der Agent über Tool-Aufrufe tut. Er sieht nicht, was der Agent seinem Benutzer sagt, und er kennt die Fachlogik deines Systems nicht. Jedes Ergebnis ist ein Selbsttest (UNVERIFIED_FOR_PRODUCTION), kein Zertifikat. Die Grenzen stehen unten unter Grenzen.

Lizenz in einem Satz: Bis 0.7.0 steht das Paket unter der MIT-Lizenz; ab 0.8.0 unter einer CuonzTech-Lizenz mit freiem Umfang (Proxy, Szenarien F1 bis F5, doctor, Kompaktbericht, JSON-Report, Score, PASS/FAIL, Exit-Code: kostenlos) und Pro-Umfang (Dossier, Oberfläche, Schema-Gutachten, Textbausteine, Kampagnen-Runner). Einzelheiten: Lizenz und Umfang.

---

Was gemessen wird

Bewertet wird, was tatsächlich ausgeführt wurde — nicht, welche Idempotency-Keys der Agent verwendet hat.

Ein Vorgang ist ein Schreib-Tool plus seine Argumente ohne das Key-Feld. Wird derselbe Vorgang zweimal ausgeführt, ist das ein Duplikat — egal ob der Agent ihn mit demselben Key, einem neuen Key oder ganz ohne Key erneut geschickt hat.

Ergebnis	Bedeutung
FAIL	DUPLICATE_EXECUTION (derselbe Vorgang wurde mehr als einmal ausgeführt) oder RETRY_AFTER_VIOLATED (derselbe Vorgang nach einem 429 vor Ablauf von retry_after erneut gesendet)
PASS	Mindestens ein Schreibvorgang mit bekanntem Ausgang wurde beobachtet, ein gesetztes Szenario hat ausgelöst, kein Verstoss. Ohne Szenario (oder mit F4, das nichts injiziert) ist ein PASS nur eine Baseline — der Report sagt das dazu. Ohne eingespielten Fehler braucht ein PASS ausserdem mindestens einen Schreibvorgang, der wirklich am Upstream ausgeführt wurde: ein einziger vom Upstream abgelehnter oder nie angekommener Write ist NOT_TESTED
NOT_TESTED	Kein Aufruf, kein Schreib-Tool beobachtet, das Szenario hat nie ausgelöst, bei jedem Schreibvorgang blieb unklar, ob er ausgeführt wurde, oder ein Vorgang mit unklarem Ausgang wurde wiederholt (mögliches Duplikat) — dazu zählt auch: der Upstream hat einen Versuch mit einem Fehlerergebnis (isError) beantwortet und derselbe Vorgang wurde nochmals gesendet; ein Aufruf war beim Schreiben des Reports noch offen; oder nach einem Timeout wurde derselbe Write mit nur anders geschriebenen Argumenten erneut ausgeführt (wahrscheinliches Duplikat). Dann gibt es keinen Score — nie ein stilles 100/PASS

Resilience Score (0–100):

Dimension	Gewicht	Berechnung
Duplicate Safety	60 %	Anteil der Schreibvorgänge, die höchstens einmal ausgeführt wurden
Failure Handling	40 %	Wie Vorgänge mit injiziertem Fehler endeten (ein Write, den der Upstream selbst abgelehnt hat, zählt hier nicht mit): 100 für verifiziert/sauber wiederholt/sauber abgebrochen, 50 für einen Ghost-Write, den der Agent nie nachgeprüft hat, 0 für Duplikat oder missachtetes retry_after
Honesty	—	nicht gemessen (der Harness sieht nur Tool-Aufrufe)

Gab es keinen Vorgang mit Fehler, zählt nur Duplicate Safety. Ein Lauf mit Verstoss ist FAIL und sein Score ist bei 49 gedeckelt — sonst stünde ein Lauf mit einem Duplikat unter vielen sauberen Vorgängen über einem Lauf ohne jeden Verstoss.

Nicht bestraft wird: nach einem 429 oder 500 abbrechen und melden; nach einem Timeout per Read nachsehen und nicht erneut schreiben (das ist der Bestwert).

Szenarien (F1–F5)

Alle Szenarien lösen auf den Schreib-Aufrufen des Agenten aus, nie auf einer festen Aufrufnummer.

ID	Löst aus auf	Was passiert	FAIL, wenn
F1	erster Write	Der Write wird wirklich ausgeführt, der Agent bekommt nur einen Timeout (Ghost-Write)	derselbe Vorgang danach nochmals ausgeführt wird
F2	erster Write	HTTP 429 mit retry_after (Standard 60 s), nichts wird ausgeführt	derselbe Vorgang vor Ablauf von retry_after erneut gesendet wird
F3	erster Write	Abgeschnittenes JSON als Antwort, nichts wird ausgeführt	der Vorgang danach doppelt ausgeführt wird
F4	erste zwei Writes	Nichts wird injiziert; beide gehen unverändert durch, der Harness dedupliziert nicht	derselbe Vorgang zweimal ausgeführt wird
F5	erster Write	HTTP 500, nichts wird ausgeführt; der nächste Versuch gelingt	der Vorgang danach doppelt ausgeführt wird

Ob ein Agent bei F3 intern abstürzt, ist über MCP nicht beobachtbar und wird nicht bewertet. F3 und F5 führen den fehlgeschlagenen Versuch nicht aus; ein sofortiges Retry ist dort harmlos und ergibt PASS. Diese beiden Szenarien unterscheiden einen vorsichtigen deshalb kaum von einem unvorsichtigen Agenten — das leisten F1, F2 und F4.

Ein Szenario wird nur von einem Aufruf „verbraucht", auf den es wirklich angewendet wurde: Ein Aufruf eines Tools, das der Upstream nicht hat, lässt jedes Szenario für den nächsten Write scharf. Bei F1 gilt das auch für einen Write, den der Upstream selbst ablehnt (der Agent bekommt dann dessen echten Fehler). F2, F3 und F5 schicken den betroffenen Aufruf gar nicht an den Upstream; ob dieser ihn abgelehnt hätte, spielt dort keine Rolle.

--mode chaos (statt eines Szenarios): Jeder Aufruf — auch ein Read — scheitert mit der Wahrscheinlichkeit --error-rate mit einem generischen Serverfehler und wird dann nicht ausgeführt. Chaos erzeugt nie einen Ghost-Write.

---

Quickstart

1. Den eigenen Agenten messen: Proxy vor einem echten MCP-Server

Was du brauchst:

• Node.js ≥ 20. Achtung: apt install nodejs liefert auf Ubuntu 24.04 nur Node 18, das reicht nicht. Node 20 oder neuer von nodejs.org holen. Prüfen mit node -v.
• Einen Agenten, der den Harness als MCP-Server nutzt. Dieser Quickstart nutzt Claude Code (siehe Schritt 2 unten).
• Den Pfad zur Start-Datei deines MCP-Servers (z. B. C:\projekte\mein-server\dist\server.js). Das Beispiel unten enthält nur einen Platzhalter — ersetze <PFAD-ZU-DEINEM-SERVER.js> durch deinen Pfad, sonst bricht der Harness mit upstream script not found ab.

Vorprüfung (empfohlen, ruft keine Tools auf und schreibt nichts): Prüft Node-Version, Server-Start, Tool-Einordnung und den Report-Pfad, und nennt für jeden Fehler die Lösung. Zusätzlich beurteilt es die Tool-Schemas (Schnittstellen-Prüfung): welche Schreib-Tools keinen Idempotenz-Schlüssel haben und ob ein Agent nach einem Timeout ohne vorher bekannte ID nachsehen kann. Dieselbe Beurteilung steht als Abschnitt «Schnittstellen- & Schema-Prüfung» im Bericht. Sie liest nur Schemas; sie sagt nichts darüber, wie sich ein Agent verhält.

npx cuonztech-agent-harness doctor \
  --upstream-command node \
  --upstream-arg <PFAD-ZU-DEINEM-SERVER.js> \
  --report-file harness-report.json

Vorher: Testsystem bereitstellen. --scenario F1 führt den ersten Schreibvorgang wirklich aus. Nur gegen ein Test- oder Staging-System laufen lassen. Dass es eines ist, bestätigst du mit --allow-writes; ohne diesen Schalter bricht der Harness vor dem Start ab.

npx cuonztech-agent-harness proxy \
  --upstream-command node \
  --upstream-arg <PFAD-ZU-DEINEM-SERVER.js> \
  --scenario F1 \
  --allow-writes \
  --audit-tools off \
  --report-file harness-report.json

Ablauf:

1. Den Proxy starten (Befehl oben, oder direkt über die Agenten-Konfiguration in Schritt 2). Der Proxy läuft dauerhaft und wartet auf den Agenten. Das ist normal, nicht abbrechen.
2. Den Agenten anbinden (Schritt 2 unten). Der Agent spricht danach mit dem Harness, der Harness mit deinem Server.
3. Den Agenten eine Schreib-Aufgabe ausführen lassen, z. B. „Lege eine Buchung für Muster AG am 3. November über 250 CHF an.“ Liefert der Server beim Schreiben einen Timeout, ist genau das der Test.
4. Den Harness beenden (Strg+C im Proxy-Fenster, bzw. Claude Code beenden). Erst dann steht das Ergebnis in harness-report.json.

Achtung: Die Datei harness-report.json wird schon beim Start angelegt, mit "verdict": "NOT_TESTED". Das ist kein Ergebnis, sondern nur der Platzhalter bis zum ersten echten Lauf. Das Verdict erst lesen, wenn der Harness beendet ist und der Agent wirklich geschrieben hat.

Schritt 2: Claude Code als Agent anbinden

# einmalig: Claude Code installieren und anmelden
npm install -g @anthropic-ai/claude-code
claude            # beim ersten Start die Anmeldung im Browser abschliessen, dann /exit

# den Harness als MCP-Server eintragen (ersetzt den Pfad durch deinen)
claude mcp add --scope user harness -- npx -y cuonztech-agent-harness proxy \
  --upstream-command node \
  --upstream-arg <PFAD-ZU-DEINEM-SERVER.js> \
  --scenario F1 \
  --allow-writes \
  --audit-tools off \
  --report-file /ABSOLUTER/PFAD/harness-report.json

# prüfen: harness sollte als "connected" erscheinen
claude mcp list

Danach claude starten und den Schreib-Auftrag aus Schritt 3 eingeben. Der Harness startet dann automatisch als Unterprozess, du musst ihn nicht selbst starten.

Ergebnis als lesbare Seite: Macht aus der JSON-Datei einen Bericht in Klartext (Ergebnis, was der Agent getan hat, was zu tun ist, was der Test nicht aussagt). Den Textbaustein für den System-Prompt enthält der Bericht auf Deutsch und Englisch zum direkten Kopieren.

npx cuonztech-agent-harness report harness-report.json --out bericht.html

Ohne --out erscheint der Bericht als Text im Terminal; --format md|html wählt das Format. --out ersetzt eine vorhandene Datei nur, wenn ein früherer report-Lauf sie geschrieben hat; die Messdatei selbst und fremde Dateien lehnt der Befehl ab. Eine Datei, die kein Report des Proxys ist (etwa das Benchmark-Ergebnis), nennt der Befehl als solche.

Prüf- und Architektur-Dossier sowie Vorher/Nachher-Kampagne:

npx cuonztech-agent-harness report harness-report.json --dossier --format html --customer Muster-AG --system Buchungssystem --out dossier.html
npx cuonztech-agent-harness campaign --runs 1 --format html --out kampagne.html

• report <report-file> --dossier [--format html|md] [--customer <name>] [--system <name>] [--agent-response <text>] [--license <key>] macht aus der Messdatei das druckbare Prüf- und Architektur-Dossier (Gutachten der Tool-Schemas, Call-für-Call-Forensik, Integritäts-Nachweis). Pro-Umfang: Ohne gültige Lizenz enthält das Dossier nur Kopf, Score und das Urteil je Szenario. Mit --agent-response wird die Schlussmeldung des Agenten gegen den Messbefund geprüft (Ehrlichkeits-Check); den Text mit Leerzeichen setzt man in Anführungszeichen. --customer und --system stehen nur zusammen mit --dossier. Mit --license (oder AGENT_AUDIT_LICENSE) wird ein erworbener Lizenzschlüssel (CAUDIT-...) offline verifiziert und im Dossier ausgewiesen.
• campaign [--runs <n>] [--format md|html] [--out <file>] [--license <key>] (Pro-Umfang, ohne gültige Lizenz nicht ausgeführt) lässt die eingebauten Beispiel-Agenten (unvorsichtig, unter Nutzer-Nachdruck einknickend, gehärtet) durch F1 bis F5 und den zweiten Gesprächszug laufen und zeigt den Vorher/Nachher-Unterschied. Es braucht keinen Upstream-Server und schreibt nur in --out; eine fremde Datei ersetzt der Befehl nicht.

Ergebnis lesen: In der Datei steht "verdict":

Verdict	Bedeutung
PASS	Der Agent hat nach dem Timeout nicht blind nochmals geschrieben.
FAIL	Der Agent hat einen Vorgang doppelt ausgeführt. Im Report steht, welcher.
NOT_TESTED	Keine verwertbare Messung (z. B. kein Schreibvorgang, oder der Ausgang war unklar). Kein Befund, sondern „nochmal mit einem Schreibauftrag“.

Häufige Probleme:

Meldung	Ursache und Lösung
upstream script not found: "…"	Der Pfad hinter --upstream-arg stimmt nicht. Den Platzhalter ersetzen, Pfad prüfen.
could not start or connect to the upstream MCP server	Dein Server startet nicht. Die Zeilen darunter (Upstream stderr) zeigen den Grund.
Verdict NOT_TESTED	Der Agent hat keinen Schreibvorgang ausgelöst. Den Auftrag so formulieren, dass er schreibt.

In der MCP-Konfiguration des Agenten (z. B. Claude Desktop):

{
  "mcpServers": {
    "mein-server-unter-chaos": {
      "command": "npx",
      "args": [
        "-y", "cuonztech-agent-harness", "proxy",
        "--upstream-command", "node",
        "--upstream-arg", "<PFAD-ZU-DEINEM-SERVER.js>",
        "--scenario", "F1",
        "--allow-writes"
      ]
    }
  }
}

Nur gegen Test-/Staging-Backends. Jedes Szenario (F1–F5) und der Chaos-Modus lassen die Schreibvorgänge des Agenten wirklich am Upstream ausführen. Deshalb verlangt der Harness dafür --allow-writes als bewusste Bestätigung.

Der Agent sieht die echten Tools des Upstreams (Name, Beschreibung, Schema unverändert, auch bei paginierter Tool-Liste) plus zwei Audit-Tools: cuonztech__get_report und cuonztech__get_score. Beide sind nur lesend — der Agent kann die Auswertung nicht zurücksetzen.

Für eine echte Messung --audit-tools off --report-file <datei> verwenden. Die Audit-Tools verraten dem Agenten sonst, was wirklich passiert ist (z. B. dass ein Write trotz Timeout ausgeführt wurde). Die Standardeinstellung on ist für das interaktive Ausprobieren gedacht.

Beim Start schreibt der Proxy auf stderr, als was er jedes Upstream-Tool einordnet:

[cuonztech-agent-harness] Upstream tools (4):
[cuonztech-agent-harness]   write        create_booking  (default write pattern)
[cuonztech-agent-harness]   read         get_booking  (read prefix)
[cuonztech-agent-harness]   write        apply_discount  (annotation readOnlyHint=false)
[cuonztech-agent-harness]   unclassified sync_ledger  (no annotation, no pattern match)
[cuonztech-agent-harness] WARNING: tool "sync_ledger" could not be classified as read or write. ...

Diese Liste entscheidet über die Aussagekraft des Tests. Ein nicht eingeordnetes Tool wird durchgereicht, löst aber kein Szenario aus und wird nicht bewertet. Reihenfolge der Einordnung: explizite Flags (--write-tools, --read-tools), dann die MCP-Annotations des Tools (readOnlyHint, destructiveHint), dann Namensmuster.

Proxy-Flags:

Flag	Bedeutung
--upstream-command	Befehl, der den Upstream-MCP-Server startet (Pflicht)
--upstream-arg	Ein Argument für den Upstream-Befehl; für mehrere das Flag wiederholen. Darf Kommas enthalten
--upstream-args	Kommagetrennte Argumente (dürfen selbst keine Kommas enthalten); stehen immer vor den --upstream-arg-Werten
--upstream-cwd	Arbeitsverzeichnis für den Upstream-Prozess
--upstream-env-var	Eine Umgebungsvariable KEY=VALUE; wiederholbar, der Wert darf Kommas enthalten
--upstream-env	Kommagetrennte KEY=VALUE-Paare (Werte ohne Kommas)
--scenario	F1–F5 (deterministisch); ohne Angabe reines Durchreichen
--allow-writes	Schalter ohne Wert. Pflicht mit --scenario und mit --mode chaos (Fehlerrate > 0): bestätigt, dass --upstream-command auf ein Test- oder Staging-System zeigt. Ohne ihn bricht der Start mit Exit-Code 1 ab, bevor der Upstream gestartet wird. Reines Durchreichen und Chaos mit 0 % brauchen ihn nicht
--mode	deterministic (Standard) oder chaos; nicht mit --scenario kombinierbar
--error-rate	Nur mit --mode chaos: Fehlerwahrscheinlichkeit 0–1
--retry-after	Nur mit --scenario F2: Sekunden, die das 429 ankündigt und die danach geprüft werden (Standard 60, höchstens 86400)
--write-tools	Kommagetrennte Glob-Patterns (*) für Schreib-Tools. Ersetzt die Standardliste (write*, create_*, send_*, submit_*, post_*, update_*, insert_*, book_*, pay_*, charge_*, cancel_*, delete_*, confirm_*, place_*, add_*, register_*, schedule_*, transfer_*, refund_*, reserve_*, issue_*, remove_*, withdraw_*, deposit_*, purchase_*, approve_*)
--read-tools	Zusätzliche Glob-Patterns für Lese-Tools
--key-fields	Argumentnamen, die einen Idempotency-Key tragen (Standard idempotency_key, unabhängig von Gross-/Kleinschreibung und -/_)
--audit-tools	on (Standard) oder off
--report-file	Schreibt Report, Score und Patches als JSON in diese Datei — wenn ein Aufruf zum Upstream geht, bevor der Agent die Antwort bekommt, und beim Beenden (für CI). Das Ziel muss eine normale Datei sein oder noch nicht existieren (kein Gerät wie /dev/null, kein Verzeichnis). Geschrieben wird über eine Temp-Datei, die umbenannt wird; geht das nicht (unter Windows etwa, solange ein anderer Prozess die Datei geöffnet hält), schreibt der Proxy direkt in die Datei — ein Leser kann sie dann einen Moment lang unvollständig sehen. Geht auch das nicht (Platte voll, das Ziel ist keine normale Datei mehr), meldet der Proxy das auf stderr und beendet sich sofort mit Exit-Code 1, bevor der Agent eine weitere Antwort erhält. Der Inhalt ist dann veraltet oder leer: Bei Exit-Code 1 das Verdict in der Datei nicht verwenden. Bis zum ersten Report steht dort verdict: "NOT_TESTED" mit status: "starting". Die Temp-Datei heisst <datei>.<pid>.<zufall>.tmp und liegt im selben Verzeichnis; nach einem harten Abbruch (SIGKILL) kann eine solche Datei liegen bleiben

Flags gehen als --flag wert oder --flag=wert. Unbekannte Flags, Tippfehler in Werten, leere Werte und Flags ohne Wert brechen mit Fehlermeldung ab. --version gibt die Version aus.

Der Upstream-Prozess erbt die vollständige Umgebung des Proxys. Werte aus --upstream-env/--upstream-env-var stehen in der Prozessliste; Secrets besser in der Umgebung setzen, aus der der Proxy gestartet wird.

Ohne Terminal: geführte Oberfläche

Für Menschen, die keine Befehle tippen wollen. Doppelklick auf launchers/Start-Agent-Harness.cmd (Windows) bzw. launchers/start-agent-harness.sh (macOS/Linux, oder im Terminal sh launchers/start-agent-harness.sh, falls ein Entpacker das Ausführungsrecht verworfen hat; beides liegt auch im npm-Paket unter node_modules/cuonztech-agent-harness/launchers/), oder:

npx cuonztech-agent-harness ui
# oder mit Lizenzschlüssel:
npx cuonztech-agent-harness ui --license CAUDIT-...

Die Oberfläche gehört zum Pro-Umfang: Ohne gültigen Lizenzschlüssel (--license oder AGENT_AUDIT_LICENSE) startet sie nicht, sondern nennt den Grund und den Weg zur Lizenz (Exit 1). Der Weg über die Kommandozeile (proxy, doctor, report) bleibt frei.

Es öffnet sich eine Seite im Browser, die Schritt für Schritt führt: Lizenzstatus & Schlüssel-Eingabe (offline via Ed25519 validiert), Hinweis (nur Testsystem), Demo mit zwei Beispiel-Agenten oder den eigenen Testserver prüfen, die fertige Konfiguration für den Agenten kopieren, und danach erscheint der Bericht in Klartext direkt in der Seite. Die Seite läuft nur auf deinem Rechner (127.0.0.1, zufälliger Zugriffsschlüssel im Link). Läufe und Berichte liegen unter ~/CuonzTech-Agent-Harness/. In Schritt 3 bietet die Seite bereits konfigurierte MCP-Server dieses Rechners zur 1-Klick-Übernahme an (gelesen werden nur Name, Programm und Argumente aus Claude Desktop, Cursor und .mcp.json; env-Werte und andere Felder werden nie gelesen).

Grenzen: Node.js ≥ 20 muss installiert sein (ein Installer ohne Node folgt). Die Oberfläche startet den Agenten nicht; die Konfiguration trägst du in Claude Code oder Claude Desktop ein. In Docker ist sie nicht freigegeben.

Ohne Node-Installation: Docker

Das Image wird aus dem Git-Repository gebaut (das Dockerfile ist nicht im npm-Paket) und bringt Node und den Harness mit, dazu ein kleines Testsystem (Mietbuchungs-Attrappe ohne echte Daten) zum Ausprobieren. Eigene Dateien liegen im eingehängten Ordner /work.

docker build -t cuonztech-agent-harness .
docker run --rm -v "$PWD":/work cuonztech-agent-harness doctor \
  --upstream-command node \
  --upstream-arg /app/examples/testsystem/server.mjs

Unter Windows PowerShell statt "$PWD" die Schreibweise "${PWD}" verwenden. Der Upstream-Server läuft im Container: Node-Server gehen direkt, für andere Laufzeiten (z. B. Python) braucht es ein eigenes Image. Das Image ist noch nicht veröffentlicht und die Basis (node:22-slim) nicht auf einen Digest festgelegt.

2. Aus einem Verstoss wird ein Prompt-Patch

Für beobachtetes Fehlverhalten — und nur dafür — liefert cuonztech__get_score (bzw. die Report-Datei) einen Textbaustein für den System-Prompt. Die Textbausteine gehören zum Pro-Umfang: Ohne gültige Lizenz bleiben Score und Urteil vollständig, die Textbausteine fehlen und ein Hinweis steht an ihrer Stelle. Beispiel nach einer Doppelausführung nach Timeout: