Spring AI MCP Weather Server Sample with WebMVC Starter

Spring AI MCP Weather Server Sample with WebMVC Starter

このサンプルプロジェクトでは、WebMVC トランスポートを使用して Spring AI MCP Server Boot Starter で MCP サーバーを作成する方法を紹介します。National Weather Service API を使用して天気情報を取得するツールを公開する天気サービスを実装します。

詳細については、MCP Server Boot Starter のリファレンスドキュメントをご覧ください。

概要

このサンプルでは、次の内容を紹介します。

• spring-ai-mcp-server-webmvc-spring-boot-starter との統合
• SSE（Server-Sent Events）と STDIO の両トランスポートをサポート
• Spring AI の @Tool アノテーションを使用したツールの自動登録
• 天気関連の 2 つのツール：
  • 位置情報（緯度／経度）による天気予報の取得
  • 米国の州ごとの気象警報の取得

依存関係

このプロジェクトには Spring AI MCP Server WebMVC Boot Starter が必要です。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mcp-server-webmvc-spring-boot-starter</artifactId>
</dependency>

このスターターには、次の機能が含まれます。

• Spring MVC を使用した HTTP ベースのトランスポート（WebMvcSseServerTransport）
• SSE エンドポイントの自動構成
• オプションの STDIO トランスポート
• spring-boot-starter-web および mcp-spring-webmvc 依存関係

プロジェクトのビルド

Maven を使用してプロジェクトをビルドします。

./mvnw clean install -DskipTests

サーバーの実行

サーバーは 2 種類のトランスポートモードをサポートしています。

WebMVC SSE モード（デフォルト）

java -jar target/mcp-weather-starter-webmvc-server-0.0.1-SNAPSHOT.jar

STDIO モード

STDIO トランスポートを有効にするには、適切なプロパティを設定します。

java -Dspring.ai.mcp.server.stdio=true -Dspring.main.web-application-type=none -jar target/mcp-weather-starter-webmvc-server-0.0.1-SNAPSHOT.jar

構成

application.properties を使用してサーバーを構成します。

# Server identification
spring.ai.mcp.server.name=my-weather-server
spring.ai.mcp.server.version=0.0.1

# Server type (SYNC/ASYNC)
spring.ai.mcp.server.type=SYNC

# Transport configuration
spring.ai.mcp.server.stdio=false
spring.ai.mcp.server.sse-message-endpoint=/mcp/message

# Change notifications
spring.ai.mcp.server.resource-change-notification=true
spring.ai.mcp.server.tool-change-notification=true
spring.ai.mcp.server.prompt-change-notification=true

# Logging (required for STDIO transport)
spring.main.banner-mode=off
logging.file.name=./target/starter-webmvc-server.log

利用可能なツール

天気予報ツール

• 名前：getWeatherForecastByLocation
• 説明：指定した緯度／経度の天気予報を取得します
• パラメーター：
  • latitude：double - 緯度座標
  • longitude：double - 経度座標

気象警報ツール

• 名前：getAlerts
• 説明：米国の州の気象警報を取得します
• パラメーター：
  • state：String - 2 文字の米国州コード（例：CA、NY）

サーバーの実装

このサーバーでは、Spring Boot と Spring AI のツールアノテーションを使用してツールを自動登録します。

@SpringBootApplication
public class McpServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(McpServerApplication.class, args);
    }

    @Bean
    public ToolCallbackProvider weatherTools(WeatherService weatherService){
      return MethodToolCallbackProvider.builder().toolObjects(weatherService).build();
    }
}

WeatherService は @Tool アノテーションを使用して天気ツールを実装します。

@Service
public class WeatherService {
    @Tool(description = "Get weather forecast for a specific latitude/longitude")
    public String getWeatherForecastByLocation(double latitude, double longitude) {
        // Implementation using weather.gov API
    }

    @Tool(description = "Get weather alerts for a US state. Input is Two-letter US state code (e.g., CA, NY)")
    public String getAlerts(String state) {
        // Implementation using weather.gov API
    }
}

MCP クライアント

STDIO または SSE トランスポートを使用して天気サーバーに接続できます。

手動クライアント

WebMVC SSE クライアント

SSE トランスポートを使用するサーバーの場合：

var transport = new HttpClientSseClientTransport("http://localhost:8080");
var client = McpClient.sync(transport).build();

STDIO クライアント

STDIO トランスポートを使用するサーバーの場合：

var stdioParams = ServerParameters.builder("java")
        .args("-Dspring.ai.mcp.server.stdio=true",
                "-Dspring.main.web-application-type=none",
                "-Dspring.main.banner-mode=off",
                "-Dlogging.pattern.console=",
                "-jar",
                "target/mcp-weather-starter-webmvc-server-0.0.1-SNAPSHOT.jar")
        .build();

var transport = new StdioClientTransport(stdioParams);
var client = McpClient.sync(transport).build();

サンプルプロジェクトには、クライアントの実装例が含まれています。

• SampleClient.java：手動で実装した MCP クライアント
• ClientStdio.java：STDIO トランスポート接続
• ClientSse.java：SSE トランスポート接続

より快適な開発環境を実現するには、MCP Client Boot Starters の利用を検討してください。これらのスターターを使用すると、MCP サーバーへの複数の STDIO および／または SSE 接続を自動構成できます。例については、starter-default-client プロジェクトをご覧ください。

Boot Starter クライアント

starter-default-client クライアントを使用して、天気の starter-webmvc-server に接続してみましょう。

starter-default-client の README の手順に従って、クライアントアプリケーション mcp-starter-default-client-0.0.1-SNAPSHOT.jar をビルドします。

STDIO トランスポート

1. 次の内容で mcp-servers-config.json 構成ファイルを作成します。

{
  "mcpServers": {
    "weather-starter-webmvc-server": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-Dspring.main.web-application-type=none",
        "-Dlogging.pattern.console=",
        "-jar",
        "/absolute/path/to/mcp-weather-starter-webmvc-server-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

2. 構成ファイルを使用してクライアントを実行します。

java -Dspring.ai.mcp.client.stdio.servers-configuration=file:mcp-servers-config.json \
 -Dai.user.input='What is the weather in NY?' \
 -Dlogging.pattern.console= \
 -jar mcp-starter-default-client-0.0.1-SNAPSHOT.jar

SSE（WebMVC）トランスポート

1. mcp-weather-starter-webmvc-server を起動します。

java -jar mcp-weather-starter-webmvc-server-0.0.1-SNAPSHOT.jar

これにより、ポート 8080 で MCP サーバーが起動します。

2. 別のコンソールで、SSE トランスポートを構成したクライアントを起動します。

java -Dspring.ai.mcp.client.sse.connections.weather-server.url=http://localhost:8080 \
 -Dlogging.pattern.console= \
 -Dai.user.input='What is the weather in NY?' \
 -jar mcp-starter-default-client-0.0.1-SNAPSHOT.jar

追加リソース

• Spring AI ドキュメント
• MCP サーバー Boot スターター
• MCP クライアント Boot スターター
• Model Context Protocol 仕様
• Spring Boot 自動構成