Servidor MCP de Clima

Un servidor del Protocolo de Contexto de Modelo (MCP) para datos meteorológicos con soporte para OpenAPI. Este servidor proporciona información meteorológica de la API de OpenWeatherMap y puede ser utilizado por agentes LLM a través de MCP.

Características

• Transporte stdio de MCP para la integración con agentes LLM

• API REST HTTP con especificación OpenAPI 3.0

• 4 herramientas meteorológicas:

  1. Obtener el clima actual por ciudad

  2. Obtener el clima actual por coordenadas

  3. Obtener pronóstico del tiempo (5 días, intervalos de 3 horas)

  4. Obtener resumen del rango de temperatura

• Soporte de datos simulados (mock) para pruebas sin clave de API

• Implementación en TypeScript con seguridad de tipos completa

Instalación

cd weather-mcp-server
npm install
npm run build

Uso

1. Servidor MCP (transporte stdio)

Ejecute el servidor MCP para agentes LLM:

npm start

O en modo de desarrollo:

npm run dev

2. Servidor HTTP con OpenAPI

Ejecute el servidor HTTP con API REST:

npm run dev:http

El servidor se iniciará en http://localhost:3000 con:

• /health - Punto de conexión de verificación de estado

• /openapi - Especificación OpenAPI

• /api/v1/weather/current/{city} - Clima actual por ciudad

• /api/v1/weather/current/coordinates - Clima actual por coordenadas

• /api/v1/weather/forecast/{city} - Pronóstico del tiempo

3. Configuración

Establezca su clave de API de OpenWeatherMap (opcional: se utilizarán datos simulados si no se proporciona):

export OPENWEATHER_API_KEY=your_api_key_here

O cree un archivo .env:

OPENWEATHER_API_KEY=your_api_key_here

Herramientas MCP

El servidor proporciona las siguientes herramientas MCP:

Puntos de conexión de la API

API REST HTTP

Todos los puntos de conexión devuelven JSON con la siguiente estructura:

{
  "success": true,
  "data": { ... }
}

1. Clima actual por ciudad

GET /api/v1/weather/current/{city}

Ejemplo:

curl http://localhost:3000/api/v1/weather/current/London

2. Clima actual por coordenadas

GET /api/v1/weather/current/coordinates?lat={latitude}&lon={longitude}

Ejemplo:

curl "http://localhost:3000/api/v1/weather/current/coordinates?lat=51.5074&lon=-0.1276"

3. Pronóstico del tiempo

GET /api/v1/weather/forecast/{city}?days={days}

Ejemplo:

curl "http://localhost:3000/api/v1/weather/forecast/New%20York?days=3"

Pruebas

Ejecute la suite de pruebas:

npm test

Ejecute el inspector MCP para depuración:

npm run inspect

Estructura del proyecto

weather-mcp-server/
├── src/
│   ├── index.ts              # MCP stdio server
│   ├── http-server.ts        # HTTP server with OpenAPI
│   ├── types/
│   │   └── weather.ts        # TypeScript types and Zod schemas
│   ├── utils/
│   │   └── weather-client.ts # OpenWeatherMap API client
│   └── tools/
│       └── weather-tools.ts  # MCP tool definitions
├── dist/                     # Compiled JavaScript
├── test/
│   └── test.js              # Test suite
├── package.json
├── tsconfig.json
└── README.md

Dependencias

• @modelcontextprotocol/sdk - SDK de MCP para TypeScript

• express - Marco de trabajo para servidor HTTP

• axios - Cliente HTTP para llamadas a la API

• zod - Validación de esquemas

• typescript - Compilador de TypeScript

Licencia

MIT