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

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 - Handles elicitation requests for gathering additional information

  • @McpProgress - Handles progress notifications during long-running operations

  • @McpToolListChanged - Handles tool list change notifications

  • @McpResourceListChanged - Handles resource list change notifications

  • @McpPromptListChanged - Handles prompt list change notifications

Special Parameters and Annotations

  • McpSyncRequestContext - Special parameter type for synchronous operations that provides a unified interface for accessing MCP request context, including the original request, server exchange (for stateful operations), transport context (for stateless operations), and convenient methods for logging, progress, sampling, and elicitation. This parameter is automatically injected and excluded from JSON schema generation. Supported in Complete, Prompt, Resource, and Tool methods。

  • McpAsyncRequestContext - Special parameter type for asynchronous operations that provides the same unified interface as McpSyncRequestContext but with reactive (Mono-based) return types. This parameter is automatically injected and excluded from JSON schema generation. Supported in Complete, Prompt, Resource, and Tool methods。

  • McpTransportContext - Special parameter type for stateless operations that provides lightweight access to transport-level context without full server exchange functionality. This parameter is automatically injected and excluded from JSON schema generation

  • @McpProgressToken - Marks a method parameter to receive the progress token from the request. This parameter is automatically injected and excluded from the generated JSON schema. Note: When using McpSyncRequestContext or McpAsyncRequestContext, the progress token can be accessed via ctx.request().progressToken() instead of using this annotation.

  • McpMeta - Special parameter type that provides access to metadata from MCP requests, notifications, and results. This parameter is automatically injected and excluded from parameter count limits and JSON schema generation. Note: When using McpSyncRequestContext or McpAsyncRequestContext, metadata can be obtained via ctx.requestMeta() instead.

入門

依存関係

Add the MCP annotations dependency to your project:

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

The MCP annotations are automatically included when you use any of the MCP Boot Starters:

  • 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

構成

The annotation scanning is enabled by default when using the MCP Boot Starters. You can configure the scanning behavior using the following properties:

Client Annotation Scanner

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

Server Annotation Scanner

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

簡単な例

Here’s a simple example of using MCP annotations to create a calculator tool:

@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;
    }
}

And a simple client handler for logging:

@Component
public class LoggingHandler {

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

With Spring Boot auto-configuration, these annotated beans are automatically detected and registered with the MCP server or client.

ドキュメント

追加リソース