Tools

Five tools covering aviation weather — station lookup, current observations, terminal forecasts, pilot reports, and active advisories:

aviation_find_stations

Resolve and discover weather stations by multiple search modes.

• Look up one or more stations by 4-letter ICAO ID (up to 20 IDs per call) — lookup is ICAO-only, but each returned record includes its IATA/FAA aliases when available
• Discover all stations within a geographic bounding box
• List stations for one of the 50 US states or DC via two-letter USPS code (uses bbox + client-side state filter)
• Returns data_types (METAR, TAF, etc.) so agents can confirm what's available before querying
• Every result states whether the upstream 400-row cap cut it, so a truncated draw is never mistaken for every station in the area — a capped state query also reports the row count from before the state filter, and a smaller bbox is the named lever

aviation_get_metar

Fetch current or recent METAR observations (1–10 stations per call).

• hours parameter (1–12) returns observation history per station; default 1 returns only the most recent
• Flight category (VFR/MVFR/IFR/LIFR) is returned directly from the AWC API — no client-side computation needed
• Decodes cloud layers, wind with gusts, visibility, and present weather (the raw groups plus plain English, one reading per group) in addition to the raw METAR string
• Ceiling covers broken, overcast, and obscuration layers, and reports whether the height was measured or is an indefinite ceiling — vertical visibility into an obscuration
• METAR type field distinguishes METAR (routine) from SPECI (special observation triggered by significant weather change)
• Every batch reports which of the requested stations came back, so a partial result is never mistaken for full coverage — missing IDs are named with recovery guidance

aviation_get_taf

Fetch Terminal Aerodrome Forecasts for 1–4 airports.

• Returns structured forecast periods with change types (FM, TEMPO, BECMG) and probabilities
• Forecast weather decoded group by group beside the raw groups (-SHRA BR → light rain showers; mist), the same shape aviation_get_metar returns
• Forecast obscurations keep their layer and carry the vertical visibility into them (VV002 → a 200 ft indefinite ceiling), rather than reading as a clear sky
• Low-level wind shear (WS020/20040KT) is decoded to the shear-layer top and the forecast wind at that height
• valid_from / valid_to in ISO 8601 for straightforward time comparisons
• Every batch reports which of the requested stations came back, so a partial result is never mistaken for full coverage — missing IDs are named with recovery guidance

aviation_get_pireps

Search for recent Pilot Reports by station+radius or bounding box.

• station_id + distance_nm (10–500 nm, 100 when omitted) for radial search around an airport
• bbox for geographic area search — useful for en-route corridor checks; distance_nm has no meaning here and is rejected alongside it
• altitude_min_ft / altitude_max_ft filters to isolate reports at cruise altitude, either bound alone or both (min must not exceed max)
• Turbulence and icing arrays include up to two layers per report (as reported by the API)
• Every result states whether the upstream 400-row cap cut it, naming bbox, distance_nm, and hours as the levers that narrow a query before the cap applies — the altitude filter runs after it and cannot recover a dropped report
• Note: absence of PIREPs does not mean smooth conditions — they are sparse by nature

aviation_get_advisories

List currently active domestic SIGMETs.

• advisory_type filter: sigmet or all (default) — both return the active SIGMET set
• hazard filter: CONVECTIVE, TURBULENCE, ICING, IFR
• bbox filter applied client-side (AWC API returns all active advisories; the tool filters by polygon overlap)
• AIRMETs are not served. The upstream feed carries domestic SIGMETs only, so advisory_type: airmet and the MTN OBSCN, SURFACE WIND, and LLWS hazards are rejected with guidance rather than answered with SIGMETs or an empty array
• During fair-weather periods, no SIGMETs may be active — an empty result is a valid state, not an error

Prompts

All resource data is reachable via tools. This server has no resources — all aviation weather data is time-sensitive (METARs valid ~1 hour, advisories minutes to hours) and unsuitable for stable-URI resources.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool and prompt definitions — single file per primitive, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Pluggable auth: none, jwt, oauth
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

Aviation-weather-specific:

• Keyless — no API key or authentication required; all data is from the public AWC Data API
• Single service (aviation-weather-service) with retry + exponential backoff for the keyless public endpoint
• Raw coded strings (rawOb, rawTAF, rawAirSigmet) surfaced alongside decoded fields so agents have both layers
• State→bbox table enables US-state station queries that the AWC API doesn't natively support
• Server-level instructions field surfaces the "not an official briefing" safety disclaimer to all clients on initialize

Agent-friendly output:

• Flight category (VFR/MVFR/IFR/LIFR) as a discriminated string field — agents can branch on it without parsing ceiling + visibility
• Structured error contracts with typed reason fields and recovery hints (e.g., "Verify ICAO IDs with aviation_find_stations")
• aviation_preflight_brief prompt encodes the correct METAR → TAF → PIREPs → advisories briefing sequence that agents frequently get wrong by omitting steps