Spring AI Weather Server

Um servidor MCP que fornece ferramentas meteorológicas da API do National Weather Service (weather.gov), construído com Spring Boot.

GitHubExperimente este MCPPatrocinado

Documentação

‼️IMPORTANTE‼️

O código-fonte deste projeto é: spring-ai-examples | starter-stdio-server, e a LICENÇA DE CÓDIGO ABERTO segue o projeto original.

A fonte do código deste projeto: spring-ai-examples | starter-stdio-server, a licença de código aberto segue o projeto original.

Spring AI MCP Weather STDIO Server

Um projeto inicial Spring Boot que demonstra como construir um servidor Model Context Protocol (MCP) que fornece ferramentas relacionadas ao clima usando a API do National Weather Service (weather.gov). Este projeto mostra as capacidades do Spring AI MCP Server Boot Starter com implementação de transporte STDIO.

Para mais informações, consulte a documentação de referência do MCP Server Boot Starter.

Pré-requisitos

  • Java 17 ou posterior
  • Maven 3.6 ou posterior
  • Compreensão dos conceitos de Spring Boot e Spring AI
  • (Opcional) Claude Desktop para integração com assistente de IA

Sobre o Spring AI MCP Server Boot Starter

O spring-ai-mcp-server-spring-boot-starter fornece:

  • Configuração automática dos componentes do servidor MCP
  • Suporte para modos de operação síncronos e assíncronos
  • Implementação da camada de transporte STDIO
  • Registro flexível de ferramentas através de beans Spring
  • Capacidades de notificação de alterações

Estrutura do Projeto

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

Compilação e Execução

O servidor usa o modo de transporte STDIO e normalmente é iniciado automaticamente pelo cliente. Para compilar o jar do servidor:

./mvnw clean install -DskipTests

Implementação de Ferramentas

O projeto demonstra como implementar e registrar ferramentas MCP usando injeção de dependência e auto-configuração do Spring:

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

A auto-configuração registra automaticamente essas ferramentas no servidor MCP. Você pode ter vários beans produzindo listas de ToolCallbacks, e a auto-configuração os mesclará.

Ferramentas Disponíveis

1. Ferramenta de Previsão do Tempo

@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. Ferramenta de Alertas Meteorológicos

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

Integração com o Cliente

Exemplo de Cliente Java

Criar Cliente MCP Manualmente

// 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();

O ClientStdio.java demonstra como implementar um cliente MCP manualmente.

Para uma melhor experiência de desenvolvimento, considere usar os MCP Client Boot Starters. Esses starters permitem a auto-configuração de múltiplas conexões STDIO e/ou SSE para servidores MCP. Veja os projetos starter-default-client e starter-webflux-client para exemplos.

Usar o MCP Client Boot Starter

Use o starter-default-client para conectar-se ao starter-stdio-server do clima:

  1. Siga as instruções do readme starter-default-client para compilar um aplicativo cliente mcp-starter-default-client-0.0.1-SNAPSHOT.jar.

  2. Execute o cliente usando o arquivo de configuração:

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

Integração com Claude Desktop

Para integrar com o Claude Desktop, adicione a seguinte configuração às suas configurações do 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/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

Substitua /absolute/path/to/ pelo caminho real do seu arquivo jar compilado.

Configuração

Propriedades da Aplicação

Todas as propriedades são prefixadas com 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=mcp-weather-stdio-server.log

Notas de Configuração Importantes

  1. Requisitos do Modo STDIO

    • Desative o tipo de aplicação web (spring.main.web-application-type=none)
    • Desative o banner do Spring (spring.main.banner-mode=off)
    • Limpe o padrão de log do console (logging.pattern.console=)

  2. Tipo de Servidor

    • SYNC (padrão): Usa McpSyncServer para padrões simples de requisição-resposta
    • ASYNC: Usa McpAsyncServer para operações não bloqueantes com suporte a Project Reactor

Recursos Adicionais