OpenAPI Schema Explorer

MCP OpenAPI スキーマ エクスプローラー

MCP リソースを介して OpenAPI (v3.0) および Swagger (v2.0) 仕様へのトークン効率の高いアクセスを提供する MCP (モデル コンテキスト プロトコル) サーバー。

プロジェクトの目標

このプロジェクトの主目的は、MCPクライアント（ClineやClaude Desktopなど）が、LLMのコンテキストウィンドウにファイル全体を読み込むことなく、大規模なOpenAPI仕様の構造と詳細を探索できるようにすることです。これは、読み取り専用のデータ探索に適したMCPリソースを通じて仕様の一部を公開することで実現します。

このサーバーは、ローカルファイルパスとリモートHTTP/HTTPS URLの両方からの仕様の読み込みをサポートしています。Swagger v2.0仕様は、読み込み時に自動的にOpenAPI v3.0に変換されます。

MCP リソースを選ぶ理由

モデル コンテキスト プロトコルは、リソースとツールの両方を定義します。

• **リソース:**データソース（ファイル、APIレスポンスなど）を表します。MCPクライアントによる読み取り専用アクセスや探索（例：Claude DesktopでのAPIパスの参照）に最適です。
• **ツール:**実行可能なアクションまたは機能を表します。LLM がタスクを実行したり外部システムと対話したりする際によく使用されます。

ツール経由でOpenAPI仕様へのアクセスを提供するMCPサーバーは他にも存在しますが、このプロジェクトはリソース経由でのアクセス提供に特化しています。そのため、MCPクライアントアプリケーション内で直接探索する場合に特に便利です。

MCP クライアントとその機能の詳細については、 MCP クライアントのドキュメントを参照してください。

インストール

推奨される使用方法（以下で説明するnpxとDocker）では、別途インストール手順は必要ありません。MCPクライアントは、指定された設定に基づいてパッケージをダウンロードするか、Dockerイメージを自動的にプルします。

ただし、サーバーを明示的にインストールしたい場合やインストールする必要がある場合は、次の 2 つのオプションがあります。

1. グローバルインストール: npm を使用してパッケージをグローバルにインストールできます。
   npm install -g mcp-openapi-schema-explorer
   グローバルにインストールされたサーバーを使用するように MCP クライアントを構成する方法については、以下の方法 3 を参照してください。
2. **ローカル開発/インストール:**リポジトリをクローンしてローカルでビルドできます。
   git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git cd mcp-openapi-schema-explorer npm install npm run build
   nodeを使用してローカル ビルドからサーバーを実行するように MCP クライアントを構成する方法については、以下の方法 4 を参照してください。

MCPクライアントにサーバーを追加する

このサーバーは、MCPクライアント（Claude Desktop、Windsurf、Clineなど）で実行されるように設計されています。使用するには、クライアントの設定ファイル（通常はJSONファイル）に設定エントリを追加します。このエントリは、クライアントにサーバープロセスの実行方法（例： npx 、 docker 、 nodeなど）を指示します。サーバー自体は、クライアント設定エントリで指定されたコマンドライン引数以外に、別途設定する必要はありません。

以下は、クライアントの構成にサーバー エントリを追加するための一般的な方法です。

方法1: npx (推奨)

グローバル/ローカル インストールを回避し、クライアントが最新の公開バージョンを使用することを保証するため、 npxの使用が推奨されます。

クライアント構成エントリの例 (npx メソッド):

MCPクライアントの設定ファイルのmcpServersセクションに、以下のJSONオブジェクトを追加します。このエントリは、 npxを使用してサーバーを実行する方法をクライアントに指示します。

構成に関する注意事項:

• "My API Spec (npx)"を、クライアント内のこのサーバー インスタンスの一意の名前に置き換えます。
• <path-or-url-to-spec> 、仕様の絶対ローカル ファイル パスまたは完全なリモート URL に置き換えます。
• --output-formatはオプション ( json 、 yaml 、 json-minified ) で、デフォルトはjsonです。
• 複数の仕様を調べるには、 mcpServersに個別のエントリを追加し、それぞれに一意の名前を付けて異なる仕様を指します。

