🌤️ Agente Meteorológico MCP

Un asistente meteorológico inteligente y multirregional impulsado por OpenAI y el Protocolo de Contexto de Modelo (MCP).

Obtén pronósticos y alertas meteorológicas en tiempo real para Israel y Estados Unidos a través de una interfaz de chat en lenguaje natural. El agente enruta inteligentemente las preguntas a la fuente de datos adecuada y compila respuestas a partir de datos web en vivo y API meteorológicas oficiales.

✨ Características

• 🤖 Chat impulsado por IA: Consultas meteorológicas conversacionales usando GPT-4o-mini

• 🌍 Dos fuentes de datos:

  • 🇮🇱 Israel: Extracción web en vivo de Weather2day mediante Playwright

  • 🇺🇸 EE. UU.: API oficial del Servicio Meteorológico Nacional

• 🔄 Enrutamiento inteligente de herramientas: El agente selecciona automáticamente la herramienta adecuada según tu pregunta

• 💬 Lenguaje natural: Haz preguntas en inglés sencillo; el agente entiende el contexto y la intención

• 🔐 Seguro: Las claves de API se almacenan en .env y se excluyen del control de versiones

• 🎯 Interactivo: Bucle de chat en tiempo real con automatización visible del navegador para consultas de Israel

Related MCP server: Weather MCP Agent

📋 Tabla de Contenidos

• Inicio rápido

• Requisitos

• Configuración

• Ejecutar el agente

• Arquitectura

• Consultas de ejemplo

• Solución de problemas

• Preguntas frecuentes

• Seguridad

🚀 Inicio Rápido

Ponte en marcha en 3 minutos:

# 1. Install dependencies
uv sync
uv run playwright install chromium

# 2. Create .env file with your OpenAI API key
copy .env.example .env
# Edit .env and add: OPENAI_API_KEY=sk-...

# 3. Run the agent
uv run .\host.py

# 4. Ask a weather question!
# Example: "What is the weather forecast for Jerusalem?"

📦 Requisitos

🔧 Configuración

1. Instalar Dependencias

Abre una terminal en el directorio del proyecto y ejecuta:

# Install Python dependencies
uv sync

# Download Chromium browser for Playwright (required for Israel weather)
uv run playwright install chromium

¿La primera vez tarda mucho? Sí—Playwright descarga Chromium (~300 MB). Esta es una operación única.

2. Configurar la Clave de API de OpenAI

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

# Option A: Copy the template
copy .env.example .env

# Option B: Create manually
echo OPENAI_API_KEY=your_openai_api_key > .env

Reemplaza your_openai_api_key con tu clave real de API de OpenAI desde platform.openai.com/account/api-keys.

⚠️ Importante: Nunca hagas commit de .env ni compartas tu clave de API. El .gitignore ya la excluye.

3. Verificar la Instalación

Prueba la configuración:

uv run .\host.py

Deberías ver:

Connected to server with tools: [...]

MCP Client Started!
Type your queries or 'quit' to exit.

Query:

Presiona Ctrl+C o escribe quit para salir.

▶️ Ejecutar el Agente

Inicia el chat interactivo:

uv run .\host.py

El agente se lanza en modo interactivo. Escribe una pregunta meteorológica y presiona Enter. El agente:

1. ✅ Analiza tu pregunta

2. 🔍 Enruta a la herramienta meteorológica adecuada (Israel o EE. UU.)

3. 🌐 Obtiene datos en tiempo real (puede abrir una ventana del navegador para Israel)

4. 📊 Procesa y formatea la respuesta

5. 💬 Devuelve la respuesta

Escribe quit para salir.

Para consultas de Israel: Se abre automáticamente una ventana del navegador Chromium. Esto es normal—el agente usa Playwright para interactuar con Weather2day. La ventana se cierra cuando la consulta se completa.

