MCP Failure Lab

Ein Chaos-Engineering- und Resilienz-Testwerkzeug für Model Context Protocol-Server.

Dokumentation · Projektseite

Schnellstart

Führen Sie ein reales deterministisches Verzögerungsszenario aus, ohne das Repository zu klonen oder das Paket global zu installieren:

npx mcp-failure-lab demo

Beispielausgabe:

MCP Failure Lab — Demo
Running a real 500ms delay scenario...

Scenario: Deterministic delay demo
Outcome: success
Duration: ~500 ms
Assertions: passed

Die genaue Dauer kann zwischen den Läufen leicht variieren. Es ist kein API-Schlüssel oder externer MCP-Server erforderlich.

Verfügbare Befehle anzeigen:

npx mcp-failure-lab --help

Starten Sie den integrierten MCP-Server über stdio:

npx mcp-failure-lab serve

Related MCP server: mcp-chaos-rig

Zweck

MCP Failure Lab hilft Server-Autoren, Verzögerungen, hängende Werkzeuge, Abbrüche und Transportverluste auf deterministische Weise zu reproduzieren.

Es bietet kontrolliertes Fehlerverhalten zum Testen von Timeout-Behandlung, Abbruchbereinigung, Wiederherstellung nach Transportverlust, Zusicherungen und CI-Ergebnissen.

Aktueller Umfang

MCP Failure Lab führt deterministische JSON-Szenarien gegen seinen eigenen integrierten MCP-Server über die Befehlszeile aus.

Derzeit verfügbar:

• ping-, delay-, hang- und disconnect-Werkzeuge

• MCP-Kommunikation über stdio

• Code-first- und JSON-Szenariodefinitionen

• Ergebnis- und Maximaldauer-Zusicherungen

• MCP-Ergebnis-Zusicherungen

• Sequentielle Observer-Aufrufe zur Überprüfung von Nachbedingungen

• Konsolen- und JSON-Berichterstattung

• Maschinenlesbare Befehlsfehler

• CI-freundliche Exit-Codes

• Unit-, Integrations- und End-to-End-Tests

Nicht implementiert:

• Externe MCP-Client-Orchestrierung

• Zielclient-Adapter

• Streamable HTTP

• JUnit-Berichterstattung

• Fehler durch fehlerhafte Nachrichten, doppelte Antworten und Sitzungsverlust

MCP Failure Lab ist derzeit weder ein Allzweck-Proxy noch ein externer MCP-Client-Test-Orchestrator.

So funktioniert es

MCP Failure Lab führt deterministische Szenarien über seinen integrierten MCP-Client und -Server aus. Ein Szenario ruft ping, delay, hang oder disconnect auf, zeichnet das beobachtete Ergebnis und die Dauer auf und bewertet die deklarierten Erwartungen.

Optionale Observer-Aufrufe werden sequenziell auf derselben MCP-Client-Verbindung ausgeführt, um Nachbedingungen über einen separaten Werkzeugpfad zu verifizieren.

Siehe die Architekturdokumentation für Diagramme, Verantwortlichkeiten und Implementierungsgrenzen.

Dokumentation

Vollständige Anleitungen und Referenzen finden Sie unter mcplab.dev/docs.

• Erste Schritte

• Szenarien

• Fehlerwerkzeuge

• CLI-Referenz

• Berichterstattung

• Architektur

• Beispiele

• Fehlerbehebung

Anforderungen

• Node.js 22.19.0 oder neuer

• npm

Protokollkompatibilität

MCP Failure Lab zielt standardmäßig auf MCP 2026-07-28. Sein CLI-Server verwendet den SDK-v2-Ära-bewussten stdio-Einstiegspunkt, und sein integrierter Szenario-Client pinnt 2026-07-28, sodass modernes Verhalten explizit getestet wird.

Der Server akzeptiert auch den 2025-11-25-Initialisierungsablauf für Kompatibilität. Dieser Legacy-Pfad bleibt durch Integrationstests abgedeckt, aber die neue Entwicklung zielt auf 2026-07-28. Die vorhandenen Fehlerwerkzeuge ping, delay, hang und disconnect haben in beiden Ären dasselbe benutzerseitige Verhalten; Protokollfunktionen, die auf serverinitiierte Anfragen angewiesen sind, unterscheiden sich zwischen den Ären und liegen außerhalb dieser Fehlerwerkzeuge.

Installation

Führen Sie das Paket direkt mit npx aus:

npx mcp-failure-lab demo

Keine globale Installation erforderlich.

Um den Befehl global zu installieren:

npm install -g mcp-failure-lab

CLI

# Run the built-in demonstration
npx mcp-failure-lab demo

# Display command help
npx mcp-failure-lab --help

# Display the installed version
npx mcp-failure-lab --version

# Start the MCP server over stdio
npx mcp-failure-lab serve

Der serve-Prozess wartet auf einen MCP-Client. Drücken Sie Ctrl+C, um ihn ordnungsgemäß zu beenden.

Ein Szenario ausführen

Szenariodateien verwenden JSON:

{
  "name": "bounded delay succeeds",
  "call": {
    "tool": "delay",
    "args": {
      "delayMs": 250
    }
  },
  "timeoutMs": 1000,
  "expect": {
    "outcome": "success",
    "maxDurationMs": 500
  }
}

Führen Sie aus einem Repository-Checkout das enthaltene Szenario aus:

npm run dev -- run examples/scenarios/delay-success.json

Maschinenlesbare Ausgabe erzeugen:

npm run dev -- run examples/scenarios/delay-success.json --report json

Der Befehl beendet sich mit:

Für Ergebnis-Zusicherungen, Observer-Aufrufe, Berichtsformate und Timeout-Verhalten siehe die Szenario- und Berichterstattung-Dokumentation.

Fehlerwerkzeuge

Siehe die Fehlerwerkzeug-Referenz für Argumente und Verhalten.

Server untersuchen

Starten Sie MCP Inspector gegen das veröffentlichte Paket:

npx @modelcontextprotocol/inspector npx mcp-failure-lab serve

Verbinden Sie sich über stdio, listen Sie die verfügbaren Werkzeuge auf und rufen Sie ping, delay, hang oder disconnect auf.

Teilen oder committen Sie keine temporären Authentifizierungstokens, die in Inspector-URLs enthalten sind.

Externe Integrationsvalidierung

MCP Failure Lab wurde unabhängig mit einer Future-AGI-Simulation unter Verwendung eines unabhängigen Python-MCP-Clients validiert. Das Experiment rief das echte hang-Werkzeug über stdio auf und wandte einen clientseitigen Timeout an, bevor simulierte Agentenantworten ausgewertet wurden.

Dies ist ein Beispiel für eine externe Validierung, keine offizielle Future-AGI-Integration oder -Befürwortung.

Siehe das Future-AGI-Beispiel für Ergebnisse und Reproduktionsschritte.

Entwicklung

Klonen Sie das Repository und installieren Sie seine Abhängigkeiten:

git clone https://github.com/anilloutombam/mcp-failure-lab.git
cd mcp-failure-lab
npm install

Führen Sie die Entwicklungs-CLI aus:

npm run dev -- --help

Bevor Sie einen Pull-Request öffnen, führen Sie Folgendes aus:

npm run format:check
npm run typecheck
npm test
npm run build

Siehe CONTRIBUTING.md für den Beitragsablauf.

Roadmap

Geplante Arbeiten werden in GitHub Issues verfolgt.

Roadmap-Punkte sind nicht Teil der aktuellen Implementierung, sofern sie nicht explizit als verfügbar dokumentiert sind.

Lizenz

MIT