Runnywhere — Route Your Run Anywhere!

Submission for the Kakao PlayMCP Agentic Player 10 competition. Tell the AI chatbot "5km from City Hall, no uphill, whale shape" and it will generate a runnable course on Seoul's pedestrian road network. Seoul city slope (elevation · contour lines), pedestrian traffic lights, and streetlamp location data are reflected in the Running Friendliness Score (RFS) to provide flat-priority and safe night courses. Seoul city public restroom and OSM convenience store data are also reflected, using requests like "pass by a restroom/convenience store" to select course candidates. PRD: ../runart-mcp-prd/PRD.md

Execution

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)

Save the JSON report for PlayMCP judging evidence as follows.

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

Apply a 2.85-second upper limit to the entire MCP Tool response, including address search, retries, and course generation. Internal course generation and external geocoding share the same, shorter deadline.

Environment variables: HOST (local default 127.0.0.1, container 0.0.0.0) · PORT (default 8000) · RUNART_BASE_URL (preview link domain) · RUNART_RELEASE_SHA (deployment Git SHA, linked to Docker build argument) · KAKAO_JAVASCRIPT_KEY (Kakao Map Web API, required) · KAKAO_REST_API_KEY (geocoding, optional) · RUNART_TOKEN_SECRET (32+ character signing key for illustrated guide/relay tokens, required in production) · RUNART_LEGAL_CONTACT (policy contact email, required for public distribution) · WEB_CONCURRENCY (number of web workers, default 1) · RUNART_POOL_WORKERS (number of course search processes, default 2) · RATE_LIMIT_RPS (per IP, default 20) · RUNART_MAX_BODY_BYTES (MCP request body, default 65,536) · RUNART_MAX_CONCURRENT_MCP (concurrent MCP HTTP requests, default 4) · RUNART_ROUTE_EDIT (course editing, default 1) · RUNART_MAX_CONCURRENT_ROUTE_EDITS (concurrent edit recalculations, default 1) · RUNART_ETL_LOCAL_ONLY=1 (preserve existing OSM attributes, only reapply local slope/traffic lights/streetlamps)

If the actual graph (data/seoul_graph.pkl) is absent, the system runs on a Seoul City Hall area demo grid (for verifying the entire pipeline). Before competition submission, be sure to run the 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
# 로컬 서울시 경사도 + 보행자 신호등 + 가로등 위치 + 공중화장실을 반영

The current snapshot (data/snapshot.json, 2026-07-11) reflects: Seoul-wide pedestrian graph with 163,848 nodes / 232,006 edges, slope on 232,006 edges, crossing scores based on 26,769 pedestrian traffic light points, and lighting scores based on 19,316 streetlamp points. Facilities include 6,693 convenience stores, 4,985 restrooms, 2,237 parks, and 213 water fountains.

Before loading, the graph, facility, and infrastructure files in pickle format are checked against SHA-256 hashes in src/runart/data_integrity.py. Temporarily disable verification with RUNART_ALLOW_UNVERIFIED_DATA=1 only when recreating these three files via the ETL. After review, reflect the new checksums in the code. Do not set the bypass variable in production.

The animal course presets are formed by merging row 289 of stations.py based on identical coordinates, then searching each animal (dog, cat, whale, rabbit) for all distances up to 11 km. Runtime timeouts (3-second limit) or early termination are not applied; reference silhouette similarity is the top priority, with a shorter course selected only when similarity is comparable. Results are saved to data/animal_station_presets.json.gz. Combinations without a suitable course are also explicitly saved to prevent runtime re-searching. If the graph changes, the fingerprint changes, automatically invalidating existing presets.

At runtime, the system first uses the exact preset for the requested station. If unavailable, it finds a verified course for the same animal within 2 km of the station, specifying the actual departure station, travel distance, and walking time. Without lowering the quality gate, this expands the station×animal instant recommendation range from 421 to 905 combinations.

Related MCP server: MCPacer

Structure

Route, safety, and facility data are pre-loaded into the container and are not queried externally at runtime. However, geocoding user-entered arbitrary Seoul addresses to coordinates optionally uses the Kakao Local API if KAKAO_REST_API_KEY is set. 289 subway stations and major landmarks are interpreted without a network connection.

Tools (7 tools, all stateless and idempotent)

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

The Seoul Animal Map (/animals) allows browsing 421 verified GPS art pieces on a single screen. Completion records are linked via a self-contained passport_token instead of a server DB or login, providing a 4-type illustrated guide, 4 types of regional badges, and the nearest undiscovered animal of the week. Shape Relay (/relay/{token}) also carries course_ids for the same animal from up to 8 neighborhoods in a self-contained token, displaying them side-by-side and overlaying them as a collaborative GPS artwork. Thus, the system maintains PlayMCP's recommended stateless/no-session structure.

Deployment (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 — Verify with MCP Inspector before registering with PlayMCP.

License · Data · Safety

Source code is distributed under the MIT License. OSM-derived database uses ODbL 1.0. Seoul city slope OA-22241, streetlamps OA-22205, pedestrian traffic lights OA-22356, public restrooms OA-22586, and Seoul Metro station addresses are used under Public Data Type 1. Station coordinates are based on Seoul Metro Line 1–8 coordinate public data (no use restrictions). NASA SRTM 30m is used as an elevation fallback. Safe-i CCTV points are not used due to service termination; only OSM surveillance tags are used.

Refer to DATA_LICENSES.md for detailed sources, processing, and redistribution conditions, and THIRD_PARTY_NOTICES.md for dependency notices. The web UI provides terms of service, privacy policy, and data sources at /terms, /privacy, and /data-licenses. Courses are for reference only, not real-time navigation; users must verify onsite traffic, construction, weather, and health conditions.