Swagger Explorer

🚀 Swagger 探索器 MCP サーバー

Claude を通じて Swagger/OpenAPI 仕様を探索および分析するための管理制御プレーン（MCP）サーバーです。

🚀 クイックスタート

npx を使用してグローバルにインストールして実行するには、以下のコマンドを実行します。

npx -y @johnneerdael/swagger-mcp

または、環境変数を使用してインストールすることもできます。

npx -y @johnneerdael/swagger-mcp \
  --env BASE_URL=/api \
  --env AUTH_TOKEN=your-token \
  --env PORT=3000

📦 インストール

Claude Desktop ユーザー向けのインストール手順

1. ツールと統合メニューを開きます。
2. 「MCP サーバーを追加」ボタンをクリックします。
3. 以下の設定を入力します。
   • アドレス：localhost
   • ポート：3000
4. 完了すると、MCP サーバーが自動的に起動します。

💻 使用例

基本的な使用法

基本的な探索

Claude: Swagger インターフェースを通じて、利用可能なすべての API エンドポイントをリストアップしてくれますか？
あなた: もちろんです！Swagger URL を提供してください。

特定のエンドポイントの分析

Claude: GET /users エンドポイントが返すデータ形式は何ですか？
あなた: Swagger ドキュメントを確認します。このエンドポイントは、ID、ユーザー名、および電子メールを含むユーザー情報を含むオブジェクトを返します。

✨ 主な機能

1. 認証サポート：ベアラートークンによる認証をサポートします。
2. カスタムレスポンス形式：Minimal および Detailed の2つのレスポンスモードをサポートします。
3. スキーマ分析：API インターフェースの構造を自動的に解析して表示します。
4. API 探索：完全な API ドキュメントの閲覧機能を提供します。

📚 ドキュメント

設定説明

1. 環境変数の設定
   • BASE_URL: サービスのベース URL。デフォルトは/apiです。
   • AUTH_TOKEN: 認証に使用するアクセストークン。
   • PORT: サービスが実行されるポート。デフォルトは3000です。
   • SWAGGER_URL: Swagger ドキュメントの URL アドレス。

API エンドポイントの使用方法

API の探索

curl http://localhost:3000/explore \
  -H "Authorization: Bearer your-token"

スキーマの詳細を取得する

curl http://localhost:3000/schema-details \
  -H "Authorization: Bearer your-token" \
  -d '{"schemaName":"User"}'

レスポンススキーマを取得する

curl http://localhost:3000/response-schemas \
  -H "Authorization: Bearer your-token"

レスポンス形式

Minimal モード

{
  "status": "success",
  "data": {}
}

Detailed モード

{
  "status": "success",
  "data": {},
  "description": "完全な API インターフェースドキュメント"
}

一般的な使用シナリオ

1. API エンドポイントの探索と分析。
2. 特定のスキーマの詳細情報の取得。
3. レスポンス形式の分析と検証。

トラブルシューティング

1. 接続問題
   • Swagger URL が利用可能であることを確認します。
   • トークンが正しいことを確認します。
   • ポートが使用されていないことを確認します。
2. 認証エラー
   • AUTH_TOKEN が正しく設定されていることを確認します。
   • リクエストにベアラートークンが含まれていることを確認します。
3. スキーマが見つからない
   • スキーマ名が正確であることを確認します。
   • Swagger 仕様が正しく読み込まれていることを確認します。

セキュリティに関する注意事項

1. MCP は認証が必要です。AUTH_TOKEN が設定されている場合は、必ず提供する必要があります。
2. すべてのリクエストはデバッグ用に記録されます。
3. 機密情報はキャッシュされません。
4. 乱用を防止するためにレート制限が実装されています。

開発に関する説明

1. リポジトリをクローンします。

git clone [リポジトリのアドレス]

2. 依存関係をインストールします。

npm install

3. プロジェクトをビルドします。

npm run build

4. ローカルで実行します。

npm start

📄 ライセンス

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