seoul-timeavg-air-mcp: Instructions file for Claude Code

CLAUDE.md — seoul-timeavg-air-mcp

Claude Code는 이 문서만 먼저 읽고 시작한다. 다른 문서(README, DEVLOG) 재탐색 금지. DEVPLAN.md는 API 스펙과 툴 설계를 위해 참고하되, 스펙 재해석/재설계는 하지 않는다.

0. 절대 규칙

• 웹서치 금지. 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

• 항상 UTF-8(BOM 없음)으로 저장한다. BOM이 있으면 python-dotenv가 키를 못 읽는 사례가 있었다.

1-2. 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가 발생하고 Claude.ai 커넥터에서 "사용 가능한 도구 없음"으로 보인다.

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

정상 응답은 TYPE에 따라 오지만, 일부 에러 응답은 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],
            }
        }

정상 XML 응답(TYPE=xml 요청 시)도 파싱해야 하므로, XML 파싱은 xml.etree.ElementTree로 <row> 반복 요소를 순회하는 로직을 별도로 둔다. 기본 TYPE은 json으로 요청하되, JSON 파싱 실패 시 XML 파서로 재시도하는 이중 폴백 구조를 권장한다.

1-4. 인증키는 URL 경로 세그먼트

쿼리 파라미터(?KEY=)가 아니라 경로 세그먼트다:

http://openAPI.seoul.go.kr:8088/{KEY}/{TYPE}/TimeAverageCityAir/{START}/{END}/{MSRMT_DT}

ERROR-300(필수값 누락)이 반복되면 이 구조부터 의심한다.

2. API 키 취급 원칙

• 실제 키 값은 코드에 하드코딩하지 않고 항상 os.environ으로 읽는다.
• .env를 갱신했다는 말을 들으면, 재테스트 전에 실제로 값이 바뀌었는지 파일 크기나 앞 몇 글자로 비교 확인한다.
• 키를 표준출력에 그대로 찍지 않는다. 필요하면 앞 4자리 + ... + 길이만 출력한다.
• 재테스트 요청을 받으면 "이전과 동일한 키인지, 새 키인지" 먼저 확인한다.