Labsco
MingGH logo

Spring AI Weather Server

from MingGH

An MCP server providing weather tools from the National Weather Service (weather.gov) API, built with Spring Boot.

๐Ÿ”ฅโœ“ VerifiedFreeQuick setup
#automation#ai-image#git#maps#weather

โ€ผ๏ธIMPORTANTโ€ผ๏ธ

The code source of this project is: spring-ai-examples | starter-stdio-server, and the OPEN SOURCE LICENSE follows the original project.

ๆœฌ้กน็›ฎไปฃ็ ๆฅๆบ๏ผšspring-ai-examples | starter-stdio-server๏ผŒ ๅผ€ๆบ่ฎธๅฏ่ฏ้ตๅพชๅŽŸๅง‹้กน็›ฎ

Spring AI MCP Weather STDIO Server

A Spring Boot starter project demonstrating how to build a Model Context Protocol (MCP) server that provides weather-related tools using the National Weather Service (weather.gov) API. This project showcases the Spring AI MCP Server Boot Starter capabilities with STDIO transport implementation.

For more information, see the MCP Server Boot Starter reference documentation.

About Spring AI MCP Server Boot Starter

The spring-ai-mcp-server-spring-boot-starter provides:

  • Automatic configuration of MCP server components
  • Support for both synchronous and asynchronous operation modes
  • STDIO transport layer implementation
  • Flexible tool registration through Spring beans
  • Change notification capabilities

Project Structure

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

Tool Implementation

The project demonstrates how to implement and register MCP tools using Spring's dependency injection and auto-configuration:

@Service
public class WeatherService {
    @Tool(description = "Get weather forecast for a specific latitude/longitude")
    public String getWeatherForecastByLocation(
        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);
    }
}

The auto-configuration automatically registers these tools with the MCP server. You can have multiple beans producing lists of ToolCallbacks, and the auto-configuration will merge them.

Available Tools

1. Weather Forecast Tool

@Tool(description = "Get weather forecast for a specific latitude/longitude")
public String getWeatherForecastByLocation(
    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("getWeatherForecastByLocation",
        Map.of(
            "latitude", 47.6062,    // Seattle coordinates
            "longitude", -122.3321
        )
    )
);

2. Weather Alerts Tool

@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")
    )
);

Client Integration

Java Client Example

Create MCP Client Manually

// 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/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar")
    .build();

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

The ClientStdio.java demonstrates how to implement an MCP client manually.

For a better development experience, consider using the MCP Client Boot Starters. These starters enable auto-configuration of multiple STDIO and/or SSE connections to MCP servers. See the starter-default-client and starter-webflux-client projects for examples.

Use MCP Client Boot Starter

Use the starter-default-client to connect to the weather starter-stdio-server:

  1. Follow the starter-default-client readme instructions to build a mcp-starter-default-client-0.0.1-SNAPSHOT.jar client application.

  2. Run the client using the configuration file:

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/mcp-weather-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 Integration

To integrate with Claude Desktop, add the following configuration to your Claude Desktop settings:

{
  "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/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

Replace /absolute/path/to/ with the actual path to your built jar file.

Additional Resources