MCP Weather Assistant

Un asistente meteorológico interactivo construido con el Protocolo de Contexto de Modelo (MCP). El host se conecta a dos servidores MCP locales, publica sus herramientas a un modelo de lenguaje compatible con OpenRouter y permite que el modelo decida cuándo recuperar información meteorológica.

Características

• Pronósticos meteorológicos para ubicaciones en los Estados Unidos a través de la API del Servicio Meteorológico Nacional.

• Alertas meteorológicas activas para un estado de los Estados Unidos.

• Pronósticos meteorológicos israelíes a través del sitio web weather2day.co.il y un navegador Chromium visible controlado por Playwright.

• Una interfaz de chat interactiva en terminal.

• Múltiples servidores MCP conectados a través de stdio.

• Descubrimiento automático de herramientas y asignación de espacios de nombres para evitar colisiones entre servidores.

Related MCP server: MCP Weather Assistant

Estructura del Proyecto

Requisitos

• Windows, macOS o Linux.

• Python 3.13 o más reciente.

• Una clave de API de OpenRouter.

• Acceso a Internet para OpenRouter, api.weather.gov y weather2day.co.il.

• Chromium, instalado a través de Playwright, para consultas meteorológicas israelíes.

• Se recomienda un entorno virtual.

Instalación

Usando uv

Desde el directorio del proyecto:

uv sync
uv run playwright install chromium

El proyecto actualmente importa httpx directamente. Si aún no está presente en el entorno bloqueado, instálalo con:

uv add httpx

Usando herramientas estándar de Python

py -3.13 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install anthropic mcp python-dotenv playwright openai google-genai httpx
python -m playwright install chromium

En macOS o Linux, activa el entorno con:

source .venv/bin/activate

Las dependencias declaradas incluyen varios SDK de proveedores que actualmente no son utilizados por host.py; permanecen como parte de los metadatos del proyecto por compatibilidad con la plantilla.

Configuración

Crea un archivo .env en la raíz del proyecto:

OPENROUTER_API_KEY=your_openrouter_api_key

host.py carga este archivo con python-dotenv y envía la clave como token Bearer a OpenRouter. No confirmes .env ni expongas la clave en control de versiones, registros, capturas de pantalla o informes de errores.

El modelo actual está configurado en host.py:

MODEL = "nvidia/nemotron-3-super-120b-a12b:free"

Cambia esta constante si deseas usar otro modelo de OpenRouter que admita llamadas a herramientas.

Ejecución del Asistente

Con uv:

uv run python host.py

Con un entorno virtual activado:

python host.py

Deberías ver un mensaje de inicio seguido de un indicador Query:. Escribe una pregunta y presiona Enter. Escribe quit para detener la aplicación.

Preguntas de ejemplo:

What is the forecast for 34.05, -118.25?
Are there any active weather alerts in California?
What is the weather forecast in Tel Aviv?

El host imprime las llamadas a herramientas a medida que ocurren, seguidas de la respuesta final del modelo.

Servidores MCP y Herramientas

Servidor de Estados Unidos

weather_USA.py inicia un servidor MCP llamado weather-USA y proporciona:

• get_alerts_in_USA(state)

  • state: código de estado de dos letras como CA o NY.

  • Utiliza el endpoint de alertas activas del NWS.

• get_forecast_in_USA(latitude, longitude)

  • latitude: latitud decimal.

  • longitude: longitud decimal.

  • Resuelve la ubicación a través del endpoint de puntos del NWS y luego devuelve los primeros cinco períodos de pronóstico.

La solicitud a la API del NWS utiliza Accept: application/geo+json y un User-Agent personalizado.

Servidor de Israel

weather_Israel.py inicia un servidor MCP llamado weather-Israel y proporciona:

1. open_weather_forecast_israel()

   • Abre un navegador Chromium no headless y navega al sitio web de pronóstico israelí.

2. enter_weather_forecast_city_israel(city)

   • Ingresa un nombre de ciudad y espera las sugerencias de autocompletado.

3. select_weather_forecast_city_israel()

   • Selecciona la primera sugerencia de autocompletado y espera la página de pronóstico.

