ドキュメント

MCP Fusion/Security and governance/コントラクトとロックファイル

コントラクトとロックファイル

VinkiusについてAIに質問

コネクターの動作コントラクトを扱います。正規化された SHA-256 サーフェスダイジェスト、mcpfusion.lock、CI でのコントラクト差分判定、影響範囲の権限、HMAC アテステーションを説明します。

AI コネクターは、言語モデルが利用者となる公開 API です。説明、必須フィールド、エラー形式は動作の一部です。MCP Fusion はその動作を具象化したコントラクトに変換し、ハッシュ化、差分比較、ロックを行います。変更が静かなドリフトではなくレビュー可能なイベントになります。ガバナンス がワークフローで、このページが仕組みです。

コントラクトの具象化

フレームワークは各ツールについて、4 つのセクションを持つ ToolContract をコンパイルします。

セクション内容
surface説明、アクション、入力スキーマダイジェスト
behavior出力スキーマダイジェスト、システムルールのフィンガープリント、破壊的および読み取り専用アクション、ミドルウェアチェーン、アフォーダンストポロジー、認知ガードレール
token economics膨張リスク、スキーマフィールド数、無制限コレクションフラグ
entitlementsファイルシステム、ネットワーク、サブプロセス、暗号、コード評価

権限を自分で宣言する必要はありません。EntitlementScanner がハンドラーのソース、つまり関数テキストを読み、正規表現ファミリーで能力を検出します。対象は fs.* とストリーム呼び出し、fetch と HTTP クライアント、child_process とワーカー、暗号署名と暗号方式、コード評価です。回避ヒューリスティックは (0, eval)、計算されたグローバルアクセス、リテラルでない require、String.fromCharCode による再構築、Base64 ブロブ、約 15% を超えるエスケープシーケンス密度、長いリテラルの高いシャノンエントロピーを検出します。読み取り専用アクションがファイルを書き込んだりプロセスを起動したりする場合、それは警告ではなく違反です。

ロックファイル

bash
mcpfusion lock
mcpfusion lock --check

各セクションはキーをソートした JSON として正規化され、SHA-256 でハッシュ化されます。4 つのセクションハッシュからツールごとのダイジェストを作り、ソートしたツールダイジェストからサーバーダイジェストを作ります。結果が 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 }
      }
    }
  }
}

シリアライズは決定的です。キーをソートし、2 スペースでインデントし、末尾に改行を付けるため、レビューで差分を確認できます。--check は再計算し、ずれがあるとゼロ以外で終了します。この終了コードが CI ゲートです。

差分比較: どの種類の変更か

diffContracts(before, after) はすべての差分を分類し、その分類がレビュー方針になります。

判定ルールの例
BREAKINGツール名変更、入力スキーマダイジェスト変更、アクション削除、破壊的または読み取り専用フラグ変更、新しい必須フィールド、Presenter 削除、出力ダイジェスト変更、システムルール変更、膨張リスク上昇、ハンドラーへの権限追加
RISKY冪等性フラグ変更、アクション別スキーマ変更、Presenter 交換、ガードレール削除、ミドルウェアチェーン変更、状態同期または並行性フィンガープリント変更、組み込み Presenter 変更、コレクションの無制限化
SAFEアクション追加、必須フィールド削除、タグ削除、ガードレール強化、膨張リスク低下、コレクションの制限、権限の喪失
COSMETIC説明変更、タグ追加

失われた権限が SAFE なのは、影響範囲が縮小するためです。追加された権限が BREAKING なのは、レビュアーが確認する必要があるためです。この非対称性は意図的です。

アテステーション

ハッシュ化は 2 つの成果物が異なることを証明します。アテステーションは、実行中のものが承認したものだと証明します。attestServerDigest(digest, { signer: 'hmac', secret }) は HMAC-SHA256 でサーバーダイジェストに署名します。本番では 32 文字未満のシークレットは拒否され、起動時にサーバーがダイジェストを再計算して比較します。不一致の場合は AttestationError とともに起動を拒否します。署名者は KMS や透明性ログ向けに差し替え可能で、比較は定時間で行われます。信頼機能は mcpfusionTrust としてクライアントにも公開されます。

セマンティックプローブ

説明も動作の一部であり、説明のドリフトは構造的な差分には現れません。セマンティックプローブは既知の正常な入力を再生し、ベースラインと現在の出力をツールのコントラクトとともに judge に送り、類似度を採点します。0.95 以上はドリフトなし、0.75 は低、0.5 は中、それ未満は高です。失敗したプローブはブロックせず、中立的な中スコアに低下します。モジュールが独自にネットワークを呼び出すことはなく、judge アダプターを注入します。

エラーパスでの自己修復

実行中のエージェントでコントラクトが変わっても、失敗は謎ではありません。selfHealing を設定すると、バリデーションエラーに失敗したアクションの BREAKING と RISKY の差分を含む <contract_awareness> ブロックが埋め込まれます。デフォルトでは 5 件に制限され、適応する指示も含まれます。エージェントは古いコントラクトに違反した同じターンに、新しいコントラクトを学習します。エラーをご覧ください。

次のステップ