Spring AI Weather Server

Un servidor MCP que proporciona herramientas meteorológicas de la API del Servicio Meteorológico Nacional (weather.gov), construido con Spring Boot.

GitHubPrueba este MCPPatrocinado

Documentación

‼️IMPORTANTE‼️

El código fuente de este proyecto es: spring-ai-examples | starter-stdio-server, y la LICENCIA DE CÓDIGO ABIERTO sigue al proyecto original.

El código fuente de este proyecto es: spring-ai-examples | starter-stdio-server, la licencia de código abierto sigue al proyecto original.

Spring AI MCP Weather STDIO Server

Un proyecto inicial de Spring Boot que demuestra cómo construir un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona herramientas relacionadas con el clima utilizando la API del Servicio Meteorológico Nacional (weather.gov). Este proyecto muestra las capacidades del Spring AI MCP Server Boot Starter con implementación de transporte STDIO.

Para más información, consulte la documentación de referencia del MCP Server Boot Starter.

Requisitos previos

  • Java 17 o posterior
  • Maven 3.6 o posterior
  • Comprensión de los conceptos de Spring Boot y Spring AI
  • (Opcional) Claude Desktop para la integración con asistentes de IA

Acerca de Spring AI MCP Server Boot Starter

El spring-ai-mcp-server-spring-boot-starter proporciona:

  • Configuración automática de los componentes del servidor MCP
  • Soporte para modos de operación síncronos y asíncronos
  • Implementación de la capa de transporte STDIO
  • Registro flexible de herramientas a través de beans de Spring
  • Capacidades de notificación de cambios

Estructura del proyecto

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

Compilación y ejecución

El servidor utiliza el modo de transporte STDIO y normalmente lo inicia automáticamente el cliente. Para compilar el jar del servidor:

./mvnw clean install -DskipTests

Implementación de herramientas

El proyecto demuestra cómo implementar y registrar herramientas MCP utilizando la inyección de dependencias y la auto-configuración de 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);
    }
}

La auto-configuración registra automáticamente estas herramientas con el servidor MCP. Puede tener múltiples beans que produzcan listas de ToolCallbacks, y la auto-configuración los fusionará.

Herramientas disponibles

1. Herramienta de pronóstico del clima

@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. Herramienta de alertas meteorológicas

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

Integración con clientes

Ejemplo de cliente Java

Crear un 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();

El archivo ClientStdio.java demuestra cómo implementar un cliente MCP manualmente.

Para una mejor experiencia de desarrollo, considere utilizar los MCP Client Boot Starters. Estos starters permiten la auto-configuración de múltiples conexiones STDIO y/o SSE a servidores MCP. Consulte los proyectos starter-default-client y starter-webflux-client para ver ejemplos.

Usar MCP Client Boot Starter

Utilice el starter-default-client para conectarse al starter-stdio-server de clima:

  1. Siga las instrucciones del readme de starter-default-client para compilar una aplicación cliente de mcp-starter-default-client-0.0.1-SNAPSHOT.jar.

  2. Ejecute el cliente utilizando el archivo de configuración:

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

Integración con Claude Desktop

Para integrarse con Claude Desktop, agregue la siguiente configuración a la configuración de 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"
      ]
    }
  }
}

Reemplace /absolute/path/to/ con la ruta real a su archivo jar compilado.

Configuración

Propiedades de la aplicación

Todas las propiedades tienen el prefijo 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 clave de configuración

  1. Requisitos del modo STDIO

    • Deshabilitar el tipo de aplicación web (spring.main.web-application-type=none)
    • Deshabilitar el banner de Spring (spring.main.banner-mode=off)
    • Limpiar el patrón de registro de consola (logging.pattern.console=)

  2. Tipo de servidor

    • SYNC (predeterminado): Utiliza McpSyncServer para patrones simples de solicitud-respuesta
    • ASYNC: Utiliza McpAsyncServer para operaciones no bloqueantes con soporte de Project Reactor

Recursos adicionales