faa-traffic-delays-mcp-server

---

概要

FAA コマンドセンターからの米国航空交通状況をリアルタイムで確認できます。これは nasstatus.faa.gov の情報源です。空港ごとの地上停止、地上遅延プログラム、遅延、閉鎖を確認できます。全国で発生中のすべてのイベントを一覧表示し、本日の運用計画を参照できるほか、過去の日付を含め、任意のプログラムに関する詳細な勧告を取得できます。

ツール

ツール	説明
faa_delays_get_airport_status	1 回の呼び出しで、米国内の異なる最大 25 空港の現在の状況を確認できます。対象には地上停止、遅延プログラム、遅延、閉鎖、除氷、滑走路構成が含まれ、残りの空港名も表示されます
faa_delays_list_active_events	航空路交通プログラムを含む、全米航空宇宙システム全体で発生中のすべてのイベントを、重大度順に種類別件数とともに表示します
faa_delays_get_operations_plan	コマンドセンターの運用計画を表示します。本日後半に予定されているプログラムと取り組みを、予定時刻および実施可能性とともに確認できます
faa_delays_get_advisory	番号と UTC 日付を指定して、1 件の ATCSCC 勧告の全文を取得します。プログラムの処理率、対象範囲、コメント、計画上の制約が含まれます
faa_delays_list_advisories	指定した UTC 日付に発行された ATCSCC 勧告を新しい順に番号付きで表示します。発行済み、提案、改訂、キャンセルされたプログラム、経路変更、運用計画が含まれます
faa_delays_list_reference	イベントの種類、航空交通管理用語、ARTCC コード、FAA のペーシング空港、識別子の形式を解説します

機能リファレンス

faa_delays_get_airport_status _ツール

• airports：配列またはカンマ区切り文字列で指定する、1～100個のコード。各コードは3文字のFAA識別子（SEA）またはICAOコード（KSEA、PHNL）です。不明なコードがあると、呼び出し全体がunknown_airportとして失敗します。処理されるのは先頭の重複しない空港25件のみです（cap: 25）。残りはprocessedCountとomittedAirportsで示され、次の呼び出しに渡せます
• リクエスト順に空港ごとに1行：status（closed、ground_stop、ground_delay_program、delays、restrictions_only、no_active_events）、listedInFeed、airportName、artcc、座標、および各アクティブイベント（groundStop、15分ごとのdelayProfileを含むgroundDelayProgram、arrivalDelay／departureDelay、closure、closureNotam、deicing）
• runwayConfiguration（滑走路とarrivalRatePerHour）は、フィードに掲載されている空港についてのみ表示されます。PHXはtimezone: "America/Phoenix"とreportedTimezone: "US/Mountain"を報告します

---

faa_delays_list_active_events _ツール

• 任意のevent_typesフィルターで、ground_stop、ground_delay_program、airspace_flow_program、arrival_delay、departure_delay、airport_closure、closure_notam、deicingを指定できます（別名はgs、gdp、afp）。行は重大度順に並び、reason、遅延の数値、時刻、およびFAAがリンクしている場合はadvisory参照を含みます
• totalActiveとcountsByTypeは、フィルター適用前のフィード全体を対象とします。airspace_flow_programの行にはafpの詳細（制限区域、フィルター、高度、遅延プロファイル）が含まれます
• enRouteFeed（ok、unavailable、format_changed）は、Airspace Flow Programsを読み取れたかどうかを示します。読み取れない場合、それらはnoticeとともに省略されます。ただし、リクエストされた種類がそれだけの場合を除きます

---

faa_delays_get_operations_plan _ツール

• 入力なし。terminalPlannedとenRoutePlannedの項目には、text、timeQualifier（after、until、by、between）、timeUtc（日付なしのHHMM）、likelihood（possible、probable、expected）が含まれます
• announcementsには現在のATCSCC発表が一覧表示されます（読み取れない場合はnoticeとともに省略されます）。advisoryは、faa_delays_get_advisoryで取得できる計画全文を指します

---

faa_delays_get_advisory _ツール

