Spring Web to MCP Converter 🚀

Spring Web から MCP への変換 🚀

Spring Web REST API を Spring AI Model Context Protocol（MCP）サーバーツールに自動変換する、OpenRewrite のレシピ集です。

📋 はじめに

このプロジェクトでは、従来の Spring Web REST API を Spring AI の Model Context Protocol（MCP）サーバーツールに移行するための OpenRewrite レシピを提供します。変換内容は次のとおりです。

1. 🔄 Spring Web のアノテーションを Spring AI MCP の @Tool アノテーションに変換します
2. 🔧 必要な MCP 設定とコンポーネントを追加します
3. 📦 Maven の依存関係を更新し、Spring AI MCP サーバーコンポーネントを含めます

レシピは既存の REST コントローラーからドキュメントを自動抽出し、適切にドキュメント化された MCP ツールを作成します。これにより、Model Context Protocol を通じて AI エージェントが API を利用できるようになります。

Spring AI による MCP の実装の詳細については、Spring AI MCP のドキュメントを参照してください。

🛠️ ビルドとインストール方法

前提条件

• Java 17 以上
• Maven 3.6+

移行対象の REST API プロジェクトの前提条件

Spring Web REST API を MCP に正常に移行するには、プロジェクトが次の条件を満たしている必要があります。

• Spring Boot 3.2+（3.2.0 以降）を使用している
• REST コントローラーに Spring Web MVC を使用している
• Maven ビルドツールを使用している

レシピは Spring AI MCP の依存関係（バージョン 1.0.0-SNAPSHOT 以降）をプロジェクトに自動で追加します。

ビルド手順

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

   git clone https://github.com/yourusername/web-to-mcp.git
   cd web-to-mcp
   

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

   mvn clean install
   

これにより、コードがコンパイルされ、成果物がローカルの Maven リポジトリにインストールされます。

🔥 使用方法

Spring Web プロジェクトにレシピを適用するには、次の Maven コマンドを実行します。

mvn org.openrewrite.maven:rewrite-maven-plugin:6.4.0:run \
  -Drewrite.activeRecipes=RewriteWebToMCP \
  -Drewrite.recipeArtifactCoordinates=com.atbug.rewrite:web-to-mcp:1.0-SNAPSHOT \
  -Drewrite.exportDatatables=true

重要：このコマンドは 2 回実行する必要があります。

1. 1 回目の実行で、必要なリポジトリと依存関係を追加するために pom.xml を更新します
2. 2 回目の実行で、Spring Web コントローラーを MCP ツールに実際に変換します

✨ 機能

このレシピでは、次の 3 つの主要コンポーネントに分けて、複数の変換を実行します。

1. POM の更新（UpdatePom）

• Spring Snapshots リポジトリ（https://repo.spring.io/snapshot）を追加します
• Central Portal Snapshots リポジトリ（https://central.sonatype.com/repository/maven-snapshots/）を追加します
• Spring AI MCP サーバー WebMVC の依存関係（spring-ai-starter-mcp-server-webmvc）を追加します

2. コード変換

• AddToolAnnotationToMappingMethod：Spring Web コントローラーメソッドを MCP ツールに自動変換します

  • Spring Web のマッピングアノテーション（@GetMapping、@PostMapping など）が付与されたメソッドに @Tool アノテーションを追加します
  • JavaDoc コメントからメソッドの説明を抽出し、description 属性に設定します
  • メソッドパラメーターに @ToolParam アノテーションを追加し、JavaDoc の説明を保持します

• AddToolCallbackProviderBean：MCP ツールを登録する Bean を作成または更新します

  • Spring Boot アプリケーションのエントリポイントクラスを特定します
  • @Tool アノテーションが付与されたすべてのコントローラーを登録する ToolCallbackProvider Bean を作成します
  • 既存のプロバイダー Bean がある場合は、適切に更新します

• AddSpringAIMcpProperties：MCP サーバーのプロパティを設定します

  • application.properties または application.yml に必要な MCP サーバー設定を追加します
  • サーバー名、バージョン、タイプ、メッセージエンドポイントを設定します
  • YAML 形式と Properties ファイル形式の両方をサポートします

🧪 例

変換前（Spring Web コントローラー）

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    /**
     * Get a user by ID
     * @param id The user identifier
     * @return The user details
     */
    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        // Implementation
    }
}

変換後（MCP ツール）

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    /**
     * Get a user by ID
     * @param id The user identifier
     * @return The user details
     */
    @GetMapping("/{id}")
    @Tool(description = "Get a user by ID")
    public User getUserById(@ToolParam(description = "The user identifier") @PathVariable Long id) {
        // Implementation
    }
}

