🌤️ MCP Weather Agent

Интеллектуальный многозонный погодный ассистент на базе OpenAI и Model Context Protocol (MCP).

Получайте прогнозы погоды и оповещения в реальном времени для Израиля и США через интерфейс чата на естественном языке. Агент интеллектуально направляет вопросы к соответствующему источнику данных и формирует ответы на основе живых веб-данных и официальных погодных API.

✨ Возможности

• 🤖 Чат на основе ИИ: Погодные запросы в диалоговом режиме с использованием GPT-4o-mini

• 🌍 Два источника данных:

  • 🇮🇱 Израиль: Живой веб-скрапинг с Weather2day через Playwright

  • 🇺🇸 США: Официальный API Национальной метеорологической службы

• 🔄 Умная маршрутизация инструментов: Агент автоматически выбирает нужный инструмент на основе вашего вопроса

• 💬 Естественный язык: Задавайте вопросы на простом английском; агент понимает контекст и намерение

• 🔐 Безопасность: Ключи API хранятся в .env и исключены из системы контроля версий

• 🎯 Интерактивность: Цикл чата в реальном времени с видимой автоматизацией браузера для запросов по Израилю

Related MCP server: Weather MCP Agent

📋 Содержание

• Быстрый старт

• Требования

• Настройка

• Запуск агента

• Архитектура

• Примеры запросов

• Устранение неполадок

• FAQ

• Безопасность

🚀 Быстрый старт

Запустите за 3 минуты:

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

📦 Требования

🔧 Настройка

1. Установка зависимостей

Откройте терминал в каталоге проекта и выполните:

# Install Python dependencies
uv sync

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

Первый запуск занимает время? Да — Playwright загружает Chromium (~300 МБ). Это разовая операция.

2. Настройка ключа OpenAI API

Создайте файл .env в корне проекта:

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

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

Замените your_openai_api_key на ваш реальный ключ OpenAI API с platform.openai.com/account/api-keys.

⚠️ Важно: Никогда не коммитьте .env и не делитесь вашим ключом API. .gitignore уже исключает его.

3. Проверка установки

Проверьте настройку:

uv run .\host.py

Вы должны увидеть:

Connected to server with tools: [...]

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

Query:

Нажмите Ctrl+C или введите quit для выхода.

▶️ Запуск агента

Запустите интерактивный чат:

uv run .\host.py

Агент запускается в интерактивном режиме. Введите вопрос о погоде и нажмите Enter. Агент:

1. ✅ Анализирует ваш вопрос

2. 🔍 Направляет к соответствующему погодному инструменту (Израиль или США)

3. 🌐 Получает данные в реальном времени (для Израиля может открыться окно браузера)

4. 📊 Обрабатывает и форматирует ответ

5. 💬 Возвращает ответ

Введите quit для выхода.

Для запросов по Израилю: Автоматически открывается окно браузера Chromium. Это нормально — агент использует Playwright для взаимодействия с Weather2day. Окно закрывается после завершения запроса.

🏗️ Архитектура

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

Поток данных:

1. Вы задаёте вопрос в чате

2. Хост отправляет его в OpenAI с доступными инструментами

3. OpenAI выбирает, какой инструмент вызвать, на основе вопроса

4. Соответствующий MCP-сервер выполняет и возвращает данные

5. Хост форматирует и возвращает ответ

💬 Примеры запросов

🇮🇱 Погода в Израиле

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?

Поддерживаемые города: Иерусалим, Тель-Авив, Хайфа, Эйлат, Беэр-Шева, Кфар-Сава, Тверия, Назарет и большинство крупных израильских городов, распознаваемых Weather2day.

🇺🇸 Погода в США

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?

Формат:

• Прогнозы: Используйте координаты широты/долготы

• Оповещения: Используйте двухбуквенные коды штатов (CA, NY, TX и т.д.)

🎯 Умное поведение агента

Агент понимает контекст:

• ✅ «Какая погода в Иерусалиме?» → Использует израильский инструмент

• ✅ «Я собираюсь в Нью-Йорк, какой прогноз?» → Использует инструмент США (40.71, -74.01)

• ✅ «Расскажи о погоде в Тель-Авиве и Лос-Анджелесе» → Вызывает оба инструмента

• ✅ «Сейчас идёт дождь в Чикаго?» → Направляет к инструменту США

