aviation-weather-mcp-server

---

概述

来自 NWS Aviation Weather Center 的航空天气信息：METAR、TAF、PIREP、国内／国际 SIGMET 以及 Center Weather Advisories。查询站点，获取当前和预报天气状况，并检索飞行员报告和危险天气公告。不提供 AIRMET。

工具

工具	描述
aviation_find_stations	按标识符、边界框或美国州查找机场和气象站。返回 ICAO/IATA/FAA ID、坐标、海拔和可用数据类型。
aviation_get_metar	获取指定机场的当前天气观测（METAR），或调查边界框内的所有报告站点。返回解码后的风、能见度、云底高、当前天气、温度/露点、气压高度表读数、云层、飞行类别（VFR/MVFR/IFR/LIFR）以及原始 METAR 字符串。
aviation_get_taf	获取一个或多个机场的终端机场预报。返回每个预报时段的有效时间、地面风、低空风切变、能见度、解码后的天气、云层、预报遮蔽区内的垂直能见度，以及原始 TAF 字符串。
aviation_get_pireps	获取机场附近或边界框内近期的飞行员报告。返回解码后的颠簸、结冰和云况报告，包含高度、机型、强度、外界气温、高空风、飞行天气以及原始 PIREP 字符串。
aviation_get_advisories	获取国内/国际 SIGMET 和中心天气公告。返回来源覆盖范围、危险天气、严重程度、高度、有效期、移动情况、多段几何信息和原始公告；缺失的信息保持为 null。

提示词

提示词	描述
aviation_preflight_brief	为一次飞行整理飞行前天气简报，按顺序调用上述工具，并综合生成天气风险摘要。

---

能力参考

aviation_find_stations _工具

• 按标识符查找一个或多个站点（每次调用最多 20 个）——查找会匹配注册表自身的 ID；对于机场，该 ID 为 4 个字符的 ICAO ID（例如 KSEA、K0S9）；3 个字母的 IATA 代码无法解析，不过每条记录都会在可用时包含其 IATA/FAA 别名
• 查找地理边界框内的站点，或通过两字母 USPS 代码列出美国 50 个州之一或 DC 的站点
• 返回 data_types（METAR、TAF 等），供 Agent 在查询前确认可用数据
• 每条结果都会说明是否触发了上游 400 行上限；limit（1–400）限制 bbox 或 state 搜索返回的站点数量，结果按 ICAO 标识符升序排列，没有标识符的站点排在最后——此参数不能与 station_ids 同时使用，因为该模式已明确指定集合。区域搜索在未设置 limit 时若返回超过 130 个站点，会说明这一点并指出可调整的参数；省略 limit 仍会返回所有匹配项
• ID 查找会列出所有未能解析的标识符，并区分永远无法解析的 3 个字母 IATA 代码与注册表中未列出的标识符
• ID 前后的空白会被去除，而不会导致批次失败；只有空条目或仅含空白的条目会被拒绝

---

aviation_get_metar _tool

• station_ids（每次调用 1–10 个；4 个 ASCII 字母或数字，不区分大小写并会规范化为大写，因此 ksea 和 K0S9 均可用），用于指定机场；或使用 bbox 调查区域内所有有报告的站点——两者互斥
• hours（1–12）是回溯时间范围，不是行数限制：使用 station_ids 时会返回范围内的每条观测；使用 bbox 时则返回每个站点的最新观测
• flight_category（例如 ["IFR", "LIFR"]）可将 bbox 调查范围缩小到属于这些类别的站点——依据每个站点的最新观测判断，在 limit 之前应用，并说明筛选前调查的站点数；AWC 无法评级的站点永远不会匹配，筛选后结果为空时也会明确说明。与 station_ids 同时使用时会被拒绝
• bbox 调查会说明上游 400 行上限是否截断了结果；当 hours 大于 1 时，会指出应优先调整 hours——较宽的时间范围会让上限更多地用于重复读数，而非更多站点；limit（1–400）限制返回的站点数量，按站点 ID 升序排列，与 station_ids 同时使用时会被拒绝。若调查返回超过 40 个站点且未指定 limit，会提示这一点并说明可调整的参数；省略 limit 仍会返回所有站点
• 飞行类别（VFR/MVFR/IFR/LIFR）直接取自 AWC API；除原始 METAR 字符串外，还会解码风、能见度、当前天气和云层
• 云底高度报告包含高度和类型（实测值，或因遮蔽而产生的垂直能见度不定值）——当 clouds 为空时，sky_condition 可区分报告的晴空与未报告天空状况
• metar_type 用于区分常规的 METAR 与特殊的 SPECI 观测
• 每批结果都会报告哪些请求的站点已返回，并列出缺失的 ID 及恢复建议

---

aviation_get_taf _tool

• 每次调用接受 1–4 个 ICAO 站点 ID：4 个 ASCII 字母或数字，大小写均可，并会规范化为大写
• 提供结构化的预报时段，包含变化类型（FM、TEMPO、BECMG）和概率；天气按组解码，并与原始组并列展示
• 预报中的遮蔽现象会保留所在云层，并附带其中的垂直能见度，而不是显示为晴空；sky_condition 可区分未修订时段与明确报告的晴空
• 上游解码器未能解码的文本（通常是第四个云层）会按时段列入 not_decoded，而不会被丢弃
• 低空风切变（WS020/20040KT）会解码为风切变层顶及该高度处的预报风
• 提供 ISO 8601 格式的 valid_from / valid_to，用于时间比较
• 每批结果都会报告哪些请求的站点已返回，并列出缺失的 ID 及恢复建议

---

aviation_get_pireps _工具

• station_id（4 个 ASCII 字母或数字，大小写均可，会规范为大写）+ distance_nm（10–500 nm，省略时为 100）用于径向搜索，或使用 bbox 进行区域搜索；两者互斥。若 AWC 不将某个 station_id 识别为搜索中心，则返回类型化错误，并提示使用 aviation_find_stations 或 bbox
• altitude_min_ft / altitude_max_ft 用于筛选海平面以上英尺（MSL）的巡航高度范围，范围为 0–60000 ft（最小值不得大于最大值）；设置任一边界后，未知高度的报告会被剔除
• min_intensity（lgt / mod / sev）用于筛选包含达到或超过该强度的湍流层或结冰层的报告；匹配的报告仍会包含较低强度的图层
• 每份报告的湍流和结冰数组最多包含两个图层；如果某份报告从未提及结冰，则会剔除 API 为其合成的结冰层
• PIREP 和 AIREP 均包含外部气温（temp_c）、高空风（wind），以及与原始组别一同解码的 /WX 飞行天气（weather）。风向按报告中的原样发布，不作转换——PIREP 的 /WV 风向为磁北方向，与 METAR 和 TAF 中以真北为基准的风向不同
• 每个结果都会说明上游 400 行上限是否截断了结果，并仅列出此次调用仍可使用的缩小结果集选项；limit（1–400）用于限制返回的报告数量，结果按时间从新到旧排序。若结果超过 50 份且未指定 limit，则会说明这一点并列出可用选项；省略 limit 仍会返回所有匹配项
• PIREP 天生较为稀疏——没有报告并不意味着飞行条件平稳

---

aviation_get_advisories _工具

• advisory_type：sigmet（国内）、isigmet（国际，包括海洋区域）、cwa（Center Weather Advisories，中心天气咨询），或 all（默认值：所有三个独立产品）
• hazard 在上游应用：国内支持 CONVECTIVE、TURBULENCE、ICING、IFR；国际支持 TS、TURBULENCE、ICING、MTW、DS、SS、TC、VA；CWA 支持 TS、TURBULENCE、ICING、IFR、PCPN、UNK。不兼容的数据源会标记为 not_applicable；若所选项没有兼容的数据源，则会拒绝请求
• coverage 会将每个选定的数据源报告为 ok、failed 或 not_applicable，并且仅对可读取的数据源提供已解码的绘制数量。partial 表示数据源失败或跳过了无法读取的行。某个数据源失败时，其他正常的独立产品仍会保留；所有适用产品均失败时则返回错误。一次 45 秒的截止时间限制并发咨询读取和重试；调用方取消请求会中止所有任务
• bbox 使用每个几何部分的边界包络（包括跨越日期变更线的情况），而非进行精确的多边形相交判断。输入顺序保持不变（minLat <= maxLat、minLon <= maxLon）。使用 bbox 时，drawn 统计产品/危险类型筛选后的行数，matched 统计地理位置匹配数，returned 统计应用任何限制后的行数，unlocated 则单独统计没有已解码几何信息的行数
• limit 为可选项，且没有默认值：省略时返回所有可用的匹配项。显式设置时，结果按数据源、签发方、序列和有效期排序，并报告 total/returned/truncated，同时说明如何通过省略或调高限制来获取未返回的匹配项
• 缺失的签发方、序列、危险类型、有效期和原始文本保留为 null。geometry.parts 会保留独立的环/线以及源数据原生的 kind（包括 null）；对于多部分、线状或缺失的几何数据，兼容字段 polygon 为 null。国内数值严重程度/移动信息保持不变；国际移动信息会保留 direction_text 和已解码的节数。CWA 的严重程度/移动信息保留为 null，且绝不会从公告文本推断高度
• 原始公告会以安全代码围栏呈现，并保留空行和嵌入的反引号。空结果会说明可读取的数据源和筛选阶段；不可用的数据源不会用于判断天气良好
• 不提供 AIRMET。请求 AIRMET（或 MTN OBSCN / SURFACE WIND / LLWS）会被拒绝，并提示应分别获取 AIRMET 产品

aviation_preflight_brief _提示词

