@cyanheads/aviation-weather-mcp-server

公開ホスト型サーバー: https://aviation-weather.caseyjhand.com/mcp

ツール

航空気象をカバーする5つのツール — 地点検索、現在の観測、空港予報、パイロットレポート、有効なアドバイザリー:

aviation_find_stations

複数の検索モードで気象観測地点を解決・発見します。

• 4文字の ICAO ID で1つ以上の観測地点を検索（1回の呼び出しで最大20 ID）— 検索は ICAO のみですが、各返却レコードには利用可能な場合 IATA/FAA の別名が含まれます

• 地理的なバウンディングボックス内のすべての観測地点を発見

• 2文字の USPS コードで米国50州または DC の観測地点を一覧表示（bbox + クライアント側の州フィルターを使用）

• data_types（METAR、TAF など）を返すため、エージェントはクエリ前に利用可能なものを確認できます

• すべての結果は、上流の400行の上限が結果を切り詰めたかどうかを示すため、切り詰められた描画がその地域のすべての観測地点と誤解されることはありません — 上限に達した州クエリは、州フィルター前の行数も報告し、より小さい bbox が指定されたレバーです

aviation_get_metar

現在または最近の METAR 観測を取得します（1回の呼び出しで1〜10観測地点）。

• hours パラメータ（1〜12）は観測地点ごとの観測履歴を返します。デフォルトの1は最新のみを返します

• 飛行カテゴリー（VFR/MVFR/IFR/LIFR）は AWC API から直接返されます — クライアント側の計算は不要です

• 雲層、風（ガストを含む）、視程、現在の天気（生のグループと平易な英語、グループごとに1つの読み取り）を、生の METAR 文字列に加えて解読します

• シーリングは、切れ間、曇り、遮蔽層をカバーし、高度が測定されたか、不定のシーリングであるかを報告します — 遮蔽への垂直視程

• METAR タイプフィールドは、METAR（定期）と SPECI（重大な気象変化によって引き起こされる特別観測）を区別します

• 各バッチは、要求された観測地点のうちどれが返されたかを報告するため、部分的な結果が完全なカバレッジと誤解されることはありません — 欠落した ID は回復ガイダンスとともに名前が付けられます

Related MCP server: Aviation Weather MCP Server

aviation_get_taf

1〜4の空港のターミナル飛行場予報を取得します。

• 変更タイプ（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〜500 nm、省略時は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 がアクティブでない場合があります — 空の結果はエラーではなく有効な状態です

プロンプト

すべてのリソースデータはツール経由で到達可能です。このサーバーにはリソースがありません — すべての航空気象データは時間に敏感であり（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 → PIREPs → advisories のブリーフィングシーケンスをエンコードします

はじめに

公開ホスト型インスタンス

公開ホスト型インスタンスは 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 フィールドを通じてこの免責事項を提示します。

コントリビューション

Issue とプルリクエストを歓迎します。提出前にチェックとテストを実行してください:

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。