Documentation

MCP Fusion/Security and governance/Contrats et lockfile

Contrats et lockfile

Demandez à l’IA à propos de Vinkius

Le contrat comportemental d’un connecteur : digests SHA-256 canoniques de la surface, mcpfusion.lock, verdicts de diff de contrats dans la CI, habilitations de rayon d’impact et attestation HMAC.

Un connecteur d’IA est une API publique dont le consommateur est un modèle de langage. Les descriptions, les champs requis et les formes d’erreur sont un comportement. MCP Fusion transforme ce comportement en contrat matérialisé, le hache, le compare et le verrouille, afin qu’un changement soit un événement révisable plutôt qu’une dérive silencieuse. La Gouvernance est le workflow ; cette page en décrit la mécanique.

Matérialiser le contrat

Pour chaque tool, le framework compile un ToolContract en quatre sections :

SectionContenu
surfacedescription, actions, digest du schéma d’entrée
behaviordigest du schéma de sortie, empreinte des règles système, actions destructives et en lecture seule, chaîne de middleware, topologie des affordances, garde-fous cognitifs
token economicsrisque d’inflation, nombre de champs du schéma, indicateur de collection sans limite
entitlementssystème de fichiers, réseau, sous-processus, cryptographie, évaluation de code

Les habilitations ne sont pas déclarées par vous. EntitlementScanner lit le code source du handler, son texte de fonction, et détecte les capacités avec des familles de regex : fs.* et appels de flux, fetch et clients HTTP, child_process et workers, signature et chiffrements cryptographiques, et évaluation de code. Les heuristiques d’évasion détectent les cas intéressants : (0, eval), accès global calculé, require non littéral, reconstruction avec String.fromCharCode, blobs base64, densité de séquences d’échappement supérieure à environ 15 % et forte entropie de Shannon dans les littéraux longs. Une action en lecture seule qui écrit des fichiers ou crée un processus est une violation, pas un avertissement.

Le lockfile

bash
mcpfusion lock
mcpfusion lock --check

Chaque section est canonisée en JSON à clés triées et hachée avec SHA-256. Les quatre hashes de section composent un digest par tool, puis les digests triés par tool composent le digest du serveur. Le résultat est 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 }
      }
    }
  }
}

La sérialisation est déterministe, avec des clés triées, une indentation de deux espaces et un saut de ligne final, le fichier est donc diffable en revue. --check recalcule et se termine avec un code non nul dès qu’une dérive existe : ce code de sortie est le gate de la CI.

Diffing : quel était ce changement

diffContracts(before, after) classe chaque différence et cette classification constitue la politique de revue :

VerdictExemples des règles
BREAKINGtool renommé, digest du schéma d’entrée modifié, action supprimée, indicateur destructif ou lecture seule modifié, nouveau champ requis, Presenter supprimé, digest de sortie modifié, règles système modifiées, risque d’inflation accru, habilitation ajoutée au handler
RISKYindicateur d’idempotence modifié, schéma par action modifié, Presenter remplacé, garde-fou supprimé, chaîne de middleware modifiée, empreinte de synchronisation d’état ou de concurrence modifiée, presenters intégrés modifiés, collection devenue illimitée
SAFEaction ajoutée, champ requis supprimé, tags supprimés, garde-fou renforcé, risque d’inflation réduit, collection limitée, habilitation perdue
COSMETICdescription modifiée, tags ajoutés

Une habilitation perdue est SAFE, car le rayon d’impact diminue. Une habilitation ajoutée est BREAKING, car un réviseur doit la voir. Cette asymétrie est délibérée.

Attestation

Le hashing prouve que deux artefacts diffèrent ; l’attestation prouve que celui qui s’exécute est celui que vous avez approuvé. attestServerDigest(digest, { signer: 'hmac', secret }) signe le digest du serveur avec HMAC-SHA256, les secrets de moins de 32 caractères étant refusés en production, puis au démarrage le serveur recalcule son digest et le compare : en cas d’écart, il refuse de démarrer avec AttestationError. Les signataires sont extensibles vers un KMS ou un journal de transparence, et la comparaison est à temps constant. La capacité de confiance est aussi exposée aux clients sous mcpfusionTrust.

Probes sémantiques

Les descriptions sont aussi un comportement, et leur dérive est invisible dans les différences structurelles. Une probe sémantique rejoue des entrées connues, envoie les sorties de référence et actuelles à un judge avec le contrat du tool et évalue la similarité : 0,95 ou plus signifie aucune dérive, 0,75 une dérive faible, 0,5 moyenne, et moins une dérive élevée. Les probes échouées se dégradent vers un score moyen neutre au lieu de bloquer, et le module n’appelle jamais le réseau seul : vous injectez l’adaptateur du judge.

Auto-réparation dans le chemin d’erreur

Lorsqu’un contrat change sous un agent en cours d’exécution, l’échec n’est pas mystérieux : avec selfHealing, les erreurs de validation intègrent un bloc <contract_awareness> portant les différences BREAKING et RISKY de l’action en échec, limité à cinq par défaut, ainsi que l’instruction de s’adapter. L’agent apprend le nouveau contrat au même tour que celui où il a violé l’ancien. Consultez les Erreurs.

Étapes suivantes