🏗️ Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                        OpenAI (GPT-4o-mini)                     │
│                      (Tool Selection & Reasoning)               │
└────────────────────────────┬────────────────────────────────────┘
                             │
                ┌────────────┴────────────┐
                │                         │
        ┌───────▼────────┐       ┌───────▼────────┐
        │  MCP Host      │       │   MCP Host     │
        │  (client.py)   │       │   (client.py)  │
        └───────┬────────┘       └───────┬────────┘
                │                         │
        ┌───────▼──────────────┐  ┌──────▼─────────────┐
        │ weather_Israel.py    │  │ weather_USA.py    │
        │ (Playwright + Web)   │  │ (NWS API)         │
        └───────┬──────────────┘  └──────┬─────────────┘
                │                         │
        ┌───────▼──────────────┐  ┌──────▼─────────────┐
        │   Weather2day.co.il  │  │    api.weather.gov│
        │  (Live Web Browser)  │  │   (REST API)      │
        └──────────────────────┘  └───────────────────┘

Flujo de datos:

1. Haces una pregunta en el chat

2. El host la envía a OpenAI con las herramientas disponibles

3. OpenAI selecciona qué herramienta llamar según la pregunta

4. El servidor MCP correspondiente ejecuta y devuelve los datos

5. El host formatea y devuelve la respuesta

💬 Consultas de Ejemplo

🇮🇱 Clima en Israel

What is the weather forecast for Jerusalem?
Give me the forecast for Tel Aviv.
What is the weather like in Haifa today?
Show me the forecast for Eilat.
What is the weather in Beer Sheva?
Is it going to rain in Kfar Saba tomorrow?
Tell me about the weather in Nazareth.
What's the forecast for Tiberias?

Ciudades compatibles: Jerusalén, Tel Aviv, Haifa, Eilat, Beer Sheva, Kfar Saba, Tiberíades, Nazaret y la mayoría de las principales ciudades israelíes reconocidas por Weather2day.

🇺🇸 Clima en EE. UU.

What is the weather forecast for New York City? (40.7128, -74.0060)
What's the weather at latitude 34.0522, longitude -118.2437? (Los Angeles)
Are there any active weather alerts in California?
What weather alerts are in effect in New York?
Give me the forecast for Chicago coordinates. (41.8781, -87.6298)
Are there any severe weather warnings in Texas?

Formato:

• Pronósticos: Usa coordenadas de latitud/longitud

• Alertas: Usa códigos de estado de dos letras (CA, NY, TX, etc.)

🎯 Comportamiento Inteligente del Agente

El agente entiende el contexto:

• ✅ "¿Cómo está el clima en Jerusalén?" → Usa la herramienta de Israel

• ✅ "Voy a visitar Nueva York, ¿cuál es el pronóstico?" → Usa la herramienta de EE. UU. (40.71, -74.01)

• ✅ "Cuéntame sobre el clima en Tel Aviv y Los Ángeles" → Llama a ambas herramientas

• ✅ "¿Está lloviendo en Chicago ahora mismo?" → Enruta a la herramienta de EE. UU.

📂 Estructura del Proyecto

MCP Weather/
├── host.py                  # Main chat host (OpenAI + tool orchestration)
├── client.py                # MCP client connector
├── weather_Israel.py        # Israel MCP server (Playwright + Web)
├── weather_USA.py           # USA MCP server (NWS API)
├── pyproject.toml           # Dependencies and project metadata
├── uv.lock                  # Locked dependency versions
├── .env.example             # Template for environment variables
├── .env                     # Your API keys (git-ignored)
├── README.md                # This file
└── .gitignore               # Git exclusion rules

🐛 Solución de Problemas

❌ OPENAI_API_KEY is missing

Problema: El agente no encuentra tu clave de API.

Solución:

1. Verifica que .env exista en la raíz del proyecto (misma carpeta que host.py)

2. Comprueba que el archivo contenga: OPENAI_API_KEY=sk-your-actual-key-here

3. Reinicia el host: uv run .\host.py

❌ El navegador Chromium no se inicia

Problema: Error "Failed to launch browser".

Solución:

uv run playwright install chromium

Si sigue fallando, verifica el espacio en disco (Chromium necesita ~500 MB).

