OpenAPI to MCP Generator

OpenAPI から MCP へのジェネレーター

このプロジェクトは、OpenAPI／Swagger の仕様を MCP サーバーに自動変換する強力なツールを提供します。これにより、LLM は標準化されたツールを通じてあらゆる REST API を操作できます。

コンポーネント

SwaggerToMcpGenerator.java

あらゆる OpenAPI／Swagger 仕様を、完全に機能する MCP サーバーに変換する総合的なユーティリティです。

• OpenAPI 仕様ファイルを解析します
• API エンドポイントを MCP ツールに変換します
• パスパラメーター、クエリパラメーター、リクエストボディを処理します
• 複数の HTTP メソッド（GET、POST、PUT、DELETE、PATCH）をサポートします
• 認証（API キー、Bearer トークン、Basic 認証）をサポートします
• JSON レスポンスを読みやすく整形します
• 堅牢なエラー処理を生成します
• 有効な値やデフォルト値を含むパラメーターのドキュメントを備えています

OpenAPI からの MCP サーバーの生成

任意の OpenAPI 仕様から MCP サーバーを生成するには、次のようにします。

jbang SwaggerToMcpGenerator.java path/to/swagger.json GeneratedMcpServer [options]

パラメーター：

• path/to/swagger.json：OpenAPI／Swagger 仕様ファイルのパス
• GeneratedMcpServer：出力する Java ファイルの名前（.java 拡張子なし）

オプション：

• --server-index <index>：OpenAPI 仕様から使用するサーバーのインデックス（0 始まり）
• --server-url <url>：使用するサーバーの URL（server-index を上書きします）

これにより、swagger ファイルで定義された各 API エンドポイントに対応するツールを備えた MCP サーバーを実装する、新しいファイル GeneratedMcpServer.java が作成されます。OpenAPI 仕様に複数のサーバーが定義されていて、明示的に選択されていない場合、ジェネレーターは警告を出力します。

生成した MCP サーバーの実行

生成した MCP サーバーを実行するには、次のようにします。

jbang GeneratedMcpServer.java

サーバーの選択

生成した MCP サーバーには、OpenAPI 仕様で定義されたすべてのサーバーの定数が含まれているため、実行時に使用するサーバーを選択できます。デフォルトではリストの最初のサーバーが使用されますが、環境変数を使って特定のサーバーを選択できます。

# Select server by index (0-based)
export SERVER_INDEX=1

# Or select server by URL
export SERVER_URL="https://api-example.com/v2"

jbang GeneratedMcpServer.java

認証

生成した MCP サーバーは、環境変数を通じて複数の認証方式をサポートします。

• API キー：環境変数 API_KEY と API_KEY_HEADER を設定します
• Bearer トークン：環境変数 BEARER_TOKEN を設定します
• Basic 認証：環境変数 API_USERNAME と API_PASSWORD を設定します

例：

export API_KEY="your-api-key"
export API_KEY_HEADER="X-API-Key"
jbang GeneratedMcpServer.java

例

Open-Meteo Weather API

このプロジェクトには、Open-Meteo Weather API の OpenAPI 仕様の例が examples/open-meteo ディレクトリに含まれています。

Open-Meteo MCP サーバーの生成

cd examples/open-meteo
jbang ../../SwaggerToMcpGenerator.java open-meteo-openapi.yml OpenMeteoMcpServer

これにより、天気予報データにアクセスするための MCP ツールを備えた OpenMeteoMcpServer.java が生成されます。

Open-Meteo MCP サーバーの実行

cd examples/open-meteo
jbang OpenMeteoMcpServer.java

Open-Meteo MCP サーバーの使用

生成した MCP サーバーは、天気予報にアクセスするためのツールを提供します。サーバーを使用する際は、有効な値やデフォルト値を含むパラメーターの説明を確認してください。たとえば、次のとおりです。

• wind_speed_unit パラメーターには、メートル毎秒を表す ms（「m/s」ではありません）を使用します
• wind_speed_unit の有効な値は、kmh（デフォルト）、ms、mph、kn です
• 温度単位には、celsius（デフォルト）または fahrenheit を使用します

スペインのセビリアの天気を問い合わせる例：

