Documentación

MCP Fusion/Security and governance/Contratos y lockfile

Contratos y lockfile

Pregunta a la IA sobre Vinkius

El contrato de comportamiento de un conector: digests SHA-256 canónicos de la superficie, mcpfusion.lock, veredictos de diferencias de contratos en CI, permisos de radio de impacto y atestación HMAC.

Un conector de IA es una API pública cuyo consumidor es un modelo de lenguaje. Las descripciones, los campos obligatorios y las formas de error son comportamiento. MCP Fusion convierte ese comportamiento en un contrato materializado, le calcula un hash, lo compara y lo bloquea, para que un cambio sea un evento revisable y no una desviación silenciosa. Gobernanza es el flujo; esta página es la maquinaria.

Materializar el contrato

Para cada tool el framework compila un ToolContract con cuatro secciones:

SecciónContenido
surfacedescripción, acciones, digest del esquema de entrada
behaviordigest del esquema de salida, fingerprint de reglas del sistema, acciones destructivas y de solo lectura, cadena de middleware, topología de affordances, guardrails cognitivos
token economicsriesgo de inflación, cantidad de campos del esquema, indicador de colección sin límite
entitlementssistema de archivos, red, subproceso, criptografía, evaluación de código

Los permisos no los declaras tú. EntitlementScanner lee el código fuente del handler, su texto de función, y detecta capacidades con familias de regex: fs.* y llamadas de stream, fetch y clientes HTTP, child_process y workers, firma y cifrado criptográficos y evaluación de código. Las heurísticas de evasión detectan casos interesantes: (0, eval), acceso global calculado, require no literal, reconstrucción con String.fromCharCode, blobs base64, densidad de secuencias de escape superior a aproximadamente 15% y alta entropía de Shannon en literales largos. Una acción de solo lectura que escribe archivos o inicia un proceso es una infracción, no una advertencia.

El lockfile

bash
mcpfusion lock
mcpfusion lock --check

Cada sección se canonicaliza como JSON con claves ordenadas y recibe un hash SHA-256. Los cuatro hashes de sección forman un digest por tool, y los digests ordenados por tool forman el digest del servidor. El resultado es 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 serialización es determinista, con claves ordenadas, sangría de dos espacios y salto de línea final, así que el archivo se puede revisar mediante diferencias. --check recalcula y termina con un código distinto de cero cuando algo ha cambiado: ese código de salida es el gate de CI.

Diffing: qué tipo de cambio fue

diffContracts(before, after) clasifica cada diferencia, y la clasificación es la política de revisión:

VeredictoEjemplos de las reglas
BREAKINGtool renombrada, digest del esquema de entrada cambiado, acción eliminada, flag destructiva o de solo lectura cambiada, campo obligatorio nuevo, Presenter eliminado, digest de salida cambiado, reglas del sistema cambiadas, riesgo de inflación elevado, el handler obtuvo un permiso
RISKYflag de idempotencia cambiada, esquema por acción cambiado, Presenter sustituido, guardrail eliminado, cadena de middleware cambiada, fingerprint de sincronización de estado o concurrencia cambiado, presenters integrados cambiados, una colección pasó a no tener límite
SAFEacción añadida, campo obligatorio eliminado, tags eliminados, guardrail endurecido, riesgo de inflación reducido, colección limitada, permiso perdido
COSMETICdescripción cambiada, tags añadidos

Un permiso perdido es SAFE porque el radio de impacto se redujo. Un permiso añadido es BREAKING porque un revisor debe verlo. Esa asimetría es deliberada.

Attestation

El hashing demuestra que dos artefactos difieren; la atestación demuestra que el que se está ejecutando es el que aprobaste. attestServerDigest(digest, { signer: 'hmac', secret }) firma el digest del servidor con HMAC-SHA256, rechazando en producción secretos de menos de 32 caracteres, y al iniciar el servidor recalcula su digest y lo compara: si no coincide, se niega a arrancar con AttestationError. Los firmantes pueden conectarse a un KMS o a un registro de transparencia, y la comparación usa tiempo constante. La capacidad de confianza también se expone a los clientes como mcpfusionTrust.

Probes semánticos

Las descripciones también son comportamiento, y su desviación es invisible para las diferencias estructurales. Una probe semántica repite entradas conocidas, envía las salidas baseline y actual a un judge con el contrato de la tool y puntúa la similitud: 0,95 o más significa que no hay desviación, 0,75 es baja, 0,5 es media y por debajo es alta. Las probes fallidas bajan a una puntuación media neutral en vez de bloquear, y el módulo nunca llama a la red por su cuenta: inyectas el adaptador del judge.

Autocorrección en la ruta de error

Cuando cambia un contrato bajo un agente en ejecución, el fallo no es un misterio: con selfHealing configurado, los errores de validación incorporan un bloque <contract_awareness> con las diferencias BREAKING y RISKY de la acción fallida, limitado a cinco por defecto, además de la instrucción de adaptarse. El agente aprende el nuevo contrato en el mismo turno en que infringió el anterior. Consulta Errores.

Siguientes pasos