MCP API Guardian

MCP API Guardian

AI エージェントによる API の破壊を防止：MCP を介した OpenAPI コントラクトチェックと破壊的変更の差分検出を、完全ローカルで実行します。

OpenAPI 仕様を扱う AI コーディングエージェント向けの、ローカル優先のガードレールです。コントラクトエラー（operation ID の欠落、解決されない参照、認証のない公開エンドポイント）を検出し、破壊的変更（操作の削除、新しい必須パラメーター、認証方式の変更）を見つけ、リリース前に API の利用者が引き続き利用できるようにします。

設定不要。API キー不要。ネットワーク不要。Model Context Protocol を介して、すべてお使いのマシン上で実行されます。

---

目次

• クイックインストール
• API Guardian を選ぶ理由
• ツール
• ユースケース
• 代替製品との比較
• 制限事項
• ソースから実行
• ロードマップ
• ホステッドパス（コントロールプレーン）
• コントリビューション
• ライセンス
• 作者によるその他の MCP サーバー

---

クイックインストール

ワンクリックインストール

Cursor:

または、直接プロトコルリンクを使用してください：cursor://anysphere.cursor-deeplink/mcp/install?name=api-guardian&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1hcGktZ3VhcmRpYW4iXX0=

Claude Code:

claude mcp add api-guardian -- npx -y mcp-api-guardian

petrovicistefan/mcp-marketplace にインストール済みの場合は、こちらを使用してください：

/plugin marketplace add petrovicistefan/mcp-marketplace

手動インストール

Claude Desktop:

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "api-guardian": {
      "command": "npx",
      "args": ["-y", "mcp-api-guardian"]
    }
  }
}

Cursor:

~/.cursor/mcp.json に追加します：

{
  "mcpServers": {
    "api-guardian": {
      "command": "npx",
      "args": ["-y", "mcp-api-guardian"]
    }
  }
}

VS Code / GitHub Copilot:

または、.vscode/mcp.json を手動で作成または編集します：

{
  "servers": {
    "api-guardian": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-api-guardian"]
    }
  }
}

Windsurf:

~/.codeium/windsurf/mcp_config.json に追加します：

{
  "mcpServers": {
    "api-guardian": {
      "command": "npx",
      "args": ["-y", "mcp-api-guardian"]
    }
  }
}

Zed:

Zed の settings.json に追加します：

{
  "context_servers": {
    "api-guardian": {
      "command": "npx",
      "args": ["-y", "mcp-api-guardian"]
    }
  }
}

npx を直接実行（1 行テスト）：

npx -y mcp-api-guardian

---

⭐ 役立ったらこのリポジトリにスターを付けてください

この MCP が役立ちましたか？このリポジトリにスターを付けてください!

GitHub のスターは、ほかの開発者がこのプロジェクトを見つける助けになり、あとで見返すために保存できます。オープンソースを応援していただき、ありがとうございます！

---

API Guardian を選ぶ理由

AI コーディングエージェントが API 機能、ドキュメント、インテグレーションに取り組むなかで、OpenAPI 仕様を変更する機会が増えています。エージェントの反復処理が 1 回行われるだけで、次のような変更が起こる可能性があります：

• クライアントが依存している操作を削除する
• デフォルト値のない必須リクエストパラメーターを追加する
• 生成 SDK が依存している operationId を変更する
• 認証のない公開エンドポイントを誤って公開する
• 外部参照を壊したり、ID の重複を発生させたりする

API Guardian は、これらが本番環境に影響する前に検出します。 AI エージェントが呼び出せる 2 つの MCP ツールを提供します：

1. audit_openapi — 単一の OpenAPI 仕様をチェックし、コントラクトエラー、メタデータの欠落、認証リスクを検出します
2. compare_openapi — 2 つの仕様バージョンを比較し、破壊的変更を検出します

完全ローカルで、読み取り専用、依存関係はゼロです。テレメトリー、API キー、ネットワーク呼び出しはありません。

