airkorea-realtime-mcp: Instructions file for Claude Code

CLAUDE.md — airkorea-realtime-mcp

절대 규칙

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

---

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

.env

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

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

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

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

이유: fly.io는 기본 2대 머신(고가용성)을 띄우므로, 세션이 프로세스 인메모리에만 저장되면 다른 머신으로 라우팅될 때 404가 발생한다. 이 옵션 누락 시 Claude.ai 커넥터에서 "사용 가능한 도구 없음"으로 보이는 문제가 발생한 전례가 있으므로 절대 빠뜨리지 않는다.

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

returnType=json으로 요청해도 일부 에러 응답은 XML로 돌아올 수 있다 (다른 공공 API에서 실측 확인된 패턴). response.json()이 ValueError를 던지면 정규식으로 <resultCode>/<resultMsg> 패턴을 추출하는 폴백을 반드시 구현한다.

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",
                }
            }
        }

이 API의 에러코드 체계 (DEVPLAN.md 1-6절 참고)

서울시 계열(INFO-000/ERROR-3xx)과 다른 공공데이터포털 표준 방식이다. resultCode가 "00"이 아니면 에러로 처리하고, resultMsg를 그대로 사용자에게 전달한다. HTTP status는 정상 요청/에러 요청 모두 200에 가까우므로 반드시 body의 resultCode로 판단해야 한다.

숫자/결측 필드는 항상 안전하게 변환

이 API는 결측치가 문자열 "-"로 오는 사례가 명세서 예제에서 실제로 확인되었다 (<khaiValue>-</khaiValue>). 다른 프로젝트에서 확인된 null/빈 문자열/실수(float) 패턴에 더해 이 "-" 케이스까지 처리하는 안전 변환 함수를 반드시 넣는다: