Ассистент погоды MCP

Интерактивный ассистент погоды, построенный на протоколе Model Context Protocol (MCP). Хост подключается к двум локальным MCP-серверам, публикует их инструменты в языковую модель, совместимую с OpenRouter, и предоставляет модели решать, когда получать информацию о погоде.

Возможности

• Прогнозы погоды для местоположений в США через API Национальной службы погоды.

• Активные предупреждения о погоде для штата США.

• Израильские прогнозы погоды через сайт weather2day.co.il и видимый браузер Chromium под управлением Playwright.

• Один интерактивный чат-интерфейс в терминале.

• Несколько MCP-серверов, подключенных через stdio.

• Автоматическое обнаружение инструментов и пространств имен для предотвращения коллизий между серверами.

Related MCP server: MCP Weather Assistant

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

Требования

• Windows, macOS или Linux.

• Python 3.13 или новее.

• Ключ API OpenRouter.

• Доступ в Интернет к OpenRouter, api.weather.gov и weather2day.co.il.

• Chromium, установленный через Playwright, для израильских запросов о погоде.

• Рекомендуется использовать виртуальное окружение.

Установка

С помощью uv

Из каталога проекта:

uv sync
uv run playwright install chromium

Проект в настоящее время напрямую импортирует httpx. Если его нет в заблокированном окружении, установите его с помощью:

uv add httpx

Использование стандартного инструментария 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

На macOS или Linux активируйте окружение с помощью:

source .venv/bin/activate

Объявленные зависимости включают несколько SDK-провайдеров, которые в настоящее время не используются host.py; они остаются частью метаданных проекта для совместимости с шаблоном.

Конфигурация

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

OPENROUTER_API_KEY=your_openrouter_api_key

host.py загружает этот файл через python-dotenv и отправляет ключ как Bearer-токен в OpenRouter. Не коммитьте .env и не раскрывайте ключ в системе контроля версий, журналах, скриншотах или отчетах об ошибках.

Текущая модель настраивается в host.py:

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

Измените эту константу, если хотите использовать другую модель OpenRouter, поддерживающую вызовы инструментов.

Запуск ассистента

uv run python host.py

С активированным виртуальным окружением:

python host.py

Вы должны увидеть приветственное сообщение, за которым следует приглашение Query:. Введите вопрос и нажмите Enter. Введите quit, чтобы остановить приложение.

Примеры вопросов:

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?

Хост выводит вызовы инструментов по мере их выполнения, а затем финальный ответ модели.

MCP-серверы и инструменты

Сервер для США

weather_USA.py запускает MCP-сервер с именем weather-USA и предоставляет следующие инструменты:

• get_alerts_in_USA(state)

  • state: двухбуквенный код штата, например CA или NY.

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

• get_forecast_in_USA(latitude, longitude)

  • latitude: десятичная широта.

  • longitude: десятичная долгота.

  • Резолвит местоположение через конечную точку NWS points, затем возвращает первые пять прогнозных периодов.

Запрос к API NWS использует Accept: application/geo+json и пользовательский User-Agent.

Израильский сервер

weather_Israel.py запускает MCP-сервер с именем weather-Israel и предоставляет:

1. open_weather_forecast_israel()

   • Открывает не-headless браузер Chromium и переходит на израильский сайт прогноза погоды.

2. enter_weather_forecast_city_israel(city)

   • Вводит название города и ожидает появления подсказок автодополнения.

3. select_weather_forecast_city_israel()

   • Выбирает первый вариант автодополнения и ожидает загрузки страницы прогноза.

4. get_weather_forecast_content_israel()

   • Извлекает видимый текст со страницы, очищает пустые строки и ограничивает результат 4000 символами.

Израильские инструменты являются состояниями и должны вызываться по порядку. Браузер должен быть открыт до ввода названия города, а город должен быть выбран перед извлечением прогноза.

Архитектура

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

При запуске ChatHost создаёт один экземпляр MCPClient для каждого сервера погоды. Каждый клиент запускает сервер как дочерний процесс, используя тот же интерпретатор Python, что и хост. Хост обнаруживает все MCP-инструменты и предоставляет их OpenRouter с помощью схем вызова функций.

Чтобы предотвратить дублирование имён, инструменты предоставляются модели в следующем виде:

<server_script_name>__<tool_name>

Например, инструмент США выводится как weather_USA__get_alerts_in_USA. Когда OpenRouter запрашивает инструмент, хост сопоставляет это публичное имя с соответствующим MCP-клиентом и исходным именем инструмента, вызывает его и отправляет результат обратно в диалог с моделью.

Запуск отдельного MCP-сервера

Каждый сервер можно запустить напрямую для MCP-совместимых клиентов или для базового дымового тестирования:

python weather_USA.py
python weather_Israel.py

Эти программы используют stdio-транспорт MCP, поэтому они предназначены для связи с MCP-клиентом, а не для отображения веб-страниц или командной строки.

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

ModuleNotFoundError: No module named 'httpx'

Установите недостающий модуль:

uv add httpx

или:

python -m pip install httpx

Chromium не запускается

Установите бинарный файл браузера Playwright:

python -m playwright install chromium

Израильский сервер намеренно запускает Chromium с headless=False, поэтому для этого провайдера требуется сеанс рабочего стола.

Ошибка аутентификации OpenRouter

Убедитесь, что .env находится в том же каталоге, что и host.py, что переменная называется именно OPENROUTER_API_KEY и что ключ активен. Перезапустите хост после изменений.

Инструменты недоступны

Убедитесь, что оба скрипта сервера находятся в корне проекта и что хост запускается из этого каталога. Хост использует относительные пути ./weather_USA.py и ./weather_Israel.py.

Сбой запроса погоды

Приложение зависит от внешних сервисов. Проверьте доступ к интернету, ответ NWS для запрошенного местоположения и не изменились ли селекторы HTML на израильском сайте.

Вопросы безопасности и эксплуатации

• host.py и MCP-серверы отключают проверку TLS-сертификатов (verify=False). Это может быть необходимо в текущей сетевой среде, но снижает безопасность транспорта и должно быть заменено на обычную проверку сертификатов в производственной среде.

• OpenRouter получает запрос пользователя и результаты, возвращаемые инструментами.

• Израильский провайдер открывает видимый браузер и извлекает текст со страницы. Изменения в вёрстке сайта могут нарушить селекторы или изменить извлекаемый контент.

• Приложение не хранит историю диалога; каждый запрос в терминале начинает новый список сообщений модели.

• Ошибки выводятся в терминал и не записываются в журнал.

Замечания по разработке

MCP-серверы используют декораторы FastMCP для инструментов и асинхронные операции для сетевых запросов и работы с браузером. При модификации сервера оставляйте канал stdio зарезервированным для протокола MCP; диагностический вывод следует обрабатывать аккуратно, чтобы не нарушать связь.

В репозитории в настоящее время нет автоматических тестов. Полезным следующим шагом было бы добавление тестов, которые имитируют NWS, вызовы инструментов OpenRouter и работу Playwright, чтобы проверять оркестрацию без доступа к сети.

Лицензия

В настоящее время в репозитории нет файла лицензии.