flightaware-mcp CLAUDE.md

CLAUDE.md — flightaware-mcp

Guidance for Claude working in this repo.

TL;DR

FlightAware AeroAPI (v4) MCP server. Wraps the AeroAPI REST API (https://aeroapi.flightaware.com/aeroapi) and exposes 33 tools to Claude over stdio: flight lookup/search/positions/count/track/position/route/map/history/ canonical, airport boards + counts + routes + delays + weather + nearby + canonical, operators, aircraft owner, scheduled flights, Foresight predictive search, and flight-alert management.

Auth is an AeroAPI key (AEROAPI_API_KEY) sent in the x-apikey header — AeroAPI does not use Authorization: Bearer. This is the bearer/direct-API archetype: reads go through the fleet-shared createApiClient (configured with a non-Bearer tokenHeader); mutations go through a small raw-fetch write() because AeroAPI returns the new-resource id in the Location header on create and an empty body on delete (neither fits a JSON-only client). No fetchproxy.

Environment

AEROAPI_API_KEY=<key>            # Required. Create at https://www.flightaware.com/aeroapi/portal/
AEROAPI_OUTPUT_DIR=<dir>         # Optional. Where flight-map PNGs are written (default: cwd)
AEROAPI_CACHE_TTL=<secs>        # Optional. Live-data read-cache TTL (default 15; 0 disables)
AEROAPI_STATIC_CACHE_TTL=<secs> # Optional. Reference-data read-cache TTL (default 3600; 0 disables)

client.get(path, { cache }) is backed by an in-memory cache keyed by full path, with two TTL tiers to cut AeroAPI's per-query billing: dynamic (AEROAPI_CACHE_TTL, default 15s) for live data, and static (AEROAPI_STATIC_CACHE_TTL, default 3600s) for reference data that barely changes — opted in per tool via get(path, { cache: 'static' }) (airport/ operator info, fa_list_*, routes, aircraft owner, fa_resolve_*). Writes are never cached. Tier note: alerts, fa_get_flight_history, and the fa_resolve_* canonical tools require a Standard/Premium tier (Personal 401s).

Loaded via loadDotenvSafely from .env next to dist/ (failure swallowed — the .mcpb bundle has no dotenv). The config error is deferred: the server boots without a key and the actionable error surfaces on the first tool call, so the host's install-time tools/list probe still succeeds.