airkorea-forecast-alert-mcp

MCP-сервер для запросов к OpenAPI прогноза качества воздуха, предупреждений о мелкодисперсной пыли, предупреждений об озоне/жёлтой пыли от Korea Environment Corporation (Air Korea).

Предоставляемые инструменты

Примечание по проектированию: В разделе 3 DEVPLAN.md предписывалось в первую очередь рассмотреть вариант объединения предупреждений об озоне и жёлтой пыли в один инструмент (с разделением по параметру advisory_type), однако по результатам фактического тестирования поля ответов этих двух операций сильно различаются (озон — 8 полей, включая концентрацию, стадию объявления и т.д.; жёлтая пыль — 2 текстовых поля: номер и регион), поэтому было решено, что объединение снизит удобство использования, и инструменты были разделены на 2 (всего 6 инструментов).

Related MCP server: seoul-timeavg-air-mcp

Источники данных

• Предоставляющая организация: Отдел поддержки политики в области качества воздуха, Департамент атмосферной среды, Климатическо-атмосферный штаб Korea Environment Corporation

• Платформа: Портал открытых данных (data.go.kr)

• Группа сервисов: Korea Environment Corporation_Air Korea_Информация о загрязнении воздуха (частично), Korea Environment Corporation_Air Korea_Информация о прогнозе высоких концентраций сверхмелкодисперсной пыли (свыше 50), Korea Environment Corporation_Air Korea_Статус объявления предупреждений о мелкодисперсной пыли, Korea Environment Corporation_Air Korea_Информация о возникновении озона и жёлтой пыли (код группы сервисов B552584)

• Область разрешения на использование: Указание авторства — запрет изменений (обязательное соблюдение указания источника данных (Министерство окружающей среды / Korea Environment Corporation))

Периодичность публикации (важно)

Известные ограничения (подтверждено фактическим тестированием, по операциям — тестирование 22/23 августа 2026 г.)

get_air_quality_forecast (getMinuDustFrcstDspth)

• Поле informData подтверждено как фактически существующее. Каждый элемент массива items различает прогноз на сегодня/завтра/послезавтра, а значение informData (ГГГГ-ММ-ДД) указывает целевую дату соответствующего прогноза. (Например: когда dataTime — "объявлено 23:00 22.08.2026", items приходят в порядке informData "2026-08-22"/"2026-08-23"/"2026-08-24")

• При запросе вне сезона озона (O3) (ноябрь–март) без ошибки возвращается нормальный пустой список (resultCode: "00", totalCount: 0) (подтверждено тестированием 15.01.2026).

• Параметр ver=1.1 в этом тестировании не использовался (подтверждена достаточная работа базовым/старым способом). URL изображений (imageUrl1–imageUrl9) возвращаются как есть, в качестве справочных ссылок.

get_high_pm25_forecast (getMinuDustFrcstDspth50Over)

• В спецификации нет таблицы спецификаций (указано только со ссылкой на документ SWAGGER), поэтому всё определено путём фактического тестирования.

• Параметры searchDate, informCode (PM10/PM25/O3) подтверждены как работающие нормально.

• Полный список имён полей {регион}50Over для 19 регионов (подтверждено фактическим тестированием, в алфавитном порядке): busan50Over, chungbuk50Over, chungnam50Over, daegu50Over, daejeon50Over, gwangju50Over, gyeongbuk50Over, gyeonggibuk50Over, gyeongginam50Over, gyeongnam50Over, incheon50Over, jeju50Over, jeonbuk50Over, jeonnam50Over, sejong50Over, seoul50Over, ulsan50Over, youngdong50Over, youngseo50Over (также предоставляются поля {регион}Grade с тем же шаблоном имени, с текстом хорошо/нормально/плохо/очень плохо).

• ⚠️ Требуется проверка (не решено): Фактическим тестированием подтверждено, что при отсутствии превышения значение равно "X", однако значение при превышении (предполагаемое значение из текста спецификации "O") не воспроизводилось в течение августа 2026 года (сезонно низкий уровень PM2.5) и остаётся неподтверждённым. В коде в качестве значения по умолчанию установлено предполагаемое значение из спецификации ("O"), требуется повторная проверка при фактическом возникновении высоких концентраций.

• Фактическим тестированием подтверждено, что период запроса ограничен примерно последним месяцем (при запросе searchDate за более ранние даты возвращается пустой список с totalCount: 0).

get_pm_alarm_status (getUlfptcaAlarmInfo)

• Согласно спецификации, для ещё не снятых предупреждений clearDate приходит как "--", clearTime как ":00", clearVal как "공람" (не число). Этот инструмент в таком случае при безопасном преобразовании обрабатывает соответствующие поля как null и дополнительно явно указывает статус "не снято (в процессе)" через отдельные поля cleared (bool)/status (строка).

• ⚠️ Требуется проверка (не решено): Были запрошены все фактические данные за 2025–2026 гг. (всего 448 записей), но все они уже были в состоянии снятия, и не удалось найти случай фактического воспроизведения паттерна неснятых ("--"/"공람"). Требуется повторная проверка при возникновении неснятых предупреждений в будущем.

get_ozone_advisory / get_yellowdust_advisory

• Предупреждения об озоне имеют сезонность — публикуются только с апреля по октябрь каждого года (данных вне сезона просто нет; в приведённом выше фактическом тестировании O3 вне сезона для get_air_quality_forecast было отдельно подтверждено, что сам API работает нормально).

• Для обоих get_ozone_advisory и get_yellowdust_advisory подтверждён нормальный вызов с параметром year (2026/2025).

Общее: периодическая нестабильность самого API портала открытых данных

• Во время тестирования при вызовах getMinuDustFrcstDspth, getMinuDustWeekFrcstDspth, getMinuDustFrcstDspth50Over периодически возникали SERVICETIMEOUT_ERROR (код 05) или чистые сетевые таймауты. При повторной попытке того же запроса в большинстве случаев приходил нормальный ответ — это оценивается не как дефект кода, а как проблема нагрузки самого сервера портала открытых данных. Клиент использует таймаут httpx 30 секунд, при необходимости вызывающей стороне рекомендуется выполнять повторные попытки.

Переменные окружения

Установка и запуск (локально)

pip install -r requirements.txt --break-system-packages
cp .env.example .env   # AIRKOREA_SERVICE_KEY 값 입력
python server.py

Развёртывание (fly.io)

fly launch --no-deploy
# fly.toml이 [http_service] 방식인지 확인 후
fly secrets set AIRKOREA_SERVICE_KEY=발급받은키
flyctl deploy

Подключение коннектора Claude.ai

https://airkorea-forecast-alert-mcp.fly.dev/mcp

Политика ограничения частоты запросов

• При превышении 3 запросов в минуту — 429 (при многосерверном развёртывании может фактически смягчаться пропорционально количеству серверов)

• При получении 5 или более ответов 429 в течение 1 часа — блокировка на 24 часа

• При превышении суммарно 30 запросов в сутки (скользящие 24 часа) — 429

Коды ошибок

Используется стандартная система кодов ошибок портала открытых данных (1-й уровень — та же, что в airkorea-realtime-mcp).

Связанные проекты

OpenAPI Air Korea имеет большой масштаб, поэтому разрабатывается раздельно в виде 3 независимых MCP:

Лицензия

MIT (код) / соблюдение KOGL тип 1 (указание авторства) — указание источника данных (Министерство окружающей среды / Korea Environment Corporation)