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

"강남역 지금 혼잡해?"
→ 실시간 혼잡도 + 다음 열차 도착 시간

"강남에서 역삼까지 9시까지 도착해야 해"
→ 필요한 출발 시간 + 그 시간대 혼잡도

"강남역 열차 언제 와?"
→ 다음 3개 열차 도착 시간 + 각 혼잡도

"2호선 지금 지연돼?"
→ 최신 운행 이슈, 고장, 시위 정보

git clone https://github.com/yourusername/subway-congestion-mcp.git
cd subway-congestion-mcp

# uv 사용 (권장 - 빠름)
uv venv
source .venv/bin/activate  # Mac/Linux
# 또는
.venv\Scripts\activate  # Windows

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

# uv 사용
uv pip install -e .

# 또는 pip 사용
pip install -e .

cp .env.example .env
# .env 파일을 열어서 API 키 입력

python scripts/download_data.py

pytest

# 가상환경 활성화 상태에서 실행
python -m subway_congestion_mcp

# 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

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

{
  "mcpServers": {
    "subway-congestion": {
      "command": "python",
      "args": [
        "-m",
        "subway_congestion_mcp"
      ],
      "env": {
        "PYTHONPATH": "/절대경로/subway-congestion-mcp/src"
      }
    }
  }
}

사용자: "강남역에서 역삼역 가려는데"

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)

[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",             # 타입 체킹
]

# MCP Inspector로 테스트
npx @modelcontextprotocol/inspector uv --directory . run subway-congestion-mcp

# 또는 직접 실행
python -m subway_congestion_mcp

# 전체 테스트
pytest

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

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

# 포맷팅
black src/

# 린팅
ruff check src/

# 타입 체킹
mypy src/

# 실시간 로그
tail -f logs/app.log

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

# 직접 실행해보기
cd /절대경로/subway-congestion-mcp
source .venv/bin/activate
python -m subway_congestion_mcp

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

# 스크립트로 API 키 테스트
python scripts/test_api_keys.py

# Retry 데코레이터
@retry(max_attempts=3, backoff=exponential)
async def call_api():
    ...

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