.codex-plugin— mcp server

<div align="center"> <h1>@cyanheads/faa-aircraft-registry-mcp-server</h1> <p><b>Decode N-numbers to aircraft, engine, status, and owner; search the US civil aircraft registry by owner, type, or state; resolve active/deregistered/reserved status — offline 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">

Public Hosted Server: https://faa-aircraft-registry.caseyjhand.com/mcp

</div>

Overview

The entire US civil aircraft registry as an offline lookup server. Resolve a tail number to its aircraft, make/model, engine, year, and registered owner; search by owner, type, or state; decode manufacturer and engine codes to specs; and resolve registration status across active, deregistered, and reserved records.

The data is the FAA's Releasable Aircraft Database — the full registry published by the FAA Civil Aviation Registry as a public-domain bulk download (a US Government work, no copyright). There is no keyless live FAA registry API, so the server builds a local index from that download instead: MASTER → ACFTREF → ENGINE are pre-joined into an embedded SQLite + FTS5 index, and every coded field is decoded at query time. Queries hit that local index — keyless, no runtime network, no per-request rate limit.

The index is not bundled with the package. On first use the operator runs mirror:init to download and build it (see First-run setup). Owner name and address are redacted by default (see Owner-PII redaction).

Composes with live flight-tracking data: the Mode S (hex) code this server returns is the ICAO 24-bit address that OpenSky and similar feeds key on, so a tail number or transponder code seen in the air decodes here to its aircraft and status.

Tools

Five tools covering the registry — two exact-key lookups, two full-text searches, and one cross-file status resolver. Searches return decoded summaries with N-numbers (or 7-char reference codes) to drill into via the matching lookup.

faa_lookup_registration

The primary tool. Decode one N-number to its full record in a single call.

• Accepts N12345 or 12345 — the leading N is optional, and the number is normalized before lookup
• Resolves the MASTER → ACFTREF → ENGINE join and decodes every coded field (aircraft type, engine type, status, airworthiness class, region) — each surfaced as both the raw FAA code and the decoded label
• Returns the Mode S code in both octal and hex; the hex form is the ICAO 24-bit address used by live flight-tracking feeds
• Owner name/address are included only when FAA_REDACT_OWNER_PII=false; otherwise ownerRedacted: true flags that they were withheld
• A known-but-inactive number (deregistered or reserved) is not found here — use faa_get_registration_status for the cross-file answer

faa_get_registration_status

Resolve where an N-number stands across the registry, even when it is no longer active.

• Checks the active (MASTER), deregistered (DEREG), and reserved (RESERVED) files in priority order, returning a discriminated recordType: active, deregistered, reserved, or unknown
• A number that was never issued resolves to recordType: "unknown" — a valid, informative answer rather than an error
• Each branch carries the fields relevant to that state (active: status + airworthiness + dates; deregistered: cancel date + serial; reserved: reservation type + reserve/purge dates)
• Owner-PII–free — returns status facts only

faa_search_registrations

Full-text search over active registrations, returning decoded summaries with N-numbers for follow-up.

• Filter by ownerName, makeModel, state, aircraftType, or modeSCode; at least one filter is required
• Owner-name search is disabled when `FAA_REDACT_OWNER_PII` is on — search by make/model, state, type, or Mode S code instead
• Each result carries an N-number to pass to faa_lookup_registration for full detail
• Discloses truncation when the result count hits limit (1–200, default 25), so a partial result set is never mistaken for complete

faa_search_aircraft_types

Discover the 7-char manufacturer/model/series codes by name before decoding them.

• Filter by query (manufacturer/model name, full-text), aircraftType code, or category code; at least one filter is required
• Returns reference summaries with the code to pass to faa_get_aircraft_type
• Discloses truncation at the limit (1–200, default 25)

Resources

All registry data is also reachable via tools — the resource is a convenience for clients that inject resources as context. Tool-only clients (the majority) reach the same record through faa_lookup_registration, so no data is locked behind the resource. Search collections are not exposed as resources; use the search tools instead.

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, with typed per-tool error contracts and recovery hints
• Pluggable auth: none, jwt, oauth
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

FAA-registry-specific:

• Offline and keyless at runtime — every query hits the local SQLite + FTS5 index; no API key, no runtime network, no rate limit
• Built on the framework MirrorService: mirror:init builds the index out-of-band, and the HTTP server schedules a daily refresh aligned to the FAA's nightly re-release
• Pre-joined MASTER → ACFTREF → ENGINE records, so one call returns "2008 Cessna 172S, Lycoming IO-360, valid registration" rather than raw join codes
• Fail-safe owner-PII redaction — redaction defaults on and drops owner name/address from output and disables owner-name search

Agent-friendly output:

• Coded fields surface both the raw FAA code and the decoded label — the label for reasoning, the code so nothing is lost
• Truncation disclosure — search tools flag truncated with shown/cap when the result set is capped, so a partial page is never read as the whole
• Permissible-field honesty — fields the FAA leaves blank (year, cruise speed, co-owner names) stay absent rather than fabricated
• ownerRedacted flag on every affected payload, so the agent knows owner data was withheld and why
• Discriminated status output (recordType) so callers branch on data, not string parsing

Getting started

Public Hosted Instance

A public instance is available at https://faa-aircraft-registry.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

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

Self-Hosted / Local