latitude: 37.3891
longitude: -5.9845
current_weather: true
wind_speed_unit: ms

Clever Cloud MCP サーバーの生成

cd examples/clever-cloud
jbang ../../SwaggerToMcpGenerator.java clever-cloud-openapi.yml CleverCloudMcpServer --server-index 1

ここでは --server-index 1（リストの2番目のサーバー）を使用しています。これは、トークン認証に必要な API Bridge URL です。これにより、Clever Cloud のリソースを管理するための MCP ツールを備えた CleverCloudMcpServer.java が生成されます。

また、サーバー URL を直接指定することもできます。

cd examples/clever-cloud
jbang ../../SwaggerToMcpGenerator.java clever-cloud-openapi.yml CleverCloudMcpServer --server-url https://api-bridge.clever-cloud.com/v2

Clever Cloud MCP サーバーの実行

cd examples/clever-cloud
# Set your Clever Cloud API token
export BEARER_TOKEN=your_api_token
jbang CleverCloudMcpServer.java

Clever Cloud API トークンの生成

Clever Cloud の API トークンを生成するには、Clever Tools CLI を使用します。

# Install Clever Tools (if not already installed)
npm install -g clever-tools

# Login to Clever Cloud
clever login

# Enable the tokens feature
clever features enable tokens

# Create a token (with optional expiration)
clever tokens create "MCP Server Token"
clever tokens create "Temporary Token" --expiration 24h

トークンの一覧表示や取り消しもできます。

# List existing tokens
clever tokens -F json

# Revoke a token
clever tokens revoke api_tokens_xxx

Clever Cloud MCP サーバーの使用方法

生成された MCP サーバーは、Clever Cloud API とやり取りするためのツールを提供します。利用可能なツールは次のとおりです。

• get_self：現在のユーザー情報を取得します
• get_summary：ユーザーの概要を取得します
• get_organisations__organisationId__applications：組織のアプリケーション一覧を取得します
• get_organisations__organisationId__applications__applicationId_：アプリケーションの詳細を取得します

組織のアプリケーション一覧を取得するクエリの例：

organisationId: your_organization_id

動作の仕組み

MCP プロトコル

Model Context Protocol（MCP）は、ツールと LLM が通信するための標準化された方法であり、次のことが可能になります。

1. ツールが、MCP 互換のあらゆる LLM に機能を公開できます
2. LLM が特定の実装に縛られることなく、ツールを検出して使用できます
3. ツールの仕様と呼び出しに一貫したインターフェースを提供できます

OpenAPI から MCP への変換

ジェネレーターは次の手順で動作します。

1. Swagger Parser を使用して OpenAPI 仕様を解析します
2. 各 API エンドポイントを @Tool アノテーション付きのメソッドに変換します
3. パラメーターをマッピングします。
   • パスパラメーターは URL に組み込まれます
   • クエリパラメーターは URL ビルダーに追加されます
   • リクエストボディは適切にフォーマットされ、リクエストに含められます
4. 適切なエラー処理を備えた HTTP クライアントコードを生成します
5. コンテンツタイプに基づいてレスポンスをフォーマットします（JSON を整形表示します）
6. 環境変数に基づいて認証を追加します

高度な機能

• 複数の HTTP メソッド：GET、POST、PUT、DELETE、PATCH をサポートします
• コンテンツタイプの処理：さまざまなコンテンツタイプを適切に処理します
• エラー処理：ステータスコードとレスポンスボディを含む詳細なエラー情報を報告します
• 認証：API キー、Bearer トークン、Basic 認証をサポートします
• タイムアウト：接続、読み取り、書き込みのタイムアウトを設定できます
• 複数のサーバー：OpenAPI 仕様で定義された複数のサーバー URL から選択できます

環境に関する注意事項

jbang-wrapper.sh スクリプトは、Mac で Claude Desktop などの AI アシスタントから実行する際の環境に関する問題に対処し、正しい PATH と環境変数が利用できるようにします。

次のステップ

• フォームデータとマルチパートリクエストのサポートを追加する
• OAuth 2.0 認証フローを実装する
• カスタムレスポンス変換のサポートを追加する
• OpenAPI 仕様をアップロードしてサーバーを生成する Web UI を作成する
• WebSocket エンドポイントのサポートを追加する