Swagger Testcase MCP

swagger-testcase-mcp

API テスト向けの MCP サーバーです。Swagger/OpenAPI 仕様からテストケースを生成し、仕様を検証し、バージョンを比較して、モックデータを作成します。

API 仕様の URL を指定するだけで、手動テストや TMS へのインポートにすぐ使える、分類済みのテストケース（ポジティブ、ネガティブ、境界値、認証、セキュリティ、冪等性、ページネーション）を取得できます。

導入の背景

• テストケースの手動作成には時間がかかります。 パラメーターが 10 個以上ある単一のエンドポイントでは、ポジティブ、ネガティブ、境界値、セキュリティのシナリオを網羅するために、30〜50 件のテストケースが必要になる場合があります。エンドポイントが数十個あれば、実際のテストではなく、定型作業に何日も費やすことになります。
• ネガティブケースや境界値ケースは省かれがちです。 納期に追われると、QA は正常系を優先します。エッジケース、無効な入力、セキュリティチェックは真っ先に削られ、そして本番環境のインシデントを引き起こす原因にもなります。
• 仕様の変更にテストドキュメントが追いつかず、社内 API は置き去りにされます。 新しいエンドポイント、フィールド名の変更、制約の変更などに合わせてテストケースを更新し続けるのは、絶え間ない負担です。VPN や独自の認証の背後にある企業 API では、認証付きの仕様アクセスに対応していないツールが多いため、さらに困難です。
• テストケースを TMS に取り込むには、追加の手順が必要です。 優れたテストケースを作成しても、TestRail、Allure、Postman にインポートできる形式に整える作業は面倒で、価値を生みません。

このツールは、基本的な作業を自動化します。公開、社内、localhost のいずれの Swagger/OpenAPI 仕様でも指定すれば、数秒で分類済みのテストケースを取得し、TMS やテストランナーにすぐインポートできるファイルとして保存できます。ビジネスロジックと探索的テストに集中し、残りの作業はツールに任せましょう。

機能

• Swagger 2.0 と OpenAPI 3.x を解析 — JSON および YAML に対応
• スマートなテストケース生成 — パラメーター、スキーマ、制約、レスポンスコード、セキュリティを分析し、関連性の高いテストケースを作成
• 8 種類のテストカテゴリ — ポジティブ、ネガティブ、境界値、認可、ビジネスロジック、セキュリティインジェクション、冪等性、ページネーションとソート
• 9 種類のエクスポート形式 — Markdown、JSON、CSV、Allure CSV、Gherkin、Postman、k6、pytest、TestRail CSV（Steps と Text の 2 つのテンプレート）
• 仕様の検証 — 11 個のルールによる品質スコアと、実行可能な改善提案
• 仕様の比較 — 2 つのバージョンを比較し、破壊的変更を検出
• モックデータの生成 — ロケールに対応した、スキーマに基づくリアルなテストデータ
• カバレッジ分析 — テストカバレッジの不足箇所を特定し、優先度付きの推奨事項を提示
• ファイルへの自動保存 — エクスポート結果を作業ディレクトリに自動保存するため、手動でコピー＆ペーストする必要はありません
• 生成設定のカスタマイズ — カテゴリ、優先度、ロケール、独自の前提条件によるフィルタリング
• 一括生成 — タグ、HTTP メソッド、パスのプレフィックス、非推奨ステータスによるフィルタリング
• あらゆる MCP クライアントで動作 — Claude Desktop、Cursor、VS Code + Cline など

生成されるテストケースのカテゴリ

インストール

npm install -g swagger-testcase-mcp

または、npx で直接実行します。

npx swagger-testcase-mcp

設定

{
  "mcpServers": {
    "swagger-testcase-mcp": {
      "command": "npx",
      "args": ["-y", "swagger-testcase-mcp"]
    }
  }
}

{
  "mcpServers": {
    "swagger-testcase-mcp": {
      "command": "npx",
      "args": ["-y", "swagger-testcase-mcp"]
    }
  }
}

{
  "servers": {
    "swagger-testcase-mcp": {
      "command": "npx",
      "args": ["-y", "swagger-testcase-mcp"]
    }
  }
}

{
  "swagger-testcase-mcp": {
    "command": "npx",
    "args": ["-y", "swagger-testcase-mcp"]
  }
}

{
  "servers": {
    "swagger-testcase-mcp": {
      "command": "npx",
      "args": ["-y", "swagger-testcase-mcp"]
    }
  }
}

{
  "mcpServers": {
    "swagger-testcase-mcp": {
      "command": "npx",
      "args": ["-y", "swagger-testcase-mcp"]
    }
  }
}

クイックスタート

1. "Load the spec from https://petstore3.swagger.io/api/v3/openapi.json"
2. "Generate test cases for POST /pet"
3. "Export as Postman collection"

生成される出力の例を以下に示します（Markdown エクスポート）：

## Positive Tests (1)

### TC-001: POST /pet — happy path with required fields only

- **Priority:** high
- **Preconditions:** Valid authentication credentials are available
- **Steps:**
  1. Send POST request to /pet
  2. Include only required parameters/fields with valid values
  3. Verify response status and body
- **Input:** `{"name":"Buddy","photoUrls":["https://example.com/photo.jpg"]}`
- **Expected Result:** Returns success response with expected data
- **Expected Status:** 200

## Negative Tests (2)

### TC-002: POST /pet — missing required field "name"

- **Priority:** high
- **Preconditions:** Valid authentication credentials are available
- **Steps:**
  1. Send POST request to /pet
  2. Omit required field "name"
  3. Verify error response
- **Input:** `{"_omit":"name"}`
- **Expected Result:** Returns validation error indicating "name" is required
- **Expected Status:** 422

### TC-003: POST /pet — invalid type for "name"

- **Priority:** medium
- **Preconditions:** Valid authentication credentials are available
- **Steps:**
  1. Send POST request to /pet
  2. Set "name" to invalid type value: 12345
  3. Verify error response
- **Input:** `{"name":12345}`
- **Expected Result:** Returns validation error for invalid type of "name"
- **Expected Status:** 422

ジェネレーターは 8 つのカテゴリ（ポジティブ、ネガティブ、境界値、認証、ビジネスロジック、セキュリティ、冪等性、ページネーション）にわたってテストケースを生成します。上記の例には、その一部のみが表示されています。generate_test_cases_batch を使用すると、API 全体をまとめてカバーできます。

各ツールとワークフローの詳しい例については、EXAMPLES.md を参照してください。

利用可能なツール

生成設定

すべての生成ツールは、任意の config パラメーターを受け付けます：

{
  "config": {
    "categories": ["positive", "negative", "security"],
    "priorityFilter": ["high"],
    "maxFieldsForNegative": 15,
    "locale": "ru",
    "customPreconditions": ["Database seeded with test data"],
    "skipDeprecated": true
  }
}

ファイルへのエクスポート

エクスポートはすべて、作業ディレクトリに自動的に保存されます。ファイル名はエンドポイントと形式に基づいて生成されます：

test-cases_POST__pet_postman.json
test-cases_GET__users_testrail_csv.csv
test-cases_POST__orders_k6.js

カスタムパスを指定することもできます：

"Export as postman to /path/to/my-collection.json"

制限事項

このツールは、OpenAPI 仕様に記述されているパラメーター、スキーマ、制約、レスポンスコード、セキュリティ定義に基づいてテストケースを生成します。次の内容には対応していません。

• ビジネスロジック — 「管理者以外のユーザーは割引率が 50％を超えてはならない」「注文には在庫のある商品が少なくとも 1 つ必要」などのルールは仕様に含まれないため、テストケースは自動生成されません。
• エンドポイント間の依存関係 — このツールは各エンドポイントを個別に処理します。「ユーザーを作成 → 注文を作成 → ステータスを確認」のような一連のテストは生成されません。
• カスタム検証ルール — OpenAPI がサポートする範囲を超える制約（条件付きのフィールド要件やフィールド間の検証など）は検出されません。

補完方法： このツールは MCP クライアント（Claude、Cursor など）内で動作するため、チャットでビジネスルールを説明し、生成されたテストケースの拡張や調整を LLM に依頼できます。このツールがベースラインを提供し、LLM がコンテキストを補います。

ヒント： OpenAPI 仕様の品質が高いほど（制約、列挙値、例、説明など）、生成されるテストケースの関連性も高まります。validate_spec を使用して仕様の品質を確認し、改善の提案を取得してください。

サポートされているソース

公開、社内ネットワーク、localhost、ローカルファイルなど、あらゆる Swagger/OpenAPI 仕様で動作します。

公開およびローカルの仕様

