# 🚇 지하철 혼잡도 알리미 MCP 서버

> 서울 지하철 1~8호선의 혼잡도 정보를 제공하는 Model Context Protocol (MCP) 서버

출퇴근 시간대에 지하철이 얼마나 혼잡한지 미리 알고, 가장 쾌적한 시간에 이동할 수 있도록 도와주는 똑똑한 비서입니다.

---

## 📋 목차

- [주요 기능](#-주요-기능)
- [왜 이 프로젝트인가?](#-왜-이-프로젝트인가)
- [시작하기](#-시작하기)
- [사용 방법](#-사용-방법)
- [폴더 구조](#-폴더-구조)
- [개발 가이드](#-개발-가이드)
- [문제 해결](#-문제-해결)

---

## ✨ 주요 기능

### 1. 🔍 경로 검색
```
"강남역에서 역삼역 가려는데"
→ 최적 경로 + 혼잡도 정보 + 대안 경로 2개 제시
```

### 2. 📊 역 혼잡도 조회
```
"강남역 지금 혼잡해?"
→ 실시간 혼잡도 + 다음 열차 도착 시간
```

### 3. ⏰ 도착 시간 계산
```
"강남에서 역삼까지 9시까지 도착해야 해"
→ 필요한 출발 시간 + 그 시간대 혼잡도
```

### 4. 🚆 열차 도착 정보
```
"강남역 열차 언제 와?"
→ 다음 3개 열차 도착 시간 + 각 혼잡도
```

### 5. 🔔 지하철 이슈 검색
```
"2호선 지금 지연돼?"
→ 최신 운행 이슈, 고장, 시위 정보
```

---

## 🎯 왜 이 프로젝트인가?

### 기존 앱의 한계
- 네이버/카카오맵: 혼잡도 정보 없음
- 서울교통공사 앱: 실시간 정보만 제공, 예측 불가

### 우리의 차별점
✅ **통계 기반 예측**: 과거 데이터로 시간대별 혼잡도 예측  
✅ **의사결정 지원**: "지금 vs 30분 후" 비교 제공  
✅ **대화형 인터페이스**: Claude와 자연어로 소통  
✅ **대안 제시**: 단순 정보 → 최적 선택 추천

---

## 🚀 시작하기

### 필수 요구사항

- **Python** 3.10 이상
- **pip** 또는 **uv** (권장)
- **Claude Desktop** (MCP 클라이언트)
- API 키 2개 (무료, 필수):
  - ODsay API Key
  - 서울시 Open API Key
  - (선택) Kakao REST API Key

---

### 설치 방법

#### 1단계: 저장소 복제
```bash
git clone https://github.com/yourusername/subway-congestion-mcp.git
cd subway-congestion-mcp
```

#### 2단계: 가상환경 생성 (권장)
```bash
# uv 사용 (권장 - 빠름)
uv venv
source .venv/bin/activate  # Mac/Linux
# 또는
.venv\Scripts\activate  # Windows

# 또는 일반 venv
python -m venv .venv
source .venv/bin/activate
```

#### 3단계: 의존성 설치
```bash
# uv 사용
uv pip install -e .

# 또는 pip 사용
pip install -e .
```

#### 4단계: 환경 설정
```bash
cp .env.example .env
# .env 파일을 열어서 API 키 입력
```

#### 5단계: 데이터 다운로드
```bash
python scripts/download_data.py
```

#### 6단계: 테스트
```bash
pytest
```
 
#### 7단계: 실행
```bash
# 가상환경 활성화 상태에서 실행
python -m subway_congestion_mcp
```

---

### API 키 발급

#### 1. ODsay API (대중교통 경로 검색)

**발급 사이트**: https://lab.odsay.com

1. 회원가입 (무료)
2. "API 사용 신청" 클릭
3. 앱 정보 입력:
   - 앱 이름: `지하철 혼잡도 알리미`
   - 사용 목적: `개인 프로젝트`
   - 플랫폼: `Web/Mobile`
4. API 키 복사 → `.env` 파일의 `ODSAY_API_KEY`에 붙여넣기

**제한**: 하루 1,000건 (무료)

---

#### 2. 서울시 Open API (실시간 도착 정보)

**발급 사이트**: https://data.seoul.go.kr

1. 회원가입 (무료)
2. 상단 메뉴 "인증키 신청" 클릭
3. "활용 신청" 버튼 클릭
4. 인증키 복사 → `.env` 파일의 `SEOUL_API_KEY`에 붙여넣기

**제한**: 하루 1,000건 (무료)

---

### 설정

#### `.env` 파일 예시
```bash
# ODsay API (필수)
ODSAY_API_KEY=your_odsay_api_key_here

# 서울시 Open API (필수)
SEOUL_API_KEY=your_seoul_api_key_here

# 로그 레벨 (DEBUG, INFO, WARNING, ERROR)
LOG_LEVEL=INFO

# 캐시 TTL (초)
CACHE_TTL=300
```

#### Claude Desktop 설정

Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`  
Windows: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "subway-congestion": {
      "command": "uv",
      "args": [
        "--directory",
        "/절대경로/subway-congestion-mcp",
        "run",
        "subway-congestion-mcp"
      ]
    }
  }
}
```

**또는 일반 Python 사용 시:**
```json
{
  "mcpServers": {
    "subway-congestion": {
      "command": "python",
      "args": [
        "-m",
        "subway_congestion_mcp"
      ],
      "env": {
        "PYTHONPATH": "/절대경로/subway-congestion-mcp/src"
      }
    }
  }
}
```

설정 후 Claude Desktop을 재시작하세요.

---

## 💬 사용 방법

### 예제 1: 경로 검색
```
사용자: "강남역에서 역삼역 가려는데"

Claude: 
🚇 최적 경로: 2호선 상선 직통 (1역, 2분)
 • 강남역: 혼잡도 152% (매우혼잡) ⛔
 • 역삼역: 혼잡도 148% (혼잡) 🔴

📌 대안 경로:
 1. 9호선 환승 (12분) - 혼잡도 정보 없음
 2. 146번 버스 (15분) - 혼잡도 정보 없음

💡 2호선이 가장 빠르지만 현재 매우 혼잡합니다.
```

---

## 📁 폴더 구조

```
subway-congestion-mcp/
├── README.md                    # 👈 지금 보고 있는 파일
├── pyproject.toml               # 프로젝트 메타데이터 및 의존성
├── .env.example                 # 환경 변수 템플릿
├── .gitignore                   # Git 제외 파일
│
├── src/
│   └── subway_congestion_mcp/   # 메인 패키지
│       ├── __init__.py
│       ├── __main__.py          # MCP 서버 진입점
│       │
│       ├── server.py            # MCP 서버 설정
│       │
│       ├── tools/               # MCP 도구 정의
│       │   ├── __init__.py
│       │   ├── search_route.py          # 경로 검색
│       │   ├── get_station_congestion.py  # 역 혼잡도 조회
│       │   ├── get_route_congestion.py    # 경로 혼잡도 + 시간 계산
│       │   ├── get_train_arrival.py       # 열차 도착 정보
│       │   └── search_issues.py           # 지하철 이슈 검색
│       │
│       ├── services/            # 비즈니스 로직
│       │   ├── __init__.py
│       │   ├── odsay_service.py     # ODsay API 호출
│       │   ├── seoul_metro_service.py # 서울시 API 호출
│       │   ├── congestion_service.py  # 혼잡도 계산 로직
│       │   └── cache_service.py       # 캐싱 레이어
│       │
│       ├── data/                # 데이터 처리
│       │   ├── __init__.py
│       │   ├── loader.py        # CSV 데이터 로더
│       │   ├── parser.py        # 데이터 파싱
│       │   └── validator.py     # 데이터 검증
│       │
│       ├── utils/               # 유틸리티
│       │   ├── __init__.py
│       │   ├── logger.py        # 로깅 설정
│       │   ├── time_utils.py    # 시간 변환
│       │   ├── error_handler.py # 에러 핸들링
│       │   └── constants.py     # 상수 정의
│       │
│       └── models/              # 데이터 모델 (Pydantic)
│           ├── __init__.py
│           ├── route.py         # 경로 관련 모델
│           ├── station.py       # 역 관련 모델
│           └── congestion.py    # 혼잡도 관련 모델
│
├── data/                        # 정적 데이터
│   ├── congestion/              # 혼잡도 CSV 파일
│   │   ├── line1.csv
│   │   ├── line2.csv
│   │   └── ...
│   └── stations.json            # 역 정보 (좌표, 노선 등)
│
├── tests/                       # 테스트 코드
│   ├── __init__.py
│   ├── test_services/           # 서비스 테스트
│   │   ├── test_odsay_service.py
│   │   └── test_congestion_service.py
│   └── test_tools/              # 도구 테스트
│       ├── test_search_route.py
│       └── test_get_station_congestion.py
│
├── scripts/                     # 유틸리티 스크립트
│   ├── download_data.py         # CSV 데이터 다운로드
│   └── validate_env.py          # 환경 변수 검증
│
└── logs/                        # 로그 파일 (gitignore)
```

---

## 🛠 기술 스택

### 핵심 기술
- **Python 3.10+** - 런타임
- **MCP SDK** - Model Context Protocol
- **Pydantic** - 데이터 검증
- **pandas** - CSV 데이터 처리

### 주요 라이브러리
```toml
[project]
dependencies = [
    "mcp>=0.9.0",              # MCP SDK
    "pydantic>=2.0.0",         # 데이터 검증
    "pandas>=2.0.0",           # CSV 처리
    "requests>=2.31.0",        # HTTP 클라이언트
    "python-dateutil>=2.8.2",  # 날짜/시간 처리
    "python-dotenv>=1.0.0",    # 환경 변수
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",           # 테스트 프레임워크
    "pytest-asyncio>=0.21.0",  # 비동기 테스트
    "black>=23.0.0",           # 코드 포맷팅
    "ruff>=0.1.0",             # 린팅
    "mypy>=1.5.0",             # 타입 체킹
]
```

---

## 👨‍💻 개발 가이드

### 개발 서버 실행
```bash
# MCP Inspector로 테스트
npx @modelcontextprotocol/inspector uv --directory . run subway-congestion-mcp

# 또는 직접 실행
python -m subway_congestion_mcp
```

### 테스트
```bash
# 전체 테스트
pytest

# 특정 파일 테스트
pytest tests/test_services/test_congestion_service.py

# 커버리지 확인
pytest --cov=subway_congestion_mcp --cov-report=html
```

### 코드 품질
```bash
# 포맷팅
black src/

# 린팅
ruff check src/

# 타입 체킹
mypy src/
```

### 로그 확인
```bash
# 실시간 로그
tail -f logs/app.log

# 에러 로그만
tail -f logs/error.log
```

---

## 🐛 문제 해결

### Q1. MCP 서버가 Claude Desktop에 연결되지 않아요

**확인 사항**:
1. `claude_desktop_config.json` 경로가 정확한가?
2. 절대 경로를 사용했는가?
3. 가상환경이 활성화되어 있는가?
4. Claude Desktop을 재시작했는가?

**디버깅**:
```bash
# 직접 실행해보기
cd /절대경로/subway-congestion-mcp
source .venv/bin/activate
python -m subway_congestion_mcp

# 로그 확인
cat ~/Library/Logs/Claude/mcp*.log
```

---

### Q2. API 호출이 실패해요

**확인 사항**:
1. `.env` 파일에 API 키가 정확히 입력되었는가?
2. API 키가 유효한가?
3. 인터넷 연결이 정상인가?

**디버깅**:
```python
# 스크립트로 API 키 테스트
python scripts/test_api_keys.py
```

---

### Q3. 혼잡도 데이터가 없다고 나와요

**확인 사항**:
1. CSV 데이터를 다운로드했는가?
   ```bash
   python scripts/download_data.py
   ```
2. `data/congestion/` 폴더에 파일이 있는가?
3. 1~8호선 역인가? (9호선 미지원)

---

## 📊 성능 최적화

### 캐싱 전략
- **혼잡도 데이터**: 메모리 캐시 (pandas DataFrame)
- **실시간 도착 정보**: 30초 TTL
- **경로 검색 결과**: 10분 TTL

### 에러 핸들링
```python
# Retry 데코레이터
@retry(max_attempts=3, backoff=exponential)
async def call_api():
    ...

# Fallback 전략
try:
    return await get_realtime_data()
except APIError:
    return get_statistical_data()  # 통계 데이터로 대체
```

---

## 🔒 보안

- ✅ API 키는 `.env` 파일에만 저장하고 `.gitignore`로 커밋 제외
- ✅ 키 유출 시 즉시 재발급 및 폐기
- ✅ 샘플 설정은 `.env.example`만 공유
- ✅ 민감한 정보는 로그에 남기지 않음
- ✅ 의존성은 `pyproject.toml`에서 관리

---

## 📈 로드맵

### v1.0 (현재) - MVP
- ✅ 기본 5가지 도구 구현
- ✅ 1~8호선 지원
- ✅ 통계 기반 혼잡도

### v1.1 (예정)
- ⬜ 9호선, 신분당선 지원
- ⬜ 대안 역 추천
- ⬜ 웹 인터페이스

### v2.0 (계획)
- ⬜ 개인화 기능
- ⬜ 알림 설정
- ⬜ 통계 대시보드

---

## 🤝 기여하기

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

---

## 📝 라이센스

MIT License - 자유롭게 사용하세요!

---

## 💬 연락처

문의사항이나 제안사항이 있으시면:
- GitHub Issues
- Email: kimjinjuind@gmail.com

---

**Made with ❤️ for Seoul Subway Commuters**