L-Dopa

Ein MCP-Server, der KI-Agenten hilft, sich zu erholen, neu zu fokussieren und was zu schaffen.

L-Dopa hat mich wieder hingekriegt, okay??

L-Dopa ist ein kleiner, produktionsorientierter Model Context Protocol (MCP) Server, der einem Agenten hilft, sich zu erholen, wenn ein Ansatz scheitert, Kontext verstreut ist oder Retries sich in einer Schleife verfangen. Er führt keine Befehle aus, verändert keine externen Systeme und ersetzt nicht das Urteilsvermögen eines Agenten. Er analysiert die ihm gelieferten Belege, behält einen begrenzten Recovery-Zustand und schlägt einen sichereren nächsten Schritt vor.

Der Name ist ein Witz. Die Recovery-Schleife nicht.

Was es tut

L-Dopa v0.1 bietet sechs MCP-Tools, die einem Agenten ermöglichen, Fehler zu diagnostizieren, den Umfang zu reduzieren, relevanten Kontext wiederherzustellen und Retries bewusst zu verwalten.

Related MCP server: nautilus-compass

Designprinzipien

Installation

Klone das Repository und installiere die Abhängigkeiten:

git clone https://github.com/mshanghai570/L-Dopa.git
cd L-Dopa
npm install
npm run build

Starte den stdio-Server manuell mit:

npm start

npm start wartet absichtlich auf Eingaben. MCP-Server sprechen JSON-RPC über Standardeingabe und -ausgabe, daher startet normalerweise ein MCP-Client den Server für dich.

MCP-Client verbinden

Baue L-Dopa zuerst und verwende dann seinen ausführbaren Einstiegspunkt. Die folgende generische MCP-Konfiguration ist mit Clients kompatibel, die lokale stdio-Server unterstützen:

{
  "mcpServers": {
    "l-dopa": {
      "command": "node",
      "args": ["/absolute/path/to/L-Dopa/dist/index.js"],
      "env": {
        "LDOPA_STATE_FILE": "/absolute/path/to/l-dopa-state.json",
        "LDOPA_MAX_HISTORY": "50",
        "LDOPA_RETRY_LIMIT": "3",
        "LDOPA_LOG_LEVEL": "info"
      }
    }
  }
}

Bei einem installierten Paket kann der Befehl je nach Client-Umgebung auch l-dopa lauten. Halte die Standardausgabe für MCP-Protokollmeldungen reserviert. L-Dopa schreibt seine eigenen kompakten, strukturierten Betriebsprotokolle in die Standardfehlerausgabe.

Konfiguration

L-Dopa läuft mit sicheren Standardeinstellungen und kann über eine JSON-Datei und/oder Umgebungsvariablen konfiguriert werden. Kopiere das bereitgestellte Beispiel, um loszulegen:

cp l-dopa.config.example.json l-dopa.config.json
LDOPA_CONFIG=./l-dopa.config.json npm start

Umgebungsvariablen überschreiben Dateiwerte.

Die Konfiguration enthält keine Provider-Zugangsdaten-Einstellungen, da diese Version keine Modell- oder Provideraufrufe tätigt. Sollte eine zukünftige Erweiterung Zugangsdaten erfordern, übergib sie über Umgebungsvariablen; füge sie nicht zu einem Repository, einer Konfigurationsdatei oder einem Recovery-Prompt hinzu.

Tool-Referenz

Alle Textargumente sind in der Länge begrenzt und werden um Zugangsdaten geschwärzt, bevor L-Dopa sie speichert oder zurückgibt. sessionId ist standardmäßig "default", aber Agenten sollten für jede Aufgabe oder Konversation eine stabile ID verwenden, um zu verhindern, dass nicht zusammenhängende Recovery-Verläufe vermischt werden.

diagnose

Verwende diagnose nach einem Fehler mit so viel nützlichem Kontext wie verfügbar. errorMessage, recentOperation, logs, attemptedSolution, expectedResult und actualResult sind optional, aber eine präzise Fehlermeldung oder ein tatsächliches Ergebnis macht die Antwort nützlicher.

{
  "sessionId": "deploy-2026-08-27",
  "recentOperation": "Deploy version 0.1.0",
  "errorMessage": "429 Too Many Requests",
  "attemptedSolution": "Immediately retried the deployment",
  "expectedResult": "Deployment accepted",
  "actualResult": "The API rejected the request"
}

Die Antwort enthält likelyCause, confidence, evidence, recommendedNextActions, retryAppropriate, tryDifferentStrategy und einen redacted-Indikator. Die Erkennung ist bewusst heuristisch und nicht irreführend autoritativ.

stimulate

Verwende stimulate, wenn ein Agent aufhören muss zu erzählen und anfangen muss zu lernen. Gib ein erforderliches task und einen optionalen context mit hohem Signalwert an.

{
  "sessionId": "deploy-2026-08-27",
  "task": "Repair the deployment",
  "context": "The health check timed out twice after a successful build"
}

Die Recovery-Strategie betont eine minimale, überprüfbare Aktion und warnt vor unveränderten Schleifen.

focus

Verwende focus, um eine breite Aufgabe in eine bewusst kurze Sequenz zu verwandeln. maxSteps ist optional und reicht von eins bis fünf; standardmäßig ist es drei.

