ourairports-mcp-server

Öffentlich gehosteter Server: https://ourairports.caseyjhand.com/mcp

Übersicht

ourairports-mcp-server ist die statische Luftfahrt-Referenzschicht zum Auflösen von Flughafenkennungen und zur Verortung von Koordinaten. Es beantwortet, was existiert — den Katalog der Flughäfen, ihrer Codes, Start- und Landebahnen, Navigationsfunkfeuer und Funkfrequenzen — und ergänzt damit Live-Luftfahrtdienste, die beantworten, was gerade passiert (Wetter, Positionen).

Der gesamte OurAirports-Datensatz ist der Public Domain gewidmet und wird als flache CSVs veröffentlicht. Diese sechs CSV-Dateien — airports, runways, navaids, airport frequencies, countries und regions (~178k Zeilen, ~20 MB) — sind in das Paket gebündelt und werden zur Build-Zeit in das Docker-Image eingebacken. Beim Start parst der Server sie in In-Memory-Indizes; jedes Tool ist dann eine lokale Abfrage. Das Ergebnis hat keinen API-Schlüssel, kein Rate-Limit und keine Upstream-Abhängigkeit, von der man einen Ausfall erben könnte.

Wie das Arbeitsmodell zusammenhängt:

• Codeauflösung über fünf Kennungsräume. Flughäfen tragen IATA, ICAO, GPS, lokal und die OurAirports-ident. Ein einzelner code-Parameter wird gegen einen einheitlichen Index aufgelöst (Priorität: ident → ICAO → IATA → GPS → lokal), und die Antwort spiegelt den vollständigen Codesatz wider, sodass sich ein mehrdeutiger nationaler Code selbst korrigiert. Ein fehlender Code (keine IATA für einen kleinen Platz) wird als null gemeldet, niemals als 404.

• Nächster Nachbar über Großkreis-Entfernung. Koordinatenabfragen führen einen Haversine-Scan über ein flaches Float64Array mit den Positionen aller Flughäfen (oder Navigationsfunkfeuer) aus und liefern die nächsten Treffer nach Entfernung sortiert, jeweils mit Peilung — bei dieser Größenordnung unter einer Millisekunde, kein räumlicher Index nötig.

• Ehrliche Datenlücken. Fehlende Upstream-Felder (keine Höhe, null Startbahnmaße) erscheinen als unbekannt. Gedeckelte Ergebnislisten weisen auf Kürzung hin.

OurAirports wird von der Community gepflegt. Die Daten werden unverändert bereitgestellt und sind nicht maßgeblich für den realen Flugbetrieb — behandeln Sie sie wie jede Crowd-sourced-Referenz.

Related MCP server: mcp-metar

Tools

Sechs schreibgeschützte Tools, alle lokale Abfragen gegen den gebündelten Index — Codeauflösung und -details, Flughafen- und Startbahn-Suche, Koordinatenverortung, Navigationsfunkfeuer und die Länder-/Regionen-Nachschlagetabelle:

ourairports_search_airports

Der gängige Einstiegspunkt — Suche nach Freitext, Facetten oder beidem.

• Freitextsuche über Name, Gemeinde und Schlüsselwörter; Token werden UND-verknüpft (Wortreihenfolge und Teilwörter werden berücksichtigt)

• Facettenfilter: country (ISO 3166-1 alpha-2), region (ISO 3166-2) und type — country/region sind exakte Übereinstimmungen, ohne Beachtung der Groß-/Kleinschreibung, umgebende Leerzeichen werden ignoriert

• Geschlossene Flughäfen standardmäßig ausgeschlossen; Opt-in über include_closed

• Ergebnisse sortiert nach betriebenen/größeren Flughäfen zuerst, jeweils mit vollständigem Codesatz und Koordinaten zur Weiterverwendung in ourairports_get_airport

• Offenlegung von Kürzungen — Gesamtzahl der Treffer, angewandtes Limit und Hinweise zum Erweitern oder Eingrenzen

ourairports_search_runways

Flughafenübergreifende Startbahn-Suche — das Gegenstück zu ourairports_get_airport, das die Start- und Landebahnen für einen bereits bekannten Flughafen auflistet.

• Flughafen-Facetten (country, region, type) grenzen zuerst die Flughäfen ein; Startbahn-Facetten (surface, min_length_ft, min_width_ft, lighted) filtern dann deren Start- und Landebahnen

• surface ist eine case-insensitive Teilstring-Übereinstimmung gegen den rohen Upstream-Oberflächenstring (kein kontrolliertes Vokabular — ein kürzeres Fragment wie asp matcht ASP, ASPH und Asphalt), kein exakter Code

• Liefert eine flache Zeile { airport, runway } pro passender Startbahn — ein Flughafen mit drei passenden Start- und Landebahnen trägt drei Zeilen bei

