MCP OpenAPI Schema Explorer

MCP OpenAPI Schema Explorer

MCP（Model Context Protocol）サーバーです。MCP リソーステンプレートを通じて、OpenAPI（v3.0）および Swagger（v2.0）の仕様にトークン効率よくアクセスできます。

プロジェクトの目標

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

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

**注：**このサーバーが提供するのは、事前列挙されたリソースではなく、リソーステンプレートです。MCP クライアントは、resources/templates/list プロトコルメソッドを通じてこれらのテンプレートにアクセスします。リソーステンプレートの詳細については、MCP リソーステンプレートのドキュメントをご覧ください。

MCP リソーステンプレートを使用する理由

Model Context Protocol では、リソースとツールの両方が定義されています。

• リソース：（ファイルや API レスポンスなどの）データソースを表します。読み取り専用のアクセスや、MCP クライアントによる探索に適しています。
  • **リソーステンプレート：**パラメーター化された URI（例：openapi://paths/{path}/{method}）を使用する特別な種類のリソースです。可能な値をすべて事前列挙せずに、動的にアクセスできます。
• **ツール：**実行可能なアクションや関数を表し、LLM がタスクを実行したり外部システムとやり取りしたりする際によく使用されます。

OpenAPI 仕様へのアクセスを_ツール_経由で提供する他の MCP サーバーもありますが、このプロジェクトは特に_リソーステンプレート_経由のアクセスに重点を置いています。この方法は、次の理由から大規模な API に特に効率的です。

• 数千ものパスやコンポーネント候補を事前列挙する必要がありません
• クライアントはテンプレートパターンを使って、利用可能なリソースを動的に見つけられます
• 仕様の特定の部分に、構造化された形式で必要に応じてアクセスできます

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

クライアント別クイックスタートガイド

• Claude Code - Claude を使ったコーディング向けの Anthropic の CLI ツール
• Claude Desktop、Cline、Windsurf - 以下のインストール手順をご覧ください

インストール

推奨される使用方法（後述の 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 クライアントへのサーバーの追加

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

以下では、クライアントの設定にサーバーの項目を追加する一般的な方法を説明します。

方法 1：npx（推奨）

グローバル／ローカルインストールが不要で、公開済みの最新バージョンをクライアントが使用できるため、npx の使用を推奨します。

クライアント設定項目の例（npx の方法）：

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

{
  "mcpServers": {
    "My API Spec (npx)": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-openapi-schema-explorer@latest",
        "<path-or-url-to-spec>",
        "--output-format",
        "yaml"
      ],
      "env": {}
    }
  }
}

設定に関する注意：

• "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 の方法）：

次のいずれかの JSON オブジェクトを、MCP クライアントの設定ファイルの mcpServers セクションに追加します。これらの項目によって、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 はコンテナ内で対応するパスです。

方法 3：グローバルインストール（あまり一般的ではありません）

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

# Run this command once in your terminal
npm install -g mcp-openapi-schema-explorer

クライアント設定項目の例（グローバルインストールの方法）：

次の項目を MCP クライアントの設定ファイルに追加します。mcp-openapi-schema-explorer コマンドがクライアントの実行環境の PATH からアクセスできることを前提としています。

{
  "mcpServers": {
    "My API Spec (Global)": {
      "command": "mcp-openapi-schema-explorer",
      "args": ["<path-or-url-to-spec>", "--output-format", "yaml"],
      "env": {}
    }
  }
}

• MCP クライアントが使用する PATH 環境変数から、command（mcp-openapi-schema-explorer）にアクセスできることを確認してください。

方法 4：ローカルでの開発／インストール

この方法は、開発用に、または変更を加えたバージョンを実行するために、リポジトリをローカルにクローンした場合に便利です。

セットアップ手順（ターミナルで一度だけ実行）：

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 で実行します。

{
  "mcpServers": {
    "My API Spec (Local Dev)": {
      "command": "node",
      "args": [
        "/full/path/to/cloned/mcp-openapi-schema-explorer/dist/src/index.js",
        "<path-or-url-to-spec>",
        "--output-format",
        "yaml"
      ],

      "env": {}
    }
  }
}

重要： /full/path/to/cloned/mcp-openapi-schema-explorer/dist/src/index.js を、クローンしたリポジトリ内にあるビルド済み index.js ファイルの正しい絶対パスに置き換えてください。

機能

• MCP リソーステンプレートへのアクセス： パラメーター化された URI テンプレート（openapi://info、openapi://paths/{path}/{method}、openapi://components/{type}/{name}）を使って 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 リソーステンプレートを公開します。

重要： このサーバーが提供するのはリソーステンプレートであり、事前に列挙されたリソースではありません。MCP クライアントを使用する場合：

• クライアントは resources/templates/list を呼び出して、利用可能なテンプレートパターンを確認します
• 次に、テンプレートのパラメーターを埋めて特定の URI を作成します（例：{path} を users%2F%7Bid%7D に置き換えます）
• クライアントは、作成した URI を使って resources/read を呼び出し、実際のコンテンツを取得します

resources/list（「templates」を含まないもの）を呼び出すと、空のリストが返されます。これは想定された動作です。

複数値パラメーター（*）について

一部のリソーステンプレートには、{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%2F%7Bid%7D になります）。
  • 例： openapi://paths/users%2F%7Bid%7D
  • 出力： メソッドの一覧を text/plain で出力します。
  • 補完： 読み込んだ仕様で見つかったパスに基づいて、{path} の動的な候補を提示します（URL エンコード済み）。

• openapi://paths/{path}/{method*}

  • 説明： 特定の API パスに対する 1 つ以上の操作（HTTP メソッド）の詳細な仕様を取得します。
  • パラメーター：
    • {path} - API パス文字列です。URL エンコードが必須です。
    • {method*} - 1 つ以上の HTTP メソッド（例：get、post、get,post）です。大文字と小文字は区別されません。
  • 例（単一）： openapi://paths/users%2F%7Bid%7D/get
  • 例（複数）： openapi://paths/users%2F%7Bid%7D/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 を使用しています。

今後の予定

（今後の予定は未定です）