🌤️ MCP Wetter-Agent

Ein intelligenter, multi-regionaler Wetterassistent, unterstützt von OpenAI und dem Model Context Protocol (MCP).

Erhalten Sie Echtzeit-Wettervorhersagen und -warnungen für Israel und die Vereinigten Staaten über eine natürlichsprachliche Chat-Oberfläche. Der Agent leitet Fragen intelligent an die passende Datenquelle weiter und erstellt Antworten aus Live-Webdaten und offiziellen Wetter-APIs.

✨ Funktionen

• 🤖 KI-gestützter Chat: Konversationelle Wetterabfragen mit GPT-4o-mini

• 🌍 Zwei Datenquellen:

  • 🇮🇱 Israel: Live-Web-Scraping von Weather2day über Playwright

  • 🇺🇸 USA: Offizielle National Weather Service API

• 🔄 Intelligentes Tool-Routing: Der Agent wählt automatisch das richtige Tool basierend auf Ihrer Frage

• 💬 Natürliche Sprache: Stellen Sie Fragen in einfachem Englisch; der Agent versteht Kontext und Absicht

• 🔐 Sicher: API-Schlüssel werden in .env gespeichert und von der Versionskontrolle ausgeschlossen

• 🎯 Interaktiv: Echtzeit-Chat-Schleife mit sichtbarer Browser-Automatisierung für Israel-Abfragen

Related MCP server: Weather MCP Agent

📋 Inhaltsverzeichnis

• Schnellstart

• Anforderungen

• Einrichtung

• Agent ausführen

• Architektur

• Beispielabfragen

• Fehlerbehebung

• FAQ

• Sicherheit

🚀 Schnellstart

In 3 Minuten einsatzbereit:

# 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?"

📦 Anforderungen

🔧 Einrichtung

1. Abhängigkeiten installieren

Öffnen Sie ein Terminal im Projektverzeichnis und führen Sie aus:

# Install Python dependencies
uv sync

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

Dauert der erste Start etwas? Ja—Playwright lädt Chromium herunter (~300 MB). Dies ist ein einmaliger Vorgang.

2. OpenAI API-Schlüssel konfigurieren

Erstellen Sie eine .env-Datei im Projektstamm:

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

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

Ersetzen Sie your_openai_api_key durch Ihren tatsächlichen OpenAI API-Schlüssel von platform.openai.com/account/api-keys.

⚠️ Wichtig: Committen Sie niemals .env oder teilen Sie Ihren API-Schlüssel. Die .gitignore schließt ihn bereits aus.

3. Installation überprüfen

Testen Sie die Einrichtung:

uv run .\host.py

Sie sollten sehen:

Connected to server with tools: [...]

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

Query:

Drücken Sie Ctrl+C oder geben Sie quit ein, um zu beenden.

▶️ Agent ausführen

Starten Sie den interaktiven Chat:

uv run .\host.py

Der Agent startet im interaktiven Modus. Geben Sie eine Wetterfrage ein und drücken Sie Enter. Der Agent wird:

1. ✅ Ihre Frage analysieren

2. 🔍 An das passende Wetter-Tool weiterleiten (Israel oder USA)

3. 🌐 Echtzeitdaten abrufen (kann ein Browserfenster für Israel öffnen)

4. 📊 Die Antwort verarbeiten und formatieren

5. 💬 Die Antwort zurückgeben

Geben Sie quit ein, um zu beenden.

Für Israel-Abfragen: Ein Chromium-Browserfenster öffnet sich automatisch. Das ist normal—der Agent verwendet Playwright, um mit Weather2day zu interagieren. Das Fenster schließt sich, wenn die Abfrage abgeschlossen ist.

🏗️ Architektur

┌─────────────────────────────────────────────────────────────────┐
│                        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)      │
        └──────────────────────┘  └───────────────────┘

Datenfluss:

1. Sie stellen eine Frage im Chat

2. Der Host sendet sie an OpenAI mit verfügbaren Tools

3. OpenAI wählt basierend auf der Frage aus, welches Tool aufgerufen werden soll

4. Der entsprechende MCP-Server führt aus und gibt Daten zurück

5. Der Host formatiert und gibt die Antwort zurück

💬 Beispielabfragen

🇮🇱 Israel-Wetter

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?

Unterstützte Städte: Jerusalem, Tel Aviv, Haifa, Eilat, Beerscheba, Kfar Saba, Tiberias, Nazareth und die meisten größeren israelischen Städte, die von Weather2day erkannt werden.

🇺🇸 USA-Wetter

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?

Format:

• Vorhersagen: Verwenden Sie Breiten-/Längengrad-Koordinaten

• Warnungen: Verwenden Sie zweistellige Bundesstaatscodes (CA, NY, TX usw.)

🎯 Intelligentes Agentenverhalten

Der Agent versteht Kontext:

• ✅ "Wie ist das Wetter in Jerusalem?" → Verwendet Israel-Tool

• ✅ "Ich besuche New York, wie ist die Vorhersage?" → Verwendet USA-Tool (40.71, -74.01)

• ✅ "Erzähl mir vom Wetter in Tel Aviv und Los Angeles" → Ruft beide Tools auf

• ✅ "Regnet es gerade in Chicago?" → Leitet an USA-Tool weiter

📂 Projektstruktur

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

🐛 Fehlerbehebung

❌ OPENAI_API_KEY fehlt

