k11 API Contract QA

k11 API コントラクト QA — MCP サーバーと Claude Code プラグイン

API の変更をマージする前に、どのサービスに影響するのか、その理由とともに把握できます。REST、GraphQL、gRPC、イベント、SOAP に対応しています。

プルリクエストでフィールド名を変更したり、リクエストボディの制約を厳しくしたりしても、その変更自体のテストは通ります。しかし、本番環境ではほかの 3 つのサービスが壊れます。仕様差分ツールは、変更が「破壊的」かどうかは示せても、どのサービスが影響を受けるかは示せません。そのため、チームは警告を無視するか、すべての変更をブロックすることになります。この MCP サーバーは、本当に知りたいことに答えます。

• OpenAPI 3.x、Swagger 2.0、GraphQL、gRPC/protobuf、AsyncAPI 2.x/3.x、SOAP/WSDL 1.1 に対応した破壊的変更の検出。$ref、ネストされたフィールド、配列項目も対象とし、各変更でどのルールに違反したかを示します。
• コンシューマーを考慮した影響分析。 どのサービスがどのエンドポイントを呼び出し、どのフィールドを読み取る、または送信するかを把握します。削除されたフィールドは、それを使用するコンシューマーに対してのみ問題として扱われます。
• 根拠を示す判定： 破壊的、破壊的だが使用が判明しているコンシューマーなし、または互換性あり。2 つ以上のコンシューマーに影響する場合、または重要なコンシューマーに影響する場合は、マージ前に人が判断すべきだと通知します。
• デプロイ済みコントラクトとの乖離： 稼働中のサービスが公開する内容（GraphQL イントロスペクション、?wsdl、/v3/api-docs）と仕様ファイルを比較します。
• REST のライブ適合性チェック：ステータスコード、コンテンツタイプ、スキーマに照らして検証した JSON ボディを確認します。
• コンシューマーの検出：コンシューマーのソースコード（Python、Java、TypeScript、Go など）をスキャンし、API の呼び出しをファイル名と行番号とともに特定します。GraphQL では、コンシューマーが実際に使用するクエリを解析するため、読み取るフィールドを正確に把握できます。
• pytest + httpx または Java REST Assured 向けのコントラクトテスト生成。
• contract-ci：影響を受けるすべてのコンシューマーとその理由を一覧表示する、プルリクエストへのコメント。

決定的なルールに基づいており、LLM の呼び出しはありません。実行のたびに同じ結果が得られます。Claude Code（/check-api-change と /api-contract-tests を備えたプラグインとして）、Claude Desktop、およびあらゆる MCP クライアントで動作します。公式の MCP Registry に io.github.K11-Software-Solutions/api-contract-qa として登録されています。

---

プルリクエストで確認する

デモでは、Order Service v2 が total を数値から文字列に変更し、customer.email を削除し、POST /orders に必須の channel を追加して、DELETE /orders/{id} を削除します。4 つのサービスがこの API を利用しています。contract-ci は次のコメントを投稿しました。

API コントラクトチェック：🔴 既知のコンシューマーに対して破壊的

Order Service：main → この PR。11 件の変更、うち 6 件が破壊的（最も深刻なもの：重大）。既知のコンシューマーは 4 件、うち 3 件に影響。

マージ前に人による判断が必要： 3 件のコンシューマーに影響します（しきい値：2）。重要度の高いコンシューマーにも影響します：notification-svc、billing-svc、checkout-web。

コンシューマー	オーナー	重要度	破壊的変更	影響する理由
billing-svc	@team-billing	重大	GET /orders/{id}：レスポンスフィールド 'total' の型が数値から文字列に変更されました	'total' を読み取っています
checkout-web	@team-web	高	POST /orders：新たに必須のリクエストフィールド 'channel' が追加されました	必須になった 'channel' を送信していません
notification-svc	@team-notify	高	GET /orders/{id}：レスポンスフィールド 'customer.email' が削除されました	'customer.email' を読み取っています

破壊的だが、既知のコンシューマーなし： DELETE /orders/{orderId} が削除されました。また、POST /orders のレスポンスに関する変更が 2 件ありますが、checkout-web はそれらのフィールドを読み取りません。

analytics-svc も GET /orders を呼び出しますが、読み取るのは id と status のみなので、影響ありとは判定されません。

対応するコントラクト

ファイルから形式が自動検出されます。どの形式も、同じルール、コンシューマーへの影響、レポート、contract-ci に加えて、その形式固有のルールに従います。

