mcp-weather-connector

MCP-сервер, который даёт ИИ-агенту доступ к прогнозу погоды через Open-Meteo — публичное API без ключа и регистрации.

Небольшой, намеренно: репозиторий про то, как устроен инструментальный слой для агента, а не про погоду. Погода здесь — понятный предлог показать границу доверия между моделью и внешним миром.

Зачем это

Model Context Protocol — способ дать языковой модели право совершать действия во внешних сервисах. Как только такое право появляется, возникает вопрос: что будет, если модель передаст в инструмент мусор, а чужой сервис в этот момент отдаст 503.

Три решения, которые в этом коде показаны явно:

Вход от модели — недоверенный. Модель может передать пустую строку, простыню на десять килобайт или управляющие символы. Всё это отсекается в server.py до сетевого вызова, а не в чужом API.

Ошибки различаются по типу. 4xx повторять бессмысленно — это ошибка запроса, повтор её не исправит. 5xx чаще разовый сбой — один повтор с паузой. Логика в _get_json, проверяется тестами на счётчик вызовов.

Наружу уходит текст, а не сырой JSON. Агенту нечего домысливать и не в чем ошибиться при пересказе. Ответ 200 без нужного поля считается сбоем, а не поводом отдать пустоту.

Отдельно: число дней вне диапазона приводится к границе, а не считается ошибкой. Если модель попросила прогноз на 30 дней, полезнее отдать семь, чем уронить диалог сообщением об ошибке.

Инструменты

Инструмент	Что делает
current_weather(city)	Текущая погода: температура, ощущается как, влажность, ветер
forecast(city, days=3)	Прогноз на 1–7 дней с осадками
locate(query)	Проверяет существование населённого пункта и уточняет страну

locate существует ради одного сценария: когда агент не уверен в написании, лучше уточнить у пользователя, чем молча выдать погоду не того города.

Установка

pip install -e .

Подключение к Claude Desktop

В claude_desktop_config.json:

{
  "mcpServers": {
    "weather": {
      "command": "mcp-weather"
    }
  }
}

После перезапуска приложения инструменты появятся в списке доступных.

Разработка

pip install -e ".[dev]"
pytest
ruff check .

Тесты покрывают то, что реально ломается: пустой и переразмеренный ввод, нечисловое количество дней, 4xx без повтора, 5xx с одним повтором, успех со второй попытки, ответ 200 без полезной нагрузки, неизвестный код погоды. HTTP замокан через respx — сеть в тестах не нужна.

Структура

src/mcp_weather/
    client.py    — работа с Open-Meteo: типы, повторы, разбор ответа
    server.py    — MCP-слой: валидация входа и форматирование вывода
tests/
    test_tools.py

Сетевой код отделён от MCP-слоя намеренно: клиент тестируется сам по себе, а инструменты агента остаются тонкой обёрткой над понятными функциями.

Лицензия

MIT