ourairports-mcp-server

公開ホストサーバー: https://ourairports.caseyjhand.com/mcp

概要

ourairports-mcp-server は、空港識別子の解決と座標のグラウンディングを行う静的航空参照レイヤーです。何が存在するか — 空港のカタログ、そのコード、滑走路、navaids、無線周波数 — に答え、何が起きているか（天候、位置）に答えるライブ航空サービスを補完します。

OurAirports のデータセット全体はパブリックドメインに提供され、フラットなCSVとして公開されています。これら6つのCSVファイル — airports、runways、navaids、airport frequencies、countries、regions（約178k行、約20MB）— はパッケージに同梱され、ビルド時にDockerイメージに組み込まれます。起動時にサーバーはこれらをメモリ内インデックスにパースし、すべてのツールはローカルクエリとなります。その結果、APIキーもレート制限もなく、障害を引き継ぐ上流依存もありません。

動作モデルの全体像は次のとおりです:

• 5つの識別子空間にわたるコード解決。 空港はIATA、ICAO、GPS、local、そしてOurAirportsのidentを持ちます。単一のcodeパラメータは統合インデックスに対して解決され（優先順位: ident → ICAO → IATA → GPS → local）、レスポンスは完全なコードセットをエコーバックするため、曖昧な国内コードでも自己修正が可能です。欠落したコード（小さな飛行場にIATAがない場合）はnullとして報告され、決して404にはなりません。

• 大円距離による最近傍探索。 座標ルックアップは、すべての空港（またはnavaid）位置のフラットなFloat64Arrayに対してハバーサインスキャンを実行し、距離順にランク付けされた最近傍結果を、それぞれの方角とともに返します。この規模ではサブミリ秒で、空間インデックスは不要です。

• 正直なスパース性。 上流に存在しないフィールド（標高なし、nullの滑走路寸法）は不明として表示されます。上限に達した結果リストは切り詰めを明示します。

OurAirportsはコミュニティ編集です。データはそのまま提供され、実際の運航において権威あるものではありません。クラウドソースの参考情報として扱ってください。

Related MCP server: mcp-metar

ツール

6つの読み取り専用ツール。すべて同梱インデックスに対するローカルクエリです — コード解決と詳細、空港・滑走路検索、座標のグラウンディング、navaids、国・地域ルックアップテーブル:

ourairports_search_airports

一般的なエントリポイントです。フリーテキスト、ファセット、またはその両方で検索します。

• 名前、自治体、キーワードに対するフリーテキスト検索。トークンはANDマッチ（語順と部分語に対応）

• ファセットフィルタ: country（ISO 3166-1 alpha-2）、region（ISO 3166-2）、type。country/regionは大文字小文字を区別しない完全一致で、前後の空白は無視されます

• 閉鎖空港はデフォルトで除外。include_closedでオプトイン

• 結果は運航中・大規模な空港を優先してランク付けされ、各結果に完全なコードセットと座標が含まれ、ourairports_get_airportへの連鎖が可能

• 切り詰めの開示 — 一致した総数、適用された上限、そして範囲を広げる・狭めるためのガイダンス

ourairports_search_runways

空港横断の滑走路検索です。既知の1つの空港の滑走路を一覧表示するourairports_get_airportの対になるツールです。

• 空港ファセット（country、region、type）で先に空港を絞り込み、次に滑走路ファセット（surface、min_length_ft、min_width_ft、lighted）でその滑走路をフィルタリングします

• surfaceは、上流の生の表面文字列に対する大文字小文字を区別しない部分文字列マッチです（管理された語彙はありません。aspのような短い断片はASP、ASPH、Asphaltに一致します）。正確なコードではありません

• 一致する滑走路ごとに1つのフラットな{ airport, runway }行を返します。3本の滑走路が一致する空港は3行を返します

• 長さまたは幅が不明な滑走路は、対応するmin_*_ftフィルタが設定されている場合に除外されます。データが確認できない閾値を満たすと想定されることはありません

• 閉鎖空港と閉鎖滑走路は、include_closed_airports / include_closed_runwaysが設定されない限り、両方とも除外されます

• 切り詰めの開示 — 一致した総数、適用された上限、そして範囲を広げる・狭めるためのガイダンス

ourairports_get_airport

詳細ツールです。1回の呼び出しで一般的なケースに必要なすべてを返します。

• 単一のcodeを5つの識別子空間すべてに対して大文字小文字を区別せず解決します（優先順位: ident → ICAO → IATA → GPS → local）。前後の空白は無視されます

• 滑走路と無線周波数をインラインで返します。includeでレスポンスをサブセットに絞り込め、出力のincludedフィールドはincludeによって省略された関連と、実際にレコードがない関連を区別します

• 空港の完全なコードセットに加えてresolvedVia / resolutionNoteをエコーバックし、共有された国内コードには曖昧さの警告を返すため、誤った解決は自己修正されます

• 存在しないコードはnullとして報告されます。閉鎖空港は常に解決されます

• どの識別子空間にも一致しない場合は、回復のヒント付きのunknown_codeエラーを返します

ourairports_find_airports

グラウンディングツールです。緯度/経度を最寄りの空港に変換します。

• 大円（ハバーサイン）ランキングで近い順に並び、各結果にクエリ地点からのdistanceKmとbearingDeg（真方位）が含まれます

• radius_km（1〜500、デフォルト100）、オプションのtypeフィルタ、include_closedオプトイン

• 座標を入力すると、ランク付けされた空港が出力されます。ジオコーディングは行わないため、事前に地名を緯度/経度に解決しておく必要があります

• 半径内に結果がない場合、より広いradius_kmを提案するガイダンス

ourairports_find_navaids

航空保安無線施設を2つの方法で検索します。空間的、または空港別です。

• 座標モード: latitude + longitude（+ オプションのradius_km）で、navaidsを距離と方角付きで近い順にランク付けします

• 空港モード: airport_codeで、その空港にサービスを提供するnavaidsを返します

• どちらか一方のモードのみ必須です。両方またはどちらも指定しない場合は検証エラーになります

• 周波数はkHz（保存値。114.5 MHzのVORはfrequencyKhz 114500と表示）とMHzの両方で表示されます

• 空港モードは「空港が見つからない」（unknown_codeエラー）と「空港は見つかったが関連するnavaidsがない」（メモ付きの空リスト）を区別します

リソースとプロンプト

airport://{code}リソースは、リソースコンテキストを注入するクライアント向けのourairports_get_airportの安定URI版です。すべてのデータはツールだけで到達可能であり、ツールのみのクライアントも何も失いません。コーパスはリソースリストとして公開されません（85kの空港を列挙するのはダンプであり、発見の助けには

• パッケージとDockerイメージに組み込まれたバンドル済みパブリックドメインデータセット — 実行時API不要、キー不要、レート制限なし、上流の障害の影響なし

• 起動時に一度だけ構築されるインメモリインデックス: IDマップ、優先順位付き統合コードインデックス、滑走路と周波数に対するairport-ref結合、identをキーとするnavaid結合、座標のフラットなFloat64Array、国/地域マップ、トークン化されたテキスト検索インデックス

• 座標配列に対する総当たりのhaversine最近傍探索 — 85k空港に対してサブミリ秒、空間インデックスへの依存なし

• CSVは列位置ではなくヘッダー名で解析されるため、上流で列の順序が変更されても、フィールドが静かにずれることはありません

エージェントに優しい出力:

• 正直なスパース性 — 上流に存在しないフィールド(IATAなし、標高なし、滑走路寸法はnull)はnullとして表出し、決して捏造されません

• 自己修正型のコード解決 — すべての空港レコードは完全なコードセットとresolvedVia / resolutionNoteをそのまま返し、国をまたいで共有されるコードには曖昧性警告を添えます

• 切り詰めと空結果の開示 — 総数、適用された上限、回復ガイダンスを返すことで、呼び出し側は文章を解析することなく、範囲を広げたり、狭めたり、再クエリしたりできます

はじめに

公開ホステッドインスタンス

公開インスタンスはhttps://ourairports.caseyjhand.com/mcpで利用できます — インストールは不要です。Streamable HTTP経由で任意のMCPクライアントをこのインスタンスに接続してください。クライアント設定は次のとおりです:

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

ローカル / セルフホスト

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

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

またはnpxを使用する場合(Bunは不要):

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

またはDockerを使用する場合:

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

APIキーは不要です — データセットはパッケージとイメージに同梱されています。

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キー、アカウント、外部サービスは不要 — すべてのデータはバンドルされています。

インストール

1. リポジトリをクローン:

git clone https://github.com/cyanheads/ourairports-mcp-server.git

2. ディレクトリに移動:

cd ourairports-mcp-server

3. 依存関係をインストール:

bun install

4. データセットを取得してバンドル(6つのCSVをdata/に書き込みます):

bun run build:data

データの更新

バンドルされたスナップショットの鮮度は、最後にbuild:dataを実行した時点(またはDockerイメージの場合は最後のビルド時点)と同じです。OurAirportsミラーから最新のデイリードロップを取得するには、bun run build:dataを再実行してリビルドしてください。再ビルドせずに既存のローカルデータドロップを参照するには、OURAIRPORTS_DATA_DIRを設定します。

設定

オプションの上書き設定の全一覧は.env.exampleを参照してください。

サーバーの実行

ローカル開発

• ビルドして実行:

  # One-time data fetch + build
  bun run build:data
  bun run rebuild
  
  # Run the built server
  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 ourairports-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=stdio ourairports-mcp-server

ビルドステージでbun run build:dataが実行されるため、データセットは取得されてイメージに組み込まれます — 生成されたコンテナは完全に自己完結しており、実行時にネットワーク呼び出しを行いません。DockerfileはデフォルトでHTTPトランスポートとstatelessセッションモードを使用し、ログは/var/log/ourairports-mcp-serverに出力します。OpenTelemetryのピア依存関係はデフォルトでインストールされます — これらを除外するには--build-arg OTEL_ENABLED=falseを指定してビルドしてください。

プロジェクト構造

開発ガイド

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

• ハンドラーがスローし、フレームワークがキャッチする — ツールロジックにtry/catchは不要

• リクエストスコープのロギングにはctx.log、テナントスコープのストレージにはctx.stateを使用

• 新しいツールとリソースはsrc/mcp-server/*/definitions/index.tsのバレルを介して登録

• 上流データをそのまま表出させる: 存在しないフィールドはnullとして報告し、欠損値を決して捏造しない

帰属

空港、滑走路、navaid、周波数のデータはOurAirportsから提供されており、パブリックドメインに寄贈されています。帰属表示は任意であり、必須ではありません。ソースCSVはdavidmegginson.github.io/ourairports-dataで毎日公開されています。

コントリビューション

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

bun run devcheck
bun run test

ライセンス

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