Runnywhere — Laufstrecken überall planen!

Einreichung für den Kakao PlayMCP Agentic Player 10 Wettbewerb. Sage im KI-Chat "5 km vom Rathaus, ohne Steigungen, in Walform" und es wird eine Laufstrecke auf dem Fußwegenetz von Seoul generiert. Die Daten zu Seouls Steigungen (Höhenlinien), Fußgängerampeln und Laternenstandorten werden in den Running Friendliness Score (RFS) einbezogen, um flache, vorzugsweise nachtsichere Strecken zu bieten. Auch öffentliche Toiletten und OSM-Konvenienzläden in Seoul werden berücksichtigt, um Anfragen wie "an Toiletten/Konvenienzläden vorbei" bei der Streckenauswahl zu nutzen. PRD: ../runart-mcp-prd/PRD.md

Ausführung

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)

Der JSON-Bericht für den PlayMCP-Jury-Nachweis wird wie folgt gespeichert.

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

Die gesamte Antwort der MCP-Tools einschließlich Adresssuche, Wiederholungsversuch und Streckenerstellung unterliegt einer Obergrenze von 2,85 Sekunden, wobei die interne Streckenerstellung und das externe Geocoding dieselbe kürzere Deadline teilen.

Umgebungsvariablen: HOST(Standard lokal 127.0.0.1, Container 0.0.0.0) · PORT(Standard 8000) · RUNART_BASE_URL(Domain für Vorschaulinks) · RUNART_RELEASE_SHA(Deployment Git SHA, verknüpft mit Docker-Build-Argumenten) · KAKAO_JAVASCRIPT_KEY(KakaoMap Web API, erforderlich) · KAKAO_REST_API_KEY(Geocoding, optional) · RUNART_TOKEN_SECRET(32+ Zeichen Signaturschlüssel für Bestiarium- und Relay-Tokens, in Produktion erforderlich) · RUNART_LEGAL_CONTACT(E-Mail für Richtlinienanfragen, bei öffentlicher Verteilung erforderlich) · WEB_CONCURRENCY(Anzahl Web-Worker, Standard 1) · RUNART_POOL_WORKERS(Anzahl Prozesse für Streckensuche, Standard 2) · RATE_LIMIT_RPS(pro IP, Standard 20) · RUNART_MAX_BODY_BYTES(MCP-Anfragebody, Standard 65.536) · RUNART_MAX_CONCURRENT_MCP(gleichzeitige MCP-HTTP-Anfragen, Standard 4) · RUNART_ROUTE_EDIT(Streckenbearbeitung, Standard 1) · RUNART_MAX_CONCURRENT_ROUTE_EDITS(gleichzeitige Neuberechnung von Bearbeitungen, Standard 1) · RUNART_ETL_LOCAL_ONLY=1(vorhandene OSM-Attribute beibehalten, nur lokale Steigungen/Ampeln/Laternen neu anwenden)

Wenn der Laufgraph (data/seoul_graph.pkl) nicht existiert, wird mit einem Demo-Gitter um das Seoul Rathaus gearbeitet (zur Überprüfung der gesamten Pipeline). Vor der Einreichung zum Wettbewerb muss die ETL ausgeführt werden:

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
# 로컬 서울시 경사도 + 보행자 신호등 + 가로등 위치 + 공중화장실을 반영

Aktueller Snapshot (data/snapshot.json, 2026-07-11): Das gesamte Fußgängernetz von Seoul mit 163.848 Knoten / 232.006 Kanten hat Steigungsdaten für 232.006 Kanten, Fußgängerampeln als 26.769 Punkt-basierte Querungswerte und Laternen als 19.316 Punkt-basierte Beleuchtungswerte. An Einrichtungen sind 6.693 Konvenienzläden, 4.985 Toiletten, 2.237 Parks und 213 Trinkbrunnen enthalten.

Die Graph-, Einrichtungs- und Infrastrukturdateien im Pickle-Format werden vor dem Laden mit den SHA-256-Hashes in src/runart/data_integrity.py abgeglichen. Nur bei Neuerstellung dieser drei Dateien durch die ETL wird die Überprüfung mit RUNART_ALLOW_UNVERIFIED_DATA=1 vorübergehend deaktiviert; nach der Prüfung müssen die neuen Prüfsummen in den Code übernommen werden. In der Produktion wird die Deaktivierungsvariable nicht gesetzt.

