Runnywhere-PlayMCP: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

프로젝트

Runnywhere(러니웨어) — 서울 보행 도로망 위에 러닝 코스와 동물 모양 GPS 아트 코스를 생성하는 MCP 서버. 카카오 PlayMCP 공모전 출품작이며, PlayMCP 심사 기준(stateless, p99 ≤ 3s, avg ≤ 100ms)이 설계 전반을 지배한다. 사용자 대면 텍스트는 전부 한국어, 코드 주석은 영어다. README.md에 데이터 스냅숏·환경변수 전체 목록이 있다.

명령어

source .venv/bin/activate && pip install -e '.[dev]'
python -m runart.server                  # http://localhost:8000/mcp (Streamable HTTP, JSON)
pytest                                   # 전체 (실제 58MB 그래프 로드 — 첫 테스트가 느림)
pytest 'tests/test_shapes.py::test_shape_course_passes_similarity_gate[dog]' -q  # 단일 테스트
pytest -k "zigzag or detour" -q          # 이름으로 골라 실행
python scripts/loadtest.py 1000 10       # 서버 구동 상태에서 부하 테스트
RUNART_LOADTEST_REPORT=artifacts/playmcp-loadtest.json python scripts/loadtest.py 1000 10
docker build -t runnywhere . && docker run -p 8000:8000 -e RUNART_BASE_URL=https://<endpoint> runnywhere

ETL(그래프·RFS·프리셋 재생성)은 pip install -e '.[etl]' 후 README.md "실행" 절의 순서를 그대로 따른다. 오래 걸리고 결과물이 코드의 체크섬과 묶여 있으므로, 요청받지 않았다면 실행하지 않는다.

아키텍처

의존 방향은 단방향이다: geo → graph/rfs/facilities/infrastructure → course → shapes → server. render·widget·insights·exploration은 표현 계층이고 models는 전역 공유된다. 역방향 import를 만들지 말 것.

• server.py — MCP 툴 9개 + 웹 라우트 17개를 한 앱에서 서빙. FastMCP stateless_http=True, json_response=True.
• course.py — 목표 거리의 원주에 waypoint 4개를 놓고 RFS 가중 Dijkstra로 잇는 순환 코스. 여러 bearing을 시도하고 ±5% 안에 들 때까지 원을 rescale. 후보 순위에는 RFS·경사·따라가기 쉬움과 함께 retrace_share(같은 길 되돌아오는 비율)가 들어간다 — 공원 보행망은 격자가 아니라 나무 구조라 이게 없으면 왕복 코스가 뽑힌다.
• shapes.py — 동물 템플릿(닫힌 폴리라인)을 스케일·회전·스냅한 뒤 유사도 게이트로 판정. 게이트를 못 넘으면 나쁜 코스를 내보내는 대신 거절하고 대안을 제안한다. 게이트 값은 동물마다 다르다(SHAPE_STYLES).
• rfs.py — 러닝 친화도 점수(6개 항목 가중합) + 라우팅 가중치. night_mode는 별도 프로파일, include_hills는 경사 항을 감점에서 가점으로 뒤집는다.
• insights.py — 코스가 스스로에 대해 말하는 것(특징 칩·좋은 점·참고할 점). 파생 문장은 전부 코스가 이미 가진 데이터(RFS 성분·누적 오르막·횡단 수·편의시설)에서만 만든다. 성분 임계값은 서울 전역 실측 중앙값 기준이라 절대 수치가 아니다 — 조명은 도시 전체가 무데이터 기본값 0.5 아래라, 고정 컷오프를 쓰면 "조명 어두움"이 네 코스 중 셋에 붙는다.
• etl/ — 오프라인 파이프라인. 런타임에는 경로·안전·시설 데이터를 위해 외부 API를 절대 호출하지 않는다(지오코딩만 예외).