• advisory_number（1～999）とdate（UTC、YYYY-MM-DD。MM/DD/YYYYも使用可能）を指定します。これらはfaa_delays_list_advisoriesの行またはadvisory参照から取得します。番号はUTC日ごとに1から始まり、過去のアドバイザリーも引き続き読み取れます
• title、controlElement、subject、effectiveTime、sentAt、全文のtextを返します。不明な番号の場合はfound: falseを返し、guidanceでfaa_delays_list_advisoriesを案内します
• 50,000文字を超えるテキストは切り詰められ、truncatedとtotalCharsでその旨が示されます。失敗はadvisory_service_unavailableまたはadvisory_contract_changedとして通知されます

---

faa_delays_list_advisories _ツール

• date（UTC、YYYY-MM-DD。MM/DD/YYYYも使用可能。明日以前。デフォルトは今日）、任意のcategories（ground_stop、ground_delay_program、airspace_flow_program、ctop、route、other。別名はgs、gdp、afp）、control_element（FAAまたはICAOコードによる空港、ARTCC、または全国向けアドバイザリーを示すDCC）、limit 1～200（デフォルトは50）、およびoffset
• queryは、subjectまたはdetails内の大文字と小文字を区別しない部分文字列に一致します。たとえば、計画内の特定のFCAを検索するには、query: "FCA005"を指定します
• 行は新しいものから順に並びます。numberとdate（faa_delays_get_advisory用）、controlElement、subject、details、sentAtが含まれます。totalCountは一致したすべての件数を示し、残りがある場合はnextOffsetが含まれます。一致する項目がない場合は、空のリストとnoticeが返されます

---

faa_delays_list_reference _ツール

• topic：event_types、terms、artccs、pacing_airports、またはidentifiers
• FAAに問い合わせるのはpacing_airportsのみです（ライブデータ、6時間キャッシュ）。identifiersでは、同梱の空港ディレクトリのサイクル日付と空港数も報告されます

特長

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、差し替え可能な認証（none／jwt／oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングに対応した構造化ログを提供します。

FAA 固有の機能：

• NAS Status フィード（nasstatus.faa.gov/api）および ATCSCC アドバイザリデータベース（www.fly.faa.gov/adv）を、API キーなしで読み取ります。FAA のデータはパブリックドメインです（17 U.S.C. §105）。
• 空港コードは同梱の FAA NASR 空港ディレクトリと照合され、ICAO コードは FAA 識別子にマッピングされます（KSEA → SEA）。そのため、誤ったコードを指定すると、イベントのない空港として読み取るのではなく、エラーになります。
• フィードは 60 秒間（ペーシング対象空港リストは 6 時間）キャッシュされ、各 FAA ホストへのリクエストにはペーシングが適用されます。
• 未文書化のフィードにも対応したパースを行います。読み取れない行はスキップされ、notice に件数が記録されます。

エージェント向けの出力：

• 型付きの失敗理由により、障害（feed_unavailable）、FAA の応答遅延またはスロットリング（retry_deadline_exceeded、upstream_rate_limited、pacer_shed）、フォーマット変更（再試行不可の feed_contract_changed）を区別します。復旧のヒントには、次に呼び出すツールが示されます。
• 副次的なリスト（ペーシング対象空港、航路上のイベント、アナウンス）を読み取れない場合は、呼び出しを失敗させず、notice を添えて省略します。
• fetchedAt はスナップショットの取得日時を示し、6 時間を超えて更新されていない遅延情報は notice で通知されます。
• FAA が作成したテキストは content[] 内で引用され、データとして読み取れる形式になっています。また、structuredContent では原文のまま保持されます。

制限事項：

