airkorea-statistics-mcp: Instructions file for Claude Code

CLAUDE.md — airkorea-statistics-mcp 개발 지침 (Claude Code용)

0. 시작 전 필독

DEVPLAN.md 하나만 먼저 읽고 시작한다. 다른 문서는 재탐색하지 않는다. 웹서치 금지 — API 스펙은 DEVPLAN.md에 이미 있다.

---

1. 절대 규칙

• DEVPLAN.md 하나만 먼저 읽고 시작. 다른 문서 재탐색 금지.
• 웹서치 금지.
• 불확실하면 추측성 재설계 대신 기본값 1개로 구현 후 DEVLOG.md에 "확인 필요"로 기록.
• 동일 오류 최대 3회까지만 재시도. 3회 실패 시 기록하고 사용자에게 보고.
• 역할은 "코드 구현 + 로컬 실측 테스트"까지다. fly launch, fly secrets set, flyctl deploy, fly logs 등 fly.io 관련 명령은 절대 스스로 실행하지 않는다.
• 배포 준비(코드 구현, 로컬 테스트, git commit/push)가 끝나면 아래 "작업 순서"의 정지 시점에서 멈추고, 사용자에게 PowerShell에서 배포를 진행하라고 안내한다.

---

2. 기술적으로 반드시 적용할 것 (과거 실패 원인 → 재발 방지)

2-1. .env 관련

BOM 문제로 python-dotenv가 키를 못 읽었던 사례가 있음. .env는 항상 UTF-8(BOM 없음)로 저장한다.

2-2. stateless_http=True 필수

mcp.run(transport="streamable-http", host="0.0.0.0", port=port, stateless_http=True)

이 옵션 없이 배포하면 Claude.ai 커넥터에서 "사용 가능한 도구 없음"으로 보이는 문제가 발생했던 전례가 있으므로 절대 빠뜨리지 않는다.

2-3. 응답 파싱은 JSON 우선, XML 폴백 필수

에러 응답이 returnType=json 요청에도 XML로 돌아올 수 있다 (1·2단계 실측 확인). response.json()이 ValueError를 던지면 정규식으로 <CODE>/<MESSAGE> 또는 <resultCode>/<resultMsg> 패턴을 추출하는 폴백을 반드시 구현한다.

2-4. 숫자 필드는 항상 안전하게 변환

def _safe_float(v):
    if v is None or v in ("", "-"):
        return None
    try:
        return float(v)
    except (ValueError, TypeError):
        return None

이 서비스(ArpltnStatsSvc)는 결측과 실측 0을 구분해야 하는 대기질 데이터이므로, 0 대신 None을 반환하는 것을 기본으로 한다. 실측 결과에 따라 조정.

2-5. IP 추출 — Fly-Client-IP 우선

def _get_client_ip(request: Request) -> str:
    fly_client_ip = request.headers.get("fly-client-ip")
    if fly_client_ip:
        return fly_client_ip.strip()
    forwarded = request.headers.get("x-forwarded-for")
    if forwarded:
        return forwarded.split(",")[0].strip()
    return request.client.host if request.client else "unknown"

2-6. CORS preflight(OPTIONS)는 rate limit 카운터에서 제외

class RateLimitMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        if request.method == "OPTIONS":
            return await call_next(request)
        # ... 이하 카운팅 로직