# Seoul Mobility Advisor (`mobility-mcp`)

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

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

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

### MCP Inspector로 점검
```bash
npx @modelcontextprotocol/inspector uv run mobility-mcp
```

### 원격 실행 (PlayMCP 등록/배포용, Streamable HTTP)
```bash
MCP_TRANSPORT=http uv run mobility-mcp     # → http://localhost:8000/mcp/
```

## 테스트
```bash
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/
```