weather-mcp-server

AlexCevallosC/weather-mcp-server

3.2

If you are the rightful owner of weather-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Weather MCP Server is a Spring Boot application that implements the Model Context Protocol (MCP) to provide real-time weather data integration with Amazon Q Developer.

Tools
1
Resources
0
Prompts
0

Weather MCP Server

📋 Descripción del Proyecto

Weather MCP Server es un servidor de protocolo MCP (Model Context Protocol) desarrollado con Spring Boot y Spring AI que proporciona funcionalidades meteorológicas en tiempo real. Este servidor está diseñado para integrarse con Amazon Q Developer, permitiendo consultas de temperatura basadas en coordenadas geográficas.

El proyecto implementa el protocolo MCP para facilitar la comunicación entre Amazon Q y servicios externos, específicamente para obtener datos meteorológicos de la API de Open-Meteo.

🏗️ Arquitectura del Sistema

Diagrama de Arquitectura General

graph TB
    subgraph "Amazon Q Developer"
        AQ[Amazon Q CLI]
        QC[Q Chat Interface]
    end
    
    subgraph "MCP Protocol Layer"
        MCP[MCP Client]
        MCPS[MCP Server Protocol]
    end
    
    subgraph "Weather MCP Server"
        WS[Weather Spring Boot App]
        WT[Weather Tool]
        WServ[Weather Service]
        WM[Weather Model]
    end
    
    subgraph "External APIs"
        OM[Open-Meteo API]
    end
    
    QC --> MCP
    MCP --> MCPS
    MCPS --> WS
    WS --> WT
    WT --> WServ
    WServ --> OM
    
    OM --> WServ
    WServ --> WM
    WM --> WT
    WT --> WS
    WS --> MCPS
    MCPS --> MCP
    MCP --> QC

Diagrama de Flujo de Datos

sequenceDiagram
    participant Q as Amazon Q
    participant MCP as MCP Client
    participant WS as Weather Server
    participant WT as Weather Tool
    participant API as Open-Meteo API
    
    Q->>MCP: weather-get-temperature(lat, lon)
    MCP->>WS: HTTP Request /mcp
    WS->>WT: @McpTool invocation
    WT->>API: GET forecast?latitude={lat}&longitude={lon}
    API-->>WT: Weather JSON Response
    WT-->>WS: WeatherResponse object
    WS-->>MCP: MCP Protocol Response
    MCP-->>Q: Temperature data

Diagrama de Componentes

graph LR
    subgraph "Spring Boot Application"
        subgraph "Controller Layer"
            MC[MCP Controller]
        end
        
        subgraph "Tool Layer"
            WT[Weather Tool<br/>@McpTool]
        end
        
        subgraph "Service Layer"
            WS[Weather Service<br/>@Service]
        end
        
        subgraph "Model Layer"
            WR[WeatherResponse<br/>Record]
        end
        
        subgraph "Configuration"
            AC[Application Config<br/>application.yml]
        end
    end
    
    MC --> WT
    WT --> WS
    WS --> WR
    AC --> WS

📁 Estructura del Proyecto

weather-mcp-server/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/vce/demo/mcp/server/
│   │   │       ├── WeatherMcpServerApplication.java    # Clase principal
│   │   │       ├── model/
│   │   │       │   └── WeatherResponse.java            # Modelo de datos
│   │   │       ├── service/
│   │   │       │   └── WeatherService.java             # Lógica de negocio
│   │   │       └── tool/
│   │   │           └── WeatherTool.java                # Herramienta MCP
│   │   └── resources/
│   │       ├── application.yml                         # Configuración principal
│   └── test/
│       └── java/
│           └── com/vce/demo/mcp/server/
│               └── WeatherMcpServerApplicationTests.java
├── target/                                            # Archivos compilados
├── .mvn/                                              # Maven wrapper
├── pom.xml                                            # Configuración Maven
├── .gitignore                                         # Archivos ignorados por Git
└── README.md                                          # Este archivo

🔧 Tecnologías Utilizadas

Core Framework

  • Spring Boot 4.0.0-M1: Framework principal de la aplicación
  • Spring AI 1.1.0-M4: Integración con IA y protocolo MCP
  • Java 25: Versión del lenguaje de programación

Dependencias Principales

  • spring-boot-starter: Configuración básica de Spring Boot
  • spring-ai-starter-mcp-server-webmvc: Soporte para servidor MCP con WebMVC
  • spring-boot-starter-test: Herramientas de testing

APIs Externas

  • Open-Meteo API: Servicio gratuito de datos meteorológicos

⚙️ Configuración

Configuración del Servidor MCP

spring:
  ai:
    mcp:
      server:
        enabled: true
        protocol: STREAMABLE
        name: weather-mcp-server
        version: 0.0.1
        type: SYNC
        streamable-http:
          mcp-endpoint: /mcp
          keep-alive-interval: 30s
        capabilities:
          resource: true
          tool: true
          prompt: true
          completion: true

Configuración del Servicio Weather

custom:
  weather:
    endpoint: https://api.open-meteo.com/v1/forecast?latitude={latitude}&longitude={longitude}&current=temperature_2m

🚀 Instalación y Ejecución

Prerrequisitos

  • Java 25 o superior
  • Maven 3.6+
  • Amazon Q CLI configurado

Pasos de Instalación

  1. Clonar el repositorio
git clone <repository-url>
cd weather-mcp-server
  1. Compilar el proyecto
./mvnw clean compile
  1. Ejecutar tests
./mvnw test
  1. Ejecutar la aplicación
./mvnw spring-boot:run
  1. Generar JAR ejecutable
./mvnw clean package
java -jar target/weather-mcp-server-0.0.1.jar

🔌 Integración con Amazon Q

Configuración del Cliente MCP

Para integrar este servidor con Amazon Q Developer, configura el cliente MCP en el archivo ~/.aws/amazonq/mcp.json:

{
  "mcpServers": {
    "weather-server": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

Uso desde Amazon Q

Una vez configurado, puedes usar la herramienta desde Amazon Q:

Q: ¿Cuál es la temperatura en Guayaquil?
# Amazon Q utilizará automáticamente weather-get-temperature(-2.1894, -79.889)

Q: Dame el clima en Quito
# Amazon Q utilizará weather-get-temperature(-0.1807, -78.4678)

📊 API Reference

Weather Tool

weather-get-temperature

Obtiene la temperatura actual para una ubicación específica.

Parámetros:

  • latitude (double): Latitud de la ubicación
  • longitude (double): Longitud de la ubicación

Respuesta:

{
  "current": {
    "time": "2024-11-06T03:00:00",
    "interval": 900,
    "temperature_2m": 15.2
  }
}

🔍 Logging y Debugging

El proyecto incluye logging detallado para facilitar el debugging:

logging:
  level:
    com.vce.demo.mcp: DEBUG
    org.springframework.ai: DEBUG

Los logs incluyen:

  • Solicitudes de temperatura con coordenadas
  • Respuestas de la API externa
  • Información del protocolo MCP

🧪 Testing

Ejecutar Tests

./mvnw test

Test de Integración

El proyecto incluye tests de integración que verifican:

  • Carga correcta del contexto de Spring
  • Configuración del servidor MCP
  • Funcionalidad de las herramientas

Versión: 0.0.1
Última actualización: Noviembre 2025
Compatibilidad: Amazon Q Developer, Spring Boot 4.0.0-M1, Spring AI 1.1.0-M4, Java 25