Dokumentation

MCP Fusion/Get started/Produktionsmuster

Produktionsmuster

Frag die KI über Vinkius

Acht Produktionsfehler und der MCP-Fusion-Mechanismus, der jeden behebt: Teilverarbeitung, halluzinierte Parameter, Herdenlast, Kontextüberlauf, veraltete Daten, blinde Wiederholungen, Datenlecks und Schreibkonflikte.

Die stärksten Funktionen des Frameworks lassen sich als Fehlermuster leichter merken. Jede folgende Zeile beschreibt eine echte Klasse von Produktionsvorfällen und einen konkreten Mechanismus, kein Schlagwort.

Teilfehler in einer mehrstufigen Operation

Failure: Schritt eins gelingt, Schritt zwei schlägt fehl und der Agent weiß nicht, welcher Seiteneffekt bereits eingetreten ist.

Mechanism: Fassen Sie den Workflow zu einer Aktion mit einem ausdrücklichen Kompensationspfad zusammen. Geben Sie f.error() mit verfügbaren Wiederherstellungsaktionen zurück. Lassen Sie einen Agenten nicht raten, ob ein erneuter Versuch sicher ist. Eine Transaktion oder Idempotenzschlüssel gehört in Handler und Datenbank.

Halluzinierte Parameter

Failure: Das Modell erfindet tenantId, emailAddress oder ein anderes plausibles Feld.

Mechanism: Jedes Aktionsschema ist strikt. Unbekannte Schlüssel werden vor Middleware und Handler mit <validation_error> abgelehnt, das Gesendetes und Erwartetes erklärt. Die Tenant-Identität muss aus ctx kommen, niemals aus der Tool-Eingabe.

Anfragesturm

Failure: Viele Agenten wiederholen denselben langsamen Upstream, bis Ihr Connector seine Ressourcen erschöpft.

Mechanism: .concurrency({ maxActive, maxQueue }) begrenzt aktive und wartende Arbeit. Volle Kapazität gibt SERVER_BUSY mit Wiederholungshinweisen zurück. Kombinieren Sie dies mit Upstream-Timeouts und einem Ratenbegrenzer nach Tenant oder Token.

Überlauf des Kontextfensters

Failure: Eine Collection-Antwort ist zu groß, das Modell verliert die wichtige Zeile und trifft eine falsche Entscheidung.

Mechanism: Presenter .agentLimit() kürzt vor der Serialisierung und stellt eine Zusammenfassung mit der Zahl verborgener Zeilen und einem Hinweis auf Filter voran. .enableSelect() erlaubt dem Modell, nur Felder der obersten Ebene anzufordern. Die Ausgabebyte-Sperre erkennt eine abschließende Textantwort, die zu groß ist.

Veraltete Daten nach einer Mutation

Failure: Nach einer erfolgreichen Schreiboperation sieht der Agent in seinem eigenen Kontext eine alte Lesung.

Mechanism: Markieren Sie Lesevorgänge mit .cached() oder .stale() und Schreibvorgänge mit .invalidates('domain.pattern'). Die State-Sync-Schicht versieht Beschreibungen mit Zusatzinformationen, gibt im ersten Block einen Invalidierungsmarker aus und veröffentlicht Ressourcenupdates erst nach einer erfolgreichen Mutation.

Blinde Wiederholungsschleifen

Failure: Ein Modell wiederholt denselben ungültigen Aufruf, weil der Fehler nur „fehlgeschlagen“ sagt.

Mechanism: toolError(code, { suggestion, availableActions, retryAfter }) gibt einen strukturierten XML-Wiederherstellungsvertrag aus. Die nächste Aktion ist benannt, die Verzögerung ist ausdrücklich und der typisierte Client kann sie als MCPFusionClientError analysieren.

Datenleck zum Modell

Failure: Ein Handler gibt eine Datenbankzeile mit einem Feld zurück, das das Modell niemals sehen sollte.

Mechanism: Hängen Sie einen Presenter mit Allowlist-Schema und .redactPII() an. Nicht deklarierte Felder gelangen nie in die validierte Ausgabe. Die Schwärzung maskiert deklarierte sensible Pfade in der geklonten Kopie auf der Leitung. Testen Sie result.data mit @mcpfusion/testing.

Konflikte bei destruktiven Operationen

Failure: Zwei Agenten veranlassen gleichzeitig eine Erstattung, wechseln einen Workflow-Zustand oder aktualisieren denselben Datensatz.

Mechanism: f.mutation() markiert die Aktion standardmäßig als destruktiv und der Builder erstellt einen aktionsbezogenen FIFO-Mutationsserializer. Ergänzen Sie Idempotenz auch in der Domänenschicht: Serialisierung ordnet Aufrufe, macht aber keine externe Zahlungs-API idempotent.

Operative Checkliste

Vor Deploy:

  • strikte Eingaben und Tenant-Identität aus dem Kontext
  • Presenter für jedes Tool, das Domänendaten zurückgibt
  • Limits für jede Collection
  • Nebenläufigkeits- und Ratenlimits für Upstream-Aufrufe
  • Invalidierung bei Schreibvorgängen
  • Wiederherstellungsfelder für erwartete Fehler
  • Lockfile und Tests in CI
  • Telemetrie und ein Audit-Sink, der niemals rohe Geheimnisse speichert

Nächste Schritte