---

ツール

API Guardian は、OpenAPI 3.0.x および 3.1.x のドキュメントを検証する 2 つの MCP ツールを提供します。

ツール	説明	入力
audit_openapi	OpenAPI 3.0/3.1 の静的リンティングと認証宣言のレビューを行います。エンドポイントは呼び出しません。	spec（オブジェクト）：JSON 形式の OpenAPI ドキュメント
compare_openapi	2 つの OpenAPI ドキュメント間で、選択した破壊的変更を検出します。スキーマの互換性を網羅的に確認するものではありません。	before（オブジェクト）：元の OpenAPI ドキュメント after（オブジェクト）：更新後の OpenAPI ドキュメント

audit_openapi({spec})

単一の OpenAPI 仕様に対する静的なコントラクトチェックです。

• コントラクトエラー：解決できない $ref 参照、info.title／info.version の欠落、無効なパス
• オペレーションのメタデータ：operationId の欠落または重複、レスポンス定義の欠落
• パスパラメーター：すべての {param} プレースホルダーを、必須のパスパラメーターとして宣言する必要があります
• セキュリティ警告：公開オペレーション（認証が不要）、HTTP 経由の基本認証、クエリ文字列内の API キー
• 外部参照：未確認の外部 $ref URL にフラグを付けます（取得はしません）

重大度、場所、対応可能なメッセージとともに、エラーと警告を報告します。カバー範囲の制限も明示します。

compare_openapi({before, after})

2 つの OpenAPI 仕様バージョン間で破壊的変更を検出します。

• 削除されたオペレーション：以前利用可能だったエンドポイントの削除
• 変更されたオペレーション ID：生成されたクライアントやエージェントは、安定した ID に依存している場合があります
• 新たな必須パラメーター：インラインの必須パラメーターが追加されます（クライアントは値を指定できません）
• リクエストボディの必須化：任意だったボディが必須になります
• 削除されたレスポンスコード：クライアントが処理する可能性のあるステータスコードがなくなります
• セキュリティの変更：認証要件の変更（警告レベル）

確定的な破壊（error）と、互換性に影響する可能性のある問題（warning）を報告します。スキーマの差異や合成スキーマはまだ分析されません（制限事項を参照）。

---

ユースケース

個人開発者向け

プロンプト：「コミットする前に、api/openapi.json の OpenAPI 仕様を監査してください」

AI エージェントが audit_openapi を呼び出して、operationId の欠落を検出し、修正案を提示します — PR を作成する前に。

---

CI／PR チェック向け

プロンプト：「このブランチの OpenAPI 仕様を main と比較し、破壊的変更があれば失敗させてください」

エージェントが compare_openapi を実行して、削除されたエンドポイントを検出し、対応可能なレポートとともにマージをブロックします。

---

チームおよびエンタープライズ向け

プロンプト：「api/ 内のすべての OpenAPI 仕様を確認し、認証なしで公開されているエンドポイントを探してください」

エージェントが各仕様を監査して、公開オペレーションにフラグを付け、セキュリティレビューチェックリストを生成します。

---

代替ツールとの比較

機能	MCP API Guardian	oasdiff	pb33f/openapi-changes	optic（アーカイブ済み）
MCP 統合	✅ ネイティブ MCP サーバー	❌ CLI のみ	❌ CLI のみ	❌ CLI のみ
AI エージェントとの親和性	✅ JSON-RPC stdio、エージェント向けに設計	⚠️ CLI 出力の解析が必要	⚠️ CLI 出力の解析が必要	⚠️ アーカイブ済み
完全ローカル（ネットワーク不要）	✅ ネットワーク呼び出しゼロ	✅ オフライン	✅ オフライン	⚠️ クラウドサービスあり
破壊的変更の検出	✅ 中核機能	✅ 包括的（773 項目のチェック）	✅ 包括的	✅（レガシー）
静的コントラクトのリンティング	✅ 中核機能	⚠️ 検証のみ	⚠️ 変更に特化	⚠️ トラフィックに特化
Git リビジョンの比較	❌ 予定	✅ 組み込み	✅ 組み込み	✅（レガシー）
スキーマ互換性	❌ 予定	✅ 完全対応	✅ 完全対応	✅（レガシー）
HTML/Markdown レポート	❌ JSON のみ	✅ 複数の形式	✅ 複数の形式	✅（レガシー）
ライセンス	MIT	Apache 2.0	GPL-3.0 / 商用	MIT（アーカイブ済み）

