Seoul Mobility Advisor (mobility-mcp)

카카오 PlayMCP 공모전 출품작 — 날씨·대기질·실시간 교통·따릉이 데이터와 **사진(시각 맥락)**을 종합해 상황에 맞는 이동수단(도보/따릉이/대중교통/자가용)을 추천하는 MCP 서버.

설계 원칙

서버는 '데이터 + 결정론적 도구'만 제공한다. 자연어/이미지 해석과 추천 판단은 **호스트 LLM(PlayMCP AI / Claude)**이 담당한다. 사진 분석도 호스트가 수행해 constraints 태그(예: cannot_ride_bike, formal_attire)로 툴에 넘긴다.

빠른 시작

uv sync --extra dev                 # 의존성 설치
cp .env.example .env                # (선택) 키 입력 — 키 없어도 mock으로 동작
uv run mobility-mcp                 # 로컬 실행 (stdio)

MCP Inspector로 점검

npx @modelcontextprotocol/inspector uv run mobility-mcp

원격 실행 (PlayMCP 등록/배포용, Streamable HTTP)

MCP_TRANSPORT=http uv run mobility-mcp     # → http://localhost:8000/mcp/

테스트

uv run --extra dev pytest

현재 툴 (Phase 1)

툴	설명
get_bike_availability(query?, lat?, lng?, limit=5)	서울 따릉이 실시간 대여가능 수 (키 없으면 샘플)

로드맵

~/.claude/plans/temporal-drifting-peacock.md 참고. Phase 2 날씨/대기/교통 클라이언트 · Phase 3 compare_transport_options 점수엔진 · Phase 4–5 Docker→KC 배포·PlayMCP 등록.

구조

src/mobility_mcp/
  server.py            # FastMCP 앱 + 툴
  config.py            # .env 키 로딩
  clients/seoul_bike.py# 따릉이 클라이언트(+mock)
tests/