4. get_forecast_content_israel()

   • Extrae el texto visible de la página cargada, limpia las líneas vacías y limita el resultado a 4,000 caracteres.

Las herramientas israelíes son con estado y deben llamarse en orden. El navegador debe abrirse antes de ingresar una ciudad, y una ciudad debe seleccionarse antes de extraer el pronóstico.

Arquitectura

User terminal
    |
    v
host.py (ChatHost)
    |-- OpenRouter chat-completions API
    |
    |-- client.py -> weather_USA.py -> api.weather.gov
    |
    `-- client.py -> weather_Israel.py -> Playwright -> weather2day.co.il

Al inicio, ChatHost crea un MCPClient para cada servidor meteorológico. Cada cliente lanza su servidor como un proceso hijo usando el mismo intérprete de Python que el host. El host descubre todas las herramientas MCP y las expone a OpenRouter usando esquemas de llamada a funciones.

Para evitar nombres duplicados, las herramientas se exponen al modelo como:

<server_script_name>__<tool_name>

Por ejemplo, la herramienta de alertas de EE. UU. se expone como weather_USA__get_alerts_in_USA. Cuando OpenRouter solicita una herramienta, el host mapea ese nombre público de vuelta al cliente MCP propietario y al nombre original de la herramienta, la ejecuta y envía el resultado de vuelta a la conversación del modelo.

Ejecución de un Servidor MCP Individual

Cada servidor puede iniciarse directamente para clientes compatibles con MCP o para pruebas básicas de humo:

python weather_USA.py
python weather_Israel.py

Estos programas usan transporte stdio de MCP, por lo que están destinados a comunicarse con un cliente MCP en lugar de mostrar una página web normal o un indicador de comandos.

Solución de Problemas

ModuleNotFoundError: No module named 'httpx'

Instala la dependencia faltante:

uv add httpx

o:

python -m pip install httpx

Chromium no se inicia

Instala el binario del navegador Playwright:

python -m playwright install chromium

El servidor israelí inicia intencionalmente Chromium con headless=False, por lo que se requiere una sesión de escritorio para ese proveedor.

La autenticación de OpenRouter falla

Verifica que .env esté en el mismo directorio que host.py, que la variable se llame exactamente OPENROUTER_API_KEY y que la clave esté activa. Reinicia el host después de cambiar el archivo.

No hay herramientas disponibles

Confirma que ambos scripts de servidor existan en la raíz del proyecto y que el host se inicie desde ese directorio. El host actualmente usa las rutas relativas ./weather_USA.py y ./weather_Israel.py.

Una solicitud meteorológica falla

La aplicación depende de servicios externos. Verifica el acceso a Internet, la respuesta del NWS para las coordenadas o el estado solicitados, y si los selectores HTML del sitio web israelí han cambiado.

Notas de Seguridad y Operación

• host.py y el cliente NWS deshabilitan la verificación de certificados TLS con verify=False. Esto puede ser necesario en el entorno de red actual, pero reduce la seguridad del transporte y debe reemplazarse con verificación normal de certificados en producción.

• OpenRouter recibe la consulta del usuario y los resultados devueltos por las herramientas meteorológicas.

• El proveedor israelí abre un navegador visible y extrae el texto del cuerpo de la página. Los cambios en el diseño del sitio web pueden romper los selectores o alterar el contenido extraído.

• La aplicación no tiene historial de conversación persistente; cada consulta de terminal inicia una nueva lista de mensajes del modelo.

• Los errores se imprimen en la terminal y no se escriben en un servicio de registro.

Notas de Desarrollo

Los scripts del servidor MCP exponen herramientas a través de decoradores FastMCP y usan funciones asíncronas para operaciones de red y navegador. Mantén el canal stdio reservado para el tráfico del protocolo MCP al modificar un servidor; la salida de diagnóstico debe manejarse con cuidado para no corromper la comunicación del protocolo.

Actualmente no hay pruebas automatizadas en el repositorio. Una capa de pruebas útil a continuación sería simular las respuestas del NWS, las respuestas de llamadas a herramientas de OpenRouter y las interacciones de página de Playwright para que la orquestación pueda verificarse sin acceso a la red o un navegador.

Licencia

Actualmente no se incluye ningún archivo de licencia en este repositorio.