API Guardian を使用する場合：

• ✅ AI エージェント（Claude、Cursor など）に、CLI ラッパーを使わず OpenAPI コントラクトをネイティブにチェックさせたい場合
• ✅ ローカル優先で、ネットワーク通信なしの検証が必要な場合（外部依存なし）
• ✅ 対象を絞ったリンティングと破壊的変更の検出を、1 つの MCP サーバーで行いたい場合

代替ツールを使用する場合：

• 最も包括的な破壊的変更ルールセット（773 項目のチェック）と CI にネイティブ対応したワークフローが必要な場合は、oasdiff を使用してください
• 人によるレビュー向けの見やすい HTML/Markdown 差分レポートが必要な場合は、pb33f/openapi-changes を使用してください
• oasdiff と openapi-changes はどちらも、完全なスキーマ互換性チェックと Git にネイティブ対応した比較をサポートしています。これらの機能は API Guardian にも今後のリリースで追加される予定です

---

制限事項

API Guardian は対象を絞ったリンターであり、完全な OpenAPI バリデーターではありません。現在の制限事項は次のとおりです。

• ❌ YAML 仕様には未対応：JSON の OpenAPI ドキュメントのみ受け付けます。解析済みの JSON オブジェクトを MCP ツールに渡してください。YAML のサポートはロードマップに記載されています（下記参照）。
• ❌ 外部の $ref は取得しません：外部 HTTP/HTTPS 参照は警告として報告されますが、解決や検証は行いません
• ❌ スキーマ互換性はチェックされません：リクエストとレスポンスの差異、oneOf/anyOf/allOf で構成されたスキーマ、プロパティレベルの破壊的変更への対応は、今後のリリースで予定されています
• ❌ 参照パラメーターは比較されません：compare_openapi ではインラインパラメーターのみチェックします
• ❌ ライブ HTTP プローブはありません：実際の API の動作や、実行時のレスポンスは検証しません
• ❌ ファイルシステムにはアクセスできません：解析済みの JSON オブジェクトとして仕様を渡す必要があります（ファイルパスは使用できません）

公開エンドポイントは意図的な場合があります。警告は脆弱性の証拠ではありません。レポートには対応範囲の制限が明記されます。

---

ソースから実行する

git clone https://github.com/petrovicistefan/mcp-api-guardian.git
cd mcp-api-guardian
npm test
npm start

絶対パスを置き換えて、MCP クライアントの設定に追加してください。

{
  "mcpServers": {
    "api-guardian": {
      "command": "node",
      "args": ["/absolute/path/mcp-api-guardian/src/server.js"]
    }
  }
}

要件： Node.js 22+

---

ロードマップ

今後のリリースでは、次の機能を追加する予定です。

1. YAML のサポート：YAML 形式の OpenAPI 仕様を解析して検証します（現在は JSON のみ）
2. 完全なスキーマ互換性：プロパティレベルの破壊的変更、複合スキーマ（oneOf/anyOf/allOf）、リクエストとレスポンスの差異を検出します
3. ローカル参照の解決：設定可能な許可リストを使って、外部 $ref 参照を取得して検証します
4. Git にネイティブ対応した比較：手動でファイルを抽出せずに、ブランチやコミット間で仕様を比較します
5. ライブレスポンスの検証：ターゲットの許可リスト、サイズ制限、シークレットのマスキングに対応した、オプトイン方式の HTTP プローブ

