# ru-regions MCP server

MCP-сервер: по названию населённого пункта РФ или координатам отдаёт регион (через DaData).

## Tools

- `get_region(city, limit=5, refresh=False)` — определить регион по названию НП.
- `get_region_by_coords(lat, lon, radius_meters=1000, limit=1)` — обратный геокодинг.
- `cache_stats()` / `cache_clear()` — статистика и сброс локального кеша.

Результаты кешируются в SQLite, повторные запросы не идут в DaData.

## Запуск локально (stdio)

```sh
export DADATA_API_KEY=...
./server.py
```

Скрипт shebang-нутый под `uv run` — зависимости подтянутся через PEP 723 inline metadata.

## Запуск в Docker (streamable-http)

```sh
echo "DADATA_API_KEY=..." > .env
docker compose up -d --build
```

По умолчанию слушает `127.0.0.1:8311`, endpoint — `/mcp`. Перед ним обычно reverse-proxy с TLS (Caddy/nginx).

## Переменные окружения

| Переменная | По умолчанию | Описание |
|---|---|---|
| `DADATA_API_KEY` | — (обязательно) | Токен DaData (бесплатный тариф — 10k запросов/сутки) |
| `MCP_TRANSPORT` | `stdio` | `stdio` или `streamable-http` |
| `MCP_HOST` | `127.0.0.1` | Хост для HTTP-режима |
| `MCP_PORT` | `8311` | Порт для HTTP-режима |
| `RU_REGIONS_CACHE_PATH` | `cache.sqlite` рядом со скриптом | Путь к SQLite-кешу |