@cyanheads/aviation-weather-mcp-server

Öffentlich gehosteter Server: https://aviation-weather.caseyjhand.com/mcp

Tools

Fünf Tools für die Luftfahrtwetterlage — Stationssuche, aktuelle Beobachtungen, Terminal-Forecasts, Pilot Reports und aktive Warnungen:

aviation_find_stations

Wetterstationen über mehrere Suchmodi auflösen und entdecken.

• Eine oder mehrere Stationen per 4-stelliger ICAO-ID nachschlagen (bis zu 20 IDs pro Aufruf) — die Suche erfolgt ausschließlich über ICAO, aber jeder zurückgegebene Datensatz enthält die IATA/FAA-Aliasse, sofern verfügbar

• Alle Stationen innerhalb eines geografischen Begrenzungsrahmens entdecken

• Stationen für einen der 50 US-Bundesstaaten oder DC über den zweistelligen USPS-Code auflisten (verwendet Bounding Box + clientseitigen Bundesstaaten-Filter)

• Liefert data_types (METAR, TAF, usw.), damit Agenten vor der Abfrage bestätigen können, was verfügbar ist

• Jedes Ergebnis gibt an, ob das vorgelagerte 400-Zeilen-Limit greift — so wird eine abgeschnittene Ausgabe nie mit allen Stationen in der Gegend verwechselt — eine abgeschnittene Bundesstaaten-Abfrage meldet außerdem die Zeilenanzahl vor dem Bundesstaaten-Filter, und eine kleinere bbox ist der genannte Hebel

aviation_get_metar

Aktuelle oder vergangene METAR-Beobachtungen abrufen (1–10 Stationen pro Aufruf).

• Der Parameter hours (1–12) liefert den Beobachtungsverlauf pro Station; Standardwert 1 liefert nur die aktuellste

• Die Flugwetterkategorie (VFR/MVFR/IFR/LIFR) wird direkt von der AWC-API zurückgegeben — keine clientseitige Berechnung erforderlich

• Dekodiert Wolkenschichten, Wind mit Böen, Sichtweite und aktuelles Wetter (die rohen Gruppen plus verständliches Englisch, eine Angabe pro Gruppe) zusätzlich zum rohen METAR-String

• Die Wolkendecke umfasst gebrochene, bedeckte und verdeckende Schichten und gibt an, ob die Höhe gemessen wurde oder eine unbestimmte Decke ist — vertikale Sicht in eine Verdecke

• Das METAR-Typfeld unterscheidet METAR (Routine) von SPECI (Sonderbeobachtung, ausgelöst durch signifikante Wetteränderung)

• Jeder Batch meldet, welche der angeforderten Stationen zurückkamen — so wird ein Teilergebnis nie mit vollständiger Abdeckung verwechselt — fehlende IDs werden mit Wiederherstellungshinweisen benannt

aviation_get_taf

Terminal Aerodrome Forecasts für 1–4 Flughäfen abrufen.

• Liefert strukturierte Vorhersagezeiträume mit Änderungstypen (FM, TEMPO, BECMG) und Wahrscheinlichkeiten

• Vorhergesagtes Wetter gruppenweise dekodiert neben den rohen Gruppen (-SHRA BR → leichter Regenschauer; Dunst), in derselben Form wie aviation_get_metar

• Vorhergesagte Verdeckungen behalten ihre Schicht und führen die vertikale Sicht in sie auf (VV002 → eine unbestimmte Decke von 200 ft), statt als klarer Himmel zu erscheinen

• Low-Level-Windscherung (WS020/20040KT) wird zur Obergrenze der Scherungsschicht und zum vorhergesagten Wind in dieser Höhe dekodiert

• valid_from / valid_to im ISO-8601-Format für unkomplizierte Zeitvergleiche

• Jeder Batch meldet, welche der angeforderten Stationen zurückkamen — so wird ein Teilergebnis nie mit vollständiger Abdeckung verwechselt — fehlende IDs werden mit Wiederherstellungshinweisen benannt

aviation_get_pireps

Nach aktuellen Pilot Reports per Station+Radius oder Begrenzungsrahmen suchen.

• station_id + distance_nm (10–500 nm, 100 wenn weggelassen) für die Radialsuche um einen Flughafen

• bbox für die Suche in einem geografischen Gebiet — nützlich für Streckenkorridor-Checks; distance_nm hat hier keine Bedeutung und wird zusammen mit bbox abgelehnt

• altitude_min_ft / altitude_max_ft-Filter, um Meldungen auf Reiseflughöhe zu isolieren, entweder einzeln oder beide (Minimum darf Maximum nicht überschreiten)

• Turbulenz- und Vereisungs-Arrays enthalten bis zu zwei Schichten pro Meldung (wie von der API gemeldet)

• Jedes Ergebnis gibt an, ob das vorgelagerte 400-Zeilen-Limit greift, und nennt bbox, distance_nm und hours als Hebel, um eine Abfrage vor dem Limit einzugrenzen — der Höhenfilter greift erst danach und kann eine verworfenen Meldung nicht wiederherstellen

• Hinweis: Das Fehlen von PIREPs bedeutet nicht automatisch ruhige Bedingungen — sie sind von Natur aus spärlich

aviation_get_advisories

Aktuell aktive nationale SIGMETs auflisten.

