@cyanheads/aviation-weather-mcp-server

Публичный размещённый сервер: https://aviation-weather.caseyjhand.com/mcp

Инструменты

Пять инструментов, охватывающих авиационную погоду — поиск станций, текущие наблюдения, терминальные прогнозы, пилотские сообщения и активные предупреждения:

aviation_find_stations

Поиск и обнаружение метеостанций с помощью нескольких режимов поиска.

• Поиск одной или нескольких станций по 4-буквенному ICAO-коду (до 20 кодов за вызов) — поиск выполняется только по ICAO, но каждая возвращённая запись включает псевдонимы IATA/FAA, если они доступны

• Обнаружение всех станций в пределах географического ограничивающего прямоугольника

• Список станций для одного из 50 штатов США или округа Колумбия по двухбуквенному почтовому коду USPS (использует bbox + фильтр по штату на стороне клиента)

• Возвращает data_types (METAR, TAF и т. д.), чтобы агенты могли подтвердить доступность данных перед запросом

• Каждый результат указывает, был ли применён верхний предел в 400 строк от вышестоящего API, чтобы усечённая выборка никогда не была принята за все станции в районе — ограниченный запрос по штату также сообщает количество строк до применения фильтра по штату, а меньший bbox является названным рычагом управления

aviation_get_metar

Получение текущих или недавних наблюдений METAR (1–10 станций за вызов).

• Параметр hours (1–12) возвращает историю наблюдений для каждой станции; значение по умолчанию 1 возвращает только самое последнее наблюдение

• Категория полёта (VFR/MVFR/IFR/LIFR) возвращается напрямую из API AWC — не требуется вычислений на стороне клиента

• Расшифровывает слои облачности, ветер с порывами, видимость и текущую погоду (исходные группы плюс пояснения на простом английском, по одному значению на группу) в дополнение к исходной строке METAR

• Нижняя граница облачности охватывает разорванную, сплошную облачность и слои скрытия, а также сообщает, была ли высота измерена или является неопределённой — вертикальная видимость при скрытии облачности

• Поле типа METAR различает METAR (плановое) и SPECI (специальное наблюдение, вызванное значительным изменением погоды)

• Каждый пакет сообщает, какие из запрошенных станций вернулись, чтобы частичный результат никогда не был принят за полное покрытие — отсутствующие коды указываются с рекомендациями по восстановлению

aviation_get_taf

Получение терминальных аэродромных прогнозов для 1–4 аэропортов.

• Возвращает структурированные периоды прогноза с типами изменений (FM, TEMPO, BECMG) и вероятностями

• Прогнозируемая погода расшифровывается группа за группой рядом с исходными группами (-SHRA BR → лёгкие ливневые дожди; дымка), в том же формате, что возвращает aviation_get_metar

• Прогнозируемые скрытия сохраняют свой слой и содержат вертикальную видимость в них (VV002 → неопределённая нижняя граница 200 футов), а не читаются как ясное небо

• Сдвиг ветра на малых высотах (WS020/20040KT) расшифровывается до верхней границы слоя сдвига и прогнозируемого ветра на этой высоте

• valid_from / valid_to в формате ISO 8601 для простого сравнения времени

• Каждый пакет сообщает, какие из запрошенных станций вернулись, чтобы частичный результат никогда не был принят за полное покрытие — отсутствующие коды указываются с рекомендациями по восстановлению

aviation_get_pireps

Поиск недавних пилотских сообщений по станции+радиусу или ограничивающему прямоугольнику.

• station_id + distance_nm (10–500 морских миль, 100 при опускании) для радиального поиска вокруг аэропорта

• bbox для поиска по географической области — полезно для проверки маршрутных коридоров; distance_nm здесь не имеет смысла и отклоняется вместе с ним

• Фильтры altitude_min_ft / altitude_max_ft для выделения сообщений на эшелонах полёта, либо одна граница, либо обе (минимум не должен превышать максимум)

• Массивы турбулентности и обледенения включают до двух слоёв на сообщение (как сообщает API)

• Каждый результат указывает, был ли применён верхний предел в 400 строк от вышестоящего API, называя bbox, distance_nm и hours как рычаги, сужающие запрос до применения предела — фильтр по высоте выполняется после него и не может восстановить отброшенное сообщение

• Примечание: отсутствие PIREP не означает спокойных условий — они по своей природе редки

aviation_get_advisories

Список активных в настоящее время внутренних SIGMET.

• Фильтр advisory_type: sigmet или all (по умолчанию) — оба возвращают активный набор SIGMET

• Фильтр hazard: CONVECTIVE, TURBULENCE, ICING, IFR

• Фильтр bbox применяется на стороне клиента (API AWC возвращает все активные предупреждения; инструмент фильтрует по пересечению полигонов)

• AIRMET не предоставляются. Вышестоящий канал данных содержит только внутренние SIGMET, поэтому advisory_type: airmet и опасности MTN OBSCN, SURFACE WIND и LLWS отклоняются с пояснениями, а не отвечаются SIGMET или пустым массивом

• В периоды хорошей погоды SIGMET может не быть активным — пустой результат является допустимым состоянием, а не ошибкой

Related MCP server: mcp-metar

