@cyanheads/aviation-weather-mcp-server

公共托管服务器： https://aviation-weather.caseyjhand.com/mcp

工具

五个工具涵盖航空天气——站点查询、当前观测、终端天气预报、飞行员报告和活跃的咨询：

aviation_find_stations

通过多种搜索模式解析和发现气象站。

• 按 4 字母 ICAO ID 查询一个或多个站点（每次调用最多 20 个 ID）——查询仅支持 ICAO，但每条返回记录都会包含其 IATA/FAA 别名（如果有）

• 发现某个地理边界框内的所有站点

• 通过两位美国邮政服务代码（USPS）列出 50 个美国州或哥伦比亚特区的站点（使用 bbox 加客户端侧州过滤）

• 返回 data_types（METAR、TAF 等），以便代理在查询前确认哪些数据可用

• 每条结果都会说明上游 400 行上限是否截断了结果，因此截断的抽取永远不会被误认为是该区域的所有站点——被截断的州查询还会报告州过滤之前的行数，而更小的 bbox 是明确的调整手段

aviation_get_metar

获取当前或近期的 METAR 观测（每次调用 1–10 个站点）。

• hours 参数（1–12）按站点返回观测历史；默认 1 仅返回最近一次

• 飞行类别（VFR/MVFR/IFR/LIFR）直接来自 AWC API，无需客户端计算

• 除原始 METAR 字符串外，还解码云层、含阵风的风、能见度和当前天气（原始分组加上通俗英语，每组一个读数）

• 云底涵盖破碎、阴天和遮蔽层，并报告高度是否实测还是不确定云底——垂直能见度进入遮蔽现象

• METAR 类型字段区分 METAR（例行）和 SPECI（因显著天气变化触发的特殊观测）

• 每批都会报告哪些请求的站点返回了，因此部分结果永远不会被误认为是完整覆盖——缺失的 ID 会明确列出并附恢复指南

aviation_get_taf

获取 1–4 个机场的终端机场天气预报。

• 返回结构化的预报时段，包含变化类型（FM、TEMPO、BECMG）和概率

• 在原始分组旁边逐组解码预报天气（-SHRA BR → light rain showers; mist），与 aviation_get_metar 返回的形状相同

• 预报的遮蔽层保留其层次，并带有垂直能见度（VV002 → 200 英尺的不确定云底），而不是读作晴空

• 低空风切变（WS020/20040KT）被解码为剪切层顶和该高度的预报风

• valid_from / valid_to 采用 ISO 8601 格式，便于直接进行时间比较

• 每批都会报告哪些请求的站点返回了，因此部分结果永远不会被误认为是完整覆盖——缺失的 ID 会明确列出并附恢复指南

aviation_get_pireps

按站点+半径或边界框搜索近期飞行员报告。

• station_id + distance_nm（10–500 海里，省略时为 100）用于机场周围的径向搜索

• bbox 用于地理区域搜索——适合航路走廊检查；distance_nm 在此没有意义，会与它一起被拒绝

• altitude_min_ft / altitude_max_ft 过滤器用于隔离巡航高度的报告，可以单独使用一个边界，也可以同时使用（最小值不得超过最大值）

• 湍流和结冰数组每条报告最多包含两层（如 API 报告）

• 每条结果都会说明上游 400 行上限是否截断了结果，并指出 bbox、distance_nm 和 hours 是上限生效前缩小查询范围的措施——高度过滤器在上限之后运行，无法恢复被丢弃的报告

• 注意：没有 PIREP 并不意味着天气平静——它们本质上就是稀疏的

aviation_get_advisories

列出当前活跃的国内 SIGMET。

• advisory_type 过滤器：sigmet 或 all（默认）——两者都返回活跃的 SIGMET 集合

• hazard 过滤器：CONVECTIVE、TURBULENCE、ICING、IFR

• bbox 过滤器在客户端应用（AWC API 返回所有活跃的咨询；工具按多边形重叠进行过滤）

• 不提供 AIRMET。上游数据仅包含国内 SIGMET，因此 advisory_type: airmet 以及 MTN OBSCN、SURFACE WIND 和 LLWS 危险会被拒绝并提供指南，而不是用 SIGMET 或空数组来回答

• 在天气晴好的时期，可能没有活跃的 SIGMET——空结果是有效状态，不是错误

Related MCP server: mcp-metar

提示

所有资源数据都可通过工具访问。此服务器没有资源——所有航空天气数据都是时效敏感的（METAR 大约 1 小时有效，咨询从几分钟到几小时不等），不适合作为稳定 URI 的资源。

功能

基于 @cyanheads/mcp-ts-core 构建：

• 声明式工具和提示定义——每个原语一个文件，框架处理注册和验证

• 统一错误处理——处理器抛出，框架捕获、分类并格式化

• 可插拔认证：none、jwt、oauth

• 结构化日志，并可选 OpenTelemetry 追踪

• 支持 STDIO 和 Streamable HTTP 传输

航空天气专用：

• 无密钥——无需 API 密钥或认证；所有数据均来自公共 AWC Data API

• 单一服务（aviation-weather-service），对无密钥的公共端点提供重试+指数退避

• 原始编码字符串（rawOb、rawTAF、rawAirSigmet）与解码字段一同呈现，让代理同时拥有两层信息

• 州→边界框表支持 AWC API 原生不支持的美国州站点查询

• 服务器级 instructions 字段在 initialize 时向所有客户端显示“非正式简报”安全免责声明

代理友好的输出：

• 飞行类别（VFR/MVFR/IFR/LIFR）作为判别字符串字段——代理可以直接基于它进行分支，无需解析云底+能见度

• 结构化错误契约，带有类型化的 reason 字段和 recovery 提示（例如，“使用 aviation_find_stations 验证 ICAO ID”）

• 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.3.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

配置

有关可选覆盖项的完整列表，请参阅 .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 构建。

项目结构

开发指南

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

• 处理器抛出异常，框架负责捕获——工具逻辑中不使用 try/catch

• 使用 ctx.log 进行请求级日志记录，使用 ctx.state 进行租户级存储

• 通过 src/mcp-server/*/definitions/index.ts 中的桶文件注册新工具和提示词

• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出模式；绝不虚构缺失字段

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

贡献

欢迎提交 Issue 和拉取请求。提交前请运行检查与测试：

bun run devcheck
bun run test

许可证

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