@cyanheads/aviation-weather-mcp-server

공개 호스팅 서버: https://aviation-weather.caseyjhand.com/mcp

도구

항공 기상 — 관측소 조회, 현재 관측, 공항 예보, 조종사 보고, 활성 주의보를 다루는 5가지 도구:

aviation_find_stations

여러 검색 모드로 기상 관측소를 조회하고 발견합니다.

• 4자리 ICAO ID로 하나 이상의 관측소를 조회합니다(호출당 최대 20개 ID) — 조회는 ICAO 전용이지만, 각 반환 레코드에는 사용 가능한 IATA/FAA 별칭이 포함됩니다

• 지리적 공시 상자 내의 모든 관측소를 발견합니다

• 2자리 USPS 코드로 미국 50개 주 또는 DC의 관측소를 나열합니다(bbox + 클라이언트 측 주 필터 사용)

• data_types(METAR, TAF 등)를 반환하여 에이전트가 쿼리 전에 사용 가능한 것을 확인할 수 있게 합니다

• 모든 결과는 상류 400행 상한이 잘렸는지 여부를 명시하므로, 잘린 결과가 해당 지역의 모든 관측소로 오인되지 않습니다 — 상한이 적용된 주 쿼리는 주 필터 이전의 행 수도 보고하며, 더 작은 bbox가 명명된 조정 수단입니다

aviation_get_metar

현재 또는 최근 METAR 관측을 가져옵니다(호출당 1–10개 관측소).

• hours 매개변수(1–12)는 관측소별 관측 이력을 반환합니다. 기본값 1은 가장 최근 것만 반환합니다.

• 비행 범주(VFR/MVFR/IFR/LIFR)는 AWC API에서 직접 반환됩니다 — 클라이언트 측 계산이 필요 없습니다.

• 구름 층, 돌풍을 포함한 바람, 시정, 현재 기상(원시 그룹과 평이한 영어, 그룹당 하나의 판독)을 원시 METAR 문자열과 함께 디코딩합니다.

• 운량은 파편, 전체, 그리고 시정 장애 층을 포함하며, 높이가 측정되었는지 또는 무한 운량인지 보고합니다 — 시정 장애에 대한 수직 시정.

• METAR 유형 필드는 METAR(정기)와 SPECI(중대한 기상 변화로 촉발된 특별 관측)를 구분합니다.

• 모든 배치는 요청된 관측소 중 어떤 것이 반환되었는지 보고하므로, 부분 결과가 전체 범위로 오인되지 않습니다 — 누락된 ID는 복구 지침과 함께 명명됩니다.

aviation_get_taf

1–4개 공항에 대한 공항 예보(TAF)를 가져옵니다.

• 변경 유형(FM, TEMPO, BECMG)과 확률을 포함한 구조화된 예보 기간을 반환합니다.

• 예보 기상은 원시 그룹 옆에 그룹별로 디코딩됩니다(-SHRA BR → 약한 비 소나기; 안개), aviation_get_metar가 반환하는 것과 동일한 형태입니다.

• 예보된 시정 장애는 층을 유지하고 그 안으로의 수직 시정(VV002 → 200피트 무한 운량)을 전달하며, 맑은 하늘로 읽히지 않습니다.

• 저고층 윈드시어(WS020/20040KT)는 시어 층 상단과 그 고도에서의 예보 바람으로 디코딩됩니다.

• valid_from / valid_to는 ISO 8601 형식으로 시간 비교가 간단합니다.

• 모든 배치는 요청된 관측소 중 어떤 것이 반환되었는지 보고하며, 부분 결과가 전체 범위로 오인되지 않습니다 — 누락된 ID는 안내와 함께 명시됩니다.

aviation_get_pireps

관측소+반경 또는 공시 상자로 최근 조종사보를 검색합니다.

• station_id + distance_nm(10–500nm, 생략 시 100)로 공항 주변 방사형 검색

• bbox로 지리적 영역 검색 — 항로 회랑 확인에 유용합니다. distance_nm은 여기서 의미가 없으며 함께 사용하면 거부됩니다.

• altitude_min_ft / altitude_max_ft 필터로 순항 고도의 보고를 분리합니다. 하나만 또는 둘 다 사용할 수 있습니다(최소는 최대를 초과할 수 없음).

• 난기류와 착빙 배열은 보고당 최대 2개 층을 포함합니다(API가 보고한 대로).

• 모든 결과는 상위 400행 제한이 잘렸는지 여부를 명시하며, bbox, distance_nm, hours를 제한이 적용되기 전에 쿼리를 좁히는 수단으로 명명합니다 — 고도 필터는 그 후에 실행되므로 누락된 보고를 복구할 수 없습니다.

• 참고: PIREP이 없다고 해서 기상이 양호하다는 뜻은 아닙니다 — 본질적으로 희소합니다.

aviation_get_advisories

현재 활성 국내 SIGMET을 나열합니다.

• advisory_type 필터: sigmet 또는 all(기본값) — 둘 다 활성 SIGMET 집합을 반환합니다.

• hazard 필터: CONVECTIVE, TURBULENCE, ICING, IFR

• bbox 필터는 클라이언트 측에서 적용됩니다(AWC API는 모든 활성 주의를 반환하고, 도구는 다각형 겹침으로 필터링합니다).

• 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 키나 인증 불필요; 모든 데이터는 공개 AWC Data API에서 제공

• 키 없는 공개 엔드포인트에 대한 재시도 + 지수 백오프가 있는 단일 서비스(aviation-weather-service)

• 원시 코딩 문자열(rawOb, rawTAF, rawAirSigmet)이 디코딩된 필드와 함께 표시되어 에이전트가 두 계층을 모두 사용할 수 있음

• 주→bbox 테이블로 AWC API가 기본 지원하지 않는 미국 주 관측소 쿼리 가능

• 서버 수준 instructions 필드가 "공식 브리핑이 아님" 안전 고지 사항을 initialize 시 모든 클라이언트에 표시

에이전트 친화적 출력:

• 비행 범주(VFR/MVFR/IFR/LIFR)를 구분된 문자열 필드로 제공 — 에이전트는 운량+시정을 파싱하지 않고 분기할 수 있음

• 유형화된 reason 필드와 recovery 힌트가 있는 구조화된 오류 계약(예: "aviation_find_stations로 ICAO ID 확인")

• 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 키 불필요 — AWC Data API는 완전히 공개되어 있으며 키가 필요 없습니다.

설치

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에 로그를 기록합니다. OpenTelemetry 피어 의존성은 기본적으로 설치됩니다. 이를 제외하려면 --build-arg OTEL_ENABLED=false로 빌드하세요.

프로젝트 구조

개발 가이드

개발 지침과 아키텍처 규칙은 CLAUDE.md를 참조하세요. 요약:

• 핸들러는 예외를 던지고 프레임워크가 처리합니다. 도구 로직에는 try/catch를 사용하지 않습니다.

• 요청 범위 로깅에는 ctx.log를, 테넌트 범위 저장에는 ctx.state를 사용합니다.

• src/mcp-server/*/definitions/index.ts의 배럴을 통해 새 도구와 프롬프트를 등록합니다.

• 외부 API 호출을 래핑합니다: 원시 데이터 검증 → 도메인 유형으로 정규화 → 출력 스키마 반환. 누락된 필드를 임의로 생성하지 마세요.

공식 사전 비행 브리핑이 아닙니다. AWC의 데이터는 정보 제공용입니다. 실제 비행 계획에는 공인된 소스(예: Leidos/1800wxbrief.com)가 필요합니다. 서버는 모든 initialize 요청 시 instructions 필드를 통해 이 고지사항을 표시합니다.

기여

이슈와 풀 리퀘스트를 환영합니다. 제출 전에 검사와 테스트를 실행하세요:

bun run devcheck
bun run test

라이선스

Apache-2.0 — 자세한 내용은 LICENSE를 참조하세요.