# subway-mcp — 수원역 지하철 실시간 도착정보 MCP 서버

수원역의 **1호선 / 수인분당선** 실시간 도착정보를, Claude 같은 MCP 클라이언트가
조회할 수 있게 해주는 로컬 stdio MCP 서버입니다. 첫 MCP 서버 학습용 프로젝트.

## 구조

| 파일 | 역할 |
|---|---|
| `server.py` | FastMCP 서버 + `@mcp.tool` 정의만 (얇게 유지) |
| `subway_api.py` | 도착정보 API 호출/파싱 (도메인 로직 격리) |
| `.env` | `SUBWAY_SERVICE_KEY=...` (git 커밋 금지) |
| `.env.example` | 키 이름만 적어둔 템플릿 |

## 개발 환경 준비 (uv)

```powershell
cd C:\Users\admin\HJ\subway-mcp
uv sync                       # 의존성 설치 + 가상환경 생성
```

## 실행 / 디버깅 (MCP Inspector)

```powershell
uv run fastmcp dev server.py  # 브라우저로 Inspector 가 열리고 툴을 직접 호출 가능
```

## 진행 상태 (마일스톤)

- [x] **M1** — 빈 서버 + `hello` 더미 툴
- [x] **M2** — 데이터 소스 검증 → **TOPIS 확정** (역명은 "수원"으로 조회)
- [x] **M3** — `get_subway_arrivals` (전체 도착정보)
- [x] **M4** — `get_line_arrivals` (호선/방향 필터)
- [ ] **M5** — Claude Code / Desktop 연결
- [x] **M6** — 에러 처리·한국어 포맷 (역명 오류/노선 오류/타임아웃/키 없음)

## Claude 연결

**Claude Code (모든 프로젝트에서 사용):**
```powershell
claude mcp add --scope user subway-info -- uv run --directory C:\Users\admin\HJ\subway-mcp python server.py
```

**Claude Desktop:** `%APPDATA%\Claude\claude_desktop_config.json` 의 `mcpServers` 에 등록 후 앱 재시작.
```json
{
  "mcpServers": {
    "subway-info": {
      "command": "C:\\Users\\admin\\.local\\bin\\uv.exe",
      "args": ["run", "--directory", "C:\\Users\\admin\\HJ\\subway-mcp", "python", "server.py"]
    }
  }
}
```

## 키 발급

`.env.example` 을 `.env` 로 복사한 뒤 발급받은 서비스키를 넣으세요.
- TOPIS: https://data.seoul.go.kr — "지하철 실시간 도착정보" 인증키 신청