Промпты

Все данные ресурсов доступны через инструменты. Этот сервер не имеет ресурсов — все данные авиационной погоды чувствительны ко времени (METAR действительны ~1 час, предупреждения — от минут до часов) и непригодны для ресурсов со стабильными URI.

Возможности

Построен на @cyanheads/mcp-ts-core:

• Декларативные определения инструментов и промптов — один файл на примитив, фреймворк обрабатывает регистрацию и валидацию

• Унифицированная обработка ошибок — обработчики выбрасывают, фреймворк перехватывает, классифицирует и форматирует

• Подключаемая аутентификация: none, jwt, oauth

• Структурированное журналирование с опциональной трассировкой OpenTelemetry

• Транспорты STDIO и Streamable HTTP

Специфично для авиационной погоды:

• Без ключа — не требуется API-ключ или аутентификация; все данные поступают из публичного API данных AWC

• Единый сервис (aviation-weather-service) с повтором и экспоненциальной задержкой для публичной конечной точки без ключа

• Исходные закодированные строки (rawOb, rawTAF, rawAirSigmet) отображаются рядом с расшифрованными полями, чтобы агенты имели оба уровня

• Таблица штат→bbox позволяет выполнять запросы станций по штатам США, которые API AWC изначально не поддерживает

• Поле instructions на уровне сервера отображает предупреждение о безопасности «не является официальным брифингом» для всех клиентов при initialize

Дружелюбный к агентам вывод:

• Категория полёта (VFR/MVFR/IFR/LIFR) как дискриминируемое строковое поле — агенты могут ветвиться на нём без разбора нижней границы облачности и видимости

• Структурированные контракты ошибок с типизированными полями reason и подсказками recovery (например, «Проверьте ICAO-коды с помощью aviation_find_stations»)

• Промпт aviation_preflight_brief кодирует правильную последовательность брифинга METAR → TAF → PIREP → предупреждения, которую агенты часто нарушают, пропуская шаги

Начало работы

Публичный размещённый экземпляр

Публичный размещённый экземпляр доступен по адресу https://aviation-weather.caseyjhand.com/mcp. Добавьте его в конфигурацию вашего MCP-клиента:

{
  "mcpServers": {
    "aviation-weather": {
      "type": "streamable-http",
      "url": "https://aviation-weather.caseyjhand.com/mcp"
    }
  }
}

Самостоятельное размещение / локально

Добавьте следующее в файл конфигурации вашего MCP-клиента.

{
  "mcpServers": {
    "aviation-weather": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/aviation-weather-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Или с помощью npx (Bun не требуется):

{
  "mcpServers": {
    "aviation-weather": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/aviation-weather-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Или с помощью Docker:

{
  "mcpServers": {
    "aviation-weather": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/aviation-weather-mcp-server:latest"
      ]
    }
  }
}

Для Streamable HTTP установите транспорт и запустите сервер:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Предварительные требования

• Bun v1.3.0 или выше (или Node.js v24+).

• API-ключ не требуется — API данных AWC полностью публичный и не требует ключа.

Установка

1. Клонируйте репозиторий:

git clone https://github.com/cyanheads/aviation-weather-mcp-server.git

2. Перейдите в каталог:

cd aviation-weather-mcp-server

3. Установите зависимости:

bun install

4. Настройте окружение:

cp .env.example .env
# edit .env if you need to override AWC_BASE_URL or AWC_TIMEOUT_MS

Конфигурация

Полный список необязательных переопределений см. в .env.example.

Запуск сервера

Локальная разработка

• Сборка и запуск:

  bun run rebuild
  bun run start:stdio
  # or
  bun run start:http

• Запуск проверок и тестов:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t aviation-weather-mcp-server .
docker run --rm -p 3010:3010 aviation-weather-mcp-server

Dockerfile по умолчанию использует HTTP-транспорт, режим сеансов без сохранения состояния и записывает журналы в /var/log/aviation-weather-mcp-server. Peer-зависимости OpenTelemetry устанавливаются по умолчанию — для их исключения выполните сборку с --build-arg OTEL_ENABLED=false.

Структура проекта

Руководство по разработке

См. CLAUDE.md для руководства по разработке и архитектурных правил. Краткая версия:

• Обработчики выбрасывают ошибки, фреймворк перехватывает — без try/catch в логике инструментов

• Используйте ctx.log для журналирования в рамках запроса, ctx.state для хранилища в рамках тенанта

• Регистрируйте новые инструменты и промпты через barrel-файлы в src/mcp-server/*/definitions/index.ts

• Обертывайте внешние вызовы API: проверяйте сырые данные → нормализуйте к доменному типу → возвращайте выходную схему; никогда не выдумывайте отсутствующие поля

Не является официальным предполетным брифингом. Данные AWC носят исключительно информационный характер. Для реального планирования полёта требуется авторизованный источник (например, Leidos/1800wxbrief.com). Сервер передаёт этот дисклеймер через поле instructions, отправляемое при каждой initialize.

Участие в разработке

Принимаются issues и pull requests. Перед отправкой запустите проверки и тесты:

bun run devcheck
bun run test

Лицензия

Apache-2.0 — подробности см. в LICENSE.