faa-aircraft-registry-mcp-server

---

概要

FAA の公開可能な航空機データベースを基に、米国の民間航空機登録簿をオフラインで検索できます。Nナンバーから機体、エンジン、登録所有者を照会し、有効・登録抹消済み・予約済みのいずれかを確認できます。また、所有者、メーカーとモデル、州、Mode S コードで検索できます。

ツール

ツール	説明
faa_lookup_registration	1 つのNナンバーを、結合済みの有効な完全レコードに照合します。機体のメーカー／モデル、エンジン、製造年、耐空性、登録ステータス、Mode S コード、登録所有者（マスキングがオフの場合）を取得できます。
faa_get_registration_status	優先順位に従って、有効・登録抹消済み・予約済みの 3 つのステータスファイルすべてからNナンバーを照合し、確定した recordType を返します。
faa_search_registrations	所有者名、メーカー／モデル、メーカー／モデルの完全一致コード、州、機体種別、Mode S コードで有効な登録を検索します。
faa_search_aircraft_types	メーカー／モデル名、種別、カテゴリーで機体参照テーブルを検索し、メーカー／モデルコードを確認できます。
faa_get_aircraft_type	6～7 文字のメーカー／モデル／シリーズコードを機体仕様に変換します。カテゴリー、種別、エンジン、座席数、重量クラス、巡航速度、型式証明データを取得できます。

リソース

リソース	説明
faa://registration/{nNumber}	1つのNナンバーの登録記録全体です。faa_lookup_registrationと同じ、デコード済みで事前結合されたペイロードです。

faa_lookup_registrationからもアクセスできます。検索コレクションはリソースとして公開されていません。

機能リファレンス

faa_lookup_registration _ツール

• N12345または12345を受け付けます。先頭のNは省略できます。
• デコード済みの航空機、エンジン、ステータスの各フィールドを、未加工のコードとラベルで返します。また、Mode Sコードを8進数と16進数で返します（16進数はICAO 24ビットアドレスです）。
• 所有者の氏名と住所は、FAA_REDACT_OWNER_PII=falseの場合にのみ表示されます。それ以外の場合はownerRedacted: trueとなります。
• エラー：not_found（有効な登録がありません。faa_get_registration_statusをお試しください）、invalid_n_number

---

faa_get_registration_status _ツール

• 有効、登録抹消済み、予約済みのファイルをこの順に確認します。
• recordTypeはactive、deregistered、reserved、unknownのいずれかです。一度も発行されていない番号は、エラーではなくunknownを返します。
• 返されるのはステータス情報のみで、所有者データは含まれません。
• エラー：invalid_n_number

---

faa_search_registrations _ツール

• フィルター：ownerName、makeModel、manufacturerModelCode、state、aircraftType、modeSCode。少なくとも1つが必須で、複数指定した場合はANDで結合されます。
• limitは1～200（デフォルトは25）で、offsetを使ってページングできます。結果が上限で切り詰められた場合、レスポンスにtotalCountとnextOffsetが含まれます。
• 各結果には、faa_lookup_registrationに渡すNナンバーが含まれます。
• エラー：no_filters、invalid_code、invalid_state、invalid_mode_s_code、invalid_aircraft_type、owner_search_disabled（FAA_REDACT_OWNER_PIIが有効なため、所有者名検索が無効です）

---

faa_search_aircraft_types _ツール

• フィルター：query（メーカー名／モデル名）、aircraftType（1～9/H/O）、category（1～3）。少なくとも1つが必須です。
• faa_get_aircraft_typeまたはfaa_search_registrations.manufacturerModelCodeに渡すコードを含む概要を返します。
• limitは1～200（デフォルトは25）で、offsetを使ってページングできます。結果が上限で切り詰められた場合、レスポンスにtotalCountとnextOffsetが含まれます。
• エラー：no_filters、invalid_aircraft_type、invalid_category

---

faa_get_aircraft_type _ツール

• 6～7文字の大文字英数字からなるメーカー／モデル／シリーズコードを受け付けます。コードはfaa_search_aircraft_typesで検索できます。
• メーカー、モデル、タイプ、エンジン、カテゴリー、座席数、エンジン数、重量クラス、巡航速度、型式証明データを返します。
• weightClassにはFAAの未加工の文字列が保持されます。既知の値の場合はweightClassLabelがデコード済みのラベルを示します。
• エラー：not_found、invalid_code

---

faa://registration/{nNumber} _リソース

• faa_lookup_registrationと同じペイロードです。形式はapplication/jsonで、1時間キャッシュされます。
• nNumberはN12345または12345を受け付けます。
• エラー：not_found、invalid_n_number

機能

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

FAA登録簿固有の機能：

• 実行時はオフラインで、キーも不要です。クエリはローカルのSQLite + FTS5インデックスに対して実行され、APIキーやレート制限は必要ありません。
• HTTPトランスポートでは、FAAの夜間再公開に合わせてインデックスを毎日更新します。
• 事前結合された記録により、1回の呼び出しでデコード済みの航空機、エンジン、ステータス情報を取得できます。
• 所有者の氏名と住所はデフォルトで伏せられ、FAA_REDACT_OWNER_PII=falseにするまで所有者名検索は無効です。
• Mode Sの16進コードは、フライト追跡フィードで使用されるICAO 24ビットアドレスと一致します。

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

• コード化されたフィールドには、未加工のFAAコードとデコード済みのラベルの両方が含まれます。
• 検索結果が上限で切り詰められると、truncatedに加えてshownとcapが設定されます。
• FAAで空欄のフィールドは、値を補わずに省略されます。
• recordTypeとownerRedactedにより、呼び出し側はデータに応じた分岐処理を行えます。

はじめに

パブリックホストインスタンス

https://faa-aircraft-registry.caseyjhand.com/mcp でパブリックインスタンスを利用できます。インストールは不要です。Streamable HTTP を介して、任意の MCP クライアントから接続してください。

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

セルフホスト／ローカル

初回起動時にはローカルインデックスの構築が必要です。下記の初回セットアップを参照してください。 パッケージには FAA データが含まれていません。mirror:init を一度実行するまでは、クエリは「run mirror:init」という明確なエラーで失敗します。

Desktop MCPB には Node の SQLite ドライバーと、クロスプラットフォーム対応のプリビルドバイナリが含まれています。クエリを実行する前に、バンドルのミラー CLI でローカルインデックスを構築してください。

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

{
  "mcpServers": {
    "faa-aircraft-registry-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/faa-aircraft-registry-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FAA_MIRROR_PATH": "/path/to/faa-registry.db"
      }
    }
  }
}

または npx を使用する場合（Bun は不要です）。

{
  "mcpServers": {
    "faa-aircraft-registry-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/faa-aircraft-registry-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FAA_MIRROR_PATH": "/path/to/faa-registry.db"
      }
    }
  }
}

または Docker を使用する場合（コンテナー間で構築済みインデックスを保持するため、/usr/src/app/.mirror にボリュームをマウントしてください。docker exec … bun run mirror:init で一度だけ構築します）。

