.codex-plugin— mcp server

<div align="center"> <h1>@cyanheads/ourairports-mcp-server</h1> <p><b>Resolve airport codes (IATA/ICAO/GPS/local), search airports, find the nearest by coordinate, and look up runways, navaids, and radio frequencies from the bundled public-domain OurAirports dataset via MCP. STDIO or Streamable HTTP.</b> <div>5 Tools • 1 Resource</div> </p> </div>

<div align="center">

</div>

<div align="center">

</div>

<div align="center">

</div>

<div align="center">

Public Hosted Server: https://ourairports.caseyjhand.com/mcp

</div>

Overview

ourairports-mcp-server is the static aviation reference layer for resolving airport identifiers and grounding coordinates. It answers what exists — the catalog of airports, their codes, runways, navaids, and radio frequencies — to complement live aviation services that answer what is happening (weather, positions).

The entire OurAirports dataset is dedicated to the public domain and published as flat CSVs. Those six CSV files — airports, runways, navaids, airport frequencies, countries, and regions (~178k rows, ~20 MB) — are bundled into the package and baked into the Docker image at build time. At startup the server parses them into in-memory indices; every tool is then a local query. The result has no API key, no rate limit, and no upstream dependency to inherit an outage from.

How the working model fits together:

• Code resolution across five identifier spaces. Airports carry IATA, ICAO, GPS, local, and the OurAirports ident. A single code parameter resolves against a unified index (priority: ident → ICAO → IATA → GPS → local), and the response echoes the full code set so an ambiguous national code is self-correcting. A missing code (no IATA for a small field) is reported as null, never a 404.
• Nearest-neighbour by great-circle distance. Coordinate lookups run a haversine scan over a flat Float64Array of every airport (or navaid) position and return the nearest results ranked by distance, each with its bearing — sub-millisecond at this scale, no spatial index needed.
• Honest sparsity. Absent upstream fields (no elevation, null runway dimensions) surface as unknown. Capped result lists disclose truncation.

OurAirports is community-edited. The data is surfaced as-is and is not authoritative for real flight operations — treat it the way you would any crowd-sourced reference.

Tools

Five read-only tools, all local queries against the bundled index — code resolution and detail, search, coordinate grounding, navaids, and the country/region lookup table:

ourairports_search_airports

The common entry point — search by free text, facets, or both.

• Free-text search over name, municipality, and keywords; tokens are AND-matched (word order and partial words handled)
• Faceted filters: country (ISO 3166-1 alpha-2), region (ISO 3166-2), and type
• Closed airports excluded by default; opt in with include_closed
• Results ranked operational/larger-airports-first, each with its full code set and coordinates for chaining into ourairports_get_airport
• Truncation disclosure — total matched count, applied cap, and guidance to broaden or narrow

ourairports_get_airport

The detail tool — one call returns everything the common case needs.

• Resolves a single code case-insensitively across all five identifier spaces (priority: ident → ICAO → IATA → GPS → local)
• Runways and radio frequencies inline; include trims the response to a subset
• Echoes the airport's complete code set plus a resolvedVia / resolutionNote, with an ambiguity warning for shared national codes so a wrong resolution is self-correcting
• Absent codes reported as null; closed airports always resolve
• unknown_code error with a recovery hint when no identifier space matches

ourairports_find_airports

The grounding tool — turn a latitude/longitude into the nearest airport(s).

• Great-circle (haversine) ranking, nearest-first, each result with distanceKm and bearingDeg (degrees true) from the query point
• radius_km (1–500, default 100), optional type filter, include_closed opt-in
• Coordinate in, ranked airports out — no geocoding; resolve place names to lat/lon upstream first
• Empty-radius guidance suggesting a wider radius_km

ourairports_find_navaids

Navigation aids two ways — spatially or by airport.

• Coordinate mode: latitude + longitude (+ optional radius_km) ranks navaids nearest-first with distance and bearing
• Airport mode: airport_code returns the navaids serving that airport
• Exactly one mode required — supplying both or neither is a validation error
• Frequencies surfaced in both kHz (the stored value — a VOR on 114.5 MHz reads frequencyKhz 114500) and MHz
• Airport mode distinguishes "airport not found" (unknown_code error) from "airport found but has no associated navaids" (empty list with a note)

Resource and prompt

The airport://{code} resource is a stable-URI twin of ourairports_get_airport for clients that inject resource context. All data is reachable from the tools alone — tool-only clients lose nothing. The corpus is not exposed as a resource list (enumerating 85k airports is a dump, not a discovery aid); discovery is ourairports_search_airports.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool and resource 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
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase

OurAirports-specific:

• Bundled, public-domain dataset baked into the package and Docker image — zero runtime API, no key, no rate limit, no upstream outage
• In-memory indices built once at startup: id maps, a priority-ordered unified code index, airport-ref joins for runways and frequencies, an ident-keyed navaid join, a flat Float64Array of coordinates, country/region maps, and a tokenized text-search index
• Brute-force haversine nearest-neighbour over the coordinate array — sub-millisecond across 85k airports, no spatial-index dependency
• CSVs parsed by header name, not column position, so an upstream column reorder can't silently misalign fields

Agent-friendly output:

• Honest sparsity — absent upstream fields (no IATA, no elevation, null runway dimensions) surface as null, never fabricated
• Self-correcting resolution — every airport record echoes its full code set and a resolvedVia / resolutionNote, with an ambiguity warning for shared national codes
• Truncation and empty-result disclosure — total counts, applied caps, and recovery guidance so callers can broaden, narrow, or re-query without parsing prose

Getting started

Public Hosted Instance

A public instance is available at https://ourairports.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP, with this client config:

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

Local / self-hosted

Add the following to your MCP client configuration file.

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

Or with npx (no Bun required):

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

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

No API key is required — the dataset ships with the package and the image.

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.2 or higher (or Node.js v24+).
• No API key, account, or external service — all data is bundled.

Installation

1. Clone the repository:

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

1. Navigate into the directory:

cd ourairports-mcp-server

1. Install dependencies:

bun install

1. Fetch and bundle the dataset (writes the six CSVs into data/):

bun run build:data

Refreshing the data

The bundled snapshot is as fresh as the last build:data run (or, for the Docker image, the last build). To pull the latest daily drop from the OurAirports mirror, re-run bun run build:data and rebuild. To point at an existing local data drop without rebuilding, set OURAIRPORTS_DATA_DIR.

Configuration

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

Running the server

Local development

• Build and run:

  # 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

• 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 ourairports-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=stdio ourairports-mcp-server

The build stage runs bun run build:data so the dataset is fetched and baked into the image — the resulting container is fully self-contained and makes no network calls at runtime. The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/ourairports-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/AGENTS.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 resources via the barrels in src/mcp-server/*/definitions/index.ts
• Surface upstream data as-is: report absent fields as null, never fabricate missing values

Attribution

Airport, runway, navaid, and frequency data from OurAirports, dedicated to the public domain. Attribution is a courtesy, not a requirement. Source CSVs are published daily at davidmegginson.github.io/ourairports-data.

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.