> ⚠️ **서비스 종료 안내**
> 본 MCP 서버는 2026-08-23부로 fly.io 배포를 종료했습니다.
> 코드는 개발 참고용으로 저장소에 남겨둡니다.

# airkorea-statistics-mcp

한국환경공단 에어코리아 **대기오염통계 서비스(ArpltnStatsSvc)** OpenAPI를 Claude가
사용할 수 있는 MCP(Model Context Protocol) 서버로 제공합니다. 시도별/시군구별
실시간 평균정보와 측정소별 일·월평균 통계를 조회할 수 있습니다.

에어코리아 3단계 분리 개발 중 마지막 단계이며, 1단계(`airkorea-realtime-mcp`),
2단계(`airkorea-forecast-alert-mcp`)와 함께 사용하는 것을 전제로 합니다.

## 제공 기능

| 툴 이름 | 설명 |
|---|---|
| `get_sido_average` | 시도별 실시간 평균정보(시간/일평균) 조회 |
| `get_sigungu_average` | 시군구별 실시간 평균정보(시간/일평균) 조회 |
| `get_station_daily_average` | 측정소별 실시간 일평균 정보 조회(기간 지정) |
| `get_station_monthly_average` | 측정소별 실시간 월평균 정보 조회(기간 지정) |

측정 단위: SO2/CO/O3/NO2 = ppm, PM10/PM2.5 = ㎍/㎥

## 이 MCP의 범위에 대해 (중요)

대기오염통계 서비스(ArpltnStatsSvc) 소속 오퍼레이션 4개만 포함합니다. 아래 2개
오퍼레이션은 원래 3단계 후보였으나, 실제로는 다른 서비스 그룹에 속해 **이번 범위에서
제외**했습니다 (판단 근거는 DEVPLAN.md 0-1절 참고, 결정 경위는 DEVLOG.md 참고):

- `getTMStdrCrdnt`(TM 기준좌표 조회) — 측정소정보 조회 서비스(MsrstnInfoInqireSvc)
  소속, 1단계(`airkorea-realtime-mcp`)와 같은 서비스 그룹
- `getUnityAirEnvrnIdexSnstiveAboveMsrstnList`(통합대기환경지수 나쁨 이상 측정소
  목록조회) — 대기오염정보 조회 서비스(ArpltnInforInqireSvc) 소속, 1·2단계와 같은
  서비스 그룹

두 오퍼레이션을 1·2단계 저장소에 추가할지 여부는 별도로 논의 예정입니다(보류 상태).

## 설치 및 실행

```bash
pip install -r requirements.txt
cp .env.example .env  # AIRKOREA_SERVICE_KEY 입력
python server.py
```

## 환경변수

| 변수명 | 설명 |
|---|---|
| `AIRKOREA_SERVICE_KEY` | 공공데이터포털에서 발급받은 에어코리아 서비스키 |
| `PORT` | 서버 포트 (fly.io 배포 시 자동 설정) |

**주의**: 이 MCP를 호출하려면 공공데이터포털에서 **대기오염통계 서비스
(ArpltnStatsSvc)**에 대한 활용신청이 별도로 되어 있어야 합니다(서비스ID 단위 개별
활용신청 필요). 신청 후 실제 반영까지 1~2시간 소요됩니다.

## 배포 (fly.io)

```powershell
fly launch --no-deploy
fly secrets set AIRKOREA_SERVICE_KEY=발급받은키
flyctl deploy
```

배포 후 커넥터 연결 주소:
```
https://airkorea-statistics-mcp.fly.dev/mcp
```

## Rate Limit

인증 없이 접근 가능한 공개 서버이므로 IP 기준 3단계 rate limit이 적용됩니다:
- 분당 3회 초과 시 429
- 1시간 내 5회 위반 시 24시간 차단
- 일일(rolling 24h) 총 30회 초과 시 429

멀티 머신 배포 시 인메모리 카운터가 머신별로 분리되어 실질 제한이 머신 수에
비례해 완화될 수 있습니다.

## 알려진 제약사항 (실측 확인 완료, 2026-08-23)

- 숫자 필드는 JSON 문자열로 오며 코드에서 float으로 안전 변환. 결측 표현은
  `"-"`가 아니라 **빈 문자열(`""`)** 로 확인됨 (`khaiValue`, `pm10Value` 등에서
  관측).
- `getCtprvnMesureSidoLIst` 응답에 `khaiValue` 필드가 실제로 포함됨을 확인.
- `sidoName=광주` 또는 `전남`을 단독으로 넘기면 `totalCount=0`(데이터 없음)이
  반환됨 — 두 지역은 반드시 병합값 `전남광주`로 조회해야 정상 데이터가 옴
  (명세서와 다른 실제 동작).
- 에러 응답은 실측 범위(코드 30, 10) 내에서는 JSON으로 정상 반환됨. XML 폴백
  파서는 구현되어 있으나 실제 XML 에러 응답은 재현하지 못함 — 만약 향후 XML로
  오는 케이스가 발견되면 DEVLOG.md에 추가 기록 예정.
- SERVICETIMEOUT(504)은 로컬 테스트에서 재현되지 않음 — 재시도 로직(최대 3회)은
  구현되어 있으나 실제 타임아웃 상황에서의 동작은 미확인.

## 데이터 출처

- 제공기관: 한국환경공단 (환경부 업무위탁기관)
- 플랫폼: 공공데이터포털(data.go.kr)
- API명: 한국환경공단_에어코리아_대기오염통계 현황 (ArpltnStatsSvc)
- 라이선스: 공공누리 제1유형 (저작자표시-변경금지)

## 라이선스

MIT License (코드 자체). 원본 데이터는 위 공공누리 라이선스를 따릅니다.