---

ホステッドパス（コントロールプレーン）

上記のローカル stdio MCP サーバーは、アカウントやネットワーク接続がなくても十分に機能します。クォータが適用されるのは、同じ分析コアを実行する前に mcp-control-plane でユニットを確保する、独立したホステッド HTTP プロセスのみです。

# Terminal 1 — control plane (see its README for ADMIN_TOKEN)
node --env-file=.env src/server.js   # in mcp-control-plane

# Terminal 2 — hosted api-guardian
cp .env.example .env                 # set CONTROL_PLANE_URL
npm run start:hosted

コントロールプレーンの管理 API（POST /v1/admin/accounts、POST /v1/admin/keys）で顧客キーを作成します。続いて、以下を実行します。

メソッド	パス	本文
GET	/health	稼働状況
POST	/v1/audit	{ "requestId": "scan-1", "units": 1, "spec": { … } }
POST	/v1/compare	{ "requestId": "diff-1", "before": { … }, "after": { … } }

顧客向けルートには Authorization: Bearer mcp_… が必要です。成功時のレスポンスには report と usage が含まれます。クォータ超過時は { "error": "quota_exceeded" } とともに 429 を返し、分析は実行されません。デフォルトのバインド先は 127.0.0.1:3100 です。本番環境では HTTPS リバースプロキシが必要です。

プライバシー： OpenAPI ドキュメントはホステッドホスト上でのみ処理されます。コントロールプレーンへのリクエストに含まれるのは、product（api-guardian）、requestId、units のみです。仕様、レポート、認証情報は送信されません。コントロールプレーン MVP では、正常に消費されたユニットの払い戻しはありません。

このホステッドパスは、今後の商用サービスに向けた参考実装であり、公開済みのマルチテナントデプロイではありません。README に記載された価格は、課金が開始されるまでは仮説です。ローカルの MIT パッケージでは、有料クォータを確実に適用できません。有料クォータは、認証されたホステッドサービスで適用する必要があります。

---

コントリビューション

コントリビューションを歓迎します。以下に従ってください。

1. 作業を始める前に、変更について話し合うためのイシューを作成してください
2. 既存のコードスタイル（ESM、node:test、依存関係ゼロ）に従ってください
3. 新機能にはテストを追加してください
4. コミットの対象を絞り、内容が分かる説明を付けてください

CONTRIBUTING.md がある場合は参照してください。コントリビュートを希望する場合は、イシューを作成してください。

---

ライセンス

MIT — 個人利用および商用利用は無料です。詳細な条件についてはLICENSEを参照してください。

---

作者が提供するその他の MCP サーバー

petrovicistefan MCP suiteの一部 — AI コーディングエージェント向けの、ローカル優先のガードレールです。

サーバー	説明
mcp-security-guard	MCP サーバーを監査し、ツールポイズニング、ラグプル、シャドーイング、漏えいしたシークレットを検出します。OWASP MCP Top 10。
mcp-dependency-doctor	プロジェクト内の依存関係の脆弱性、ライセンス上のリスク、サプライチェーンの問題を検出します。
mcp-database-doctor	SQL スキーマのリンティング、マイグレーションの安全性チェック、クエリのパフォーマンス分析を行います。
mcp-cost-optimizer	インフラストラクチャ設定から、クラウドコストを最適化できる箇所を見つけます。
mcp-seo-auditor	Web プロジェクトのテクニカル SEO 監査を行います。メタタグ、schema.org、Core Web Vitals、アクセシビリティを対象とします。
mcp-dealfinder	eコマースや SaaS の価格比較とお得な情報の検索を行います。
mcp-marketplace	利用可能なすべての MCP サーバーとプラグインのディレクトリです。

すべてのサーバーは MIT ライセンスで、完全にローカルで動作し、API キーは不要です。

---

⭐ このプロジェクトがお役に立ったら、GitHub でスターを付けて、ほかの人にも見つけてもらえるようご協力ください！