生成される MCP 設定

レシピは、アプリケーションのプロパティに MCP サーバー設定も自動で追加します。

spring.ai.mcp.server.name=webmvc-mcp-server
spring.ai.mcp.server.sse-message-endpoint=/mcp/messages
spring.ai.mcp.server.type=SYNC
spring.ai.mcp.server.version=1.0.0

また、Spring Boot アプリケーションクラスに ToolCallbackProvider Bean を追加して、ツールを自動で登録します。

@Bean
ToolCallbackProvider toolCallbackProvider(UserController userController) {
    return MethodToolCallbackProvider.builder()
            .toolObjects(userController)
            .build();
}

🌟 デモ

変換可能な状態のサンプル Spring Boot 3 REST API プロジェクトで、この変換ツールをお試しいただけます。

サンプルプロジェクトのセットアップ

1. サンプルプロジェクトをクローンします：

   git clone https://github.com/addozhang/spring-boot-3-rest-api-sample.git
   cd spring-boot-3-rest-api-sample
   

2. サンプルプロジェクトの構成を確認します：

   • REST コントローラーを備えた標準的な Spring Boot 3 アプリケーションです
   • さまざまな HTTP メソッド（GET、POST、PUT、DELETE）を使用する一般的な REST エンドポイントが含まれています
   • MCP ツールの説明に変換される、適切な JavaDoc コメントが含まれています

変換プロセス

1. まず、必要な依存関係を追加するために Maven コマンドを実行して、POM ファイルを更新します：

   mvn org.openrewrite.maven:rewrite-maven-plugin:6.4.0:run \
     -Drewrite.activeRecipes=RewriteWebToMCP \
     -Drewrite.recipeArtifactCoordinates=com.atbug.rewrite:spring-rest-to-mcp:1.0-SNAPSHOT \
     -Drewrite.exportDatatables=true
   

2. 次に、同じコマンドをもう一度実行して、実際のコード変換を行います：

   mvn org.openrewrite.maven:rewrite-maven-plugin:6.4.0:run \
     -Drewrite.activeRecipes=RewriteWebToMCP \
     -Drewrite.recipeArtifactCoordinates=com.atbug.rewrite:spring-rest-to-mcp:1.0-SNAPSHOT \
     -Drewrite.exportDatatables=true
   

3. 変更を確認します：

   • コントローラークラスに追加された @Tool および @ToolParam アノテーションを確認します
   • メインアプリケーションクラスに新しい ToolCallbackProvider Bean が追加されていることを確認します
   • application.properties または application.yml に MCP サーバーの設定があることを確認します

4. アプリケーションを実行します：

   mvn spring-boot:run
   

5. 公式の MCP Inspector を使用して MCP サーバーをテストします：

   • MCP Inspector リポジトリをクローンします：

     git clone https://github.com/modelcontextprotocol/inspector.git
     cd inspector
     

   • 依存関係をインストールし、Inspector を起動します：

     npm install
     npm run dev
     

   • ブラウザーで http://localhost:5173/ にアクセスして Inspector を開きます
   • 左側のパネルで、次の設定を使用して MCP サーバーを構成します：
     • 種類：SSE
     • アドレス：http://localhost:8080/sse
   • 接続すると、次の操作ができます：
     • メインパネルですべての利用可能なツールを確認する
     • 各ツールを対話形式でテストする
     • MCP サーバーからの応答を確認する

期待される動作

変換後、Spring Boot アプリケーションは従来の REST API と MCP サーバーの両方として機能します。つまり、次のようになります：

• 既存のすべてのエンドポイントは、これまでどおり動作します
• MCP プロトコルに対応したアプリケーションは、API を検出して操作できます
• AI アシスタントは、MCP プロトコルの標準化された形式を通じて、ツールの使用方法を理解できます

MCP サーバーを利用するアプリケーションは、次のような設定で接続するよう構成できます：

{
  "mcpServers": {
    "spring-ai-mcp-sample": {
      "autoApprove": [],
      "disabled": false,
      "timeout": 60,
      "url": "http://localhost:8080/sse",
      "transportType": "sse"
    }
  }
}

これにより、クライアントアプリケーションは、変換された API が提供するツールをシームレスに検出して利用できます。

📄 ライセンス

このプロジェクトは Apache License 2.0 のもとでライセンスされています。詳細については LICENSE ファイルを参照してください。

👥 コントリビューション

コントリビューションを歓迎します！お気軽に Pull Request を送信してください。

📞 サポート

ご質問やサポートが必要な場合は、GitHub で issue を作成してください。