ourairports-mcp-server

---

概述

全球机场、跑道、导航台和无线电频率数据，来自公共领域的 OurAirports 数据集，并随附于项目中以供离线使用。可通过任意代码查询机场、按名称或属性搜索，并查找坐标附近的机场和导航台。

工具

工具	描述
ourairports_search_airports	按名称、市镇、国家、地区或类型，对机场数据进行全文和分面搜索。返回排序后的摘要，默认排除已关闭的机场。
ourairports_search_runways	按道面、长度、宽度和照明条件搜索所有机场的跑道，并关联对应机场；还可按国家、地区或机场类型筛选。每条匹配的跑道返回一行扁平的 { airport, runway } 数据。
ourairports_get_airport	通过任意代码（IATA/ICAO/GPS/本地代码/ident）查询单个机场的完整记录，内含其跑道和无线电频率。
ourairports_find_airports	查找坐标指定半径范围内的机场，按大圆距离从近到远排序，并提供距离和方位。
ourairports_find_navaids	查找坐标附近或服务于指定机场的导航设施（VOR、VOR-DME、DME、NDB、NDB-DME、TACAN、VORTAC）。
ourairports_list_countries	列出国家及其机场数量，并可选择包含下级地区；可按国家和／或洲筛选。该表可用于查询两个搜索工具中有效的 country／region 筛选值。

资源

资源	描述
airport://{code}	按任意代码（IATA/ICAO/GPS/本地代码/ident）查询单条机场记录，内联包含跑道和频率。

所有数据也可通过 ourairports_get_airport 获取——仅支持工具的客户端不会因此缺失任何信息。数据未以资源列表形式公开（枚举 8.5 万个机场只是倾倒数据，并非发现信息的辅助手段）；请使用 ourairports_search_airports 进行发现。

功能参考

ourairports_search_airports _工具

• 根据名称、市镇和关键词进行自由文本搜索；各词元需同时匹配（支持任意词序和部分词语匹配）
• 分面筛选：country（两个字母）、region（两个字母，后接一个或两个以连字符分隔的片段，每段为 1–3 个字母或数字）和 type。代码不区分大小写，并忽略首尾空格；字面值 "" 表示未设置，纯空白值无效。格式错误的代码会导致参数验证失败；不在随附表格中的代码会触发 unknown_country / unknown_region，并提供发现指引。有效代码即使没有匹配的机场，也会返回空结果
• 默认排除已关闭的机场；使用 include_closed 可选择包含
• 结果按运营状态和机场规模优先排序；每条结果均包含完整代码集及坐标，可用于后续调用 ourairports_get_airport
• limit 接受 1–100 行，默认值为 OURAIRPORTS_DEFAULT_SEARCH_LIMIT（20）；结果被截断时，会报告匹配总数、上限及恢复指引

---

ourairports_search_runways _工具

• 先用机场分面（country、region、type）缩小机场范围，再用跑道分面（surface、min_length_ft、min_width_ft、lighted）筛选跑道
• country / region 分面的格式、空字符串、规范化和随附数据成员资格规则与 ourairports_search_airports 相同；有效但无匹配项的筛选仍会成功
• surface 按原始上游地面类型字符串进行不区分大小写的子串匹配（没有受控词汇表——较短的片段如 asp 可匹配 ASP、ASPH 和 Asphalt），而非精确代码匹配
• 每条匹配的跑道返回一行扁平的 { airport, runway } 记录——某机场有三条匹配跑道时会贡献三行
• lengthFt 和 min_length_ft 使用 OurAirports 记录的完整跑道地面长度，包括移位入口和超长段——并非可用起飞或着陆距离；每条跑道还带有 leDisplacedThresholdFt / heDisplacedThresholdFt（未记录时为 null）
• 如果跑道长度或宽度未知，设置对应的 min_*_ft 筛选条件时，该跑道会被排除——不会假定数据无法确认的跑道满足阈值
• 默认同时排除已关闭的机场和跑道；使用 include_closed_airports / include_closed_runways 可选择包含
• limit 接受 1–100 行，默认值为 OURAIRPORTS_DEFAULT_SEARCH_LIMIT（20）；结果被截断时，会报告匹配总数、上限及恢复指引

---

ourairports_get_airport _工具

• 使用 code 不区分大小写地在全部五种标识符类型中查询单个机场（优先级：ident → ICAO → IATA → GPS → 本地代码）；忽略首尾空格
• 内联返回跑道和无线电频率；include 可将响应缩减为指定子集，输出中的 included 字段可区分因 include 而省略的关联数据与确实没有记录的数据
• 回显机场的完整代码集以及 resolvedVia / resolutionNote；当其他机场带有相同代码时，说明会列出每个机场（ident、国家、代码类型），并指出本次解析是由优先级还是数据集行顺序选定该机场，使错误解析可以自行纠正——请传入另一个机场的 ident
• 跑道包含完整地面长度 lengthFt，以及每一端的移位入口距离（leDisplacedThresholdFt / heDisplacedThresholdFt）
• 未提供的代码会报告为 null；已关闭的机场仍始终可以解析
• 如果所有标识符类型均不匹配，则返回 unknown_code 错误及恢复提示