Problem: Der Agent kann Ihren API-Schlüssel nicht finden.

Lösung:

1. Überprüfen Sie, ob .env im Projektstamm existiert (gleicher Ordner wie host.py)

2. Prüfen Sie, ob die Datei enthält: OPENAI_API_KEY=sk-ihr-tatsaechlicher-schluessel

3. Starten Sie den Host neu: uv run .\host.py

❌ Chromium-Browser startet nicht

Problem: Fehler "Failed to launch browser".

Lösung:

uv run playwright install chromium

Wenn es weiterhin fehlschlägt, prüfen Sie den Speicherplatz (Chromium benötigt ~500 MB).

❌ Verbindungszeitüberschreitung oder API-Fehler

Problem: "net::ERR_CONNECTION_RESET" oder Anforderungsfehler.

Lösung:

• Überprüfen Sie Ihre Internetverbindung

• Verifizieren Sie, dass Ihr OpenAI API-Schlüssel gültig ist unter platform.openai.com

• Prüfen Sie API-Nutzung und Abrechnung

❌ Israel-Browser öffnet, aber Suche schlägt fehl

Problem: Die Stadtsuche liefert keine Vorschläge.

Erklärung: Die Weather2day-Autovervollständigung funktioniert nur auf der /forecast-Seite. Das Tool kehrt vor jeder Suche automatisch zu dieser Seite zurück, aber wenn es fehlschlägt:

Lösung:

• Stellen Sie sicher, dass Chromium aktuell ist: uv run playwright install --with-deps chromium

• Stellen Sie sicher, dass Sie Internetzugang zu weather2day.co.il haben

• Prüfen Sie auf Browser-Pop-ups oder Cookie-Banner (der Agent behandelt diese, aber sehr langsame Verbindungen können zu Zeitüberschreitungen führen)

❌ "Ein Server kann keine Verbindung herstellen"

Problem: MCP-Server-Verbindungsfehler.

Lösung:

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

❓ FAQ

F: Wie entscheidet der Agent, welches Tool verwendet wird?
A: OpenAIs GPT-4o-mini liest Ihre Frage und wählt das beste Tool basierend auf dem Kontext (erwähntes Land/Region, bereitgestellte Koordinaten usw.). Es ist nicht regelbasiert—es verwendet Sprachverständnis.

F: Kann ich in einer Abfrage nach mehreren Regionen fragen?
A: Ja! Der Agent kann mehrere Tools aufrufen. Versuchen Sie: "Wie ist das Wetter in Tel Aviv und New York?"

F: Warum öffnet sich der Israel-Browser sichtbar?
A: Playwright automatisiert Weather2day, indem es in die Live-Suche tippt, Ergebnisse auswählt und die Seite liest. Der Headless-Modus (unsichtbar) funktioniert mit der JavaScript-lastigen Autovervollständigung dieser Website nicht, daher läuft der Browser sichtbar.

F: Wie viel kostet das?
A: Sie werden von OpenAI basierend auf API-Aufrufen abgerechnet. Jede Abfrage kostet ~$0.001–$0.01 je nach Antwortlänge. Israel-Web-Scraping ist kostenlos; USA-API ist kostenlos (NWS ist öffentlich).

F: Was, wenn ich weitere Regionen hinzufügen möchte?
A: Erstellen Sie einen neuen MCP-Server (z. B. weather_Europe.py) und registrieren Sie ihn in host.py unter self.mcp_clients. Siehe die vorhandenen Server für das Muster.

F: Ist mein API-Schlüssel sicher?
A: Ja. Ihre .env ist von Git ausgeschlossen und wird nur lokal gespeichert. Geben Sie Ihren Schlüssel niemals in Code oder öffentlichen Chats preis.

F: Kann ich das in der Produktion verwenden?
A: Dies ist ein Demo-Projekt. Für die Produktion:

• Verwenden Sie asynchrone Anforderungswarteschlangen

• Fügen Sie Protokollierung und Fehlerwiederherstellung hinzu

• Zwischenspeichern Sie Vorhersagen (Wetter ändert sich stündlich, nicht pro Abfrage)

• Richten Sie Überwachung und Warnungen ein

• Verwenden Sie umgebungsbasierte Konfiguration

🔒 Sicherheit

Wenn Ihr API-Schlüssel offengelegt wurde:

1. Widerrufen Sie ihn sofort im OpenAI-Dashboard

2. Generieren Sie einen neuen Schlüssel

3. Aktualisieren Sie .env

📝 Lizenz

Dieses Projekt wird für Bildungszwecke ohne Gewähr bereitgestellt. Details finden Sie in der LICENSE.

🤝 Mitwirken

Haben Sie Ideen zur Verbesserung des Agents? Beiträge sind willkommen!

1. Forken Sie das Repository

2. Erstellen Sie einen Feature-Branch (git checkout -b feature/amazing-feature)

3. Committen Sie Ihre Änderungen (git commit -m 'Add amazing feature')

4. Pushen Sie den Branch (git push origin feature/amazing-feature)

5. Öffnen Sie einen Pull Request

📞 Support

• 🐛 Melden Sie Fehler über GitHub Issues

• 💡 Schlagen Sie Funktionen in Discussions vor

• 📧 Für Sicherheitsprobleme senden Sie eine private E-Mail (eröffnen Sie kein öffentliches Issue)

Viel Spaß beim Vorhersagen! 🌦️☀️