seoul-uncomfort-report-mcp: Instructions file for Claude Code

CLAUDE.md — seoul-uncomfort-report-mcp 실행 지침

0. 절대 규칙 (최우선 준수)

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

---

1. 기술적으로 반드시 적용할 것

1-1. .env

BOM 없는 UTF-8로 저장. 갱신 시:

# [System.IO.File]::WriteAllText(경로, "KEY=값", [System.Text.UTF8Encoding]::new($false))

1-2. server.py의 mcp.run() — stateless_http=True 필수

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

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

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

response.json()이 실패하면 정규식으로 <CODE>/<MESSAGE> 패턴을 추출하는 폴백을 구현한다.

1-4. row 필드 정규화

API 응답에서 결과가 1건이면 row가 단일 dict, 여러 건이면 list로 올 수 있다 (JSON 변환기 특성). 항상 list로 정규화하는 방어 로직을 넣는다:

rows = data.get("row", [])
if isinstance(rows, dict):
    rows = [rows]

1-5. 빈 값 필드 처리 (SmartUncomfStatMonth 전용)

아직 지나지 않은 달은 <MON_08/>처럼 빈 태그로 온다. JSON 변환 시 빈 문자열이나 None이 될 수 있으므로, 숫자 필드 파싱 시 다음과 같이 안전 변환한다:

def _safe_int(v):
    if v is None or v == "":
        return None  # 또는 0 — DEVLOG.md에 어느 쪽으로 확정했는지 기록
    return int(v)

1-6. 인증키 위치 — 경로 세그먼트 방식 우선 시도

DEVPLAN.md 1-1절 참고. 요청 URL은 다음 형태를 기본으로 시도한다:

http://openapi.seoul.go.kr:8088/{KEY}/{TYPE}/{SERVICE}/{START_INDEX}/{END_INDEX}/{YEAR}/{MONTH}

ERROR-300(필수값 누락)이 반복되면 쿼리 파라미터 방식(?KEY=)도 시도해 실측 결과를 DEVLOG.md에 남긴다.

1-7. 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"