Covenant

StudioMeyer MCP Stack の一部 — マヨルカ島で開発 🌴 · 使用したら ⭐ を付けてください

mcp-covenant

Model Context Protocol サーバーの契約と破壊的変更を検出します — MCP インターフェースにセマンティックバージョニングを。

型付きライブラリを公開する場合、公開 API があり、それを壊すとツールが警告してくれます。MCP サーバーにはどちらもありません。あるのは、その時点で tools/list が返すものを提供することだけです。ツール名の変更、必須引数の追加、列挙型の選択肢の制限などを行うと、サーバーを基盤に構築されたすべてのエージェントが壊れます。それに気付ける仕組みは、パイプラインにありません。

mcp-covenant は、サーバーのインターフェースをスナップショットとしてコミット済みのロックファイルに保存する単一の静的バイナリです。既存のクライアントを壊す変更があると CI を失敗させ、人間のように破壊的変更／マイナー変更／パッチ変更に分類します。

$ mcp-covenant check --baseline mcp-covenant.lock -- node dist/server.js
mcp-covenant: 3 change(s) — required version bump: MAJOR

  BREAKING (2)
    x tool:legacy — tool was removed  [tool.removed]
    x tool:search → inputSchema.properties.limit — new required property  [schema.property.required.added]
  MINOR (1)
    + tool:newtool — new tool  [tool.added]
# exit code 1 → the job fails

---

Rust 製を選ぶ理由

このアイデア自体は新しくありません。MCP 向けのスキーマドリフト／契約ツールはすでにいくつかあり、いずれも Node、Python、JVM 上で動作します。mcp-covenant の特長は、単一の静的バイナリであることです。npm install も、Python の仮想環境も、CI イメージ内の JVM も必要ありません。Go や Rust を使うチームでも、素の Alpine コンテナでも、あらゆるパイプラインに組み込めます。MCP とは stdio または Streamable HTTP で通信します。

また、方向性を考慮している点も特長です。ほとんどのドリフト検出ツールが誤るのは、この部分です（以下を参照）。

mcp-armor（ランタイム防御）および mcp-gauntlet（デプロイ前のファジングと 負荷テスト）と併用できます。mcp-covenant は インターフェース安定性を担います。mcp-herald（仕様の移行）と mcp-passport（レジストリへの公開ゲート）がスタックを完成させます。

---

インストール

cargo install mcp-covenant

または、ソースからビルドします。

git clone https://github.com/studiomeyer-io/mcp-covenant
cd mcp-covenant && cargo build --release
# binary at ./target/release/mcp-covenant

より軽量な stdio 専用ビルド（HTTP トランスポートなし、依存関係を削減）：

cargo install mcp-covenant --no-default-features

---

3 つのコマンドで使う

1. スナップショット — 現在のインターフェースをベースラインとして保存し、git にコミットします。

mcp-covenant snapshot -o mcp-covenant.lock -- node dist/server.js
# or against a running HTTP server:
mcp-covenant snapshot -o mcp-covenant.lock --http https://my-server.example/mcp

2. チェック — CI で実行し、破壊的変更があればゼロ以外の終了コードを返します。

mcp-covenant check --fail-on breaking -- node dist/server.js

3. リント — スキーマの衛生状態をチェックします（ツール選択にひそかに悪影響を与える要素を検出します）。

$ mcp-covenant lint -- node dist/server.js
mcp-covenant lint: 2 finding(s) (0 error, 1 warning, 1 info)

  WARNING (1)
    tool:newtool — tool has no description; the model cannot tell when to call it  [tool.missing_description]
  INFO (1)
    tool:search → limit — parameter has no description  [tool.param.missing_description]

ロックファイルを 2 つ使えば、サーバーなしで完全にオフラインでも実行できます。

mcp-covenant check --baseline v1.lock --against v2.lock
mcp-covenant lint   --from v1.lock

---

変更の分類方法

興味深い点は、ツールの inputSchema は呼び出し元が 送信する ものであり、outputSchema は呼び出し元が 受信する ものだということです。同じ構造上の変更でも方向によって 影響範囲は逆になり、mcp-covenant はその両方をモデル化します。

変更	入力（呼び出し元が送信）	出力（呼び出し元が受信）
ツール／リソース／プロンプトの削除	破壊的変更	—
新しいツール／リソース／プロンプト	マイナー	—
新しい必須フィールド	破壊的変更	マイナー（保証が強化される）
新しい任意フィールド	マイナー	マイナー
フィールドの削除	必須の場合は破壊的変更、そうでなければマイナー	破壊的変更（フィールドがなくなる）
任意 → 必須	破壊的変更	マイナー
必須 → 任意	マイナー	破壊的変更（存在しない場合がある）
型の範囲を狭める（例：["string","number"] → string）	破壊的変更	マイナー
列挙値の追加	マイナー（より多くの値を受け入れる）	破壊的変更（未知の値）
列挙値の削除	破壊的変更（値を拒否する）	マイナー
配列への items スキーマの追加	破壊的変更（要素が制約される）	マイナー
配列からの items スキーマの削除	マイナー	破壊的変更（要素が制約されなくなる）
additionalProperties: true → false	破壊的変更	—
説明／タイトルの変更	パッチ	パッチ

ネストされたオブジェクトのプロパティと配列の items は再帰的に差分比較されます。一方の側にないキーワードは空として比較されます。properties のないスキーマはフィールドを宣言せず、required はスキーマで宣言されていないフィールドも対象にします。全体の結果は、検出された変更のうち最も重大なものとなり、ユーザーに対して適用すべき semver の変更に対応します。

---

CI

GitHub Action

# .github/workflows/mcp-contract.yml
name: MCP contract
on: [pull_request]
jobs:
  contract:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - uses: studiomeyer-io/[email protected]
        with:
          command: "node dist/server.js"   # or: http: https://my-server/mcp
          baseline: mcp-covenant.lock
          fail-on: breaking

生の出力、任意の CI

mcp-covenant check --fail-on breaking -- node dist/server.js

SARIF → GitHub コードスキャン

mcp-covenant check --format sarif -- node dist/server.js > covenant.sarif
# then upload with github/codeql-action/upload-sarif

検出結果は PR 上にインラインで表示され、mcp-covenant.lock に紐付けられます。

---

ロックファイル

mcp-covenant.lock は、整形済みで決定論的に並べられた通常の JSON です。ほかのロックファイルと同様に、コミットしてレビューしてください。インターフェースに変更がない状態で再生成するとバイト単位で一致するため、ノイズのような差分こそが変更の兆候です。

{
  "covenant_version": "0.1.1",
  "captured_at_unix": 1750000000,
  "server": { "name": "demo", "version": "1.0.0", "protocolVersion": "2025-11-25" },
  "surface": {
    "tools": [ { "name": "search", "description": "Search the catalog.", "inputSchema": { … } } ],
    "resources": [],
    "prompts": []
  }
}

---

対象範囲

mcp-covenant は読み取り専用です。initialize ハンドシェイクを行い、tools/list、 resources/list、prompts/list を呼び出しますが、ツールは呼び出しません。MCP ツールが実際に使用する JSON Schema の範囲（type、enum、properties、required、items、additionalProperties）をモデル化しており、仕様全体を対象とするものではありません。分類ルールと追加方法については、CONTRIBUTING.md を参照してください。

ライセンス

MIT © StudioMeyer