{
  "mcpServers": {
    "faa-aircraft-registry-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-v", "faa-registry:/usr/src/app/.mirror",
        "ghcr.io/cyanheads/faa-aircraft-registry-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP の場合は、トランスポートを設定してサーバーを起動してください。

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

FAA_MIRROR_PATH は、サーバーが mirror:init で構築されたインデックスを参照するためのパスです。実行をまたいでインデックスを保持できるよう、永続パスを設定してください。所有者の PII はデフォルトで秘匿されます。所有者の詳細を表示するには、信頼できるローカル環境にインストールした場合に限り、FAA_REDACT_OWNER_PII=false を設定してください。

初回セットアップ

FAA Releasable Aircraft Database はパッケージに含まれていません。これは公開データセット（圧縮時約 70 MB、FAA によって毎日更新）であり、初回使用前に運用者がダウンロードして一度インデックスを作成する必要があります。インデックスの構築により、数百 MB のローカル SQLite ファイルが生成されます。

インデックスはサーバーの起動時ではなく、別途構築してください（約 100 万行をすべて解析するため、起動を妨げないようにする必要があります）。ソースをチェックアウトした場合は、まず bun install && bun run build を実行してください。その後、チェックアウト先、インストール済みパッケージのディレクトリ、または展開した MCPB ディレクトリから、以下のコンパイル済みコマンドを実行してください。Node と Bun のどちらも使用できます。Bun の組み込み SQLite を使う場合は、node を bun に置き換えてください。Docker イメージは bun run mirror:init、mirror:verify、mirror:refresh に対応しています。

# Build the local index from the live FAA download (idempotent, resumable)
FAA_MIRROR_PATH=/path/to/faa-registry.db node dist/cli/faa-mirror-init.js

# Verify it built (readiness + integrity check)
FAA_MIRROR_PATH=/path/to/faa-registry.db node dist/cli/faa-mirror-verify.js

# Rebuild from the latest FAA release (run on a schedule, or out-of-band for stdio)
FAA_MIRROR_PATH=/path/to/faa-registry.db node dist/cli/faa-mirror-refresh.js

• パスを固定してください。 構築済みインデックスを実行間で再利用できるよう、FAA_MIRROR_PATH（および MCP クライアント設定内の同じ環境変数）を永続的な場所に設定してください。デフォルト：.mirror/faa-registry.db。
• 毎日の更新。 HTTP トランスポートでは、サーバーが FAA の夜間再公開時刻（中部時間の午後 11 時 30 分頃）に合わせて、毎日 mirror:refresh をスケジュールします。中断された再構築によってインデックスが空になった場合、再構築が成功するまで、クエリは ServiceUnavailable で明示的に失敗します。stdio の場合は、mirror:refresh を別途実行してください（例：cron ジョブ）。
• Docker。 イメージにはミラー CLI と、実行時ユーザーが所有する書き込み可能な .mirror データディレクトリが含まれています。ここにボリュームをマウントし、mirror:init を一度実行してください（例：docker exec <container> bun run mirror:init、または共有ボリュームに対する単発の初期化ジョブ）。これにより、コンテナーを再起動してもインデックスが保持されます。
• インデックスが存在するまでは、 すべてのクエリが mirror:init を指す復旧ヒント付きの ServiceUnavailable エラーで失敗します。代替となるライブ API はないため、インデックスが未構築の状態では空の結果を返さず、明示的にエラーを通知します。

ソース URL は FAA_DATABASE_URL で上書きできます（プライベートまたはキャッシュされたミラー用）。この値が読み取られるのは取り込み時のみで、リクエストごとには読み取られません。

前提条件

• Bun v1.4 以降、または Node.js v24 以降。Bun は組み込みの bun:sqlite を使用します。Node は同梱の better-sqlite3 依存関係を使用し、macOS、Windows、Linux（glibc/musl）の x64 および arm64 向けに、N-API のプリビルドバイナリが含まれています。
• FAA_MIRROR_PATH に構築済みインデックスを保存するためのディスク容量（数百 MB）。
• FAA ZIP のダウンロードに必要な、mirror:init／mirror:refresh 実行時のネットワークアクセス。クエリ実行時には不要です。

インストール

ローカル開発またはソースからのセルフホストの場合：

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

git clone https://github.com/cyanheads/faa-aircraft-registry-mcp-server.git

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

cd faa-aircraft-registry-mcp-server

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

bun install

4. サーバーをコンパイルしてインデックスを構築します（初回セットアップを参照）：

bun run build
bun run mirror:init

設定

変数	説明	デフォルト
FAA_REDACT_OWNER_PII	所有者の氏名と住所をマスキングし、所有者名による検索を無効にします。未設定、空、または不正な値の場合は true として扱われます。	true
FAA_MIRROR_PATH	SQLite インデックスファイルのパスです。永続化できる場所を指定してください。	.mirror/faa-registry.db
FAA_DATABASE_URL	FAA データベース ZIP のソース URL です。mirror:init / mirror:refresh のみが読み取ります。	FAA レジストリ ZIP
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_SESSION_MODE	セッションモード：auto、stateful、または stateless。	stateless
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_HTTP_ENDPOINT_PATH	MCP サーバーをマウントする HTTP エンドポイントのパスです。	/mcp
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）です。	info
LOGS_DIR	ログファイルのディレクトリです（Node.js のみ）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	失敗したツール呼び出しの引数と結果をそれぞれ記録します（上限：LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES、デフォルトは 16384）。	false
OTEL_ENABLED	OpenTelemetry の計装を有効にします。	false

すべての任意の上書き設定については、.env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行する：

  # One-time build
  bun run rebuild
  
  # Build the local index (see First-run setup)
  bun run mirror:init
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

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

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest unit and integration tests
  bun run test:package # npm tarball + cleaned MCPB runtime checks
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t faa-aircraft-registry-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 \
  -v faa-registry:/usr/src/app/.mirror faa-aircraft-registry-mcp-server
# Build the index once against the mounted volume:
docker run --rm -v faa-registry:/usr/src/app/.mirror faa-aircraft-registry-mcp-server bun run mirror:init

Dockerfile は、デフォルトでステートレスセッションを使用する HTTP トランスポートを設定し、mirror:init / mirror:refresh / mirror:verify CLI を含みます。また、ランタイムユーザーが所有する書き込み可能な .mirror データディレクトリをあらかじめ作成します（そこにボリュームをマウントし、mirror:init を一度実行してインデックスを作成・永続化してください）。ログは /var/log/faa-aircraft-registry-mcp-server に出力されます。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() エントリーポイントです。ツールとリソースを登録し、レジストリサービスを初期化して、HTTP トランスポート使用時には毎日の更新をスケジュールします。
src/config	サーバー固有の環境変数を Zod で解析・検証します。
src/mcp-server/tools	ツール定義（*.tool.ts）。
src/mcp-server/resources	リソース定義（*.resource.ts）。
src/services/registry	レジストリサービスです。SQLite + FTS5 ミラー、取り込み処理、デコードマップ、N 番号の正規化、所有者の個人識別情報をマスキングするゲートを含みます。
src/cli/	ミラーのライフサイクルを管理する CLI です。mirror:init、mirror:refresh、mirror:verify 用に dist/cli/ へコンパイルされます。
tests/	src/ に対応する単体テストと統合テストです。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジック内で try/catch を使用しないでください。
• リクエスト単位のログには ctx.log を、テナント単位のストレージには ctx.state を使用してください。
• src/mcp-server/*/definitions/index.ts のバレルを通じて、新しいツールとリソースを登録してください。

貢献

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

bun run devcheck
bun run test

ライセンス

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

FAA Releasable Aircraft Database は、FAA Civil Aviation Registry が公開する米国政府のパブリックドメインの著作物です。このプロジェクトはそのデータを再配布しません。運用者はインストール時に FAA から直接ダウンロードします。