---

ourairports_find_airports _工具

• 按大圆距离（haversine）排名，最近的排在前面；每条结果均包含从查询点出发的 distanceKm 和 bearingDeg（真方位角，单位：度）
• radius_km（1–500，默认值为 100）；limit（1–50）默认采用 OURAIRPORTS_DEFAULT_SEARCH_LIMIT，上限为此工具的 50 条；可选的 type 筛选；可选择包含已关闭机场
• 输入坐标，返回排名后的机场——不进行地理编码；请先在上游将地点名称解析为经纬度
• totalCount 是应用 limit 前半径范围内的筛选结果数；截断时会报告上限并提供恢复建议（缩小 radius_km、添加 type 或提高 limit）
• 当半径范围内无结果时，会建议扩大 radius_km

---

ourairports_find_navaids _工具

• **坐标模式：**提供 latitude + longitude（可选 radius_km，1–500，默认值为 100），按距离从近到远排列助航设施，并返回距离和方位角；limit（1–50）默认采用 OURAIRPORTS_DEFAULT_SEARCH_LIMIT，上限为 50
• **机场模式：**提供 airport_code，返回为该机场提供服务的助航设施
• 必须且只能选择一种完整模式——同时使用两种模式、均未使用或坐标不完整都会引发 mode_conflict；坐标不完整时，错误消息会指出缺少的对应项
• 对所有类型，frequencyKhz 均为存储值（114.5 MHz 的 VOR 显示为 114500）；VOR 或 VOR-DME 的 VHF 频率，以及 DME、TACAN 或 VORTAC 配对的 VHF 频率由 frequencyMhz 表示；对于以 kHz 调谐的 NDB 和 NDB-DME，该字段为 null；上游的 -1 占位值显示为 null
• 每个助航设施均包含上游记录的服务范围元数据：usageType（HI、LO、BOTH、TERMINAL、RNAV）、power、magneticVariationDeg（实际磁偏角，东偏为正）、slavedVariationDeg（径向中内置的磁偏角）和 dmeFrequencyKhz（DME 配对的 VHF 频率）；数据集无值时为 null
• 两种模式下的 totalCount 均为应用 limit 前的匹配数量；截断时会报告上限并提供恢复建议
• 机场模式会区分“未找到机场”（unknown_code 错误）与“已找到机场但没有关联助航设施”（返回空列表并附带说明）
• 如果 airport_code 同时也是其他机场的代码，机场模式会添加 resolutionNote，并通过 ident 列出这些机场——ourairports_get_airport 也会返回相同说明

---

ourairports_list_countries _工具

• 可选的 country 和 continent（AF、AN、AS、EU、NA、OC、SA）筛选条件按 AND 组合；可选的 include_regions 会按记录的所属国家嵌套区域（因此 KS-U-A 属于 XK）
• 要获取某个国家的区域，可使用 { "country": "US", "include_regions": true }。未指定范围时，include_regions 会返回完整区域表；未指定范围和仅指定大洲的请求仍然有效
• country 使用搜索工具相同的格式、规范化和成员资格规则；"" 表示未设置，仅包含空白字符的值无效；不存在的代码会引发 unknown_country
• 机场数量不包括已关闭的机场
• 国家按名称排序；此查找表用于 ourairports_search_airports 和 ourairports_search_runways 中有效的 country / region 筛选条件
• 国家与大洲不匹配时，会返回成功但结果为空，并附带说明列出这两个筛选条件；totalCount 为返回的国家数

---

airport://{code} _资源

• 与 ourairports_get_airport 返回相同记录，包括相同的 resolutionNote——跑道和无线电频率始终内联提供，因此没有 include / included
• code 会跨全部五种标识符空间进行不区分大小写的解析（优先级：ident → ICAO → IATA → GPS → local）
• 所有标识符空间均不匹配时，会返回 unknown_code 错误并提供恢复提示

功能

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

OurAirports 专属功能：

• 内置公有领域数据集，随软件包和 Docker 镜像一起发布——运行时无需调用 API、无需密钥、没有速率限制，也不受上游服务中断影响
• 启动时只构建一次内存索引：ID 映射、按优先级排序的统一代码索引、跑道和频率的机场引用关联、按 ident 关联的导航设施索引、存储坐标的扁平 Float64Array、国家/地区映射，以及分词后的文本搜索索引
• 基于坐标数组执行暴力 haversine 最近邻搜索——在 85k 个机场中只需几毫秒，无需依赖空间索引
• CSV 按表头名称而非列位置解析，因此上游调整列顺序不会导致字段错位却不易察觉
• 机场搜索最多保留 limit 个排名靠前的候选结果；跑道搜索保留前 limit 行，同时两者都会统计所有匹配项