{
  "sessionId": "deploy-2026-08-27",
  "task": "Repair the deployment and verify availability",
  "context": "Health checks time out",
  "maxSteps": 3
}

reuptake

Verwende reuptake, wenn der Agent relevanten Sitzungskontext benötigt, ohne ein Transkript auszugeben. limit hat den Standardwert fünf und ist auf zwanzig begrenzt.

{
  "sessionId": "deploy-2026-08-27",
  "limit": 5
}

Es gibt die aktuelle Aufgabe, den Recovery-Status, kürzliche Fehler, versuchte Lösungen, erfolgreiche Ansätze, entdeckte Fakten, ungelöste Probleme und die Anzahl der Retries zurück. Die v0.1-Tools stellen noch kein dediziertes Tool zum Aufzeichnen von Fakten bereit; discoveredFacts ist für Erweiterungen reserviert und bleibt im kompakten Schema vorhanden.

retry

Verwende retry, um einen expliziten Retry-Datensatz zu erstellen oder dessen Ergebnis zu melden. Ein proposedChange sollte benennen, was anders ist. L-Dopa erlaubt geplante, erfolgreiche und fehlgeschlagene Datensätze, führt den Retry selbst jedoch nie aus.

{
  "sessionId": "deploy-2026-08-27",
  "operation": "Deploy version 0.1.0",
  "previousFailure": "429 Too Many Requests",
  "proposedChange": "Wait for Retry-After and submit only one request",
  "result": "planned"
}

L-Dopa blockiert einen Retry, wenn das konfigurierte Vorgangslimit erschöpft ist, derselbe Fehler erneut aufgetreten ist oder ein bestehender Retry ohne eine vorgeschlagene Änderung wiederholt wird. Die Sperrantwort empfiehlt einen begrenzten alternativen Pfad, der auch darin bestehen kann, eine klar abgegrenzte Teilaufgabe und gesammelte Belege an einen anderen fähigen Agenten zu übergeben.

fix_me

Verwende fix_me für die Kurzversion von diagnose → focus → stimulate → Retry-Anleitung. Es zeichnet einen bereitgestellten Fehler auf, sofern vorhanden, und gibt dann einen Plan zurück; es führt ihn nicht aus.

{
  "sessionId": "publish-0.1.0",
  "task": "Publish the package safely",
  "recentOperation": "npm publish",
  "errorMessage": "401 Unauthorized",
  "attemptedSolution": "Re-ran the same command"
}

Zustand und Datenschutz

Der Zustandsspeicher ist eine einfache JSON-Datei, die atomar mit Modus 0600 geschrieben wird. Er hat eine versionierte Form und speichert separate Sitzungen mit sessionId als Schlüssel. Innerhalb jeder Sitzung werden Fehlerdatensätze, Retry-Datensätze, versuchte Lösungen, erfolgreiche Ansätze und entdeckte Fakten auf maxHistory begrenzt.

Der Zustand ist bewusst leichtgewichtig, kein Langzeitgedächtnis-System. Er ist lokal auf dem Rechner des ausführenden Benutzers und wird von L-Dopa nicht übertragen. Überprüfe oder lösche die konfigurierte Zustandsdatei, wann immer du den Recovery-Verlauf löschen möchtest.

Wichtig: Die Schwärzung deckt mehrere häufige Zugangsdatenmuster ab, ist aber eine Schutzmaßnahme und kein Freibrief, Geheimnisse einzureichen. Platziere nicht absichtlich Passwörter, Tokens, private Schlüssel oder vollständige Authorization-Header in diagnostischen Eingaben.

Entwicklung

npm install
npm run build
npm test

Das Projekt ist bewusst modular:

src/
  config.ts       Configuration loading and validation
  index.ts        Executable stdio MCP entry point
  logger.ts       Structured, redacted standard-error logging
  redaction.ts    Credential-detection and output redaction
  recovery.ts     Diagnostic, focus, stimulation, and plan logic
  server.ts       MCP server and tool registrations
  state.ts        Bounded, atomic JSON session storage
  types.ts        Shared contracts
tests/
  l-dopa.test.ts  End-to-end MCP and state behavior tests

Testabdeckung

Die automatisierte Suite verbindet einen echten MCP-Client und -Server über den In-Memory-Transport des SDKs. Sie deckt die Serverinitialisierung, die MCP-Tool-Erkennung, jedes Tool, die Zustandspersistenz, die begrenzte Aufbewahrung, Retry-Limits, unveränderte Retries, die Erkennung wiederholter Fehler und die Schwärzung von Zugangsdaten ab.

Führe sie aus mit:

npm test

Einschränkungen und Roadmap

L-Dopa v0.1 verwendet deterministische Heuristiken, erkennt daher häufige Fehlerklassen, ist aber kein allwissender Debugger. Es hat bewusst keinen Vektorspeicher, keine Fernpersistenz, keine Modell-Provider-Integration und keine Befehlsausführungsfähigkeit. Es untersucht nicht die verborgene Gedankenkette eines Agenten; es arbeitet nur mit bereitgestelltem operativem Kontext.

Zukünftige Erweiterungen sollten diese Grenzen wahren: Füge ein Tool nur hinzu, wenn es einen klaren Recovery-Nutzen bietet, halte die Befehlsausführung in einer separaten, berechtigungsgesteuerten Komponente und halte den Zustand begrenzt und einsehbar.

Lizenz

MIT