.codex-plugin— mcp server

<div align="center"> <h1>@cyanheads/aviation-weather-mcp-server</h1> <p><b>Fetch METARs, TAFs, PIREPs, and SIGMETs/AIRMETs from the NWS Aviation Weather Center via MCP. STDIO or Streamable HTTP.</b> <div>5 Tools • 1 Prompt</div> </p> </div>

<div align="center">

</div>

<div align="center">

</div>

<div align="center">

Public Hosted Server: https://aviation-weather.caseyjhand.com/mcp

</div>

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 ICAO, IATA, or FAA ID (up to 20 IDs per call)
• Discover all stations within a geographic bounding box
• List stations for a US state via two-letter abbreviation (uses bbox + client-side state filter)
• Returns data_types (METAR, TAF, etc.) so agents can confirm what's available before querying

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, and visibility in addition to the raw METAR string
• METAR type field distinguishes METAR (routine) from SPECI (special observation triggered by significant weather change)

aviation_get_taf

Fetch Terminal Aerodrome Forecasts for 1–4 airports.

• Returns structured forecast periods with change types (FM, TEMPO, BECMG) and probabilities
• Common weather codes (e.g., -SHRA, TSRA) decoded to plain English alongside the raw string
• valid_from / valid_to in ISO 8601 for straightforward time comparisons

aviation_get_pireps

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

• station_id + distance_nm (10–500 nm, default 100) for radial search around an airport
• bbox for geographic area search — useful for en-route corridor checks
• altitude_min_ft / altitude_max_ft filters to isolate reports at cruise altitude
• Turbulence and icing arrays include up to two layers per report (as reported by the API)
• Note: absence of PIREPs does not mean smooth conditions — they are sparse by nature

aviation_get_advisories

List currently active SIGMETs and AIRMETs.

• advisory_type filter: sigmet, airmet, or all (default)
• hazard filter: CONVECTIVE, TURBULENCE, ICING, IFR, MTN OBSCN, SURFACE WIND, LLWS
• bbox filter applied client-side (AWC API returns all active advisories; the tool filters by polygon overlap)
• During fair-weather periods, no AIRMETs 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

Getting started

Public Hosted Instance

A public hosted instance is available at https://aviation-weather.caseyjhand.com/mcp. Add it to your MCP client configuration:

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

Self-hosted / local

Add the following to your MCP client configuration file.

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

Or with npx (no Bun required):

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

Or with 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"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

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

Prerequisites

• Bun v1.3.0 or higher (or Node.js v24+).
• No API key required — the AWC Data API is fully public and keyless.

Installation

1. Clone the repository:

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

1. Navigate into the directory:

cd aviation-weather-mcp-server

1. Install dependencies:

bun install

1. Configure environment:

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

Configuration

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

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

• Run checks and tests:

  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

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/aviation-weather-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools and prompts via the barrels in src/mcp-server/*/definitions/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Not an official preflight briefing. Data from the AWC is informational only. Real flight planning requires an authorized source (e.g., Leidos/1800wxbrief.com). The server surfaces this disclaimer via its instructions field sent on every initialize.

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.