方法2: Docker

公式 Docker イメージkadykov/mcp-openapi-schema-explorerを使用して、MCP クライアントにサーバーを実行するように指示できます。

クライアント構成エントリの例 (Docker メソッド):

MCPクライアントの設定ファイルのmcpServersセクションに、以下のJSONオブジェクトのいずれかを追加します。これらのエントリはdocker runを使用してサーバーを実行する方法をクライアントに指示します。

• リモート URL: URL をdocker runに直接渡します。
• リモート URL の使用:
  { "mcpServers": { "My API Spec (Docker Remote)": { "command": "docker", "args": [ "run", "--rm", "-i", "kadykov/mcp-openapi-schema-explorer:latest", "<remote-url-to-spec>" ], "env": {} } } }
• ローカルファイルの使用: (ファイルをコンテナにマウントする必要があります)
  { "mcpServers": { "My API Spec (Docker Local)": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "/full/host/path/to/spec.yaml:/spec/api.yaml", "kadykov/mcp-openapi-schema-explorer:latest", "/spec/api.yaml", "--output-format", "yaml" ], "env": {} } } }
  重要: /full/host/path/to/spec.yamlホストマシン上の正しい絶対パスに置き換えてください。/spec/api.yaml /spec/api.yamlコンテナ内の対応するパスです。

方法3: グローバルインストール（あまり一般的ではない）

npm install -gを使用してパッケージをグローバルにインストールした場合は、クライアントが直接実行するように構成できます。

クライアント構成エントリの例 (グローバル インストール方法):

MCPクライアントの設定ファイルに以下のエントリを追加します。これはmcp-openapi-schema-explorerコマンドがクライアントの実行環境PATHでアクセス可能であることを前提としています。

• MCP クライアントが使用する PATH 環境変数でcommand ( mcp-openapi-schema-explorer ) にアクセスできることを確認します。

方法4: ローカル開発/インストール

この方法は、開発のためにリポジトリをローカルに複製した場合や、変更されたバージョンを実行した場合に便利です。

セットアップ手順 (ターミナルで 1 回実行):

1. リポジトリをクローンします: git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git
2. ディレクトリに移動します: cd mcp-openapi-schema-explorer
3. 依存関係をインストール: npm install
4. プロジェクトをビルドします: npm run build (またはjust build )

クライアント構成エントリの例 (ローカル開発方法):

MCPクライアントの設定ファイルに以下のエントリを追加します。これにより、クライアントはローカルで構築されたサーバーをnodeを使って実行するよう指示されます。

重要: /full/path/to/cloned/mcp-openapi-schema-explorer/dist/src/index.jsを、クローンされたリポジトリに構築されたindex.jsファイルへの正しい絶対パスに置き換えます。

特徴