❌ Tiempo de espera agotado o errores de API

Problema: "net::ERR_CONNECTION_RESET" o fallos en las solicitudes.

Solución:

• Comprueba tu conexión a internet

• Verifica que tu clave de API de OpenAI sea válida en platform.openai.com

• Revisa el uso y la facturación de la API

❌ El navegador de Israel se abre pero la búsqueda falla

Problema: La búsqueda de ciudades no devuelve sugerencias.

Explicación: El autocompletado de Weather2day solo funciona en la página /forecast. La herramienta vuelve automáticamente a esa página antes de cada búsqueda, pero si falla:

Solución:

• Verifica que Chromium esté actualizado: uv run playwright install --with-deps chromium

• Asegúrate de tener conectividad a weather2day.co.il

• Comprueba si hay ventanas emergentes o banners de cookies (el agente los maneja, pero las conexiones muy lentas pueden agotar el tiempo)

❌ "A server fails to connect"

Problema: Error de conexión del servidor MCP.

Solución:

# Run from the project directory
Set-Location .\project-template
uv run .\host.py

❓ Preguntas Frecuentes

P: ¿Cómo decide el agente qué herramienta usar?
R: GPT-4o-mini de OpenAI lee tu pregunta y selecciona la mejor herramienta según el contexto (país/región mencionado, coordenadas proporcionadas, etc.). No se basa en reglas—usa comprensión del lenguaje.

P: ¿Puedo preguntar sobre varias regiones en una sola consulta?
R: ¡Sí! El agente puede llamar a múltiples herramientas. Prueba: "¿Cómo está el clima en Tel Aviv y Nueva York?"

P: ¿Por qué el navegador de Israel se abre visiblemente?
R: Playwright automatiza Weather2day escribiendo en la búsqueda en vivo, seleccionando resultados y leyendo la página. El modo headless (invisible) no funciona con el autocompletado con mucho JavaScript de este sitio, por lo que el navegador se ejecuta visiblemente.

P: ¿Cuánto cuesta esto?
R: OpenAI te factura según las llamadas a la API. Cada consulta cuesta ~$0.001–$0.01 dependiendo de la longitud de la respuesta. La extracción web de Israel es gratuita; la API de EE. UU. es gratuita (NWS es público).

P: ¿Qué pasa si quiero añadir más regiones?
R: Crea un nuevo servidor MCP (por ejemplo, weather_Europe.py) y regístralo en host.py bajo self.mcp_clients. Consulta los servidores existentes para ver el patrón.

P: ¿Mi clave de API está segura?
R: Sí. Tu .env está excluido de Git y se almacena solo localmente. Nunca pegues tu clave en código o en chats públicos.

P: ¿Puedo usar esto en producción?
R: Este es un proyecto de demostración. Para producción:

• Usa colas de solicitudes asíncronas

• Añade registro y recuperación de errores

• Almacena en caché los pronósticos (el clima cambia cada hora, no por consulta)

• Configura monitoreo y alertas

• Usa configuración basada en variables de entorno

🔒 Seguridad

Si tu clave de API queda expuesta:

1. Revócala inmediatamente en el Panel de OpenAI

2. Genera una nueva clave

3. Actualiza .env

📝 Licencia

Este proyecto se proporciona tal cual con fines educativos. Consulta LICENSE para más detalles.

🤝 Contribuciones

¿Tienes ideas para mejorar el agente? ¡Las contribuciones son bienvenidas!

1. Haz un fork del repositorio

2. Crea una rama de características (git checkout -b feature/amazing-feature)

3. Haz commit de tus cambios (git commit -m 'Add amazing feature')

4. Empuja a la rama (git push origin feature/amazing-feature)

5. Abre una Pull Request

📞 Soporte

• 🐛 Reporta errores a través de GitHub Issues

• 💡 Sugiere características en Discussions

• 📧 Para problemas de seguridad, envía un correo privado (no abras un issue público)

¡Felices pronósticos! 🌦️☀️