Swagger To MCP Generator

🚀 OpenAPI から MCP への変換ツールドキュメント

このプロジェクトは、OpenAPI 仕様を Model Context Protocol (MCP) サーバーに変換する Java ツールを提供します。Swagger Parser を使用して OpenAPI ファイルを解析し、対応する MCP ユーティリティクラスを生成します。このツールは、さまざまな HTTP メソッド、コンテンツタイプの処理、エラー処理、および認証をサポートしています。

✨ 主な機能

• OpenAPI 解析：Swagger Parser を使用して OpenAPI 仕様を解析します。
• エンドポイント変換：各 API エンドポイントを @Tool アノテーション付きのメソッドに変換します。
• パラメータマッピング：
  • パスパラメータ：URL に統合されます。
  • クエリパラメータ：URL ビルダーに追加されます。
  • リクエストボディ：正しくフォーマットされ、リクエストに追加されます。
• HTTP クライアント生成：詳細なエラー処理を備えた HTTP クライアントコードを生成します。
• レスポンスフォーマット：コンテンツタイプ（JSON など）に応じて整形された出力を提供します。
• 認証サポート：環境変数に基づく認証（API キー、Bearer Token、Basic Auth）をサポートします。
• 複数サーバーサポート：OpenAPI 仕様から複数のサーバー URL を選択できます。

🚀 クイックスタート

1. 依存関係の追加

プロジェクトに以下の依存関係を追加してください。

<dependency>
    <groupId>org.swagger</groupId>
    <artifactId>swagger-parser</artifactId>
    <version>1.2.30</version>
</dependency>

2. ツールを使用して MCP サーバーコードを生成する

OpenAPIToMCPGenerator ツールを実行します。

java -jar openapi-to-mcp-generator.jar --input-spec your_openapi.yaml --output-dir output

3. 環境変数の設定

必要な環境変数を設定してください。

• API_KEY: API キー
• BEARER_TOKEN: Bearer Token
• BASIC_AUTH_USER: Basic Auth のユーザー名
• BASIC_AUTH_PASSWORD: Basic Auth のパスワード

4. サンプルコード

生成された MCP ユーティリティクラスの使用方法を示す簡単なサンプルを以下に示します。

@Tool(
    name = "Get User",
    description = " retrieves user information by ID.",
    parameters = {
        @Parameter(name = "userId", type = Type.STRING, description = "User ID"),
        @Parameter(name = "includeDetails", type = Type.BOOLEAN, description = "Include detailed information")
    }
)
public class GetUserTool {

    private static final String BASE_URL = "https://api.example.com";

    public static User getUser(String userId, boolean includeDetails) {
        // 実装 HTTP リクエストロジック
    }

}

📚 ドキュメント

MCP プロトコルの概要

MCP は、ツールと LLM 間の通信を可能にする標準化されたプロトコルです。主な特徴は以下の通りです。

1. ツール機能の公開：ツールは MCP を介して LLM にその機能を公開できます。
2. LLM ツールの発見：LLM は MCP インターフェースに準拠したツールを詳細な実装を知らずに発見して使用できます。
3. 統一されたインターフェース：ツールの仕様と呼び出しインターフェースを統一します。

OpenAPI から MCP への変換プロセス

1. OpenAPI 仕様の解析：Swagger Parser を使用して入力された OpenAPI ファイルを解析します。
2. エンドポイント変換：各 API エンドポイントを @Tool アノテーション付きのメソッドにマッピングします。
3. パラメータ処理：
   • パスパラメータを URL に統合します。
   • クエリパラメータを URL ビルダーに追加します。
   • リクエストボディを正しくフォーマットし、リクエストに追加します。
4. HTTP クライアントコードの生成：詳細なエラー処理とタイムアウト設定を備えた HTTP クライアントコードを生成します。
5. レスポンスフォーマット：コンテンツタイプ（JSON など）に応じて整形された出力を提供します。

高度な機能

• 複数の HTTP メソッドサポート：GET、POST、PUT、DELETE、PATCH をサポートします。
• コンテンツタイプの処理：異なるコンテンツタイプを正しく処理します。
• エラー処理：ステータスコードとレスポンスボディを含む詳細なエラーレポートを提供します。
• 認証：API キー、Bearer Token、Basic 認証をサポートします。
• タイムアウト設定：接続タイムアウト、読み取りタイムアウト、書き込みタイムアウトを設定できます。

🔧 環境に関する注意事項

jbang-wrapper.sh スクリプトは、Claude Desktop（macOS）などの AI アシスタント環境で実行する際の環境問題を解決し、PATH と環境変数が正しく設定されるようにします。

🔮 将来の計画

• 機能拡張：
  • フォームデータとファイルアップロードをサポートする。
  • より複雑なパラメータ検証ロジックを実装する。
• パフォーマンス最適化：解析とコード生成の速度を向上させる。
• テストカバレッジの拡充：単体テストと統合テストを充実させる。
• ドキュメントの改善：より多くのサンプルと使用ガイドを追加する。

🤝 コントリビューションガイド

コミュニティからの貢献を歓迎します！プロジェクトへの参加方法については、CONTRIBUTING.md を参照してください。