• 参数：必填 departure_icao 和 destination_icao；可选 alternates（以逗号分隔的 ICAO 代码）、departure_time（ISO 8601 UTC）、cruise_altitude（英尺 MSL）和 route_waypoints（以分号分隔的 lat,lon 坐标对）
• 每个 ICAO 参数都接受 4 个 ASCII 字母或数字，不区分大小写，并会生成大写 ID。对于 IATA/FAA 代码，请使用 aviation_find_stations 和 state 或 bbox 查找 ICAO ID；不会推断映射关系。直接 ID 不接受前后空格；以逗号分隔的备选机场代码允许包含空格
• 依次调用 aviation_get_metar、aviation_get_taf、aviation_get_pireps 和 aviation_get_advisories，并按每个工具的单次调用站点数限制分批处理
• departure_time 用于选择简报所依据的 TAF 预报时段；cruise_altitude 将 PIREP 搜索范围限定在 ±3,000 英尺区间内；route_waypoints 会转换为 advisories 的 bbox，并向四周各扩展 1°
• 即使省略这三项中的任意一项，也仍会生成简报，并指出无法进行的评估
• 报告天气风险，而非是否放行的建议——该决定需要飞行员、航空器和运行最低标准方面的背景信息，而本服务并不掌握这些信息

---

功能

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

航空天气专属功能：

• 无需密钥——无需 API 密钥或身份验证；所有数据均来自公开的 AWC Data API
• 单一服务（aviation-weather-service），针对无需密钥的公共端点提供重试和指数退避
• 除解码后的字段外，还会提供原始编码字符串（raw_metar、raw_taf、raw_pirep、raw_text），让 Agent 同时获取两种数据
• 州→bbox 表支持查询 AWC API 原生不支持的美国各州站点
• 服务端的 instructions 字段会在 initialize 时向所有客户端显示“非官方简报”安全免责声明

适合 Agent 使用的输出：

• 明确区分的输出——将飞行类别（VFR/MVFR/IFR/LIFR）作为类型化字符串字段提供，Agent 可据此分支处理，无需解析云幕高度和能见度
• 结构化错误约定——提供带有 recovery 提示的类型化 reason 字段（例如：“使用 aviation_find_stations 验证 ICAO ID”）
• 部分结果对账——批量工具会报告 requested / returned / missing / partial 字段，因此不会将不完整的批量结果误认为覆盖完整
• 工作流顺序——aviation_preflight_brief 提示词编码了正确的 METAR → TAF → PIREPs → advisories 顺序，按工具的站点数限制分批处理每个步骤，并指出无法进行的评估

---

开始使用

公共托管实例

可使用公共托管实例：https://aviation-weather.caseyjhand.com/mcp。将其添加到 MCP 客户端配置中：

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

自托管 / 本地运行

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

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

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

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

也可以使用 Docker：

{
  "mcpServers": {
    "aviation-weather": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/aviation-weather-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 密钥——AWC Data API 完全公开，无需密钥。

安装

1. 克隆代码库：

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

2. 进入目录：

cd aviation-weather-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env if you need to override AWC_BASE_URL or AWC_TIMEOUT_MS

---

配置

变量	描述	默认值
AWC_BASE_URL	NWS AWC Data API 的基础 URL。	https://aviationweather.gov/api/data
AWC_TIMEOUT_MS	每个请求的超时时间，单位为毫秒（1000–60000）。	10000
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_SESSION_MODE	HTTP 会话处理方式：auto（解析为 stateful）、stateful 或 stateless。代码中声明服务为 stateless——这里没有工具需要多轮输入——随附的 .env.example 和 Docker 镜像也固定使用相同值。设置此项会覆盖该声明。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
OTEL_ENABLED	启用 OpenTelemetry 插桩。	false

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

---

运行服务

本地开发

• 构建并运行：

  bun run rebuild
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  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 aviation-weather-mcp-server .
docker run --rm -p 3010:3010 aviation-weather-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/aviation-weather-mcp-server。默认会安装 OpenTelemetry 对等依赖项——构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

---

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具和提示词，并初始化服务。
src/config	特定于服务的环境变量解析（AWC_BASE_URL、AWC_TIMEOUT_MS）。
src/services/aviation-weather	AWC Data API 客户端——HTTP 获取、指数退避重试、响应规范化。
src/mcp-server/tools	工具定义（*.tool.ts）。
src/mcp-server/prompts	提示词定义（*.prompt.ts）。
tests/	与 src/ 结构相对应的单元测试和集成测试。

---

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简而言之：

• 处理器抛出异常，由框架捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围的日志，使用 ctx.state 存储租户范围的数据
• 在 src/index.ts 的 createApp() 数组中注册新工具和提示词
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；切勿编造缺失字段

并非官方的飞行前简报。 AWC 数据仅供参考。实际飞行计划需要使用获授权的数据源（例如 Leidos/1800wxbrief.com）。服务会通过每次 initialize 时发送的 instructions 字段展示此免责声明。

---

贡献

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

bun run devcheck
bun run test

---

许可证

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