api-test-mcp

api-test-mcp

Claude Code、Cursor、Windsurf、またはMCP互換のAIエージェントが、実際にAPIを呼び出し、レスポンスをOpenAPI仕様書の記載と照合できるようにするMCP サーバーです。ドキュメントを読むだけで推測するのではありません。

APIキーも設定も費用も不要です。あらゆるOpenAPI／Swagger 3.x仕様書（URLまたはローカルファイル）で動作します。

なぜこれが必要なのか

AIエージェントはOpenAPI仕様書を読み、それに基づいてコードを書くのが得意です。しかし、実際のAPIが仕様書どおりに動作するかは推測するしかありません。このツールを使えば、エージェント（または通常のチャットを使うあなた自身）が実際に確かめられます。稼働中のエンドポイントを呼び出し、レスポンスがドキュメントに記載されたスキーマに合致するか確認できます。

インストール

git clone <this repo>
cd api-test-mcp
npm install

MCPクライアントの設定に追加します。たとえばClaude Codeの場合は次のとおりです。

claude mcp add api-test -- node /absolute/path/to/api-test-mcp/src/index.js

または、claude_desktop_config.json／CursorのMCP設定で次のようにします。

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

ツール

ツール	機能
load_api_spec	URLまたはローカルパスからOpenAPI／Swagger仕様書を読み込み、参照を解決します。APIのタイトル、サーバー、ドキュメントに記載されたすべてのエンドポイントを返します。最初に呼び出してください。
list_endpoints	現在読み込まれているすべてのエンドポイントを一覧表示します。
call_endpoint	ドキュメントに記載されたエンドポイントに実際のHTTPリクエストを送信します。実際のステータス、ヘッダー、本文を返します。
validate_response	指定したメソッド＋パス＋ステータスに対してドキュメントに記載されたJSONスキーマに基づき、レスポンス本文を検証します。
test_endpoint	call_endpointとvalidate_responseを1ステップで実行します。メインのツールです。「このエンドポイントはドキュメントどおりに実際に動作するか？」を確認します。
run_all_tests	必須パラメーターが不要なすべてのGETエンドポイントに対して、ベストエフォートでコントラクトテストを実行します。includeMutating: trueを指定すると、スキーマからパラメーターや本文の例も自動生成し、POST／PUT／PATCHも試行します（デフォルトでは無効です。実データを書き込む可能性があります）。手動入力が必要なエンドポイントは、理由とともにスキップとして一覧表示されます。
check_health	エンドポイントのセット（または読み込んだ仕様書内の、パラメーター不要なすべてのGET）に対して一度にpingを実行し、到達可能性とレイテンシを報告します。デモの前やCIのステップとして便利です。
diff_api_specs	仕様書の2つのバージョン（例：古いタグとmain）を比較し、エンドポイントの削除、必須フィールドの追加、型の変更、列挙値の削除など、破壊的変更の可能性があるものと、安全な追加変更を判別します。

上記のすべてのツールでは、認証付きAPIでも生のヘッダーを手作業で組み立てずに済むよう、任意のauthプリセット（ヘッダーまたはクエリパラメーターでのbearer、apiKey、またはbasic）と、任意のtimeoutMsを指定できます。

例（エージェントとの会話）

あなた： https://api.example.com/openapi.jsonのAPI仕様書を読み込み、/users/{id}が実際にドキュメントどおりのレスポンスを返すか確認してください。

エージェント： （load_api_specを呼び出し、続いて実際のユーザーIDを指定してtest_endpointを呼び出します） → 「呼び出しました。200が返りましたが、レスポンスには仕様書で必須とされているcreated_atフィールドがありません。また、roleは3つの値を持つ列挙型として記載されていますが、APIはそのいずれにも該当しない"superadmin"を返しました。」

認証付きAPIの場合：

あなた： このベアラートークンを使ってステージングAPIのコントラクトテストを一通り実行し、書き込みエンドポイントも含めてください。

エージェント： （{ auth: { type: "bearer", token: "..." }, includeMutating: true }を指定してrun_all_testsを呼び出します） → 「12件成功、2件失敗、3件スキップです。POST /ordersはスキーマ検証に失敗しました。total_centsが、仕様書に記載された整数ではなく文字列で返されました。」

実際のライブトラフィックを対象としたテスト

npm test では、サーバーを装った用意済みのフィクスチャを使わず、実際のテストを3つ実行します。

• test/smoke-test.js — 仕様を読み込み、稼働中の公開 API に実際の HTTPS リクエストを送り、実際のレスポンスを検証します。また、意図的に不正なレスポンスを渡し、単に成功パスを確認するだけでなく、不一致が検証で実際に検出されることを確認します。
• test/new-features-test.js — 認証プリセットを実際の送信リクエスト URL に適用するテスト、実際のネットワークタイムアウト／中断のテスト、実際のヘルスチェック呼び出し、および仕様差分ロジックの決定論的なオフラインテストを実行します。
• test/mcp-protocol-test.js — 実際の MCP サーバーをサブプロセスとして起動し、Claude Code や Cursor と同じ方法で、実際の MCP プロトコルを介して通信します。

CI では、プッシュ／PR のたびに Node 18、20、22 を対象として、テストスイート全体を実行します。

ロードマップ

v1.0 では、コントラクトテスト、認証プリセット、変更を伴うエンドポイント向けのサンプルデータ自動生成、仕様差分の検出、ヘルスチェックを提供しました。今後のアイデア：

• YAML 出力モード／MCP 以外で使うための小さな CLI ラッパー
• 不安定なエンドポイント向けに、run_all_tests と check_health で再試行／バックオフを設定可能にする
• パターンを考慮したサンプル生成（プレースホルダー文字列ではなく、JSON Schema の pattern に準拠）
• ヘルスチェック履歴の保存（現在は単発実行のみ）

コントリビューションを歓迎します。CONTRIBUTING.md をご覧ください。適切に扱えないエンドポイントの種類や仕様の特異な点を見つけた場合は、issue を作成してください。

ライセンス

MIT