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)

export DADATA_API_KEY=...
./server.py

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

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

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-кешу