• advisory_type-Filter: sigmet oder all (Standard) — beide liefern den aktiven SIGMET-Satz

• hazard-Filter: CONVECTIVE, TURBULENCE, ICING, IFR

• bbox-Filter wird clientseitig angewendet (die AWC-API liefert alle aktiven Warnungen; das Tool filtert nach Polygon-Überlappung)

• AIRMETs werden nicht bedient. Der vorgelagerte Feed enthält nur nationale SIGMETs, daher werden advisory_type: airmet und die Gefahren MTN OBSCN, SURFACE WIND und LLWS mit Hinweisen abgelehnt, statt mit SIGMETs oder einem leeren Array beantwortet

• In Schönwetterperioden sind möglicherweise keine SIGMETs aktiv — ein leeres Ergebnis ist ein gültiger Zustand, kein Fehler

Related MCP server: mcp-metar

Prompts

Alle Ressourcendaten sind über Tools erreichbar. Dieser Server hat keine Ressourcen — alle Luftfahrtwetterdaten sind zeitkritisch (METARs ~1 Stunde gültig, Warnungen Minuten bis Stunden) und für stabile-URI-Ressourcen ungeeignet.

Funktionen

Basiert auf @cyanheads/mcp-ts-core:

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

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

• Plug-in-fähige Authentifizierung: none, jwt, oauth

• Strukturierte Protokollierung mit optionalem OpenTelemetry-Tracing

• STDIO- und Streamable-HTTP-Transports

Luftfahrtspezifisch:

• Schlüssellos — kein API-Schlüssel oder Authentifizierung erforderlich; alle Daten stammen aus der öffentlichen AWC-Data-API

• Einzelner Dienst (aviation-weather-service) mit Retry + exponentiellem Backoff für den schlüssellosen öffentlichen Endpunkt

• Rohe kodierte Strings (rawOb, rawTAF, rawAirSigmet) werden neben dekodierten Feldern ausgegeben, sodass Agenten beide Ebenen haben

• Die Bundesstaaten→Bounding-Box-Tabelle ermöglicht US-Bundesstaaten-Stationsabfragen, die die AWC-API nativ nicht unterstützt

• Das instructions-Feld auf Serverebene zeigt allen Clients bei initialize den Sicherheitshinweis „keine offizielle Besprechung" an

Agentenfreundliche Ausgabe:

• Flugwetterkategorie (VFR/MVFR/IFR/LIFR) als diskriminiertes String-Feld — Agenten können darauf verzweigen, ohne Wolkendecke + Sichtweite zu parsen

• Strukturierte Fehlerverträge mit typisierten reason-Feldern und recovery-Hinweisen (z. B. „ICAO-IDs mit aviation_find_stations überprüfen")

• Der Prompt aviation_preflight_brief kodiert die korrekte METAR → TAF → PIREPs → Warnungen-Besprechungsreihenfolge, die Agenten häufig falsch ausführen, indem sie Schritte auslassen

Erste Schritte

Öffentlich gehostete Instanz

Eine öffentlich gehostete Instanz ist unter https://aviation-weather.caseyjhand.com/mcp verfügbar. Fügen Sie sie Ihrer MCP-Client-Konfiguration hinzu:

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

Selbst gehostet / lokal

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

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

Oder mit npx (kein Bun erforderlich):

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

Oder mit Docker:

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

Für Streamable HTTP setzen Sie den Transport 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 erforderlich — die AWC-Data-API ist vollständig öffentlich und schlüssellos.

Installation

1. Repository klonen:

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

2. In das Verzeichnis wechseln:

cd aviation-weather-mcp-server

3. Abhängigkeiten installieren:

bun install

4. Umgebung konfigurieren:

cp .env.example .env
# edit .env if you need to override AWC_BASE_URL or AWC_TIMEOUT_MS

Konfiguration

Siehe .env.example für die vollständige Liste optionaler Überschreibungen.

Server ausführen

Lokale Entwicklung

• Erstellen und ausführen:

  bun run rebuild
  bun run start:stdio
  # or
  bun run start:http

• Prüfungen 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 aviation-weather-mcp-server .
docker run --rm -p 3010:3010 aviation-weather-mcp-server

Das Dockerfile ist standardmäßig auf HTTP-Transport, zustandslosen Sitzungsmodus und Protokollierung in /var/log/aviation-weather-mcp-server ausgelegt. OpenTelemetry-Peer-Abhängigkeiten werden standardmäßig installiert — erstellen Sie das Image mit --build-arg OTEL_ENABLED=false, um sie wegzulassen.

Projektstruktur

Entwicklungsleitfaden

Siehe CLAUDE.md für Entwicklungsrichtlinien und Architekturregeln. Die Kurzfassung:

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

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

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

• Kapseln Sie externe API-Aufrufe: validieren Sie Rohdaten → normalisieren Sie in den Domänentyp → geben Sie das Ausgabeschema zurück; erfinden Sie niemals fehlende Felder

Kein offizielles Preflight-Briefing. Daten der AWC sind rein informativ. Eine echte Flugplanung erfordert eine autorisierte Quelle (z. B. Leidos/1800wxbrief.com). Der Server zeigt diesen Haftungsausschluss über sein instructions-Feld an, das bei jedem initialize gesendet wird.

Mitwirken

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

bun run devcheck
bun run test

Lizenz

Apache-2.0 — siehe LICENSE für Details.