# mcp-weather-connector

MCP-сервер, который даёт ИИ-агенту доступ к прогнозу погоды через [Open-Meteo](https://open-meteo.com/) — публичное API без ключа и регистрации.

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

## Зачем это

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

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

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

**Ошибки различаются по типу.** 4xx повторять бессмысленно — это ошибка запроса, повтор её не исправит. 5xx чаще разовый сбой — один повтор с паузой. Логика в [`_get_json`](src/mcp_weather/client.py), проверяется тестами на счётчик вызовов.

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

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

## Инструменты

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

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

## Установка

```bash
pip install -e .
```

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

В `claude_desktop_config.json`:

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

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

## Разработка

```bash
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