Spring AI MCP Weather STDIO Server

Spring AI MCP Weather STDIO Server

National Weather Service（weather.gov）API を使用して、天気関連のツールを提供する Model Context Protocol（MCP）サーバーの構築方法を紹介する Spring Boot のスタータープロジェクトです。このプロジェクトでは、STDIO トランスポートを実装し、Spring AI MCP Server Boot Starter の機能を紹介します。

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

前提条件

• Java 17 以降
• Maven 3.6 以降
• Spring Boot と Spring AI の概念に関する知識
• （任意）AI アシスタントとの連携用の Claude Desktop

Spring AI MCP Server Boot Starter について

spring-ai-mcp-server-spring-boot-starter は、次の機能を提供します。

• MCP サーバーコンポーネントの自動設定
• 同期モードと非同期モードの両方をサポート
• STDIO トランスポート層の実装
• Spring Bean による柔軟なツール登録
• 変更通知機能

プロジェクト構成

Spring AI MCP Server Boot Starter について

spring-ai-mcp-server-spring-boot-starter は、次の機能を提供します。

• MCP サーバーコンポーネントの自動設定
• 同期モードと非同期モードの両方をサポート
• STDIO トランスポート層の実装
• Spring Bean による柔軟なツール登録
• 変更通知機能

プロジェクト構成

src/
├── main/
│   ├── java/
│   │   └── org/springframework/ai/mcp/sample/server/
│   │       ├── McpServerApplication.java    # Main application class with tool registration
│   │       └── WeatherService.java          # Weather service implementation with MCP tools
│   └── resources/
│       └── application.properties           # Server and transport configuration
└── test/
    └── java/
        └── org/springframework/ai/mcp/sample/client/
            └── ClientStdio.java             # Test client implementation

ビルドと実行

このサーバーは STDIO トランスポートモードを使用し、通常はクライアントによって自動的に起動されます。サーバーの JAR をビルドするには、次のようにします。

./mvnw clean install -DskipTests

ツールの実装

このプロジェクトでは、Spring の依存性注入と自動設定を使って MCP ツールを実装し、登録する方法を紹介します。

@Service
public class WeatherService {
    @Tool(description = "Get weather forecast for a specific latitude/longitude")
    public String getWeatherForecastBrazil(
        double latitude,   // Latitude coordinate
        double longitude   // Longitude coordinate
    ) {
        // Implementation
    }

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

@SpringBootApplication
public class McpServerApplication {
    @Bean
    public List<ToolCallback> weatherTools(WeatherService weatherService) {
        return ToolCallbacks.from(weatherService);
    }
}

自動設定により、これらのツールは MCP サーバーに自動的に登録されます。ToolCallbacks のリストを生成する Bean は複数作成でき、自動設定によってそれらが統合されます。

利用可能なツール

1. 天気予報ツール

@Tool(description = "Get weather forecast for a specific latitude/longitude")
public String getWeatherForecastBrazil(
    double latitude,   // Latitude coordinate
    double longitude   // Longitude coordinate
) {
    // Returns detailed forecast including:
    // - Temperature and unit
    // - Wind speed and direction
    // - Detailed forecast description
}

// Example usage:
CallToolResult forecast = client.callTool(
    new CallToolRequest("getWeatherForecastBrazil",
        Map.of(
            "latitude", 47.6062,    // Seattle coordinates
            "longitude", -122.3321
        )
    )
);

2. 気象警報ツール

@Tool(description = "Get weather alerts for a US state")
public String getAlerts(
    String state  // Two-letter US state code (e.g., CA, NY)
) {
    // Returns active alerts including:
    // - Event type
    // - Affected area
    // - Severity
    // - Description
    // - Safety instructions
}

// Example usage:
CallToolResult alerts = client.callTool(
    new CallToolRequest("getAlerts",
        Map.of("state", "NY")
    )
);

クライアント連携

Java クライアントの例

MCP クライアントを手動で作成する

// Create server parameters
ServerParameters stdioParams = ServerParameters.builder("java")
    .args("-Dspring.ai.mcp.server.transport=STDIO",
          "-Dspring.main.web-application-type=none",
          "-Dlogging.pattern.console=",
          "-jar",
          "target/my-mcp-stdio-server-0.0.1-SNAPSHOT.jar")
    .build();

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

ClientStdio.java では、MCP クライアントを手動で実装する方法を紹介しています。

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

MCP Client Boot Starter を使用する

starter-default-client を使って、天気情報を提供する starter-stdio-server に接続します。

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

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

java -Dspring.ai.mcp.client.stdio.connections.server1.command=java \
     -Dspring.ai.mcp.client.stdio.connections.server1.args=-jar,/Users/christiantzolov/Dev/projects/spring-ai-examples/model-context-protocol/weather/starter-stdio-server/target/my-mcp-stdio-server-0.0.1-SNAPSHOT.jar \
     -Dai.user.input='What is the weather in NY?' \
     -Dlogging.pattern.console= \
     -jar mcp-starter-default-client-0.0.1-SNAPSHOT.jar

Claude Desktop との連携

Claude Desktop と連携するには、次の設定を Claude Desktop の設定に追加します。

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

/absolute/path/to/ を、ビルドした JAR ファイルの実際のパスに置き換えてください。

設定

アプリケーションプロパティ

すべてのプロパティには spring.ai.mcp.server が接頭辞として付きます。

# Required STDIO Configuration
spring.main.web-application-type=none
spring.main.banner-mode=off
logging.pattern.console=

# Server Configuration
spring.ai.mcp.server.enabled=true
spring.ai.mcp.server.name=my-weather-server
spring.ai.mcp.server.version=0.0.1
# SYNC or ASYNC
spring.ai.mcp.server.type=SYNC
spring.ai.mcp.server.resource-change-notification=true
spring.ai.mcp.server.tool-change-notification=true
spring.ai.mcp.server.prompt-change-notification=true

# Optional file logging
logging.file.name=my-mcp-stdio-server.log

主な設定上の注意点

1. STDIO モードの要件

   • Web アプリケーションタイプを無効にします（spring.main.web-application-type=none）
   • Spring バナーを無効にします（spring.main.banner-mode=off）
   • コンソールのログパターンを空にします（logging.pattern.console=）

2. サーバータイプ

   • SYNC（デフォルト）：シンプルなリクエスト／レスポンスパターン向けに McpSyncServer を使用します
   • ASYNC：Project Reactor をサポートするノンブロッキング処理向けに McpAsyncServer を使用します

追加リソース

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