Faa Aircraft Registry

@pipeworx/faa-aircraft-registry

在 FAA 民用航空器注册数据库中查询美国航空器的尾号（N 编号），包括制造商、型号、序列号、发动机、适航类别、注册人类型、注册状态、证书日期，以及当 N 编号已不在有效注册数据库中时的注销信息。

属于 Pipeworx 的一部分——一个将 AI Agent 连接到 1879+ 个实时数据源的 MCP 网关。这是独立的非官方集成，与上游提供方无关联，未获其认可，也未由其发布。

工具

• faa_reg_lookup(n_number) — 将一个 N 编号（“N12345”或“12345”）解析为其航空器／发动机参考数据、注册人类型和注册状态。只有注册人类型不是个人时（公司、LLC、合伙企业、共同所有或政府），才会返回注册人姓名；个人姓名属于个人数据，会予以隐藏，并在响应中说明。对于已注销的记录，绝不会返回注册人姓名（见下文“个人数据”）。

身份验证

无需密钥。

数据来源

• https://registry.faa.gov/database/ReleasableAircraft.zip — FAA 完整的民用航空器注册数据库，每日刷新。会加载四个文件：MASTER.txt（当前已注册的航空器）、ACFTREF.txt（机身制造商／型号参考数据）、ENGINE.txt（发动机参考数据）、DEREG.txt（历史注销记录）。同一 ZIP 中还包含 DEALER.txt 和 RESERVED.txt，但不在此程序包的范围内。美国联邦数据，属于公有领域。

为什么这是本地副本程序包，而不是实时代理

没有实时查询 API——FAA 只发布每日批量 ZIP。此程序包读取 Supabase 镜像（faa_reg_acftref、faa_reg_engine、faa_reg_aircraft、faa_reg_dereg；架构见 supabase/migrations/236_faa_aircraft_registry.sql），每天由 scripts/ingest-faa-aircraft-registry.mjs（.github/workflows/faa-aircraft-registry-refresh.yml）加载一次。每个成功的查询响应都会携带该行自身 loaded_at 的值作为 data_as_of。