First run requires building the local index — see [First-run setup](#first-run-setup) below. The package does not ship the FAA data; until mirror:init has run once, queries fail with a clear "run mirror:init" error.

Add the following to your MCP client configuration file:

{
  "mcpServers": {
    "faa-aircraft-registry-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/faa-aircraft-registry-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FAA_MIRROR_PATH": "/path/to/faa-registry.db"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "faa-aircraft-registry-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/faa-aircraft-registry-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FAA_MIRROR_PATH": "/path/to/faa-registry.db"
      }
    }
  }
}

Or with Docker (mount a volume at /usr/src/app/.mirror so the built index persists across containers — build it once with docker exec … bun run mirror:init):

{
  "mcpServers": {
    "faa-aircraft-registry-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-v", "faa-registry:/usr/src/app/.mirror",
        "ghcr.io/cyanheads/faa-aircraft-registry-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

FAA_MIRROR_PATH points the server at the index that mirror:init builds — set it to a persistent path so the index survives across runs. Owner PII is redacted by default; set FAA_REDACT_OWNER_PII=false only on a trusted local install to expose owner detail.

First-run setup

The FAA Releasable Aircraft Database is not bundled with the package — it is a public dataset (~70 MB compressed, refreshed daily by the FAA) that the operator downloads and indexes once before first use. Building the index produces a local SQLite file of a few hundred MB.

After installing, build the index out-of-band (never on server startup — a full parse of ~1M rows must not block start):

# Build the local index from the live FAA download (idempotent, resumable)
FAA_MIRROR_PATH=/path/to/faa-registry.db bun run mirror:init

# Verify it built (readiness + integrity check)
FAA_MIRROR_PATH=/path/to/faa-registry.db bun run mirror:verify

# Rebuild from the latest FAA release (run on a schedule, or out-of-band for stdio)
FAA_MIRROR_PATH=/path/to/faa-registry.db bun run mirror:refresh

• Keep the path stable. Point FAA_MIRROR_PATH (and the same env var in your MCP client config) at a persistent location so the built index is reused across runs. Default: .mirror/faa-registry.db.
• Daily refresh. Under HTTP transport the server schedules a daily mirror:refresh aligned to the FAA's nightly re-release (~11:30 PM Central); the index stays queryable throughout. Under stdio, run mirror:refresh out-of-band (e.g. a cron job).
• Docker. The image ships the mirror CLI and a writable .mirror data directory owned by the runtime user. Mount a volume there and run mirror:init once (e.g. docker exec <container> bun run mirror:init, or a one-shot init job against the shared volume) so the index persists across container restarts.
• Until the index exists, every query fails with a ServiceUnavailable error whose recovery hint points to mirror:init — there is no live API to fall back to, so the cold state surfaces loudly rather than returning empty results.

The source URL is overridable via FAA_DATABASE_URL (for a private or cached mirror); it is read only at ingest time, never per request.

Prerequisites

• Bun v1.3 or higher (or Node.js v24+). bun:sqlite is built into Bun; a Node-only deployment adds better-sqlite3 (already declared as an optional peer dependency).
• Disk space for the built index (a few hundred MB) at FAA_MIRROR_PATH.
• Network access at mirror:init / mirror:refresh time to download the FAA ZIP. Not needed at query time.

Installation

For local development or self-hosting from source:

1. Clone the repository:

git clone https://github.com/cyanheads/faa-aircraft-registry-mcp-server.git

1. Navigate into the directory:

cd faa-aircraft-registry-mcp-server

1. Install dependencies:

bun install

1. Build the index (see First-run setup):

bun run mirror:init

Configuration

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

Owner-PII redaction

The FAA registry is releasable public record, but MASTER, DEREG, and RESERVED carry registrant names and physical addresses (deregistered records carry both mailing and physical address blocks plus co-owner names). This server ships a first-class redaction mode, redacted by default:

• FAA_REDACT_OWNER_PII defaults to true. Unset, empty, or malformed all resolve to redacted, so a deployment can never leak PII by omission or misconfiguration.
• When redacted: registrant name, street/physical address, and co-owner names are dropped from every output, and owner-name search is disabled (faa_search_registrations rejects ownerName). Disabling search matters — output-hiding alone would let an agent confirm a person↔aircraft link by probing the search input.
• Aircraft facts (make/model/engine/year/specs) and registration status still flow, with ownerRedacted: true on every affected payload.
• Full owner detail requires explicitly setting FAA_REDACT_OWNER_PII=false — appropriate for a trusted local or self-hosted install, not a shared endpoint.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild

  # Build the local index (see First-run setup)
  bun run mirror:init

  # 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 faa-aircraft-registry-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 \
  -v faa-registry:/usr/src/app/.mirror faa-aircraft-registry-mcp-server
# Build the index once against the mounted volume:
docker run --rm -v faa-registry:/usr/src/app/.mirror faa-aircraft-registry-mcp-server bun run mirror:init

The Dockerfile defaults to HTTP transport with stateless sessions, ships the mirror:init/mirror:refresh/mirror:verify CLI, pre-creates a writable .mirror data directory owned by the runtime user (mount a volume there and run mirror:init once to build and persist the index), and logs to /var/log/faa-aircraft-registry-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
• The registry index is the source of truth at runtime — there is no upstream API to retry; build and refresh it out-of-band, and never fabricate a value from a blank upstream field

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.

The FAA Releasable Aircraft Database is a public-domain US Government work, published by the FAA Civil Aviation Registry. This project redistributes none of that data; operators download it directly from the FAA at install time.