便于 Agent 使用的输出：

• 如实反映数据稀疏性——上游缺失的字段（没有 IATA 代码、没有海拔、跑道尺寸为 null）会显示为 null，绝不伪造
• 自动纠正的解析结果——每条机场记录都会返回其完整代码集，以及 resolvedVia / resolutionNote，列出每个与之共享代码的其他机场及其 ident
• 文本输出与结构化输出一致——坐标以完整精度呈现，上游文本仅在 content 中进行 Markdown 转义，因此 GRASS&GRAVEL 这样的名称会按记录原样显示
• 说明结果截断和空结果情况——提供总数、应用的上限和恢复建议，让调用方无需解析散文即可扩大范围、缩小范围或重新查询

快速开始

公共托管实例

可使用公共实例 https://ourairports.caseyjhand.com/mcp——无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例，并使用以下客户端配置：

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

自托管 / 本地运行

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

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

或使用 npx（无需 Bun）：

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

或使用 Docker：

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

无需 API 密钥——数据集随软件包和镜像一起发布。

要使用 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 密钥、账户或外部服务——所有数据均已内置。

安装

1. 克隆代码仓库：

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

2. 进入目录：

cd ourairports-mcp-server

3. 安装依赖：

bun install

4. 获取并打包数据集（将六个 CSV 文件写入 data/）：

bun run build:data

刷新数据

内置快照的时效性取决于上次运行 build:data 的时间（对于 Docker 镜像，则取决于上次构建的时间）。要从 OurAirports 镜像获取最新的每日数据，请重新运行 bun run build:data 并重新构建。写入所获取的数据包之前，构建过程会根据查找表验证国家/地区代码格式和机场引用；bun run build:data --check 则会验证现有数据包。如需使用现有的本地数据目录而不重新构建，请设置 OURAIRPORTS_DATA_DIR。

配置

变量	说明	默认值
OURAIRPORTS_DATA_DIR	存放六个 OurAirports CSV 文件的目录。可覆盖此值以指向更新的本地数据包。	随附的 data/
OURAIRPORTS_DEFAULT_SEARCH_LIMIT	调用方未提供 limit 时，搜索/查找工具的默认结果上限（1–100）。	20
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_HTTP_ENDPOINT_PATH	挂载服务的 HTTP 端点路径。	/mcp
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_SESSION_MODE	HTTP 会话模式：stateful、stateless 或 auto。由于工具请求不需要后续输入，此服务使用无状态模式。	stateless
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	存储后端（数据路径中未使用——索引存储在内存中）。	in-memory
OTEL_ENABLED	启用 OpenTelemetry 插桩。	false

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

运行服务

本地开发

• 构建并运行：

  # One-time data fetch + build
  bun run build:data
  bun run rebuild
  
  # Run the built server
  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 ourairports-mcp-server .
docker run --rm -i -e MCP_TRANSPORT_TYPE=stdio ourairports-mcp-server

构建阶段会运行 bun run build:data，以获取数据集并将其打包进镜像——生成的容器完全自包含，运行时不会发起网络请求。Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/ourairports-mcp-server。默认会安装 OpenTelemetry 对等依赖——使用 --build-arg OTEL_ENABLED=false 构建即可省略这些依赖。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具/资源，并在 setup() 时加载随附的索引。
src/config	使用 Zod 解析并验证服务专属的环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。六个只读机场/跑道/导航设备工具。
src/mcp-server/resources	资源定义。airport://{code} 记录。
src/services/airport-data	随附数据服务——CSV 解析、内存索引、代码解析、搜索和 haversine 地理扫描。
scripts/build-data.ts	构建时获取器，将六个 OurAirports CSV 文件打包到 data/ 中。
framework-skills/	从 @cyanheads/mcp-ts-core 同步的项目开发技能。
tests/	与 src/ 结构对应的单元和集成测试。

开发指南

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

• 处理程序抛出异常，由框架捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求作用域日志，使用 ctx.state 存储租户作用域数据
• 通过 src/mcp-server/*/definitions/index.ts 中的汇总导出文件注册新工具和资源
• 原样呈现上游数据：缺失字段报告为 null，绝不伪造缺失值

致谢

机场、跑道、导航设备和频率数据来自 OurAirports，并奉献至公有领域。注明来源是出于礼貌，并非强制要求。源 CSV 文件每日发布于 davidmegginson.github.io/ourairports-data。

OurAirports 由社区编辑；数据将原样呈现，不具权威性，不适用于实际飞行操作——请像对待任何众包参考资料一样使用这些数据。

贡献

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

bun run devcheck
bun run test

许可证

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