形式	操作の名前	形式固有のルール	デプロイ済みの差分チェック
OpenAPI 3.x	GET /orders/{id}	パラメーター、リクエストボディ、成功レスポンス、認証	公開されたドキュメントに GET
Swagger 2.0	GET /api/orders/{id}	読み込み時に OpenAPI 3 に変換（body/formData、definitions、basePath）	公開されたドキュメントに GET
GraphQL（SDL または introspection JSON）	QUERY order、MUTATION createOrder	引数を 1 つでも 削除すると破壊的変更（未知の引数はエラー）；非 null → nullable はリーダーにとって破壊的変更	introspection クエリ
gRPC / protobuf（.proto、import を追跡）	RPC shop.v1.OrderService/GetOrder	フィールド番号の変更または再利用、フィールド名の変更（ワイヤー上は安全ですが、JSON と生成コードに影響します）、削除した番号が予約されていない、ストリーミングの変更、メッセージの置き換え	未対応（サーバーリフレクションが必要です）
AsyncAPI 2.x / 3.x	EMITS order.created、RECEIVES order.cancel	発行するメッセージにはリーダーのルールを適用し、受信するメッセージにはライターのルールを適用します	公開されたドキュメントに GET
SOAP / WSDL 1.1	SOAP OrderPort/GetOrder	XSD の minOccurs／maxOccurs／nillable、列挙型、拡張；SOAPAction とバインディングスタイル；未知の要素は厳密に扱います	GET ...?wsdl

コンシューマーの検出では、HTTP パス、GraphQL クエリドキュメント（読み取るフィールドを正確に検出）、gRPC スタブ呼び出し、SOAP クライアント呼び出し（zeep、JAX-WS、.NET）、AsyncAPI トピック名を見つけます。ライブレスポンスチェックとテスト生成は REST（OpenAPI と Swagger）に対応しています。

ツール

ツール	機能
list_operations	コントラクトの操作と、検出された形式を一覧表示します。
diff_contracts	コントラクトの 2 つのバージョン間の変更をすべて分類します：ルール、フィールドパス、変更前／変更後、重大度。
assess_impact	変更によって影響を受けるコンシューマーとその理由を示します。判定と、人による判断が必要かどうかも含みます。必要に応じてレポートを書き込みます。
discover_consumer_usage	コンシューマーのソースコードから API 呼び出しを見つけ、consumers.yaml のエントリー案を作成します。
check_deployed_contract	稼働中のサービスが公開する内容と仕様を比較し、matches、drift、incompatible のいずれかを返します。
check_live_conformance	稼働中の REST エンドポイントを呼び出し、レスポンスを仕様と照合します。ヘッダー値には ${ENV:NAME} を使用できます。
generate_api_tests	pytest + httpx または REST Assured 向けに、REST コントラクトテスト（ステータス + JSON スキーマ）を生成します。
write_test	tests/ または src/test/ の下にのみ生成ファイルを書き込みます。指示がない限り、既存ファイルを上書きしません。

仕様はプロジェクト内のファイルまたは git 参照です：origin/main:openapi.yaml、origin/main:proto/orders.proto（import は同じ参照から読み込まれます）。

コンシューマーを登録する

.qa-mcp/consumers.yaml：

consumers:
  - name: billing-svc
    repo: acme/billing-svc
    owner: "@team-billing"
    criticality: critical          # critical | high | medium | low
    uses:
      - endpoint: GET /orders/{id}
        reads: [id, total, currency]   # leave out to mean "any field"
  - name: checkout-web
    owner: "@team-web"
    criticality: high
    uses:
      - endpoint: POST /orders
        sends: [customerId, items]
        reads: [id]

エンドポイントには、上の表にある操作名（QUERY order、RPC shop.v1.OrderService/GetOrder、EMITS order.created、…）を使用します。フィールドの一覧を指定すると、判定がより正確になります。一覧がない場合、エンドポイントへの破壊的変更は、そのエンドポイントを呼び出すすべてのコンシューマーに影響するものとして扱われます。まず各コンシューマーのコードに対して discover_consumer_usage を実行し、その後フィールドを追加してください。

CI での使用

k11-api-contract-qa-mcp contract-ci --spec openapi.yaml --base origin/main

プルリクエスト内の仕様を origin/main と比較し、contract-report.md（PR コメント）と contract-report.json を書き込み、GitHub Actions の出力（verdict、breaking、consumers_affected、needs_human、report）を設定します。また、--fail-on に従ってゼロ以外の終了コードを返します：

--fail-on	失敗する条件
breaking（デフォルト）	既知のコンシューマーに破壊的変更がある
needs-human	2 つ以上のコンシューマー、または重要度が critical／high のコンシューマーに破壊的変更がある
any-breaking	使用されているかどうかにかかわらず、破壊的変更がある
never	レポートのみ

docs/contract-check.yml を .github/workflows/ にコピーすると、仕様に変更があったすべてのプルリクエストにコメントします。

インストール

Python 3.10 以降が必要です。

Claude Code：プラグイン（推奨）

uv が必要です：

/plugin marketplace add K11-Software-Solutions/k11techlab-api-contract-qa-mcp
/plugin install api-contract-qa@k11-api-contract-qa

Claude Code：MCP サーバーのみ

claude mcp add api-contract-qa -- uvx k11-api-contract-qa-mcp

Claude Desktop およびその他の MCP クライアント