• Eine Startbahn, deren Länge oder Breite unbekannt ist, wird ausgeschlossen, wenn der entsprechende min_*_ft-Filter gesetzt ist — sie wird niemals als ein Limit erfüllend angenommen, das die Daten nicht bestätigen können

• Geschlossene Flughäfen und geschlossene Start- und Landebahnen sind beide ausgeschlossen, sofern nicht include_closed_airports / include_closed_runways gesetzt ist

• Offenlegung von Kürzungen — Gesamtzahl der Treffer, angewandtes Limit und Hinweise zum Erweitern oder Eingrenzen

ourairports_get_airport

Das Detail-Tool — ein Aufruf liefert alles, was der Normalfall benötigt.

• Löst einen einzelnen code ohne Beachtung der Groß-/Kleinschreibung über alle fünf Kennungsräume auf (Priorität: ident → ICAO → IATA → GPS → lokal); umgebende Leerzeichen werden ignoriert

• Start- und Landebahnen und Funkfrequenzen inline; include reduziert die Antwort auf eine Teilmenge, und das Feld included in der Ausgabe unterscheidet eine durch include weggelassene Beziehung von einer, die tatsächlich keine Datensätze hat

• Gibt den vollständigen Codesatz des Flughafens plus resolvedVia / resolutionNote wider, mit einer Mehrdeutigkeitswarnung für gemeinsam genutzte nationale Codes, sodass sich eine falsche Auflösung selbst korrigiert

• Fehlende Codes werden als null gemeldet; geschlossene Flughäfen werden immer aufgelöst

• unknown_code-Fehler mit einem Hinweis zur Behebung, wenn kein Kennungsraum übereinstimmt

ourairports_find_airports

Das Verortungs-Tool — verwandelt eine Breite/Länge in den nächstgelegenen Flughafen bzw. die nächstgelegenen Flughäfen.

• Großkreis-Rangfolge (Haversine), nächste zuerst, jedes Ergebnis mit distanceKm und bearingDeg (rechtweisende Grad) vom Abfragepunkt

• radius_km (1–500, Standard 100), optionaler type-Filter, include_closed-Opt-in

• Koordinate hinein, rangierte Flughäfen heraus — keine Geokodierung; Ortsnamen zuerst vorgelagert in Breite/Länge auflösen

• Hinweis bei leerem Radius, der ein größeres radius_km vorschlägt

ourairports_find_navaids

Navigationsfunkfeuer auf zwei Arten — räumlich oder nach Flughafen.

• Koordinatenmodus: latitude + longitude (+ optional radius_km) sortiert Navigationsfunkfeuer nach Entfernung (nächste zuerst) mit Entfernung und Peilung

• Flughafenmodus: airport_code liefert die Navigationsfunkfeuer, die diesen Flughafen versorgen

• Genau ein Modus ist erforderlich — beide oder keiner anzugeben ist ein Validierungsfehler

• Frequenzen werden sowohl in kHz (der gespeicherte Wert — ein VOR auf 114,5 MHz zeigt frequencyKhz 114500) als auch in MHz angegeben

• Der Flughafenmodus unterscheidet „Flughafen nicht gefunden" (unknown_code-Fehler) von „Flughafen gefunden, aber keine zugehörigen Navigationsfunkfeuer" (leere Liste mit einem Hinweis)

Resource und Prompt

Die airport://{code}-Resource ist ein stabiles URI-Pendant zu ourairports_get_airport für Clients, die Resource-Kontext einbetten. Alle Daten sind allein über die Tools erreichbar — reine Tool-Clients verlieren nichts. Der Bestand wird nicht als Resource-Liste exponiert (85.000 Flughäfen aufzuzählen ist ein Dump, keine Entdeckungshilfe); die Entdeckung erfolgt über ourairports_search_airports.

Features

Basiert auf @cyanheads/mcp-ts-core:

• Deklarative Tool- und Resource-Definitionen — eine Datei pro Primitive, das Framework übernimmt Registrierung und Validierung

• Einheitliche Fehlerbehandlung — Handler werfen, das Framework fängt, klassifiziert und formatiert

• Austauschbare Authentifizierung: none, jwt, oauth

• Austauschbare Speicher-Backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1

• Strukturierte Protokollierung mit optionalem OpenTelemetry-Tracing

• Läuft lokal (stdio/HTTP) oder auf Cloudflare Workers aus derselben Codebasis

OurAirports-spezifisch:

• Gebündelter Public-Domain-Datensatz, eingebettet in das Paket und das Docker-Image — keine Runtime-API, kein API-Key, kein Rate-Limit, kein Upstream-Ausfall

• In-Memory-Indizes, die einmal beim Start aufgebaut werden: ID-Maps, ein nach Priorität geordneter einheitlicher Code-Index, Airport-Ref-Joins für Start- und Landebahnen und Frequenzen, ein nach Ident-Schlüssel verknüpfter Navaid-Join, ein flaches Float64Array der Koordinaten, Länder-/Regionen-Zuordnungen und ein tokenisierter Textsuch-Index

