seoul-realtime-air-by-region-mcp: Instructions file for Claude Code

CLAUDE.md — seoul-realtime-air-by-region-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)가 끝나면 아래 "작업 순서"의 정지 시점에서 멈추고, 사용자에게 "PowerShell 창에서 fly launch --no-deploy부터 진행하세요"라고 안내한다.

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

.env

BOM 없는 UTF-8로 저장. python-dotenv가 BOM 있는 파일에서 키를 못 읽는 문제 재발 방지.

server.py의 mcp.run()

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

stateless_http=True 절대 누락 금지 — 없으면 fly.io 멀티머신 환경에서 세션 404, 커넥터에 "사용 가능한 도구 없음"으로 표시되는 문제가 재발한다.

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

정상 응답은 JSON이어도, 일부 에러 응답(INFO-100, INFO-200 등)이 TYPE=json 요청에도 XML로 돌아올 수 있다. response.json()이 실패하면 정규식으로 <CODE>/<MESSAGE> 패턴을 추출하는 폴백 파서를 반드시 구현한다.

import re

def parse_response(text: str) -> dict:
    try:
        return json.loads(text)
    except ValueError:
        code_match = re.search(r"<CODE>(.*?)</CODE>", text)
        msg_match = re.search(r"<MESSAGE>(.*?)</MESSAGE>", text)
        return {
            "RESULT": {
                "CODE": code_match.group(1) if code_match else "UNKNOWN",
                "MESSAGE": msg_match.group(1) if msg_match else text[:200],
            }
        }

API 키 취급 원칙

• 실제 키 값은 os.environ으로만 읽는다. 하드코딩 금지.
• .env 갱신 후 재테스트 전, 파일 크기/앞부분 문자열을 이전 값과 비교해 실제로 바뀌었는지 확인한다.
• 디버깅 시 키를 표준출력에 그대로 찍지 않는다. 필요하면 앞 4자리 + ... + 길이만 출력.
• 키는 쿼리 파라미터가 아니라 URL 경로 세그먼트일 가능성이 높다 (DEVPLAN.md 1-1절 참고). 실측 단계에서 경로 삽입 방식(/{KEY}/json/RealtimeCityAir/...)을 우선 시도하고, ERROR-300이 반복되면 다른 방식도 시도한다.

작업 순서

1. requirements.txt (fastmcp, httpx, python-dotenv)
2. seoul_api.py — API 호출 + 에러코드 매핑 (JSON 우선, XML 폴백 포함), 경로 세그먼트 방식 URL 빌더
3. server.py — 툴 2개 정의(docstring에 필드/단위 명시), stateless_http=True 필수, 아래 "rate limit 미들웨어" 포함
4. .env.example, .gitignore
5. 로컬 테스트 (실제 키로 각 툴 호출):
   • URL 구조(키의 위치: 쿼리 vs 경로)부터 확인. ERROR-300 반복 시 키 위치 의심.
   • SAREA_NM/MSRSTN_NM 조합별 실측: 둘 다 생략, SAREA_NM만, 둘 다 지정, MSRSTN_NM만 (권역 생략) — 각각 정상 동작하는지 확인 후 DEVPLAN.md 2절 "실측 필요 항목" 결과를 DEVLOG.md에 기록
   • START_INDEX/END_INDEX 범위를 넓혀 실제 여러 건이 반환되는지 확인
6. FastMCP 서버 스모크 테스트 (initialize 요청까지만)
7. Dockerfile, fly.toml — 아래 "표준 fly.toml 템플릿" 그대로 사용, fly launch의 자동 생성을 기다리지 않는다.
8. README/DEVLOG 갱신 — 실측으로 확인된 제약사항을 실제 동작 기준으로 정확히 기술
9. git add/commit/push까지 수행 (push는 자동 진행 가능 — 백업 목적, 실제 배포와 무관)
10. 여기서 정지 — 사용자에게 PowerShell에서 fly launch --no-deploy부터 진행하도록 안내