このバージョンはまだ開発中であり、まだ安定しているとは考えられていません。最新のスナップショットバージョンについては、Spring AI 1.1.2 を使用してください。

MCP アノテーション

Spring AI MCP アノテーションモジュールは、Java でモデルコンテキストプロトコル (MCP) [GitHub] (英語) サーバーおよびクライアント向けのアノテーションベースのメソッド処理を提供します。Java アノテーションを用いたクリーンで宣言的なアプローチにより、MCP サーバーメソッドとクライアントハンドラーの作成と登録を簡素化します。

 The MCP Annotations enable developers to create and register MCP operation handlers using declarative annotations.
This approach simplifies implementing MCP server and client functionality by reducing boilerplate code and improving maintainability.

このライブラリは MCP Java SDK [GitHub] (英語) をベースに構築され、MCP サーバーおよびクライアントを実装するための、より高レベルのアノテーションベースのプログラミングモデルを提供します。

アーキテクチャー

MCP アノテーションモジュールは次のものから構成されます。

サーバーアノテーション

MCP サーバーの場合、次のアノテーションが提供されます。

  • @McpTool - 自動 JSON スキーマ生成を備えた MCP ツールを実装します

  • @McpResource - URI テンプレートを介してリソースへのアクセスを提供します

  • @McpPrompt - プロンプトメッセージを生成する

  • @McpComplete - 自動補完機能を提供する

クライアントアノテーション

MCP クライアントには、次のアノテーションが提供されます。

  • @McpLogging - ログメッセージ通知を処理する

  • @McpSampling - サンプリングリクエストを処理する

  • @McpElicitation - 追加情報を収集するための情報開示リクエストを処理する

  • @McpProgress - 長時間実行される操作中に進行状況通知を処理します

  • @McpToolListChanged - ツールリストの変更通知を処理します

  • @McpResourceListChanged - リソースリストの変更通知を処理します

  • @McpPromptListChanged - プロンプトリストの変更通知を処理します

特別なパラメーターとアノテーション

  • McpSyncRequestContext - 同期操作用の特別なパラメーター型で、MCP リクエストコンテキスト（元のリクエスト、サーバーエクスチェンジ（ステートフル操作の場合）、トランスポートコンテキスト（ステートレス操作の場合）、ログ記録、進捗状況、サンプリング、抽出のための便利なメソッドなど）にアクセスするための統一インターフェースを提供します。このパラメーターは自動的に挿入され、JSON スキーマ生成から除外されます。Complete、Prompt、Resource、Tool メソッドでサポートされています。

  • McpAsyncRequestContext - 非同期操作用の特別なパラメーター型。McpSyncRequestContext と同じ統一インターフェースを提供しますが、戻り値はリアクティブ（Mono ベース）です。このパラメーターは自動的に挿入され、JSON スキーマ生成から除外されます。Complete、Prompt、Resource、Tool メソッドでサポートされています。

  • McpTransportContext - 完全なサーバー交換機能を使用せずに、トランスポートレベルのコンテキストへの軽量アクセスを提供する、ステートレス操作用の特別なパラメーター型。このパラメーターは自動的に挿入され、JSON スキーマ生成から除外されます。

  • @McpProgressToken - リクエストからプログレストークンを受け取るためのメソッドパラメーターをマークします。このパラメーターは自動的に挿入され、生成された JSON スキーマからは除外されます。注 : McpSyncRequestContext または McpAsyncRequestContext を使用する場合、このアノテーションの代わりに ctx.request().progressToken() を介してプログレストークンにアクセスできます。

  • McpMeta - MCP リクエスト、通知、結果からのメタデータへのアクセスを提供する特別なパラメーター型です。このパラメーターは自動的に挿入され、パラメーター数制限および JSON スキーマ生成から除外されます。注 : McpSyncRequestContext または McpAsyncRequestContext を使用する場合、メタデータは ctx.requestMeta() を介して取得できます。

入門

依存関係

プロジェクトに MCP アノテーションの依存関係を追加します。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mcp-annotations</artifactId>
</dependency>

MCP Boot スターターのいずれかを使用すると、MCP アノテーションが自動的に含められます。

  • spring-ai-starter-mcp-client

  • spring-ai-starter-mcp-client-webflux

  • spring-ai-starter-mcp-server

  • spring-ai-starter-mcp-server-webflux

  • spring-ai-starter-mcp-server-webmvc

構成

MCPBoot スターターを使用する場合、アノテーションスキャンはデフォルトで有効になっています。スキャンの動作は、以下のプロパティを使用して設定できます。

クライアントアノテーションスキャナ 

spring:
  ai:
    mcp:
      client:
        annotation-scanner:
          enabled: true  # Enable/disable annotation scanning

サーバーアノテーションスキャナ 

spring:
  ai:
    mcp:
      server:
        annotation-scanner:
          enabled: true  # Enable/disable annotation scanning

簡単な例

MCP アノテーションを使用して計算ツールを作成する簡単な例を次に示します。

@Component
public class CalculatorTools {

    @McpTool(name = "add", description = "Add two numbers together")
    public int add(
            @McpToolParam(description = "First number", required = true) int a,
            @McpToolParam(description = "Second number", required = true) int b) {
        return a + b;
    }

    @McpTool(name = "multiply", description = "Multiply two numbers")
    public double multiply(
            @McpToolParam(description = "First number", required = true) double x,
            @McpToolParam(description = "Second number", required = true) double y) {
        return x * y;
    }
}

ログ記録用のシンプルなクライアントハンドラー:

@Component
public class LoggingHandler {

    @McpLogging(clients = "my-server")
    public void handleLoggingMessage(LoggingMessageNotification notification) {
        System.out.println("Received log: " + notification.level() +
                          " - " + notification.data());
    }
}

Spring Boot 自動構成により、これらのアノテーション付き Bean は自動的に検出され、MCP サーバーまたはクライアントに登録されます。

ドキュメント

追加リソース