• Brute-Force-Haversine-Nearest-Neighbour über das Koordinaten-Array — unter einer Millisekunde über 85.000 Flughäfen, keine Abhängigkeit von einem räumlichen Index

• CSVs werden nach Kopfzeilennamen geparst, nicht nach Spaltenposition, sodass eine Neuanordnung von Spalten upstream Felder nicht stillschweigend falsch ausrichten kann

Agentenfreundliche Ausgabe:

• Ehrliche Sparsity — fehlende Upstream-Felder (keine IATA, keine Höhe, null Startbahnmaße) erscheinen als null, niemals erfunden

• Selbstkorrigierende Auflösung — jeder Flughafendatensatz gibt seinen vollständigen Codesatz sowie ein resolvedVia / resolutionNote zurück, mit einer Mehrdeutigkeitswarnung für gemeinsam genutzte nationale Codes

• Offenlegung von Kürzungen und leeren Ergebnissen — Gesamtzahlen, angewandte Obergrenzen und Hinweise zur Behebung, damit Aufrufer erweitern, eingrenzen oder erneut abfragen können, ohne Prosa zu parsen

Erste Schritte

Öffentlich gehostete Instanz

Eine öffentliche Instanz ist unter https://ourairports.caseyjhand.com/mcp verfügbar — keine Installation erforderlich. Richten Sie einen beliebigen MCP-Client über Streamable HTTP darauf aus, mit dieser Client-Konfiguration:

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

Lokal / selbst gehostet

Fügen Sie Ihrer MCP-Client-Konfigurationsdatei Folgendes hinzu.

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

Oder mit npx (kein Bun erforderlich):

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

Oder mit 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"
      ]
    }
  }
}

Es ist kein API-Schlüssel erforderlich — der Datensatz ist im Paket und im Image enthalten.

Für Streamable HTTP legen Sie den Transport fest und starten Sie den Server:

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

Voraussetzungen

• Bun v1.3.0 oder höher (oder Node.js v24+).

• Kein API-Schlüssel, kein Konto und kein externer Dienst erforderlich — alle Daten sind gebündelt enthalten.

Installation

1. Repository klonen:

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

2. In das Verzeichnis wechseln:

cd ourairports-mcp-server

3. Abhängigkeiten installieren:

bun install

4. Datensatz abrufen und bündeln (schreibt die sechs CSVs in data/):

bun run build:data

Aktualisieren der Daten

Der gebündelte Snapshot ist so aktuell wie der letzte build:data-Lauf (bzw. beim Docker-Image der letzte Build). Um den neuesten täglichen Datenabwurf vom OurAirports-Mirror zu laden, führen Sie bun run build:data erneut aus und bauen Sie neu. Um auf einen vorhandenen lokalen Datenabwurf zu verweisen, ohne neu zu bauen, setzen Sie OURAIRPORTS_DATA_DIR.

Konfiguration

Die vollständige Liste der optionalen Überschreibungen finden Sie in .env.example.

Ausführen des Servers

Lokale Entwicklung

• Bauen und ausführen:

  # 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

• Checks und Tests ausführen:

  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

Die Build-Stufe führt bun run build:data aus, sodass der Datensatz abgerufen und in das Image eingebettet wird — der resultierende Container ist vollständig in sich geschlossen und tätigt zur Laufzeit keine Netzwerkaufrufe. Das Dockerfile verwendet standardmäßig HTTP-Transport, den stateless-Sitzungsmodus und protokolliert nach /var/log/ourairports-mcp-server. OpenTelemetry-Peer-Abhängigkeiten werden standardmäßig installiert — bauen Sie mit --build-arg OTEL_ENABLED=false, um sie wegzulassen.

Projektstruktur

Entwicklungsleitfaden

Entwicklungsrichtlinien und Architekturregeln finden Sie in CLAUDE.md/AGENTS.md. Die Kurzfassung:

• Handler werfen, Framework fängt — kein try/catch in der Tool-Logik

• Verwenden Sie ctx.log für anfragenbezogenes Logging und ctx.state für mandantenbezogenen Speicher

• Registrieren Sie neue Tools und Ressourcen über die Barrels in src/mcp-server/*/definitions/index.ts

• Geben Sie Upstream-Daten unverändert aus: Melden Sie fehlende Felder als null, erfinden Sie niemals fehlende Werte

Namensnennung

Flughafen-, Startbahn-, Navaid- und Frequenzdaten von OurAirports, der Public Domain gewidmet. Die Namensnennung ist eine Höflichkeit, keine Pflicht. Die Quell-CSVs werden täglich unter davidmegginson.github.io/ourairports-data veröffentlicht.

Mitwirken

Issues und Pull-Requests sind willkommen. Führen Sie vor dem Einreichen Checks und Tests aus:

bun run devcheck
bun run test

Lizenz

Apache-2.0 — siehe LICENSE für Details.