airkorea-forecast-alert-mcp: Instructions file for Claude Code

CLAUDE.md — airkorea-forecast-alert-mcp

절대 규칙

• DEVPLAN.md 하나만 먼저 읽고 시작한다. 다른 문서 재탐색 금지.
• 웹서치 금지 (API 스펙은 DEVPLAN.md에 이미 있음). 단, getMinuDustFrcstDspth50Over는 예외적으로 명세서 자체에 스펙 표가 없으므로, 실제 API를 호출해 raw 응답을 받아보는 것으로 스펙을 확정한다 — 이것은 "웹서치"가 아니라 "실측"이므로 금지 대상이 아니다.
• 불확실하면 추측성 재설계 대신 기본값 1개로 구현 후 DEVLOG.md에 "확인 필요"로 기록.
• 동일 오류 최대 3회까지만 재시도. 3회 실패 시 기록하고 사용자에게 보고.
• 역할은 "코드 구현 + 로컬 실측 테스트"까지다. fly launch, fly secrets set, flyctl deploy, fly logs 등 fly.io 관련 명령은 절대 스스로 실행하지 않는다.
• 배포 준비(코드 구현, 로컬 테스트, git commit/push)가 끝나면 아래 "작업 순서"의 정지 시점에서 멈추고, "사용자 안내 문구"를 그대로 출력한다.

---

이 프로젝트만의 특이사항 (먼저 숙지)

1. getMinuDustFrcstDspth50Over(고농도 초미세먼지 예보)는 명세서에 요청/응답 스펙 표가 없다. 구현 순서를 다른 4개 오퍼레이션과 다르게 잡는다:

   • 먼저 informCode, searchDate 없이(또는 최소 파라미터로) 실제 호출해 raw 응답을 확인
   • 19개 권역별 {지역}50Over 필드명 전체 목록을 실제 응답에서 추출
   • 그 결과를 바탕으로 파싱 코드 작성
   • 확정된 스펙을 DEVLOG.md와 README.md에 기록 (다음에 이 코드를 보는 사람이 명세서를 다시 뒤질 필요 없도록)

2. getUlfptcaAlarmInfo(미세먼지 경보)는 해제 전 데이터의 결측 표기가 다른 오퍼레이션과 다르다. clearDate는 문자열 "--", clearTime은 문자열 ":00", clearVal은 문자열 "공람"으로 올 수 있다(정상적인 상황). 이 값들을 숫자로 강제 변환하려 하면 에러가 나므로, 이 오퍼레이션 전용 안전 변환 로직이 필요하다(아래 "숫자/결측 필드" 절 참고).

3. 오존 관련 오퍼레이션은 계절성이 있다. 오존 예보/주의보는 4월~10월에만 발표된다. 비시즌에 호출했을 때 정상적으로 빈 목록이 오는지, 에러가 나는지 반드시 확인하고 README.md에 이 계절성을 명시한다.

---

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

.env

BOM 없는 UTF-8로 저장한다.

server.py의 mcp.run()은 항상 stateless_http=True 포함

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

응답 파싱: JSON 우선, XML 폴백 필수

import re

def parse_response(text: str) -> dict:
    try:
        return json.loads(text)
    except ValueError:
        code_match = re.search(r"<resultCode>(.*?)</resultCode>", text)
        msg_match = re.search(r"<resultMsg>(.*?)</resultMsg>", text)
        return {
            "response": {
                "header": {
                    "resultCode": code_match.group(1) if code_match else "99",
                    "resultMsg": msg_match.group(1) if msg_match else "UNKNOWN_XML_RESPONSE",
                }
            }
        }