Dokumentation

MCP Fusion/Security and governance/Verträge und Lockfile

Verträge und Lockfile

Frag die KI über Vinkius

Der Verhaltensvertrag eines Connectors: kanonische SHA-256-Oberflächen-Digests, mcpfusion.lock, Vertrags-Diff-Urteile in CI, Berechtigungen für den Wirkungsradius und HMAC-Attestierung.

Ein KI-Connector ist eine öffentliche API, deren Verbraucher ein Sprachmodell ist. Beschreibungen, Pflichtfelder und Fehlerformen sind Verhalten. MCP Fusion macht dieses Verhalten zu einem materialisierten Vertrag, hasht, vergleicht und sperrt ihn, sodass eine Änderung ein prüfbares Ereignis statt stiller Abweichung ist. Governance ist der Workflow, diese Seite beschreibt die Mechanik.

Den Vertrag materialisieren

Für jedes Tool kompiliert das Framework einen ToolContract mit vier Abschnitten:

AbschnittInhalt
surfaceBeschreibung, Aktionen, Digest des Eingabeschemas
behaviorDigest des Ausgabeschemas, Fingerprint der Systemregeln, destruktive und schreibgeschützte Aktionen, Middleware-Kette, Affordance-Topologie, kognitive Guardrails
token economicsInflationsrisiko, Anzahl der Schemafelder, Kennzeichen für unbegrenzte Collection
entitlementsDateisystem, Netzwerk, Subprozess, Kryptografie, Codeauswertung

Berechtigungen werden nicht von Ihnen deklariert. EntitlementScanner liest den Handler-Quelltext, also den Funktionstext, und erkennt Fähigkeiten mit Regex-Familien: fs.* und Stream-Aufrufe, fetch und HTTP-Clients, child_process und Worker, kryptografische Signaturen und Chiffren sowie Codeauswertung. Umgehungsheuristiken erfassen die interessanten Fälle: (0, eval), berechneten globalen Zugriff, nicht-literal verwendetes require, Rekonstruktion mit String.fromCharCode, Base64-Blobs, eine Escape-Sequenz-Dichte von ungefähr mehr als 15 % und hohe Shannon-Entropie in langen Literalen. Eine schreibgeschützte Aktion, die Dateien schreibt oder einen Prozess startet, ist ein Verstoß, keine Warnung.

Die Lockdatei

bash
mcpfusion lock
mcpfusion lock --check

Jeder Abschnitt wird als JSON mit sortierten Schlüsseln kanonisiert und mit SHA-256 gehasht. Die vier Abschnitts-Hashes bilden einen Digest pro Tool, und die sortierten Tool-Digests bilden den Server-Digest. Das Ergebnis ist mcpfusion.lock:

json
{
  "lockfileVersion": 1,
  "serverName": "billing",
  "mcpfusionVersion": "...",
  "generatedAt": "...",
  "integrityDigest": "sha256:...",
  "capabilities": {
    "tools": {
      "billing": {
        "integrityDigest": "sha256:...",
        "surface": { "description": "...", "actions": [], "inputSchemaDigest": "..." },
        "behavior": { "egressSchemaDigest": "...", "systemRulesFingerprint": "...", "middlewareChain": [], "affordanceTopology": [] },
        "tokenEconomics": { "inflationRisk": "low", "schemaFieldCount": 8, "unboundedCollection": false },
        "entitlements": { "filesystem": false, "network": true, "subprocess": false, "crypto": false, "codeEvaluation": false }
      }
    }
  }
}

Die Serialisierung ist deterministisch, mit sortierten Schlüsseln, zwei Leerzeichen Einrückung und abschließendem Newline, daher kann die Datei in Reviews verglichen werden. --check berechnet neu und beendet sich mit einem Status ungleich null, sobald etwas abweicht: Dieser Exit-Code ist das CI-Gate.

Diffing: Welche Art von Änderung war das

diffContracts(before, after) klassifiziert jede Abweichung, und die Klassifikation ist die Review-Richtlinie:

UrteilBeispiele aus den Regeln
BREAKINGTool umbenannt, Eingabeschema-Digest geändert, Aktion entfernt, destruktives oder schreibgeschütztes Flag geändert, neues Pflichtfeld, Presenter entfernt, Ausgabe-Digest geändert, Systemregeln geändert, Inflationsrisiko erhöht, Handler erhielt eine Berechtigung
RISKYIdempotenz-Flag geändert, Schema pro Aktion geändert, Presenter ersetzt, Guardrail entfernt, Middleware-Kette geändert, Fingerprint für Zustandssynchronisierung oder Nebenläufigkeit geändert, eingebettete Presenter geändert, Collection wurde unbegrenzt
SAFEAktion hinzugefügt, Pflichtfeld entfernt, Tags entfernt, Guardrail verschärft, Inflationsrisiko reduziert, Collection begrenzt, Berechtigung verloren
COSMETICBeschreibung geändert, Tags hinzugefügt

Eine verlorene Berechtigung ist SAFE, weil der Wirkungsradius kleiner wurde. Eine hinzugefügte Berechtigung ist BREAKING, weil ein Reviewer sie sehen muss. Diese Asymmetrie ist beabsichtigt.

Attestierung

Hashing beweist, dass zwei Artefakte verschieden sind. Attestierung beweist, dass das laufende Artefakt dem genehmigten entspricht. attestServerDigest(digest, { signer: 'hmac', secret }) signiert den Server-Digest mit HMAC-SHA256, wobei Geheimnisse unter 32 Zeichen in Produktion abgelehnt werden. Beim Start berechnet der Server seinen Digest neu und vergleicht ihn: Bei einer Abweichung verweigert er den Start mit AttestationError. Signer können für ein KMS oder einen Transparenz-Log ausgetauscht werden, und der Vergleich erfolgt in konstanter Zeit. Die Vertrauensfähigkeit wird Clients außerdem als mcpfusionTrust bereitgestellt.

Semantische Probes

Beschreibungen sind ebenfalls Verhalten, und Beschreibungsdrift ist in strukturellen Diffs unsichtbar. Eine semantische Probe spielt bekannte Eingaben erneut ab, sendet Basis- und aktuelle Ausgaben mit dem Tool-Vertrag an einen Judge und bewertet die Ähnlichkeit: mindestens 0,95 bedeutet keine Abweichung, 0,75 niedrig, 0,5 mittel und darunter hoch. Fehlgeschlagene Probes fallen auf einen neutralen mittleren Wert zurück, statt zu blockieren, und das Modul ruft nie selbst das Netzwerk auf: Sie injizieren den Judge-Adapter.

Selbstheilung im Fehlerpfad

Wenn sich ein Vertrag unter einem laufenden Agenten ändert, ist der Fehler kein Rätsel: Mit konfiguriertem selfHealing enthalten Validierungsfehler einen <contract_awareness>-Block mit den BREAKING- und RISKY-Abweichungen der fehlschlagenden Aktion, standardmäßig auf fünf begrenzt, sowie die Anweisung zur Anpassung. Der Agent lernt den neuen Vertrag in demselben Turn, in dem er den alten verletzt hat. Siehe Fehler.

Nächste Schritte