📂 Структура проекта

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

🐛 Устранение неполадок

❌ OPENAI_API_KEY is missing

Проблема: Агент не может найти ваш ключ API.

Решение:

1. Убедитесь, что .env существует в корне проекта (та же папка, что и host.py)

2. Проверьте, что файл содержит: OPENAI_API_KEY=sk-your-actual-key-here

3. Перезапустите хост: uv run .\host.py

❌ Браузер Chromium не запускается

Проблема: Ошибка «Failed to launch browser».

Решение:

uv run playwright install chromium

Если проблема сохраняется, проверьте место на диске (Chromium требуется ~500 МБ).

❌ Тайм-аут соединения или ошибки API

Проблема: «net::ERR_CONNECTION_RESET» или сбои запросов.

Решение:

• Проверьте интернет-соединение

• Убедитесь, что ваш ключ OpenAI API действителен на platform.openai.com

• Проверьте использование API и биллинг

❌ Браузер для Израиля открывается, но поиск не работает

Проблема: Поиск города не возвращает подсказки.

Пояснение: Автодополнение Weather2day работает только на странице /forecast. Инструмент автоматически возвращается на эту страницу перед каждым поиском, но если это не удаётся:

Решение:

• Убедитесь, что Chromium обновлён: uv run playwright install --with-deps chromium

• Убедитесь, что у вас есть доступ к weather2day.co.il

• Проверьте всплывающие окна или баннеры cookie (агент обрабатывает их, но при очень медленном соединении может произойти тайм-аут)

❌ «A server fails to connect»

Проблема: Ошибка соединения с MCP-сервером.

Решение:

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

❓ FAQ

В: Как агент решает, какой инструмент использовать?
О: GPT-4o-mini от OpenAI читает ваш вопрос и выбирает лучший инструмент на основе контекста (упомянутая страна/регион, предоставленные координаты и т.д.). Это не основано на правилах — используется понимание языка.

В: Могу ли я спросить о нескольких регионах в одном запросе?
О: Да! Агент может вызывать несколько инструментов. Попробуйте: «Какая погода в Тель-Авиве и Нью-Йорке?»

В: Почему браузер для Израиля открывается видимо?
О: Playwright автоматизирует Weather2day, вводя текст в живой поиск, выбирая результаты и читая страницу. Безголовый режим (невидимый) не работает с автодополнением этого сайта, основанным на JavaScript, поэтому браузер запускается видимо.

В: Сколько это стоит?
О: Вы платите OpenAI за вызовы API. Каждый запрос стоит ~$0.001–$0.01 в зависимости от длины ответа. Веб-скрапинг для Израиля бесплатен; API США бесплатен (NWS является публичным).

В: Что если я хочу добавить больше регионов?
О: Создайте новый MCP-сервер (например, weather_Europe.py) и зарегистрируйте его в host.py в self.mcp_clients. Смотрите существующие серверы для примера.

В: Безопасен ли мой ключ API?
О: Да. Ваш .env исключён из Git и хранится только локально. Никогда не вставляйте ключ в код или публичный чат.

В: Можно ли использовать это в производстве?
О: Это демонстрационный проект. Для производства:

• Используйте асинхронную очередь запросов

• Добавьте логирование и восстановление после ошибок

• Кэшируйте прогнозы (погода меняется каждый час, а не каждый запрос)

• Настройте мониторинг и оповещения

• Используйте конфигурацию на основе переменных окружения

🔒 Безопасность

Если ваш ключ API раскрыт:

1. Немедленно отзовите его в OpenAI Dashboard

2. Сгенерируйте новый ключ

3. Обновите .env

📝 Лицензия

Этот проект предоставляется как есть для образовательных целей. Подробности см. в LICENSE.

🤝 Вклад

Есть идеи по улучшению агента? Вклад приветствуется!

1. Форкните репозиторий

2. Создайте ветку для функции (git checkout -b feature/amazing-feature)

3. Закоммитьте изменения (git commit -m 'Add amazing feature')

4. Запушьте ветку (git push origin feature/amazing-feature)

5. Откройте Pull Request

📞 Поддержка

• 🐛 Сообщайте об ошибках через GitHub Issues

• 💡 Предлагайте функции в Discussions

• 📧 По вопросам безопасности пишите на email (не открывайте публичный issue)

Хороших прогнозов! 🌦️☀️