获取操作本身通过网关路由，而非直接执行。 registry.faa.gov 使用 Akamai 进行前置防护，封锁依据是请求头格式，而不只是 IP 声誉（2026-10-08 更正：刷新任务 37731086667 从网关自身的 Worker 路由直接收到实时 Akamai 403，这与本说明早先的错误说法相反）。我们在生产账户中使用一次性 Cloudflare Worker 重现并修复了该问题：带有机器人特征的 UA 和 Accept: */* 会在这个确切 URL 上收到 Akamai 的“Access Denied”HTML（HTTP 403）；而一组符合真实浏览器特征的请求头（真实的 Chrome UA、浏览器格式的 Accept／Accept-Language，以及同源 Referer）则会收到内容真实、约 73 MB 的 ZIP，HTTP 状态为 200——使用的是同一个 Worker、同一个 IP，只有请求头不同。我们也测试了住宅 IP 和 Supabase 出口中继，两者无论请求头格式如何都会收到 403。因此，网关自身的 /admin/faa_reg_fetch_zip 路由（workers/gateway/src/index.ts）通过发送这些符合浏览器特征的请求头，成为唯一可用的路由；摄取脚本会调用该路由，并在其运行位置执行实际的解压、解析和加载。

数据库加载采用每张表执行 TRUNCATE + psql \copy 的方式，四张表在同一个事务中完成，并使用摄取脚本从其环境中读取的连接池连接字符串。这是每日完整快照，而非增量 upsert，因为当天的 MASTER.txt 完全不包含昨天已注销的 N 编号。如果四个文件中任意一个解析失败，整个事务都会回滚，因此昨天的数据仍保持可用，不会出现表仅被部分替换的情况。

空注册表防护

如果每日刷新从未成功完成过一次运行，后端表就是空的，但对这些表的查询仍会成功——因此，简单读取会对每个 N 编号都给出斩钉截铁的 found:false，无法与基于有效数据的真实未命中区分开来。faa_reg_lookup 会在作答前检查是否至少加载了一行数据；如果没有，就会抛出明确的 dataset_unavailable 类错误，指出这一情况（fleet #2790，2026-10-08）。

个人数据

MASTER 的 TYPE REGISTRANT 列用于区分个人注册人（代码 1）与合伙企业／公司／共同所有人／政府／LLC／非公民实体（代码 2,3,4,5,7,8,9）。注册人 NAME 列对于个人而言属于个人数据，会存储在镜像中（它也包含在 FAA 自己的公开批量文件中），但当 type_registrant 为 1 或为空／未知时，faa_reg_lookup 绝不会返回该列内容——只会返回非个人注册人的名称，并在响应中说明适用的是哪种情况。

DEREG.txt（历史注销记录）完全没有注册人类型列——无法从该文件中判断注册人是个人还是实体——因此，无论注销记录中的注册人实际属于哪种类型，faa_reg_lookup 都不会返回其名称。

重复注销

一个 N 编号可能会被注销、重新分配，然后再次注销——在 2026-10-08 测量的真实文件中，最坏情况下同一个 N 编号有 9 条事件记录——但镜像的注销表只以 N 编号作为键，因此只保留最近的一条事件记录（按取消日期判定）（scripts/lib/faa-dereg-dedupe.mjs）。每条注销响应都包含 dereg_events，表示合并到该记录中的历史事件数；如果该数量大于 1，还会附带 note——因此，响应绝不会暗示所显示的事件是记录中的唯一事件。

代码表

type_registrant、type_aircraft、type_engine 和适航类别（CERTIFICATION）均为 FAA 自己长期稳定、广泛发布的代码集，在 src/index.ts 中解码，并始终在标签旁保留原始代码。status_code 的代码表则是对常见代码（A/D/E/M/R/S/V/W/Z）进行的较小规模尽力解码（来源是 FAA 自己的 ardata.pdf 布局文档的公开搜索摘要；该文档在所有尝试的出口路由上都会返回 403——与数据 ZIP 不同，为了查阅一份参考文档而绕过限制并不值得）。如果遇到罕见或未来新增的代码，则会返回原始值，并将标签设为 null，而不是猜测。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "faa-aircraft-registry": {
      "url": "https://gateway.pipeworx.io/faa-aircraft-registry/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/faa-aircraft-registry/mcp 上的 tools/list 会返回上表中的工具，以及 Pipeworx 共享元工具——ask_pipeworx、discover_tools、search_within、remember／recall 和网关范围内的其他工具。因此，你看到的工具数量会多于此表所列：目前，单个工具包端点除了列出该工具包自身的工具，还会列出大约 30 个共享工具。连接的 initialize 响应会说明其确切范围，并且是特定日期下的权威答案。

这是有意为之，并非意外的多路复用。元工具可让限定范围的连接回答此工具包未涵盖的问题——通过 ask_pipeworx 路由到整个目录——而无需你再添加第二个 MCP 服务。目前无法挂载不含这些元工具的工具包端点；如果额外的模式定义带来的上下文开销大于路由功能的价值，不如连接一次完整网关，而不是连接多个工具包端点。

也可以连接完整的 Pipeworx 网关，直接列出所有工具包的工具，而不只是此工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

这两个 URL 都连接到同一个网关和相同的 1879+ 个数据源。唯一的区别是哪个工具包的工具会被直接列出；无论连接哪个端点，ask_pipeworx 都能访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/faa_reg_lookup \
  -H 'Content-Type: application/json' \
  -d '{"n_number":"N10000"}'

首次调用无需账号。查看任意工具：GET https://gateway.pipeworx.io/v1/tools/faa_reg_lookup。查找工具：使用 {"query":"..."} 调用 POST https://gateway.pipeworx.io/v1/tools/search_packs。

独立运行（无需网关账号）

此软件包也可以作为本地 stdio MCP 服务运行，无需 Pipeworx 账号，也无需经过网关：

{
  "mcpServers": {
    "faa-aircraft-registry": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-faa-aircraft-registry"]
    }
  }
}

或者直接运行，确认它能够启动：

npx -y @pipeworx/mcp-faa-aircraft-registry

它通过 stdin/stdout 使用 MCP 通信，并响应 initialize/tools/list/tools/call，仅提供此软件包的工具，不包含上述网关连接额外提供的任何共享元工具。相同的源代码，相同的工具，不使用 ask_pipeworx 路由。

使用 ask_pipeworx

你可以用通俗的英语提问，而不是直接调用工具——这既适用于上面的软件包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Faa Aircraft Registry data" })

网关会选择合适的工具并自动填充参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT