faa-aircraft-registry-mcp-server

---

概述

美国民用航空器登记信息，可通过 FAA 可公开获取的航空器数据库离线搜索。将 N 编号解码为对应航空器、发动机和登记所有者；查询其是否有效、已注销或预留；还可按所有者、制造商和型号、州或 Mode S 代码搜索。

工具

工具	描述
faa_lookup_registration	将单个 N 编号解码为完整的预连接有效记录——包括航空器制造商/型号、发动机、年份、适航性、登记状态、Mode S 代码和登记所有者（未启用信息隐藏时）。
faa_get_registration_status	按优先顺序在三个状态文件（有效、已注销、预留）中查询 N 编号，并返回明确的 recordType。
faa_search_registrations	按所有者名称、制造商/型号、精确的制造商/型号代码、州、航空器类型或 Mode S 代码搜索有效登记信息。
faa_search_aircraft_types	按制造商/型号名称、类型或类别搜索航空器参考表，以查找制造商-型号代码。
faa_get_aircraft_type	将 6–7 个字符的制造商/型号/系列代码解码为航空器规格——包括类别、类型、发动机、座位数、重量等级、巡航速度和型号合格证数据。

资源

资源	描述
faa://registration/{nNumber}	单个 N 编号的完整注册记录——与 faa_lookup_registration 返回的已解码、预联接数据相同。

也可通过 faa_lookup_registration 访问；搜索集合不会作为资源公开。

功能参考

faa_lookup_registration _工具

• 接受 N12345 或 12345；开头的 N 可省略
• 将飞机、发动机和状态字段作为原始代码及标签返回，并以八进制和十六进制形式返回 Mode S 代码（十六进制值是 ICAO 24 位地址）
• 仅当 FAA_REDACT_OWNER_PII=false 时才显示所有者姓名和地址；否则返回 ownerRedacted: true
• 错误：not_found（无有效注册记录；请尝试 faa_get_registration_status）、invalid_n_number

---

faa_get_registration_status _工具

• 按有效、注销和预留文件的顺序检查
• recordType 为 active、deregistered、reserved 或 unknown；从未签发过的编号会返回 unknown，而非错误
• 仅包含状态信息，不含所有者数据
• 错误：invalid_n_number

---

faa_search_registrations _工具

• 筛选条件：ownerName、makeModel、manufacturerModelCode、state、aircraftType、modeSCode；至少需要一个条件，多个条件按 AND 组合
• limit 为 1–200（默认值为 25），使用 offset 分页；响应在结果被截断时会报告 totalCount 和 nextOffset
• 每条结果都包含一个 N 编号，可传递给 faa_lookup_registration
• 错误：no_filters、invalid_code、invalid_state、invalid_mode_s_code、invalid_aircraft_type 和 owner_search_disabled（启用 FAA_REDACT_OWNER_PII 时会关闭所有者姓名搜索）

---

faa_search_aircraft_types _工具

• 筛选条件：query（制造商／型号名称）、aircraftType（1–9/H/O）、category（1–3）；至少需要一个条件
• 返回摘要及代码，可传递给 faa_get_aircraft_type 或 faa_search_registrations.manufacturerModelCode
• limit 为 1–200（默认值为 25），使用 offset 分页；响应在结果被截断时会报告 totalCount 和 nextOffset
• 错误：no_filters、invalid_aircraft_type、invalid_category

---

faa_get_aircraft_type _工具

• 接受 6–7 个字符的大写字母数字制造商／型号／系列代码；使用 faa_search_aircraft_types 查找代码
• 返回制造商、型号、类型、发动机、类别、座位数、发动机数量、重量等级、巡航速度和型号合格证数据
• weightClass 保留 FAA 原始字符串；已知时会解码 weightClassLabel
• 错误：not_found、invalid_code

---

faa://registration/{nNumber} _资源

• 数据与 faa_lookup_registration 相同；类型为 application/json，缓存 1 小时
• nNumber 接受 N12345 或 12345
• 错误：not_found、invalid_n_number

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔认证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及带可选 OpenTelemetry 跟踪的结构化日志。

FAA 注册信息专属功能：

• 运行时离线且无需密钥：查询使用本地 SQLite + FTS5 索引，无需 API 密钥或受速率限制
• 在 HTTP 传输下每日刷新索引，与 FAA 每晚重新发布数据的时间安排一致
• 预联接记录：一次调用即可返回已解码的飞机、发动机和状态信息
• 默认对所有者姓名和地址进行脱敏；只有设置 FAA_REDACT_OWNER_PII=false 后，才会启用所有者姓名搜索
• Mode S 十六进制代码与航班跟踪数据源使用的 ICAO 24 位地址一致

适合 Agent 使用的输出：

• 编码字段同时包含 FAA 原始代码和解码后的标签
• 达到上限的搜索结果会通过 truncated、shown 和 cap 标记
• FAA 留空的字段会保持缺省，不会填入内容
• recordType 和 ownerRedacted 便于调用方根据数据分支处理

开始使用

公共托管实例

可通过 https://faa-aircraft-registry.caseyjhand.com/mcp 使用公共实例——无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

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

自托管 / 本地部署

首次运行需要构建本地索引——请参阅下文的首次运行设置。 软件包不包含 FAA 数据；在首次运行 mirror:init 之前，查询会失败，并明确提示“运行 mirror:init”。

桌面端 MCPB 包含 Node 的 SQLite 驱动及其跨平台预编译版本。查询之前，请先使用软件包附带的 mirror CLI 构建本地索引。

将以下内容添加到 MCP 客户端配置文件中：

{
  "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"
      }
    }
  }
}

或者使用 npx（无需 Bun）：

{
  "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"
      }
    }
  }
}

或者使用 Docker（在 /usr/src/app/.mirror 挂载卷，以便在容器间保留已构建的索引——使用 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"
      ]
    }
  }
}

对于 Streamable HTTP，请设置传输方式并启动服务：

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

FAA_MIRROR_PATH 用于指定服务读取 mirror:init 构建的索引的位置——请将其设为持久路径，以便索引在多次运行间保留。默认会隐藏所有者 PII；仅在可信的本地安装中设置 FAA_REDACT_OWNER_PII=false，以显示所有者详细信息。

首次运行设置

FAA 可公开获取的飞机数据库不随软件包一同提供——这是一个公开数据集（压缩后约 70 MB，由 FAA 每日更新），操作员需在首次使用前下载并建立索引。构建索引后会生成一个数百 MB 的本地 SQLite 文件。

请在服务器启动之外构建索引（绝不要在服务器启动时构建——解析约 100 万行数据可能会阻塞启动）。从源码检出目录开始，先运行 bun install && bun run build。然后，在检出目录、已安装的软件包目录或解压后的 MCPB 目录中，运行以下已编译命令。Node 和 Bun 均可使用；将 node 替换为 bun 即可使用 Bun 内置的 SQLite。Docker 镜像支持 bun run mirror:init、mirror:verify 和 mirror:refresh。

# Build the local index from the live FAA download (idempotent, resumable)
FAA_MIRROR_PATH=/path/to/faa-registry.db node dist/cli/faa-mirror-init.js

# Verify it built (readiness + integrity check)
FAA_MIRROR_PATH=/path/to/faa-registry.db node dist/cli/faa-mirror-verify.js

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

• 保持路径稳定。 将 FAA_MIRROR_PATH（以及 MCP 客户端配置中的同一环境变量）指向持久位置，以便在多次运行间重复使用已构建的索引。默认值：.mirror/faa-registry.db。
• 每日刷新。 使用 HTTP 传输时，服务会安排每日运行一次 mirror:refresh，时间与 FAA 夜间重新发布数据的时间一致（中部时间晚上约 11:30）。如果重建中断并导致索引为空，在重建成功前，查询会明确返回 ServiceUnavailable。使用 stdio 时，请在服务器运行之外执行 mirror:refresh（例如通过 cron 作业）。
• Docker。 镜像包含 mirror CLI 和一个归运行时用户所有、可写入的 .mirror 数据目录。在该目录挂载卷并运行一次 mirror:init（例如运行 docker exec <container> bun run mirror:init，或针对共享卷运行一次性初始化作业），这样索引就能在容器重启后保留。
• 索引尚不存在时， 所有查询都会失败，并返回 ServiceUnavailable 错误，恢复提示会指向 mirror:init——没有可回退使用的实时 API，因此冷启动状态会明确报错，而不会返回空结果。

可通过 FAA_DATABASE_URL 覆盖源 URL（用于私有或缓存镜像）；该变量只在数据导入时读取，不会在每次请求时读取。

前置条件

• Bun v1.4 或更高版本（或 Node.js v24+）。Bun 使用内置的 bun:sqlite；Node 使用随附的 better-sqlite3 依赖，其中包含适用于 x64 和 arm64 架构上 macOS、Windows 和 Linux（glibc/musl）的 N-API 预编译版本。
• 在 FAA_MIRROR_PATH 指定的位置为已构建的索引预留磁盘空间（数百 MB）。
• 在运行 mirror:init / mirror:refresh 时能够联网下载 FAA ZIP 文件。查询时无需联网。

安装

如需从源码进行本地开发或自托管：

1. 克隆代码库：

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

2. 进入目录：

cd faa-aircraft-registry-mcp-server

3. 安装依赖：

bun install

4. 编译服务并构建索引（请参阅首次运行设置）：

bun run build
bun run mirror:init

配置

变量	描述	默认值
FAA_REDACT_OWNER_PII	隐去所有者姓名和地址，并禁用按所有者姓名搜索。未设置、为空或格式错误时均视为 true。	true
FAA_MIRROR_PATH	SQLite 索引文件的路径；请使用持久化位置。	.mirror/faa-registry.db
FAA_DATABASE_URL	FAA 数据库 ZIP 文件的源 URL，仅由 mirror:init / mirror:refresh 读取。	FAA 注册表 ZIP
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_SESSION_MODE	会话模式：auto、stateful 或 stateless。	stateless
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_HTTP_ENDPOINT_PATH	MCP 服务挂载的 HTTP 端点路径。	/mcp
MCP_AUTH_MODE	认证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败的工具调用参数和结果（上限：LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES，默认值为 16384）。	false
OTEL_ENABLED	启用 OpenTelemetry 插桩。	false

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  # 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
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest unit and integration tests
  bun run test:package # npm tarball + cleaned MCPB runtime checks
  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

Dockerfile 默认使用 HTTP 传输和无状态会话，提供 mirror:init / mirror:refresh / mirror:verify CLI，并预先创建由运行时用户拥有且可写的 .mirror 数据目录（在此处挂载卷，并运行一次 mirror:init 以构建和持久化索引），同时将日志写入 /var/log/faa-aircraft-registry-mcp-server。默认会安装 OpenTelemetry 对等依赖；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖。

项目结构

目录	用途
src/index.ts	createApp() 入口——注册工具和资源，初始化注册表服务，并在 HTTP 传输下安排每日刷新。
src/config	使用 Zod 解析和验证服务专属环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。
src/mcp-server/resources	资源定义（*.resource.ts）。
src/services/registry	注册表服务——SQLite + FTS5 镜像、数据导入器、解码映射、N 号标准化器，以及所有者 PII 隐去闸门。
src/cli/	镜像生命周期 CLI——编译到 dist/cli/，用于 mirror:init、mirror:refresh、mirror:verify。
tests/	与 src/ 对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md/AGENTS.md。简要来说：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，使用 ctx.state 存储租户范围内的数据
• 通过 src/mcp-server/*/definitions/index.ts 中的聚合导出文件注册新工具和资源

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。

FAA 可公开发布的航空器数据库属于美国政府公共领域作品，由 FAA 民用航空登记处发布。本项目不会重新分发其中任何数据；操作人员会在安装时直接从 FAA 下载数据。