air-emission-facility-mcp: Instructions file for Claude Code

Claude Code 실행 지침 — air-emission-facility-mcp

절대 규칙

1. DEVPLAN.md 하나만 읽고 시작. 다른 문서 재탐색 금지.
2. 웹 검색 금지. API 스펙은 DEVPLAN.md에 이미 있음.
3. 불확실하면 추측성 재설계 대신 기본값 1개로 구현 후 DEVLOG.md에 "확인 필요" 기록.
4. 동일 오류 최대 3회까지만 재시도. 3회 실패 시 기록하고 사용자에게 보고.
5. Claude Code의 역할은 "코드 구현 + 로컬 실측 테스트"까지.
   • fly launch / fly secrets set / flyctl deploy 등 fly.io 관련 명령은 절대 자동 실행 금지.
   • 배포는 사용자가 PowerShell에서 직접 수행함.
   • 로컬 테스트까지 마친 후 아래 "작업 완료" 섹션 안내 문구 그대로 출력하고 정지.

---

기술적 필수 사항

.env 파일 처리 (BOM 문제 방지)

.env 파일을 생성하거나 갱신할 때 **반드시 UTF-8 (BOM 없음)**으로 저장한다.

# python-dotenv가 BOM을 읽지 못하는 문제 방지
# .env 값을 생성/갱신할 때:
import os

env_content = f"SEOUL_AIR_EMISSION_API_KEY={api_key}\n"
# ❌ 틀린 방법:
# with open('.env', 'w') as f:
#     f.write(env_content)  # Python 기본값이 BOM을 붙일 수 있음

# ✅ 올바른 방법:
with open('.env', 'w', encoding='utf-8') as f:
    f.write(env_content)

stateless_http=True 필수

server.py의 mcp.run() 호출에 반드시 이 옵션을 포함한다:

mcp.run(
    transport="streamable-http", 
    host="0.0.0.0", 
    port=port, 
    stateless_http=True  # ← 절대 빼지 말 것
)

이유: fly.io는 기본적으로 머신 2대(HA)를 띄우는데, streamable-http 세션이 프로세스 메모리에만 저장되면 다른 머신이 요청을 받을 때 세션을 모르고 404를 반환한다. 이 옵션 없이 배포하면 Claude.ai 커넥터에서 "사용 가능한 도구 없음" 오류가 발생한다.

API 키 취급 원칙

• 실제 키 값은 코드에 하드코딩하지 않음. os.environ으로만 읽기.
• .env 파일을 갱신했다는 사용자 보고 후 재테스트하기 전에, 반드시 파일이 실제로 갱신됐는지 확인할 것.
  • 파일 크기(바이트), 값의 앞 몇 글자 등으로 이전과 달라졌는지 비교.
  • 과거: 사용자가 "갱신했다"고 했으나 실제로는 파일이 그대로여서 같은 오류가 여러 번 반복된 사례 있음.

rate limit 미들웨어 (3단계)

이 MCP는 API 키 없이 공개되므로 반드시 아래 3단계 IP 기반 rate limit을 구현한다.

# server.py 상단에 미들웨어 로직 포함

# 1단계: 분당 호출 제한 (슬라이딩 윈도우)
#   - 같은 IP에서 60초 내 3회 초과 → 429 반환

# 2단계: 반복 위반 차단
#   - 1시간 내 429 응답 5회 이상 → 해당 IP 24시간 차단

# 3단계: 일일 총량 제한
#   - IP당 24시간(rolling) 기준 총 30회 초과 → 429 반환

# 구현 원칙:
# - 저장: in-memory dict/map (서버 재시작 시 초기화 허용)
# - IP 추출: X-Forwarded-For 헤더 (fly.io 프록시 환경) 또는 remote_addr
# - 응답: 429 + "Rate limit exceeded" 메시지
# - 다른 머신의 카운터와 완벽히 동기화되지 않아도 무방 (근사값 허용)