"Load the spec from https://petstore3.swagger.io/api/v3/openapi.json"
"Load the spec from /path/to/swagger.json"
"Load the spec from ./api-spec.yaml"
"Load the spec from http://localhost:8080/v3/api-docs"

社内 API

VPN、SSO、社内ネットワーク経由で認証が必要な仕様にアクセスできます。

"Load the spec from https://internal-api.company.com/docs/swagger.json with auth_header Bearer eyJhbGci..."

{
  "source": "https://internal-api.company.com/docs/swagger.json",
  "auth_header": "Bearer eyJhbGciOiJIUzI1NiIs..."
}

{
  "source": "https://internal-api.company.com/docs/swagger.json",
  "auth_header": "Basic dXNlcjpwYXNz"
}

{
  "source": "https://internal-api.company.com/docs/swagger.json",
  "headers": { "X-API-Key": "abc123" }
}

ヒント： 仕様が社内 VPN の背後にある場合は、MCP サーバーのプロセスが内部 URL にネットワークアクセスできることを確認してください。サーバーはローカルで動作するため、お使いのマシンの VPN やプロキシの設定が自動的に適用されます。

TMS との連携

Allure TestOps

1. テストケースを生成し、allure_csv 形式でエクスポートします。
2. Allure TestOps migration tool からインポートします（以下の列に合わせて fieldMapping を設定してください）。
3. 列：名前、説明、事前条件、手順、期待結果、レイヤー、タグ
4. または、Allure TestOps MCP server と組み合わせて、API 経由でテストケースを直接作成できます。

注： Allure TestOps の UI からの CSV インポートは、バージョン 25.3.4 で削除されました。代わりに移行ツールまたは API 連携を使用してください。

"Generate test cases for POST /pet"
"Export as allure_csv"

TestRail

次の 2 つのエクスポート形式を利用できます。

• testrail_csv — ステップテンプレート（ステップごとに 1 行）。期待結果は各テストケースの最後のステップに設定され、中間ステップの期待結果は空欄になります。
• testrail_csv_text — テキストテンプレート（すべてのステップを 1 つのフィールドにまとめます）。よりシンプルで、あらゆる TestRail の設定で使用できます。

ステップテンプレート（推奨）：

1. testrail_csv 形式でエクスポートします。
2. TestRail で Test Cases → Import from CSV を開きます。
3. 「Test Case (Steps)」テンプレートを選択します。
4. 列を対応付けます：タイトル、セクション、タイプ、優先度、事前条件、ステップ、期待結果

"Generate test cases for all endpoints tagged 'users'"
"Export as testrail_csv"

テキストテンプレート：

"Export as testrail_csv_text"

汎用 CSV（Qase、Zephyr、TestLink など）

ほとんどの TMS プラットフォームは CSV インポートに対応しています。csv 形式を使用し、インポート時に列を TMS のフィールドに対応付けてください。

• Qase — title、preconditions、steps、expected_result、priority を対応付けます。
• Zephyr Scale — Name、Precondition、Test Script (Plain Text)、Priority、Folder を対応付けます。
• TestLink — 標準の CSV インポートウィザードを使用します。

"Generate test cases for GET /users"
"Export as csv"

Postman との連携

Postman Collection としてインポート

テストケースを生成し、Postman に直接インポートするか、CI で Newman 経由で実行できる Postman Collection v2.1 としてエクスポートします。

"Load the spec from https://internal-api.company.com/docs/swagger.json with auth_header Bearer eyJ..."
"Generate test cases for POST /users"
"Export as postman"

エクスポートされたコレクションには、次の内容が含まれます。

• テストカテゴリ（正常系、異常系、セキュリティなど）ごとに整理されたフォルダー
• 各テストケースに事前設定された HTTP メソッド、URL、ヘッダー、リクエストボディ
• 期待されるステータスコードのアサーションを含む、自動生成されたテストスクリプト

Postman にインポート

1. Postman を開き、インポートを選択して、エクスポートした JSON ファイルをドラッグします
2. 各エンドポイント用のフォルダーを含むコレクションが表示されます
3. API を指す baseUrl 変数を設定した環境をセットアップします

Newman で実行（CI）

newman run exported-collection.json \
  --environment env.json \
  --reporters cli,junit

開発

git clone https://github.com/eyaushev/swagger-testcase-mcp.git
cd swagger-testcase-mcp
npm install
npm run build
npm test
npm start

ライセンス

MIT