Tierstrecken-Voreinstellungen werden in stations.py ab Zeile 289 auf Basis identischer Koordinaten zusammengeführt und dann für Hund, Katze, Wal und Kaninchen jeweils bis 11 km über die gesamte Distanz gesucht. Es werden keine Laufzeitbeschränkungen von 3 Sekunden oder vorzeitige Abbrüche angewendet, sondern die Referenz-Silhouettenähnlichkeit wird priorisiert; nur bei ähnlichen Werten wird die kürzere Strecke gewählt. Ergebnisse werden in data/animal_station_presets.json.gz gespeichert; auch Kombinationen ohne passende Strecke werden explizit gespeichert, um eine erneute Suche zur Laufzeit zu verhindern. Bei Änderungen des Graphen ändert sich der Fingerabdruck, sodass vorhandene Voreinstellungen automatisch ungültig werden.

Zur Laufzeit wird zuerst die genaue Voreinstellung des Anfrageortes verwendet; falls nicht vorhanden, wird eine validierte Strecke desselben Tiers im Umkreis von 2 km gesucht und die tatsächliche Startstation, Entfernung und Gehzeit angegeben. Ohne die Qualitätsschwelle zu senken, wird der sofortige Empfehlungsbereich für Station × Tier von 421 auf 905 Kombinationen erweitert.

Related MCP server: MCPacer

Struktur

Strecken-, Sicherheits- und Einrichtungsdaten werden im Container vorab geladen und zur Laufzeit nicht extern abgefragt. Lediglich das Geocoding von vom Benutzer eingegebenen beliebigen Seoul-Adressen in Koordinaten verwendet optional die Kakao Local API, wenn KAKAO_REST_API_KEY gesetzt ist; 289 U-Bahn-Stationen und wichtige Ortsnamen werden netzwerkunabhängig interpretiert.

Tools (7 Stück, alle zustandslos · idempotent)

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

Die Seoul-Tierkarte (/animals) ermöglicht das Durchsuchen von 421 validierten GPS-Kunstwerken auf einem Bildschirm. Die Abschlussaufzeichnung erfolgt nicht über eine Server-DB oder Login, sondern über einen selbstabschließenden passport_token; es werden ein 4-teiliges Bestiarium, 4 regionale Abzeichen und das wöchentlich nächstgelegene unentdeckte Tier angeboten. Shape Relay (/relay/{token}) fasst ebenfalls bis zu 8 Nachbarschaften mit derselben Tier-course_id in einem selbstabschließenden Token zusammen, um sie nebeneinander zu vergleichen und als gemeinsames GPS-Kunstwerk überlagert anzuzeigen. Somit wird die empfohlene zustandslose/keine-Sitzung-Struktur von PlayMCP beibehalten.

Bereitstellung (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-Endpunkt: https://<kc-endpoint>/mcp — Vor der Registrierung bei PlayMCP mit MCP Inspector validieren.

Lizenz · Daten · Sicherheit

Der Quellcode wird unter der MIT License vertrieben. Die OSM-abgeleitete DB unterliegt der ODbL 1.0, die Seoul-Steigungsdaten OA-22241, Laternen OA-22205, Fußgängerampeln OA-22356, öffentliche Toiletten OA-22586 und Seoul Metro Stationsadressen werden unter der öffentlichen Nutzungslizenz Typ 1 (Public Nurri) genutzt. Stationskoordinaten basieren auf den öffentlichen Daten der Seoul Metro Linien 1–8 (keine Nutzungsbeschränkungen). NASA SRTM 30m wird als Höhenfallback verwendet. CCTV-Punkte von "Ansim-i" werden aufgrund der Dienstbeendigung nicht verwendet; nur OSM-surveillance-Tags werden genutzt.

Detaillierte Quellen, Verarbeitung und Weiterverteilungsbedingungen finden sich in DATA_LICENSES.md, Abhängigkeitshinweise in THIRD_PARTY_NOTICES.md. In der Weboberfläche sind unter /terms, /privacy und /data-licenses die Nutzungsbedingungen, Sicherheitshinweise, Datenverarbeitung und Quellen einsehbar. Die Strecken dienen nur als Referenz, nicht als Echtzeitnavigation; der Benutzer muss vor Ort die Durchlässigkeit, Baustellen, Wetter und seinen Gesundheitszustand prüfen.