• **MCP リソース アクセス:**直感的な URI ( openapi://info 、 openapi://paths/... 、 openapi://components/... ) を介して OpenAPI 仕様を調べます。
• **OpenAPI v3.0 および Swagger v2.0 のサポート:**両方の形式を読み込み、v2.0 を v3.0 に自動的に変換します。
• **ローカルおよびリモート ファイル:**ローカル ファイル パスまたは HTTP/HTTPS URL から仕様を読み込みます。
• **トークン効率:**構造化されたアクセスを提供することで、LLM のトークン使用量を最小限に抑えるように設計されています。
• 複数の出力形式: JSON (デフォルト)、YAML、または縮小された JSON ( --output-format ) で詳細ビューを取得します。
• 動的サーバー名: MCP クライアントのサーバー名は、読み込まれた仕様のinfo.titleを反映します。
• **参照変換:**内部の$ref ( #/components/... ) はクリック可能な MCP URI に変換されます。

利用可能なMCPリソース

このサーバーは、OpenAPI 仕様を調べるための次の MCP リソース テンプレートを公開します。

複数値パラメータの理解（ * ）

一部のリソーステンプレートには、 {method*}や{name*}のように、アスタリスク（ * ）で終わるパラメータが含まれています。これは、パラメータが複数のコンマ区切り値を受け入れることを示します。例えば、パスのGETメソッドとPOSTメソッドの両方の詳細を要求するには、 openapi://paths/users/get,postのようなURIを使用します。これにより、1回のリクエストで複数の項目の詳細を取得できます。

リソース テンプレート:

• openapi://{field}
  • 説明: OpenAPIドキュメントの最上位フィールド（例： info 、 servers 、 tags ）にアクセスするか、 pathsまたはcomponentsの内容を一覧表示します。使用可能なフィールドは、読み込まれた仕様によって異なります。
  • 例: openapi://info
  • 出力: pathsとcomponentsの場合はtext/plainリスト、その他のフィールドの場合は構成された形式 (JSON/YAML/縮小された JSON)。
  • **補完:**読み込まれた仕様で見つかった実際のトップレベル キーに基づいて、 {field}の動的な提案を提供します。
• openapi://paths/{path}
  • **説明:**特定の API パスで使用可能な HTTP メソッド (操作) を一覧表示します。
  • パラメータ: {path} - APIパス文字列。URLエンコードする必要があります（例： /users/{id}``users/{id}になります）。
  • 例: openapi://paths/users/{id}
  • **出力:**メソッドのtext/plainリスト。
  • **補完:**読み込まれた仕様 (URL エンコード) で見つかったパスに基づいて、 {path}の動的な提案を提供します。
• openapi://paths/{path}/{method*}
  • **説明:**特定の API パス上の 1 つ以上の操作 (HTTP メソッド) の詳細な仕様を取得します。
  • パラメータ:
    • {path} - API パス文字列。URLエンコードされている必要があります。
    • {method*} - 1つ以上のHTTPメソッド（例： get 、 post 、 get,post ）。大文字と小文字は区別されません。
  • 例（単一）: openapi://paths/users/{id}/get
  • 例（複数）: openapi://paths/users/{id}/get,post
  • **出力:**構成された形式 (JSON/YAML/縮小された JSON)。
  • 補完: {path}に対して動的な候補を表示します。 {method*} (GET、POST、PUT、DELETE などの一般的な HTTP 動詞) に対しては静的な候補を表示します。
• openapi://components/{type}
  • **説明:**特定のタイプ（例： schemas 、 responses 、 parameters ）の定義済みコンポーネントの名前をすべて一覧表示します。使用可能なタイプは、読み込まれた仕様によって異なります。また、各タイプには簡単な説明も表示されます。
  • 例: openapi://components/schemas
  • **出力:**コンポーネント名と説明のtext/plainリスト。
  • **補完:**読み込まれた仕様で見つかったコンポーネント タイプに基づいて、 {type}の動的な提案を提供します。
• openapi://components/{type}/{name*}
  • **説明:**特定のタイプの 1 つ以上の名前付きコンポーネントの詳細な仕様を取得します。
  • パラメータ:
    • {type} - コンポーネントの種類。
    • {name*} - 1つ以上のコンポーネント名（例： User 、 Order 、 User,Order ）。大文字と小文字が区別されます。
  • 例（単一）: openapi://components/schemas/User
  • 例（複数）: openapi://components/schemas/User,Order
  • **出力:**構成された形式 (JSON/YAML/縮小された JSON)。
  • 補完: {type}に対して動的な候補を提供します。 {name*}に対しては、読み込まれた仕様にコンポーネントタイプが1つだけ含まれている場合（例： schemasのみ）にのみ、動的な候補を提供します。この制限は、MCP SDKが現在、選択された{type}をスコープとした補完の提供をサポートしていないためです。すべてのタイプにわたるすべての名前を提供すると、誤解を招く可能性があります。

貢献

貢献を歓迎します！開発環境の設定、テストの実行、変更の送信に関するガイドラインについては、 CONTRIBUTING.mdファイルをご覧ください。

リリース

このプロジェクトでは、 Conventional Commitsに基づく自動バージョン管理とパッケージ公開にsemantic-releaseを使用します。

今後の計画

（今後の予定は未定）