{
  "mcpServers": {
    "api-contract-qa": {
      "command": "uvx",
      "args": ["k11-api-contract-qa-mcp"],
      "env": { "QA_MCP_ROOT": "/path/to/your/service" }
    }
  }
}

または pip install k11-api-contract-qa-mcp を実行します。

デモを試す

cd demo/order-service
k11-api-contract-qa-mcp contract-ci --spec openapi.yaml --base-spec openapi.v1.yaml
python server.py --port 8080    # v2 implementation with one deliberate contract bug

次に、Claude に GET /orders/{id} の id が 1001 の場合の check_live_conformance を依頼してください。total が引き続き数値として送信されていることが検出されます。

demo/formats/ には、その他の各形式（Swagger 2.0、GraphQL、インポートを含む protobuf、AsyncAPI 2.x → 3.x、WSDL）の v1 および v2 のコントラクトと、それぞれの小規模なコンシューマーが用意されています。例：

k11-api-contract-qa-mcp contract-ci --spec demo/formats/graphql/schema.graphql --base-spec demo/formats/graphql/schema.v1.graphql --fail-on never

ルール

これらは、各形式の入力と出力の名称で、すべての形式に適用されます：

ルール	破壊的変更？
エンドポイントが削除された	はい（重大）
レスポンスフィールドが削除された、型が変更された、nullable になった、または保証されなくなった	はい
成功レスポンスまたは JSON メディアタイプが削除された	はい
新たな必須リクエストフィールド／パラメーターが追加された、フィールドまたはパラメーターが必須になった	はい
リクエストの列挙値が削除された、リクエストフィールドが新たに列挙値に制限された	はい
新たな認証要件が追加された	はい（重大）
必須リクエストフィールドが削除された（GraphQL および SOAP では削除された入力はすべて該当）	はい
新しいエンドポイント、任意のフィールドまたはパラメーターが追加された、レスポンスの列挙値が追加された	いいえ（列挙値の追加は網羅的な switch を対象に警告）
パスパラメーターの名前が変更された、エンドポイントが非推奨になった	いいえ
protobuf：フィールド番号が変更された、メッセージが置き換えられた、ストリーミングが変更された	はい
protobuf：同じ番号のままフィールド名が変更された	はい（中程度：ワイヤー互換性はありますが、JSON と生成コードを破壊します）

このルールは、リポジトリ横断のコントラクトテストと変更影響分析に関する K11 の研究（IJECS、2026年）を拡張したものです。その参照システムは k11techlab-microservice-qa-system です。このサーバーでは、$ref、ネストされたフィールドと配列項目のルール、フィールドレベルのコンシューマー照合、および5種類の追加コントラクト形式に対応しています。

帰属表示とライセンス。 k11 API Contract QA は、新たに独立して実装されたものです。参照システムのコードではなく、その 設計（破壊的変更の分類、重大度レベル、および破損したコンシューマーが2つ以上ある場合は人が判断するというルール）を再利用しており、そのリポジトリへの依存関係はありません。参照システムは Apache-2.0 ライセンス、このプロジェクトは MIT ライセンスです。どちらも Kavita Jadhav / K11 Software Solutions LLC によるものです。

比較

	仕様差分ツール（例：oasdiff）	コンシューマー駆動型コントラクト（例：Pact）	k11 API Contract QA
影響を受ける対象がわかる	いいえ	はい	はい、フィールドレベルで
コンシューマーごとのセットアップ	不要	各コンシューマーでコントラクトテストが必要	YAML エントリー1つ。検出によって下書きを作成
理由を説明する	ルールのみ	失敗したインタラクション	ルール、フィールド、およびコンシューマーが読み取る内容や送信する内容
形式	通常は1種類	HTTP とメッセージ	OpenAPI、Swagger、GraphQL、gRPC、AsyncAPI、SOAP
AI エージェントで利用可能	いいえ	いいえ	はい、MCP 経由

安全性

• 仕様、コンシューマーフォルダー、レポートはプロジェクトフォルダー内にある必要があります。git の参照はシェルを使わず、git show で読み取ります。
• write_test は tests/ または src/test/ 内にのみ書き込み、確認なしに上書きすることはありません。
• ライブチェック用のトークンは環境変数（${ENV:NAME}）から読み取られ、出力されることはありません。

開発

python -m venv .venv && .venv/Scripts/pip install -e ".[dev]"   # bin/pip on macOS/Linux
pytest   # rules for all formats, consumer impact, discovery, drift, conformance, generated tests, contract-ci, MCP (38)

ロードマップ

• 推移的な影響（データを自身のコンシューマーに再公開するコンシューマー）
• サーバーリフレクションによるライブ gRPC チェック、WSDL 2.0、GraphQL フェデレーション
• 研究システムと同様に、「不確実」なケースに対する任意の LLM レビュー

---

K11 Software Solutions が開発しました。K11 Tech Lab のエージェント型 QA シリーズの一部であり、Playwright QA、Selenium QA、LLM Assure と並ぶ製品です。MIT ライセンスです。