faa-traffic-delays-mcp-server

---

概览

获取 FAA 指挥中心提供的美国实时空中交通状态，该中心也是 nasstatus.faa.gov 的数据来源。查询机场的地面停飞、地面延误计划、延误和关闭情况；查看全国所有进行中的事件；读取今日运行计划；还可获取任意计划的完整通告，包括过去日期的通告。

工具

工具	描述
faa_delays_get_airport_status	每次调用可查询最多 25 个不同美国机场的当前状态，并列出其余机场：地面停飞、延误计划、延误、关闭、除冰和跑道配置
faa_delays_list_active_events	查看国家空域系统中的所有进行中事件，包括空域流量计划；按严重程度排序，并统计各类型事件数量
faa_delays_get_operations_plan	指挥中心的运行计划：预计于今日晚些时候执行的计划和举措，以及计划时间和可能性
faa_delays_get_advisory	按编号和 UTC 日期获取一份 ATCSCC 通告的全文：计划流量、范围、备注和计划限制
faa_delays_list_advisories	列出某个 UTC 日期发布的 ATCSCC 通告，按时间从新到旧排列并显示编号：已发布、拟议、修订和取消的计划、绕航路线及运行计划
faa_delays_list_reference	解读事件类型、交通管理术语、ARTCC 代码、FAA 流量调控机场及标识符格式

能力参考

faa_delays_get_airport_status _工具

• airports：1–100 个代码，每个代码为 3 个字符的 FAA 标识符（SEA）或 ICAO 代码（KSEA、PHNL），可使用数组或逗号分隔的字符串。未知代码会导致整个调用失败，并返回 unknown_airport。只处理前 25 个不重复的机场（cap: 25）；processedCount 和 omittedAirports 会列出其余机场，供下一次调用传入
• 每个机场对应一行，顺序与请求一致：status（closed、ground_stop、ground_delay_program、delays、restrictions_only、no_active_events）、listedInFeed、airportName、artcc、坐标，以及每个有效事件（groundStop、带有每 15 分钟 delayProfile 的 groundDelayProgram、arrivalDelay / departureDelay、closure、closureNotam、deicing）
• 只有 FAA 信息流中列出的机场才会显示 runwayConfiguration（跑道和 arrivalRatePerHour）。PHX 报告的 timezone: "America/Phoenix" 对应 reportedTimezone: "US/Mountain"

---

faa_delays_list_active_events _工具

• 可选的 event_types 筛选器可筛选 ground_stop、ground_delay_program、airspace_flow_program、arrival_delay、departure_delay、airport_closure、closure_notam、deicing（别名为 gs、gdp、afp）。行按严重程度排序，并包含 reason、延误数据、时间，以及 FAA 提供的 advisory 引用
• totalActive 和 countsByType 统计筛选前整个信息流中的数据。airspace_flow_program 行包含 afp 详情（受限区域、筛选条件、高度、延误概况）
• enRouteFeed（ok、unavailable、format_changed）说明是否读取了空域流量计划；如果无法读取，则会将其省略并附带 notice，除非它是唯一请求的类型

---

faa_delays_get_operations_plan _工具

• 无需输入；terminalPlanned 和 enRoutePlanned 条目包含 text、timeQualifier（after、until、by、between）、timeUtc（无日期的 HHMM）和 likelihood（possible、probable、expected）
• announcements 列出当前 ATCSCC 公告（无法读取时会省略并附带 notice）；advisory 指向 faa_delays_get_advisory 可获取的完整计划文本

---

faa_delays_get_advisory _工具

• advisory_number（1–999）和 date（UTC，YYYY-MM-DD；也接受 MM/DD/YYYY），取自 faa_delays_list_advisories 的某一行或 advisory 引用。编号每天 UTC 时间重置为 1；过去的公告仍可读取
• 返回 title、controlElement、subject、effectiveTime、sentAt 和完整的 text。编号未知时返回 found: false，并提供指向 faa_delays_list_advisories 的 guidance
• 超过 50,000 个字符的文本会被截断，并通过 truncated 和 totalChars 标记；失败时会返回 advisory_service_unavailable 或 advisory_contract_changed

---

faa_delays_list_advisories _工具

• date（UTC，YYYY-MM-DD；也接受 MM/DD/YYYY；最晚为明天；默认今天）、可选的 categories（ground_stop、ground_delay_program、airspace_flow_program、ctop、route、other；别名为 gs、gdp、afp）、control_element（使用 FAA 或 ICAO 代码表示的机场、ARTCC，或用于全国公告的 DCC）、limit 1–200（默认 50）和 offset
• query 会在 subject 或 details 中匹配不区分大小写的子字符串，例如，在计划中搜索指定的 FCA，可使用 query: "FCA005"
• 行按时间从新到旧排列：number 和 date（供 faa_delays_get_advisory 使用）、controlElement、subject、details 和 sentAt。totalCount 统计所有匹配项；仍有更多结果时会提供 nextOffset；没有匹配项时返回空列表并附带 notice

