weather-mcp

Servidor MCP para consultar el tiempo en cualquier ciudad del mundo, usando la API gratuita de Open-Meteo. Sin registro, sin API key.

---

Arquitectura y componentes

┌─────────────────────────────────────────────────────────────────┐
│                        Claude Code / IA                         │
│                  (cliente MCP — cualquier host)                 │
└────────────────────────┬────────────────────────────────────────┘
                         │  stdio (JSON-RPC)
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                      weather-mcp (este servidor)                │
│                                                                 │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │                    MCP Server                           │   │
│   │         @modelcontextprotocol/sdk  +  Zod               │   │
│   │                                                         │   │
│   │  ┌─────────────────┐  ┌─────────────────┐              │   │
│   │  │get_current_      │  │  get_forecast   │              │   │
│   │  │weather           │  │  (1–7 días)     │              │   │
│   │  └────────┬────────┘  └────────┬────────┘              │   │
│   │           │                    │                        │   │
│   │  ┌────────▼────────────────────▼────────┐              │   │
│   │  │         get_uv_and_air               │              │   │
│   │  │    (índice UV + calidad del aire)    │              │   │
│   │  └──────────────────┬───────────────────┘              │   │
│   │                     │                                   │   │
│   │  ┌──────────────────▼───────────────────┐              │   │
│   │  │           Geocoding helper            │              │   │
│   │  │  ciudad → latitud / longitud          │              │   │
│   │  └──────────────────┬───────────────────┘              │   │
│   └─────────────────────┼───────────────────────────────────┘   │
└─────────────────────────┼───────────────────────────────────────┘
                          │  HTTPS (fetch nativo Node 18+)
          ┌───────────────┼───────────────────────┐
          ▼               ▼                       ▼
┌──────────────┐ ┌────────────────┐ ┌─────────────────────────┐
│  Geocoding   │ │    Forecast    │ │      Air Quality         │
│  API         │ │    API         │ │      API                 │
│  open-meteo  │ │  open-meteo   │ │  air-quality.open-meteo  │
└──────────────┘ └────────────────┘ └─────────────────────────┘

Flujo de una consulta

IA: "¿Qué tiempo hace en Bogotá?"
        │
        ▼
1. MCP llama get_current_weather({ city: "Bogotá" })
        │
        ▼
2. geocodeCity("Bogotá")
   → GET geocoding-api.open-meteo.com/v1/search
   ← { latitude: 4.71, longitude: -74.07, country: "Colombia" }
        │
        ▼
3. GET api.open-meteo.com/v1/forecast
   ← temperatura, humedad, viento, código WMO, precipitación
        │
        ▼
4. Respuesta formateada en texto legible
   → IA la presenta al usuario

---

Estructura del proyecto

weather-mcp/
├── src/
│   ├── index.ts          # Entrada: registro de herramientas MCP y arranque del servidor
│   ├── handlers.ts       # Lógica de negocio de las 3 herramientas (testeable de forma aislada)
│   ├── weather.ts        # Utilidades puras: geocodeCity, describeWeather, WMO_CODES
│   └── __tests__/
│       ├── weather.test.ts    # Tests de geocodificación y códigos WMO (9 tests)
│       └── handlers.test.ts   # Tests de herramientas con fetch mockeado (31 tests)
├── vitest.config.ts      # Configuración de tests y umbrales de cobertura (≥80%)
├── tsconfig.json
└── package.json

---

Herramientas utilizadas

Herramienta	Versión	Propósito
TypeScript	5.8	Lenguaje principal
@modelcontextprotocol/sdk	1.13	Protocolo MCP (servidor stdio)
Zod	3.24	Validación de esquemas de herramientas
tsx	4.19	Ejecución directa de TypeScript en desarrollo
Vitest	3.x	Framework de tests unitarios
@vitest/coverage-v8	3.x	Cobertura de código con motor V8
Open-Meteo Forecast API	—	Datos meteorológicos actuales y pronóstico
Open-Meteo Geocoding API	—	Conversión ciudad → coordenadas
Open-Meteo Air Quality API	—	Índice UV y calidad del aire

---

Instalación

Requisitos

• Node.js 18 o superior
• Claude Code CLI (npm install -g @anthropic-ai/claude-code)

Pasos

# 1. Clonar el repositorio
git clone https://github.com/relativismofisico/weather-mcp.git
cd weather-mcp

# 2. Instalar dependencias y compilar
npm install
npm run build

# 3. Registrar en Claude Code (global — disponible en cualquier proyecto)
claude mcp add weather --transport stdio --scope user -- node /ruta/absoluta/weather-mcp/dist/index.js

En Windows usa la ruta completa con barras normales: node C:/Users/TuUsuario/weather-mcp/dist/index.js

Verificar la instalación

claude mcp list
# weather: node .../dist/index.js - ✔ Connected

---

Uso desde una IA

Una vez registrado, abre una nueva conversación en Claude Code. Las herramientas estarán disponibles automáticamente. Puedes pedirle a la IA:

Tiempo actual

"¿Qué tiempo hace en Buenos Aires?" "Dame la temperatura actual en Tokio" "¿Está lloviendo en Londres ahora mismo?"

Pronóstico

"Dame el pronóstico de 7 días para Ciudad de México" "¿Cómo va a estar el tiempo en París esta semana?"

UV y calidad del aire

"¿Cuál es el índice UV en Medellín hoy?" "¿La calidad del aire en Beijing es buena?"

Ejemplo de respuesta

📍 Buenos Aires, Ciudad Autónoma de Buenos Aires, Argentina
🕐 2026-06-29T14:00 (hora local)  ☀️ Día

🌡️  Temperatura:      18°C  (sensación 16°C)
💧 Humedad:           65%
🌬️  Viento:           22 km/h  (dirección 180°)
🌧️  Precipitación:    0 mm
☁️  Cielo:            Parcialmente nublado

---

Herramientas MCP expuestas

get_current_weather

Obtiene el tiempo actual de una ciudad.

Parámetro	Tipo	Descripción
city	string	Nombre de la ciudad (ej. "Madrid", "New York")

Datos devueltos: temperatura, sensación térmica, humedad, velocidad y dirección del viento, precipitación, descripción del cielo (código WMO), si es de día o noche.

---

get_forecast

Pronóstico diario de hasta 7 días.

Parámetro	Tipo	Descripción
city	string	Nombre de la ciudad
days	number	Días del pronóstico (1–7, por defecto 5)

Datos devueltos por día: temperatura máx/mín, lluvia acumulada, viento máximo, hora de amanecer y atardecer, descripción del cielo.

---

get_uv_and_air

Índice UV actual y calidad del aire.

Parámetro	Tipo	Descripción
city	string	Nombre de la ciudad

Datos devueltos: índice UV con etiqueta (Bajo / Moderado / Alto / Muy alto / Extremo), AQI (US), PM2.5, PM10, monóxido de carbono.

---

Desarrollo

# Ejecutar en modo desarrollo (sin compilar)
npm run dev

# Compilar
npm run build

# Probar con MCP Inspector
npx @modelcontextprotocol/inspector
# → seleccionar "stdio", comando: node dist/index.js

---

Tests y cobertura

El proyecto usa Vitest con cobertura por V8. Los umbrales mínimos configurados son 80% en todas las métricas; actualmente se alcanza el 100%.

# Ejecutar todos los tests
npm test

# Tests en modo watch (desarrollo)
npm run test:watch

# Tests con reporte de cobertura
npm run test:coverage

Resultado actual

-------------|---------|----------|---------|---------|
File         | % Stmts | % Branch | % Funcs | % Lines |
-------------|---------|----------|---------|---------|
handlers.ts  |     100 |      100 |     100 |     100 |
weather.ts   |     100 |      100 |     100 |     100 |
-------------|---------|----------|---------|---------|
All files    |     100 |      100 |     100 |     100 |

Qué se testea

Módulo	Tests	Casos cubiertos
weather.ts	9	Todos los códigos WMO, fallback para código desconocido, geocodificación exitosa, errores HTTP, ciudad no encontrada, caracteres especiales
handlers.ts	31	Día/noche, ubicación con y sin admin1, todos los rangos UV (Bajo→Extremo) y AQI (Buena→Insalubre), extracción de amanecer/atardecer, precipitación, propagación de errores HTTP en cada API

Los tests mockean fetch globalmente con vi.stubGlobal — no se realizan llamadas reales a la red.

---

Changelog

v0.2.0 — 2026-06-29

• Refactorización: extracción de weather.ts (utilidades puras) y handlers.ts (lógica de herramientas) para habilitar tests unitarios sin dependencia del servidor MCP
• 40 tests unitarios con 100% de cobertura (statements, branches, functions, lines)
• Configuración de Vitest con umbrales de cobertura ≥ 80%
• coverage/ excluido del repositorio vía .gitignore

v0.1.0 — 2026-06-29

• Implementación inicial del servidor MCP con transporte stdio
• Herramienta get_current_weather: temperatura, humedad, viento, precipitación y descripción del cielo
• Herramienta get_forecast: pronóstico de 1 a 7 días con amanecer/atardecer
• Herramienta get_uv_and_air: índice UV y calidad del aire (PM2.5, PM10, CO, AQI)
• Geocodificación automática de ciudad a coordenadas vía Open-Meteo Geocoding API
• Descripciones de cielo en español usando códigos WMO
• Sin API key requerida — 100% gratuito