Runnywhere — ¡Crea rutas de running en cualquier lugar!

Obra presentada al concurso Agentic Player 10 de Kakao PlayMCP. Basta con decir "5 km desde el ayuntamiento, sin cuestas, con forma de ballena" en el chat de IA para que se genere una ruta sobre la red de calles peatonales de Seúl. Se incorporan los datos de pendiente de Seúl (altitud·curvas de nivel), semáforos peatonales y ubicación de farolas en la Puntuación de Amabilidad para Correr (RFS) para ofrecer rutas llanas prioritarias y seguras por la noche. También se incorporan los baños públicos de Seúl y los datos de tiendas de conveniencia de OSM para utilizar peticiones como "que pase por un baño/tienda de conveniencia" en la selección de candidatos a ruta. PRD: ../runart-mcp-prd/PRD.md

Ejecución

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)

El informe JSON para la evaluación de PlayMCP se guarda de la siguiente manera.

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

Se aplica un límite de 2,85 segundos a toda la respuesta de la herramienta MCP, incluida la búsqueda de direcciones, los reintentos y la generación de rutas. La generación interna de rutas y la geocodificación externa comparten el mismo plazo, más corto.

Variables de entorno: HOST (por defecto 127.0.0.1 en local, 0.0.0.0 en contenedor) · PORT (por defecto 8000) · RUNART_BASE_URL (dominio del enlace de vista previa) · RUNART_RELEASE_SHA (Git SHA del despliegue, vinculado al argumento de compilación de Docker) · KAKAO_JAVASCRIPT_KEY (API web de KakaoMap, obligatorio) · KAKAO_REST_API_KEY (geocodificación, opcional) · RUNART_TOKEN_SECRET (clave de firma de tokens de pasaporte y relevo, de 32 caracteres o más, obligatorio en producción) · RUNART_LEGAL_CONTACT (correo electrónico de consultas sobre políticas, obligatorio para distribución pública) · WEB_CONCURRENCY (número de workers web, por defecto 1) · RUNART_POOL_WORKERS (número de procesos de exploración de rutas, por defecto 2) · RATE_LIMIT_RPS (por IP, por defecto 20) · RUNART_MAX_BODY_BYTES (cuerpo de la solicitud MCP, por defecto 65.536) · RUNART_MAX_CONCURRENT_MCP (solicitudes HTTP MCP simultáneas, por defecto 4) · RUNART_ROUTE_EDIT (edición de rutas, por defecto 1) · RUNART_MAX_CONCURRENT_ROUTE_EDITS (recalculaciones de edición simultáneas, por defecto 1) · RUNART_ETL_LOCAL_ONLY=1 (conserva los atributos OSM existentes y solo reaplica pendientes/semáforos/farolas locales)

Si no existe el gráfico de ejecución (data/seoul_graph.pkl), se ejecuta con una cuadrícula de demostración del área del Ayuntamiento de Seúl (para verificar el funcionamiento de toda la canalización). Antes de enviar al concurso, ejecute el 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
# 로컬 서울시 경사도 + 보행자 신호등 + 가로등 위치 + 공중화장실을 반영

Instantánea actual (data/snapshot.json, 2026-07-11): refleja 163.848 nodos / 232.006 aristas en el gráfico peatonal de todo Seúl, con pendiente en 232.006 aristas, puntuación de cruce basada en 26.769 puntos de semáforos peatonales y puntuación de iluminación basada en 19.316 puntos de farolas. Las instalaciones incluyen 6.693 tiendas de conveniencia, 4.985 baños, 2.237 parques y 213 fuentes de agua potable.

Los archivos de gráfico, instalaciones e infraestructura en formato pickle se comparan con el SHA-256 de src/runart/data_integrity.py antes de cargarlos. Solo al recrear estos tres archivos con el ETL, desactive temporalmente la verificación con RUNART_ALLOW_UNVERIFIED_DATA=1 y, tras la revisión, refleje la nueva suma de comprobación en el código. En el entorno de producción, no establezca la variable de desactivación de verificación.

Los preajustes de rutas con forma de animal se combinan en la línea 289 de stations.py con las mismas coordenadas de referencia, y luego se exploran todas las distancias hasta 11 km para perro, gato, ballena y conejo. No se aplica el límite de 3 segundos en tiempo de ejecución ni la terminación anticipada; se selecciona la que tenga la mayor similitud de silueta de referencia, y solo cuando las similitudes son similares se elige la ruta más corta. Los resultados se guardan en data/animal_station_presets.json.gz, y las combinaciones sin una ruta adecuada también se guardan explícitamente para evitar una nueva exploración en tiempo de ejecución. Si el gráfico cambia, la huella digital será diferente y los preajustes existentes se invalidarán automáticamente.

En tiempo de ejecución, primero se utiliza el preajuste exacto del punto de solicitud; si no existe, se busca una ruta verificada del mismo animal en un radio de 2 km, indicando la estación de salida real, la distancia recorrida y el tiempo a pie. Sin reducir el umbral de calidad, se amplía el rango de recomendación inmediata de estación×animal de 421 a 905 combinaciones.

Related MCP server: MCPacer

Estructura

Los datos de rutas, seguridad e instalaciones se precargan en el contenedor y no se consultan externamente en tiempo de ejecución. Sin embargo, la geocodificación de direcciones arbitrarias de Seúl introducidas por el usuario a coordenadas utiliza opcionalmente la API Local de Kakao si se ha configurado KAKAO_REST_API_KEY; las 289 estaciones de metro y los nombres de lugares principales se interpretan sin conexión de red.

Herramientas (7, todas sin estado e idempotentes)

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

El Mapa de Animales de Seúl (/animals) permite explorar 421 GPS art verificados en una sola pantalla. El registro de finalización se mantiene mediante un passport_token autocontenido en lugar de una base de datos del servidor o inicio de sesión, y ofrece 4 tipos de álbum de cromos·4 tipos de insignias por región·el animal no descubierto más cercano por semana. Shape Relay (/relay/{token}) también agrupa hasta 8 course_id del mismo animal de diferentes barrios en un token autocontenido para compararlos lado a lado y superponerlos como una obra GPS conjunta. Por lo tanto, se mantiene la estructura sin estado/sin sesión recomendada por PlayMCP.

Despliegue (PlayMCP en 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

Endpoint MCP: https://<kc-endpoint>/mcp — Verificar con MCP Inspector antes de registrar en PlayMCP.

Licencia·Datos·Seguridad

El código fuente se distribuye bajo la Licencia MIT. La base de datos derivada de OSM está bajo ODbL 1.0; los datos de pendiente de Seúl OA-22241·farolas OA-22205·semáforos peatonales OA-22356·baños públicos OA-22586·direcciones de estaciones de Seúl Metro se utilizan bajo el Tipo 1 de Uso Público. Las coordenadas de las estaciones se basan en los datos públicos de coordenadas de las líneas 1–8 de Seúl Metro (sin restricciones de licencia). Se utiliza SRTM 30m de la NASA como altitud de respaldo. Los puntos de CCTV de Seguridad no se utilizan debido al cese del servicio; solo se utilizan las etiquetas de vigilancia de OSM.

Consulte DATA_LICENSES.md para conocer las condiciones detalladas de origen, procesamiento y redistribución, y THIRD_PARTY_NOTICES.md para los avisos de dependencias. En la interfaz web, /terms, /privacy y /data-licenses muestran información sobre uso, seguridad, procesamiento de datos y fuentes. Las rutas son solo de referencia, no para navegación en tiempo real; el usuario debe verificar el tránsito en el lugar, las obras, el clima y su estado de salud.