---

faa_delays_list_reference _工具

• topic：event_types、terms、artccs、pacing_airports 或 identifiers
• 只有 pacing_airports 会调用 FAA（实时获取，缓存 6 小时）；identifiers 还会报告捆绑机场目录的周期日期和机场数量

功能

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

FAA 专属功能：

• 以无密钥方式读取 NAS 状态信息流（nasstatus.faa.gov/api）和 ATCSCC 通告数据库（www.fly.faa.gov/adv）；FAA 数据属于公共领域（17 U.S.C. §105）
• 根据随附的 FAA NASR 机场目录校验机场代码，并将 ICAO 代码映射到 FAA 标识符（KSEA → SEA），因此输错的代码会报错，而不会被当作安静机场读取
• 信息流缓存 60 秒（调节机场列表缓存 6 小时），并对发往各 FAA 主机的请求进行限速
• 对未公开文档的信息流采用宽容解析：跳过无法读取的条目，并在 notice 中计数

便于 Agent 使用的输出：

• 采用带类型的失败原因，区分服务中断（feed_unavailable）、FAA 响应缓慢或受到限流（retry_deadline_exceeded、upstream_rate_limited、pacer_shed），以及格式变更（feed_contract_changed，不可重试）；恢复提示会指出下一步应调用的工具
• 无法读取的次要列表（调节机场、航路事件、公告）会在 notice 中注明并省略，不会导致调用失败
• fetchedAt 标记快照日期；若延误信息上次更新时间超过 6 小时，notice 会发出提示
• FAA 撰写的文本会在 content[] 中加引号，以表明其为数据，并在 structuredContent 中保持原文

限制：

• 仅供参考，不用于实际运行。 不能替代正式的飞行前简报或航空公司运行数据。
• 上游接口未公开文档。 nasstatus.faa.gov/api/* 是仪表板的私有后端，可能随时变更；若接口格式发生变化，服务会报错 feed_contract_changed，而不会猜测处理。
• 机场覆盖范围由事件决定。 信息流仅列出存在活动事件的机场，因此 no_active_events 表示没有 FAA 项目，不代表航班准点。信息流中没有逐航班 EDCT。
• 机场目录是快照。 FAA 在随附的 NASR 周期之后分配的标识符，在目录下次更新前会被判定为未知。仅支持美国机场。

开始使用

公共托管实例

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

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

自托管 / 本地运行

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

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

也可以使用 npx（无需 Bun）：

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

也可以使用 Docker：

{
  "mcpServers": {
    "faa-traffic-delays-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/faa-traffic-delays-mcp-server:latest"]
    }
  }
}

若使用 Streamable HTTP，请设置传输方式并启动服务：

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

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥或账户：FAA 信息流是公开的。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/faa-traffic-delays-mcp-server.git

2. 进入目录：

cd faa-traffic-delays-mcp-server

3. 安装依赖项：

bun install

4. 配置环境（可选）：

cp .env.example .env
# every variable has a default; edit .env only to change transport, logging, or telemetry

配置

服务自身不读取任何环境变量：FAA 主机、缓存时长和请求限速均在服务中固定。这些框架变量用于配置传输、日志记录和遥测。

变量	说明	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_HTTP_HOST	HTTP 服务主机。	127.0.0.1
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<app-root>/logs
OTEL_ENABLED	启用 OpenTelemetry。	false

常见的框架覆盖项请参见 .env.example。

运行服务

本地开发

• 构建并运行生产版本：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• 运行检查和测试：

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

• 从当前 FAA NASR 周期刷新机场目录（需要网络访问权限和系统的 unzip）：

  bun run refresh:airports
  

项目结构

目录	用途
src/mcp-server/tools	工具定义（*.tool.ts），以及共享输出架构、提示公告日期输入、通知片段和用于 FAA 编写文本的 Markdown 辅助工具。
src/services/nas-status	NAS Status 数据源客户端和宽容型数据源解析器。
src/services/advisory	ATCSCC advisories 数据库客户端、公告页面和索引解析器，以及公告和索引 URL 构建器。
src/services/airport-directory	内置的 FAA NASR 机场目录（名称、地点、ARTCC、坐标）和 ICAO → FAA 对照表（生成的模块）。
src/services/upstream	共享的 FAA 请求边界（节流、重试、状态分类）和进程内缓存。
scripts/refresh-airport-directory.ts	重新生成机场目录模块（bun run refresh:airports）。
tests/	单元测试和集成测试，结构与 src/ 一致，并使用合成的 FAA 测试数据。
docs/design.md	工具接口设计、上游 API 说明、设计决策和已知限制。

开发指南

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

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志；FAA 数据源会缓存在进程中，而不是 ctx.state 中
• 在 src/mcp-server/tools/definitions/index.ts 的 allToolDefinitions 中注册新工具
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

贡献

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

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。