• 運航用ではなく、情報提供を目的としています。 公式の出発前ブリーフィングや航空会社の運航データの代わりにはなりません。
• 上流フィードは未文書化です。 nasstatus.faa.gov/api/* はダッシュボードの非公開バックエンドであり、予告なく変更される可能性があります。サーバーは推測で処理せず、feed_contract_changed を返します。
• 空港の対象範囲はイベントの発生状況によって決まります。 フィードには進行中のイベントがある空港のみが掲載されるため、no_active_events は FAA のプログラムがないことを意味し、便が定刻であることを示すものではありません。便ごとの EDCT はフィードに含まれません。
• 空港ディレクトリはスナップショットです。 同梱されている NASR のサイクル後に FAA が割り当てた識別子は、次回の更新まで不明な識別子として拒否されます。対象は米国の空港のみです。

はじめに

公開ホストインスタンス

https://faa-traffic-delays.caseyjhand.com/mcp で公開インスタンスを利用できます。インストールは不要です。Streamable HTTP 経由で、任意の MCP クライアントを接続してください。

{
  "mcpServers": {
    "faa-traffic-delays-mcp-server": {
      "type": "streamable-http",
      "url": "https://faa-traffic-delays.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル環境

以下を MCP クライアントの設定ファイルに追加してください。

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

または、npx を使用します（Bun は不要です）。

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

または、Docker を使用します。

{
  "mcpServers": {
    "faa-traffic-delays-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/faa-traffic-delays-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.4.0 以上（または Node.js v24 以降）。
• API キーやアカウントは不要です。FAA のフィードは公開されています。

インストール

1. リポジトリをクローンします。

git clone https://github.com/cyanheads/faa-traffic-delays-mcp-server.git

2. ディレクトリに移動します。

cd faa-traffic-delays-mcp-server

3. 依存関係をインストールします。

bun install

4. 環境を設定します（任意）。

cp .env.example .env
# every variable has a default; edit .env only to change transport, logging, or telemetry

設定

サーバー独自の環境変数はありません。FAA ホスト、キャッシュの有効期間、リクエストのペーシングはサービス内で固定されています。以下のフレームワーク変数は、トランスポート、ログ、テレメトリを設定します。

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_HTTP_HOST	HTTP サーバーのホスト。	127.0.0.1
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto。	stateless
MCP_AUTH_MODE	認証：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）。	info
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）。	<app-root>/logs
OTEL_ENABLED	OpenTelemetry を有効にします。	false

共通のフレームワーク設定を上書きする方法については、.env.example を参照してください。

サーバーの実行

ローカル開発

• 本番バージョンをビルドして実行する：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• チェックとテストを実行する：

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

• 現在のFAA NASRサイクルに基づいて空港ディレクトリを更新する（ネットワークアクセスとシステムのunzipが必要です）：

  bun run refresh:airports
  

プロジェクト構成

ディレクトリ	目的
src/mcp-server/tools	ツール定義（*.tool.ts）、共有出力スキーマ、アドバイザリの日付入力、通知フラグメント、FAA作成テキスト用のMarkdownヘルパーです。
src/services/nas-status	NAS Statusフィードのクライアントと、寛容なフィードパーサーです。
src/services/advisory	ATCSCCアドバイザリデータベースのクライアント、アドバイザリページとインデックスのパーサー、アドバイザリおよびインデックス用URLビルダーです。
src/services/airport-directory	同梱されているFAA NASR空港ディレクトリ（名称、場所、ARTCC、座標）と、ICAO → FAAクロスウォーク（生成モジュール）です。
src/services/upstream	共有FAAフェッチ境界（間隔調整、再試行、ステータス分類）とプロセス内キャッシュです。
scripts/refresh-airport-directory.ts	空港ディレクトリモジュールを再生成します（bun run refresh:airports）。
tests/	合成FAAフィクスチャを使用した単体テストと統合テストで、src/の構成を反映しています。
docs/design.md	ツールの設計、上流APIのメモ、設計上の判断、既知の制限事項です。

開発ガイド

開発ガイドラインとアーキテクチャのルールについては、CLAUDE.mdを参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックにtry/catchを記述しないでください
• ログにはctx.logを使用してください。FAAフィードはプロセス内にキャッシュされ、ctx.stateには保存されません
• 新しいツールはsrc/mcp-server/tools/definitions/index.tsのallToolDefinitionsに登録してください
• 外部API呼び出しはラップし、未加工データを検証 → ドメイン型に正規化 → 出力スキーマを返してください。不足しているフィールドを捏造しないでください

コントリビューション

課題の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

このプロジェクトはApache 2.0 Licenseの下でライセンスされています。詳細はLICENSEファイルを参照してください。