Runnywhere — планируй маршруты для бега где угодно!

Работа, представленная на конкурс Kakao PlayMCP Agentic Player 10. Скажите в AI-чате "5 км от мэрии, без подъёмов, в форме кита" — и сервис создаст маршрут для бега по пешеходной дорожной сети Сеула. Данные о уклонах Сеула (высоты и горизонтали), пешеходных светофорах и расположении уличных фонарей учитываются в оценке дружелюбности к бегу (RFS), что обеспечивает маршруты с приоритетом равнин и безопасные для ночных пробежек. Данные о сеульских общественных туалетах и данных о круглосуточных магазинах из OSM также учитываются, чтобы такие запросы, как "пройти мимо туалета/магазина", использовались при выборе кандидатов маршрута. PRD: ../runart-mcp-prd/PRD.md

Запуск

python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
python -m runart.server           # http://localhost:8000/mcp (Streamable HTTP, JSON)
pytest                            # 테스트 (시나리오 수용 테스트 포함)
python scripts/loadtest.py 1000 10 # 콜드 미스 포함 부하 테스트 (평균 100ms / p99 3s)

JSON-отчёт для проверки PlayMCP сохраняется следующим образом.

RUNART_LOADTEST_REPORT=artifacts/playmcp-loadtest.json python scripts/loadtest.py 1000 10

Для всех ответов MCP-инструментов, включая поиск адреса, повторные попытки и создание маршрута, применяется верхний предел 2,85 секунды; внутреннее создание маршрута и внешнее геокодирование используют тот же более короткий дедлайн.

Переменные окружения: HOST (локально по умолчанию 127.0.0.1, в контейнере 0.0.0.0) · PORT (по умолчанию 8000) · RUNART_BASE_URL (домен ссылок предпросмотра) · RUNART_RELEASE_SHA (Git SHA релиза, связан с аргументом сборки Docker) · KAKAO_JAVASCRIPT_KEY (Web API Kakao Maps, обязательно) · KAKAO_REST_API_KEY (геокодирование, опционально) · RUNART_TOKEN_SECRET (ключ подписи токенов для коллекции и эстафеты, не менее 32 символов, обязательно в продакшене) · RUNART_LEGAL_CONTACT (email для вопросов по политике, обязательно при публичном развёртывании) · WEB_CONCURRENCY (количество веб-воркеров, по умолчанию 1) · RUNART_POOL_WORKERS (количество процессов поиска маршрутов, по умолчанию 2) · RATE_LIMIT_RPS (на IP, по умолчанию 20) · RUNART_MAX_BODY_BYTES (тело MCP-запроса, по умолчанию 65 536) · RUNART_MAX_CONCURRENT_MCP (одновременные MCP HTTP-запросы, по умолчанию 4) · RUNART_ROUTE_EDIT (редактирование маршрута, по умолчанию 1) · RUNART_MAX_CONCURRENT_ROUTE_EDITS (одновременные пересчёты при редактировании, по умолчанию 1) · RUNART_ETL_LOCAL_ONLY=1 (сохраняет существующие атрибуты OSM и пересчитывает только локальные уклоны/светофоры/фонари)

Если файл графа (data/seoul_graph.pkl) отсутствует, сервис работает на демо-сетке в районе мэрии Сеула (для проверки работы всего конвейера). Перед подачей на конкурс обязательно выполните ETL:

pip install -e '.[etl]'
python etl/build_graph.py         # OSM 서울 전역 보행망 -> data/seoul_graph.pkl
python scripts/build_animal_presets.py --workers 2 --fresh  # 고유 역 좌표 × 동물 4종 품질 우선 사전 계산
RUNART_ETL_LOCAL_ONLY=1 python etl/build_rfs.py
# 로컬 서울시 경사도 + 보행자 신호등 + 가로등 위치 + 공중화장실을 반영

Текущий снимок (data/snapshot.json, 2026-07-11): в граф пешеходных дорог по всему Сеулу (163 848 узлов / 232 006 рёбер) включены уклоны для 232 006 рёбер, баллы перехода на основе 26 769 пешеходных светофоров и баллы освещения на основе 19 316 уличных фонарей. Удобства включают 6 693 круглосуточных магазина, 4 985 туалетов, 2 237 парков и 213 питьевых фонтанчиков.

Файлы графа, объектов и инфраструктуры в формате pickle сверяются с SHA-256 из src/runart/data_integrity.py перед загрузкой. Только при повторном создании этих трёх файлов через ETL можно временно отключить проверку с помощью RUNART_ALLOW_UNVERIFIED_DATA=1, а после проверки необходимо внести новые контрольные суммы в код. В продакшене переменная отключения проверки не устанавливается.

Пресеты маршрутов в форме животных объединяются на основе одинаковых координат из строки 289 в stations.py, после чего для собаки, кота, кита и кролика выполняется поиск по всей дистанции до 11 км. Без ограничения в 3 секунды или досрочного завершения на этапе выполнения выбирается маршрут с максимальным приоритетом сходства с эталонным силуэтом; более короткий маршрут выбирается только при аналогичном сходстве. Результаты сохраняются в data/animal_station_presets.json.gz, причём комбинации без подходящего маршрута также явно сохраняются, чтобы предотвратить повторный поиск во время выполнения. При изменении графа fingerprint меняется, и существующие пресеты автоматически становятся недействительными.

Во время выполнения сначала используется точный пресет для запрошенной точки; если его нет, проверенный маршрут того же животного ищется в радиусе 2 км, с указанием фактической станции отправления, дистанции и времени пешком. Не снижая порог качества, диапазон мгновенных рекомендаций станция × животное расширяется с 421 до 905 комбинаций.

Related MCP server: MCPacer

Структура

Данные о маршрутах, безопасности и объектах предварительно загружены в контейнер и не запрашиваются извне во время выполнения. Однако геокодирование произвольного сеульского адреса, введённого пользователем, в координаты опционально использует Kakao Local API, если задан KAKAO_REST_API_KEY; 289 станций метро и основные топонимы распознаются без сети.

Инструменты (7, все stateless и идемпотентные)

create_seoul_running_course · list_available_shapes · find_facilities_near_course · refine_course · get_course_status · record_animal_completion · extend_shape_relay

Карта животных Сеула (/animals) позволяет просматривать 421 проверенный GPS-арт на одном экране. Записи о завершении маршрутов хранятся не в серверной БД и не через логин, а через самодостаточный passport_token; предоставляются коллекция из 4 видов, 4 значка по регионам и еженедельный ближайший неоткрытый вид животного. Shape Relay (/relay/{token}) также объединяет course_id одного и того же животного из максимум 8 районов в самодостаточный токен для параллельного сравнения и наложения в виде совместного GPS-произведения. Таким образом сохраняется рекомендуемая PlayMCP stateless/no-session архитектура.

Развёртывание (PlayMCP in KC)

docker build --build-arg RUNART_RELEASE_SHA=$(git rev-parse HEAD) -t runnywhere .
docker run -p 8000:8000 -e RUNART_BASE_URL=https://<kc-endpoint> runnywhere

MCP Endpoint: https://<kc-endpoint>/mcp — перед регистрацией в PlayMCP проверьте через MCP Inspector.

Лицензия, данные и безопасность

Исходный код распространяется под лицензией MIT. Производная БД OSM — ODbL 1.0; данные об уклонах Сеула OA-22241, уличных фонарях OA-22205, пешеходных светофорах OA-22356, общественных туалетах OA-22586 и адресах станций Seoul Metro используются по лицензии KOGL Type 1. Координаты станций основаны на открытых данных координат линий 1–8 Seoul Metro (без ограничений на использование). NASA SRTM 30m используется как резервный источник высот. Точки камер безопасности «Ансим» не используются из-за прекращения сервиса; используются только теги OSM surveillance.

Подробные условия источников, обработки и распространения см. в DATA_LICENSES.md, уведомления о зависимостях — в THIRD_PARTY_NOTICES.md. В веб-интерфейсе /terms, /privacy, /data-licenses можно ознакомиться с условиями использования, безопасностью, обработкой информации и источниками. Маршруты предназначены только для справки, а не для навигации в реальном времени; пользователь должен самостоятельно проверять условия на месте, строительные работы, погоду и состояние здоровья.