faa-airmen-registry-mcp-server

---

概要

公開可能な航空従事者データベースの FAA 航空従事者認証記録を、ローカルのスナップショットから提供します。氏名から個別の本人候補を特定し、パイロットおよび非パイロットの証明書と順序付きの限定事項を読み取り、飛行・地上教官およびリモートパイロットを検索し、参考情報としての医療関連項目を読み取れます。

stdio プロセス、ループバック Streamable HTTP サーバー（直接実行または Docker 経由）、または上記の公開ホスト型エンドポイントとして実行できます。セルフホストする場合、別の CLI でスナップショットを構築します。サーバーがデータをダウンロードすることはなく、API キーも不要です。

ツール

ツール	説明
faa_airmen_verify_certificate	氏名または FAA Unique ID で本人候補を検索します。必要に応じて証明書の種類、レベル、限定事項で絞り込み、証明書記録の全項目を読み取ります
faa_airmen_get_type_ratings	パイロット系の証明書すべてと、航空機の型式、カテゴリー／クラス、および計器飛行の限定事項を読み取ります
faa_airmen_check_medical_status	適格性や受給資格の判定を行わず、参考情報としての医療関連項目および BasicMed の項目を読み取ります
faa_airmen_search_instructors	氏名、州、および限定事項で、飛行・地上教官の記録を検索します
faa_airmen_verify_remote_pilot	氏名または Unique ID で、公開可能なリモートパイロット証明書の記録を検索します
faa_airmen_list_reference	コード、解釈ガイダンス、確認された型式記号、およびミラーの状態を読み取ります

機能リファレンス

faa_airmen_verify_certificate _ツール

• mode: "name" では lastName が必須です。firstName、state、city、zipCode を指定すると候補を絞り込めます。nameMatch は指定した各氏名フィールドに適用されます。words（デフォルト）は先頭からの単語全体に一致します。そのため、JOHN は FIRST NAME が JOHN ROBERT の人に一致します（FAA の FIRST NAME には通常ミドルネームも含まれます）。また、SMITH は LAST NAME が SMITH JR の人に一致します。単語の区切りはスペースのみなので、SMITH は SMITH-JONES には一致しません。exact はフィールド全体を比較し、prefix は単語の途中を含め、フィールドの先頭から一致します
• mode: "id" では uniqueId を1つ指定します。これは証明書番号ではなく、A または C に7桁の数字が続く形式の不透明な ID です。氏名や所在地のフィールドを指定すると拒否されます
• certificateType（種別を示す文字、参照トピック certificate_types の説明（remote pilot や flight_instructor など、大文字・小文字は区別されません）、または CFI）で人物を絞り込みますが、その人物が保有する証明書はすべて返されます。同じ名前の人物も、それぞれ別の候補として扱われます
• certificateLevel（参照トピック certificate_levels に記載された1文字。certificateType が必須）、ratingCodes（トピック ratings に記載された1～11個のコード）、typeRatings（トピック type_ratings に記載された1～11個の型式指定。例：B-737）を指定すると、さらに候補を絞り込めます。要求された資格はすべて1つの証明書に含まれている必要があります。一致した場合も、その人物が保有する証明書はすべて返されます。重複した指定はまとめられます。レベルの指定がないコードや型式指定は、どのレベルでも一致します。level/code は、そのレベルの枠に限って一致します。たとえば、A/B-737 は ATP レベルで保有する型式限定を指します。一方、certificateLevel: "A" と B-737 の組み合わせは、C/B-737 を含め、どのレベルでもこれを含む ATP 証明書を求めます
• 資格フィルターを指定した検索で結果が0件の場合、フィルターなしの氏名検索で一致する人物の数が示されるため、氏名が一致しない場合と資格が一致しない場合を区別できます
• FAA_AIRMEN_REDACT_PII が有効な場合（デフォルト）、name モードでは lastName と firstName の両方が必要です。また、nameMatch: "prefix"、city、zipCode は pii_redacted エラーで拒否されます。結果には市と ZIP は含まれません

---

faa_airmen_get_type_ratings _ツール

• faa_airmen_verify_certificate で取得した uniqueId を1つ指定します。FAA のパイロットファイルにあるすべての証明書を返します。各証明書には順序付きの ratings および typeRatings の枠が含まれ、それぞれ raw 値、ordinal、code が保持されます
• ID が不明な場合は found: false を返します。既知の人物でもパイロット以外の証明書しか保有していない場合は、空の certificates 配列を返します

---

faa_airmen_check_medical_status _ツール

• uniqueId を1つ指定します。報告された個別の医療記録をそれぞれ返します。記録には medicalClass、medicalDateRaw、medicalExpireDateRaw（通常は MMYYYY）、BasicMed の講習日とチェックリストの日付（通常は YYYYMMDD）が含まれます
• found により、不明な ID と既知の人物を区別します。hasReportedMedicalFields: false は、報告情報がないことを意味し、決して不適格との判定を示すものではありません。すべての結果に disclaimer が含まれます。これらのフィールドは参考情報であり、適性や資格を証明するものではありません
• FAA_AIRMEN_REDACT_PII が有効な場合（デフォルト）、すべての呼び出しが pii_redacted エラーで拒否されます

---

faa_airmen_search_instructors _ツール

• lastName、firstName、state、city、zipCode、ratingCodes のいずれか1つ以上が必要です。instructorType は flight（F）、ground（G）、または both（デフォルト）です
• ratingCodes には参照トピック ratings に記載された1～11個のコードを指定します。すべて同じ証明書に含まれている必要があります。重複した指定はまとめられます。レベルの指定がないコードは、元データのどのレベルでも一致します。level/code（結果で返される raw 形式。例：F/INSTA。レベルは1文字）は、そのレベルに限って一致します。CFII は F の INSTA、INSTH、INSTI、INSTP のいずれか、MEI は AME または ASME です。INST、ADV、BASIC は G にのみ存在します
• FAA_AIRMEN_REDACT_PII が有効な場合（デフォルト）、氏名検索では lastName と firstName の両方が必要です。また、nameMatch: "prefix"、city、zipCode は pii_redacted エラーで拒否されます。結果には市と ZIP は含まれません
• 一致結果には、条件を満たすすべての instructorCertificates が含まれます。旧式の有効期限フィールドから、現在も有効であるとは判断できません。また、2024年12月の規則により、CFI 証明書には有効期限がなくなりました

---

faa_airmen_verify_remote_pilot _ツール

• faa_airmen_verify_certificate と同じ mode、uniqueId、氏名セレクターを使用します。U 証明書を保有する人のみを返し、その全員を remotePilotCertificates に含めます
• FAA_AIRMEN_REDACT_PII が有効な場合（デフォルト）、同じ氏名制限が適用されます。両方の氏名が必須であり、nameMatch: "prefix"、city、zipCode は pii_redacted によって拒否されます
• 証明書の保有だけでは、Part 107 の定期訓練要件を満たしていることや運航権限があることは確認できません

---

faa_airmen_list_reference _ツール

• topic は certificate_types、certificate_levels、ratings、type_ratings、identifiers、medical_guidance、または mirror_status です。4 つの用語トピックでは、大文字と小文字を区別しない最大 80 文字の filter を指定できます
• 静的トピックと mirror_status は、スナップショットが存在する前でも応答します。type_ratings は、インポート済みスナップショットで確認された型式記号を一覧表示します
• mirror_status は、mirrorStatus.state（missing、ready、unavailable）、refreshState（idle、running、failed）、lastRefreshFailure（完了しなかった更新の段階。たとえば acquisition、validation、disk、cancelled、timeout、または結果を記録せずにプロセスが終了した場合の interrupted）、およびファイルシステムのパスを含まない最新世代の来歴情報を返します

機能

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

FAA 固有の機能：

• 4 つの月次ソースファイル（PILOT_BASIC、NONPILOT_BASIC、PILOT_CERT、NONPILOT_CERT）を対象とするオフライン SQLite 検索。FAA Unique ID で結合し、重複しないすべての証明書と、異なる身元情報のバリエーションを保持します
• 保存前に住所は破棄されます。市区町村と ZIP のインポート、出力、フィルタリングには FAA_AIRMEN_INCLUDE_LOCATION=true が必要です。州は常に利用できます
• 提供時の秘匿化はデフォルトで有効です（FAA_AIRMEN_REDACT_PII は false の場合にのみ無効化されます）。氏名検索には名と姓の両方が必要です。prefix による照合と市区町村／ZIP フィルターは拒否され、市区町村と ZIP は出力から除外され、faa_airmen_check_medical_status のすべての呼び出しが拒否されます。拒否には理由 pii_redacted が付与され、成功したすべての応答には piiRedacted が含まれます。ミラーのインポートには影響しません
• faa-airmen-registry-mirror CLI は各スナップショットをダウンロードして検証し、不変の世代として保存します。更新に失敗しても、最後に完全な世代が引き続き提供されます
• FAA は、住所の公開を拒否した航空従事者を掲載せず、証明書番号や定期訓練の日付も公開していません。検索結果がないことは、資格を持っていない証拠にはなりません。また、該当者が見つかっても、現在の資格特権を示すものではありません。確実な回答にはFAA の公式サービスを利用してください

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

• スナップショットに基づくすべての応答に出典情報が含まれます。ソース名、スナップショットの月、stale フラグ付きのソース経過時間、世代 ID、世代の所在地インポートポリシーに加え、正規化された appliedFilters が含まれます。faa_airmen_list_reference のトピック mirror_status は、ハッシュ、行数、ソース品質に関する警告件数を含む完全なレコードを返します
• レコード全体を対象とするページング：一覧ツールは約 24 KiB の応答上限内で完全な人物情報を返すため、limit（デフォルトは 10、最大 50。より大きな値を指定すると通知とともに 50 件を返します）は上限値です。totalCount、returnedCount、nextOffset は実際のページを示します。オフセットは 10,000 で上限に達し、その時点では atPagingCap がより絞り込んだフィルターの使用を促します
• 次の呼び出しを示す型付きエラー：mirror_missing、location_access_disabled、pii_redacted、invalid_filter など、宣言されている各理由には復旧手順が含まれます。検証エラーは値を示さず、フィールド名と期待される形式（state must be a two-letter state or territory code.）を示します。また、結果が空のページでも件数とガイダンスを返します

はじめに

公開ホストインスタンス

公開インスタンスは https://faa-airmen-registry.caseyjhand.com/mcp で利用できます。インストールもスナップショットも不要です。Streamable HTTP を提供しており、各クライアントで設定形式が異なります。

Claude Code の場合：

claude mcp add --transport http faa-airmen-registry-mcp-server https://faa-airmen-registry.caseyjhand.com/mcp

Cline の場合（cline_mcp_settings.json）：

{
  "mcpServers": {
    "faa-airmen-registry-mcp-server": {
      "type": "streamableHttp",
      "url": "https://faa-airmen-registry.caseyjhand.com/mcp"
    }
  }
}

Cursor の場合（mcp.json）：

{
  "mcpServers": {
    "faa-airmen-registry-mcp-server": {
      "url": "https://faa-airmen-registry.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop では、Settings → Connectors からリモートサーバーを追加します。

ホストインスタンスでは秘匿化が有効です。氏名検索には名と姓の両方が必要で、nameMatch: "prefix" による検索と市区町村／ZIP 検索は拒否され、医療関連の検索は利用できません。デフォルトの words 照合では、単語の先頭部分による検索は引き続き利用できます。すべての機能を利用するには、FAA_AIRMEN_REDACT_PII=false を設定してセルフホストしてください。

セルフホスト／ローカル

ローカルインストールでは独自のスナップショットを提供するため、クライアントを接続する前にビルドしてください。

export FAA_AIRMEN_MIRROR_DIR="$HOME/.local/share/faa-airmen-registry-mcp-server"
npx -y --package @cyanheads/faa-airmen-registry-mcp-server faa-airmen-registry-mirror init

init は現在の FAA アーカイブ（約 57 MB）をダウンロードし、約 1.75 GB の SQLite を生成します。テストでは約 12 分かかりました。インポーターはさらに 1 GiB の空き容量を確保するため、約 3 GB を見込んでください。同じ CLI で verify、status、refresh、prune も実行できます。refresh は現在の世代の隣に次の世代をビルドします（さらに約 1.75 GB）。実行中のサーバーが古い世代を読み取っている可能性があるため、古い世代は削除しません。status は、置き換えられた世代の数とサイズを報告します。ミラーを使用しているサーバープロセスをすべて停止してから、prune を実行してください。書き込みロックを取得し、公開済みのスナップショットが準備できていない場合は処理を拒否します。CURRENT が指していないすべての世代を削除し、削除した内容と解放されたバイト数を表示します。サーバーがまだ開いている世代を削除すると、そのサーバーでの検索が失敗する場合（macOS 上の Bun）や、削除自体が失敗する場合（Windows）があります。

MCP クライアントを同じ FAA_AIRMEN_MIRROR_DIR に設定してください。設定しない場合、両方ともプラットフォームのユーザーデータディレクトリを使用します。市区町村と ZIP を保持するには、インポート時とサーバー実行時の両方で FAA_AIRMEN_INCLUDE_LOCATION=true を設定してください。この設定を有効にせずにインポートしたスナップショットでは、有効化後に refresh が必要です。出力の秘匿化はデフォルトで有効になっており、サーバー実行時にのみ適用されます。医療情報の検索、名前の一部や市区町村／ZIP による検索、出力への市区町村と ZIP の表示など、すべての機能を利用する個人用のローカルインストールでは、サーバーで FAA_AIRMEN_REDACT_PII=false を設定してください。

MCP クライアントの設定

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

{
  "mcpServers": {
    "faa-airmen-registry-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/faa-airmen-registry-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "FAA_AIRMEN_MIRROR_DIR": "/absolute/path/to/airmen-mirror"
      }
    }
  }
}

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

{
  "mcpServers": {
    "faa-airmen-registry-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/faa-airmen-registry-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "FAA_AIRMEN_MIRROR_DIR": "/absolute/path/to/airmen-mirror"
      }
    }
  }
}

または Docker を使用します。イメージはスナップショットを /data/airmen に保存するため、最初に名前付きボリュームを初期化してください。メンテナンス時は同じコマンドで refresh、verify、status を実行します。ボリュームを使用するすべてのサーバーコンテナを停止した後に、prune を実行してください。

docker volume create faa-airmen-data
docker run --rm -v faa-airmen-data:/data/airmen ghcr.io/cyanheads/faa-airmen-registry-mcp-server:latest bun dist/cli/mirror.js init

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

Streamable HTTP の場合は、ループバックでサーバーを起動してください。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Or from the image, published on loopback only:
docker run --rm -p 127.0.0.1:3010:3010 -v faa-airmen-data:/data/airmen ghcr.io/cyanheads/faa-airmen-registry-mcp-server:latest
# Server listens at http://127.0.0.1:3010/mcp

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• スナップショット用に、永続的なローカルストレージが約 3 GB 必要です。ネットワークアクセスが必要なのは init と refresh の実行時のみです。
• Node では、better-sqlite3 はコンパイル手順なしで、x64 および arm64 の macOS、Linux、Windows 用のビルド済みバインディングを読み込みます。実行テストは macOS 上で Node と Bun を使用して行っています。

インストール

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

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

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

cd faa-airmen-registry-mcp-server

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

bun install

4. 環境を設定します：

cp .env.example .env
# set FAA_AIRMEN_MIRROR_DIR, and FAA_AIRMEN_INCLUDE_LOCATION if you want city and ZIP
# FAA_AIRMEN_REDACT_PII=false lifts serving-time redaction on a personal local install

5. スナップショットをビルドして初期化します：

bun run rebuild
node --env-file=.env dist/cli/mirror.js init

CLI は .env を自動では読み込みません。--env-file=.env を渡すか、変数をエクスポートしてください。

設定

変数	説明	デフォルト
FAA_AIRMEN_MIRROR_DIR	CLI とサーバーで共有する永続スナップショットディレクトリです。	プラットフォームのユーザーデータディレクトリに faa-airmen-registry-mcp-server を加えたパス
FAA_AIRMEN_INCLUDE_LOCATION	true にすると、市区町村と ZIP のインポート、および FAA_AIRMEN_REDACT_PII=false の場合の出力とフィルタリングが有効になります。false にすると無効になります。	false
FAA_AIRMEN_REDACT_PII	提供時のレダクションです。デフォルトで有効になり、false（大文字・小文字を問わない）の場合にのみ無効になります。それ以外の値では有効のままです。ミラーがインポートする内容は変更しません。	true
FAA_AIRMEN_STALE_AFTER_DAYS	ソースの経過日数に関する警告しきい値です。1～366 の整数で、認証情報の有効性を判定するものではありません。	45
MCP_TRANSPORT_TYPE	トランスポートです。stdio または http を指定します。	stdio
MCP_HTTP_HOST	HTTP のバインドアドレスです。	127.0.0.1
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_SESSION_MODE	HTTP セッションモードです。stateless、stateful、または auto を指定します。有効な値を指定すると、サーバーの stateless 宣言が上書きされます。	stateless
MCP_AUTH_MODE	認証方式です。none、jwt、または oauth を指定します。	none
MCP_LOG_LEVEL	ログレベルです（debug、info、warning、error など）。	info
OTEL_ENABLED	OpenTelemetry を有効にします。	false

共通のフレームワークのオーバーライドについては、.env.example を参照してください。フレームワークのストレージ設定を変更しても、FAA スナップショットの保存場所は変わりません。

サーバーの実行

ローカル開発

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

  # One-time build and snapshot
  bun run rebuild
  node --env-file=.env dist/cli/mirror.js init
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

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

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

プロジェクト構成

ディレクトリ	用途
src/mcp-server/tools	ツール定義（*.tool.ts）、共有スキーマ、ロスレスレンダリングです。読み取り専用ツールが 6 つあります。
src/services/airmen	FAA データの取得、ストリーミングインポート、不変スナップショットのライフサイクル、クエリ、参照テーブルです。
src/cli	オペレーター向け CLI faa-airmen-registry-mirror です。
src/config	Zod を使用した、サーバー固有の環境変数の解析と検証です。
tests/	合成ソースのライフサイクル、クエリ、MCP コントラクトのテストです。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジック内で try/catch を使わないでください。
• スナップショットはオペレーターが所有し、読み取り専用です。サービスレイヤーに置き、テナントの状態にのみ ctx.state を使用してください。
• src/index.ts の createApp() 配列に新しいツールを登録してください。
• ソース行を検証し、ドメイン型に正規化してから、出力スキーマを返してください。欠落したフィールドを捏造したり、番地を永続化したりしないでください。また、テストや例では合成 ID を使用してください。

貢献

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

bun run devcheck
bun run test

ライセンス

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