Swagger MCP

🚀 Swagger MCP Server

Swagger/OpenAPIドキュメントを通じてAPIを探索およびテストするためのツールを提供するModel Context Protocol (MCP)サーバーです。このサーバーは、複数のIDEから構成ファイルを自動検出し、包括的なAPIインタラクション機能を提供します。

✨ 主な機能

• 🔍 任意のURLからSwagger/OpenAPIドキュメントを取得して解析する
• 🧪 MCPインターフェイスを通じて直接APIエンドポイントをテストする
• 📊 APIスキーマを探索し、データ構造を理解する
• 🔧 複数のIDEをサポート - VS Code、Cursor、Windsurfなどから自動的に設定を検出する
• 🌐 柔軟な認証方式 - APIキー、基本認証、ベアラートークンをサポートする
• ⚡ 自動検出機能 - ドキュメントのURLを自動的に見つけることができる

📦 インストール

IDEの設定

IDEの設定ディレクトリにMCP構成ファイルを作成します。

• VS Code: ~/.vscode/mcp.json または .vscode/mcp.json（プロジェクト内）
• Cursor: ~/.cursor/mcp.json または .cursor/mcp.json（プロジェクト内）
• Windsurf: ~/.windsurf/mcp.json または .windsurf/mcp.json（プロジェクト内）
• 任意のIDE: mcp.json（プロジェクトルート）または .mcp/config.json

認証オプション

オプション1: APIキーを使用する

"swagger-mcp": {
  "command": "npx",
  "args": [
    "-y",
    "swagger-mcp@latest"
  ],
  "env": {
    "API_BASE_URL": "https://api.example.com",
    "API_DOCS_URL": "https://api.example.com/swagger.json",
    "API_KEY": "your-api-key-here"
  }
}

オプション2: ユーザー名とパスワードを使用する

"swagger-mcp": {
  "command": "npx",
  "args": [
    "-y", 
    "swagger-mcp@latest"
  ],
  "env": {
    "API_BASE_URL": "https://api.example.com",
    "API_DOCS_URL": "https://api.example.com/swagger.json",
    "API_USERNAME": "your-username",
    "API_PASSWORD": "your-password"
  }
}

設定オプション

🔧 技術詳細

認証フロー

サーバーは認証をインテリジェントに処理します。

1. APIリクエストの場合: API_KEYをベアラートークンとして使用し、基本認証にフォールバックします。
2. 認証エンドポイントの場合: ユーザー名/パスワードの資格情報を自動的に注入します。
3. トークン管理: ログインレスポンスからトークンを自動的に保存し、再利用します。
4. 自動更新: 401 Unauthorizedレスポンスが返された場合、トークンの更新を試みます。

利用可能なツール

fetch_swagger_info

指定されたURLからSwagger/OpenAPIドキュメントを取得して解析し、利用可能なAPIエンドポイントを発見します。

list_endpoints

Swaggerドキュメントを取得した後、利用可能なすべてのAPIエンドポイントをリストし、メソッド、パス、および概要を表示します。

get_endpoint_details

特定のAPIエンドポイントに関する詳細情報を取得します。パラメータ、リクエスト/レスポンススキーマ、およびサンプルが含まれます。

execute_api_request

認証、パラメータ、ヘッダー、およびボディを処理して、特定のエンドポイントにAPIリクエストを実行します。

validate_api_response

Swaggerドキュメントのスキーマ定義に対してAPIレスポンスを検証し、準拠していることを確認します。

💻 使用例

設定が完了したら、AI搭載のエディタでMCPサーバーを使用して以下のことができます。

• APIを探索する: "このAPIで利用可能なエンドポイントを表示して"
• エンドポイントをテストする: "このデータでPOST /usersエンドポイントをテストして"
• スキーマを理解する: "Userモデルの構造を説明して"
• API呼び出しをデバッグする: "このAPIリクエストのトラブルシューティングを手伝って"
• レスポンスを検証する: "このレスポンスがAPIスキーマに一致するか確認して"

サポートされているIDE

サーバーは以下から構成ファイルを自動検出します。

• VS Code (.vscode/mcp.json)
• Cursor (.cursor/mcp.json)
• Windsurf (.windsurf/mcp.json)
• ルートディレクトリ (mcp.json)
• 代替場所 (.mcp/config.json)

開発

# リポジトリをクローンする
git clone https://github.com/amrsa1/SwaggerMCP.git
cd SwaggerMCP

# 依存関係をインストールする
npm install

# 開発モードで実行する
npm run dev

# 本番用にビルドする
npm run build

📄 ライセンス

MITライセンス - 詳細についてはLICENSEファイルを参照してください。

コントリビューション

コントリビューションは歓迎されます！自由にプルリクエストを送信してください。