ourairports-mcp-server

公共托管服务器： https://ourairports.caseyjhand.com/mcp

概述

ourairports-mcp-server 是用于解析机场标识符和定位坐标的静态航空参考层。它回答存在什么——机场目录及其代码、跑道、导航台和无线电频率——以补充回答正在发生什么（天气、位置）的实时航空服务。

整个 OurAirports 数据集专属于公共领域，并以平面 CSV 形式发布。这六个 CSV 文件——airports、runways、navaids、airport frequencies、countries 和 regions（~178k 行，~20 MB）——被打包进软件包，并在构建时内置进 Docker 镜像。启动时，服务器将它们解析为内存索引；每个工具随后都是本地查询。结果无需 API 密钥、没有速率限制，也没有会继承故障的上游依赖。

工作模型的组合方式如下：

• 跨五个标识符空间的代码解析。 机场带有 IATA、ICAO、GPS、local 以及 OurAirports 的 ident。单个 code 参数会针对统一索引进行解析（优先级：ident → ICAO → IATA → GPS → local），响应会回显完整的代码集，因此有歧义的国家代码可以自我纠正。缺失的代码（小型机场没有 IATA）会报告为 null，绝不会是 404。

• 按大圆距离查找最近邻。 坐标查询会对所有机场（或导航台）位置的扁平 Float64Array 执行 haversine 扫描，并按距离排序返回最近的结果，每个结果都带有方位角——在此规模下为亚毫秒级，无需空间索引。

• 如实呈现稀疏数据。 上游缺失的字段（无海拔、跑道尺寸为 null）会以 unknown 形式呈现。设有上限的结果列表会披露截断情况。

OurAirports 由社区编辑。数据按原样呈现，对真实飞行运行不具权威性——请像对待任何众包参考资料一样对待它。

Related MCP server: mcp-metar

工具

六个只读工具，全部是对捆绑索引的本地查询——代码解析与详情、机场和跑道搜索、坐标定位、导航台，以及国家/地区查找表：

ourairports_search_airports

常用入口——按自由文本、分面或两者组合进行搜索。

• 对名称、城市和关键词进行自由文本搜索；词元按 AND 匹配（支持词序和部分单词）

• 分面过滤器：country（ISO 3166-1 alpha-2）、region（ISO 3166-2）和 type——country/region 为精确匹配、不区分大小写，并忽略周围空白

• 默认排除已关闭机场；可通过 include_closed 选择包含

• 结果按运营中/较大机场优先排序，每条结果都带有完整代码集和坐标，便于链式调用 ourairports_get_airport

• 截断披露——匹配总数、应用的条数上限，以及放宽或收窄搜索的建议

ourairports_search_runways

跨机场跑道搜索——与 ourairports_get_airport 相对应，后者列出某个已知机场的跑道。

• 机场分面（country、region、type）先缩小机场范围；跑道分面（surface、min_length_ft、min_width_ft、lighted）再过滤其跑道

• surface 是对上游原始道面字符串的不区分大小写子串匹配（无受控词表——像 asp 这样的较短片段可匹配 ASP、ASPH 和 Asphalt），而非精确代码

• 每条匹配跑道返回一行扁平的 { airport, runway } 记录——有三条匹配跑道的机场会贡献三行

• 当设置了对应的 min_*_ft 过滤器时，长度或宽度未知的跑道会被排除——绝不会假定其满足数据无法确认的阈值

• 已关闭机场和已关闭跑道都会被排除，除非设置了 include_closed_airports / include_closed_runways

• 截断披露——匹配总数、应用的条数上限，以及放宽或收窄搜索的建议

ourairports_get_airport

详情工具——一次调用即可返回常见场景所需的一切。

• 在全部五个标识符空间中不区分大小写地解析单个 code（优先级：ident → ICAO → IATA → GPS → local）；忽略周围空白

• 内联包含跑道和无线电频率；include 可将响应裁剪为子集，输出中的 included 字段用于区分因 include 而被省略的关系与确实没有记录的关系

• 回显机场的完整代码集以及 resolvedVia / resolutionNote，并对共享的国家代码给出歧义警告，使错误的解析结果可以自我纠正

• 缺失的代码报告为 null；已关闭机场始终可以解析

• 当没有任何标识符空间匹配时，返回带恢复提示的 unknown_code 错误

ourairports_find_airports

定位工具——将纬度/经度转换为最近的机场。

• 按大圆（haversine）距离排序，从近到远，每条结果都带有相对于查询点的 distanceKm 和 bearingDeg（真方位角，单位为度）

• radius_km（1–500，默认 100）、可选的 type 过滤器、可选择包含的 include_closed

• 输入坐标，输出排序后的机场——不进行地理编码；请先在上游将地名解析为纬度/经度

• 空结果时给出建议，提示使用更大的 radius_km

ourairports_find_navaids

两种方式查找导航台——按空间位置或按机场。

• 坐标模式： latitude + longitude（+ 可选的 radius_km）按距离从近到远对导航台排序，并附带距离和方位角

• 机场模式： airport_code 返回服务于该机场的导航台

• 必须且只能选择一种模式——同时提供或都不提供都会产生验证错误

• 频率同时以 kHz（存储值——114.5 MHz 的 VOR 显示为 frequencyKhz 114500）和 MHz 呈现

• 机场模式区分"未找到机场"（unknown_code 错误）与"找到机场但没有关联导航台"（带说明的空列表）

资源和提示词

airport://{code} 资源是 ourairports_get_airport 的稳定 URI 孪生体，供注入资源上下文的客户端使用。所有数据仅通过工具即可获取——仅使用工具的客户端不会损失任何功能。语料库不会作为资源列表暴露（枚举 85k 个机场是转储，而非发现辅助手段）；发现功能由 ourairports_search_airports 提供。

特性

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

• 声明式工具和资源定义——每个原语一个文件，框架负责注册和验证

• 统一错误处理——处理器抛出异常，框架负责捕获、分类和格式化

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

• 可替换的存储后端：in-memory、filesystem、Supabase、Cloudflare KV/R2/D1

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

• 同一代码库可本地运行（stdio/HTTP）或部署到 Cloudflare Workers

OurAirports 特有：

• 内置的公有领域数据集，已打包进软件包和 Docker 镜像中——零运行时 API、无需密钥、无速率限制、无上游故障

• 启动时一次性构建的内存索引：id 映射、按优先级排序的统一代码索引、跑道和频率的机场引用连接、以 ident 为键的导航台连接、扁平的 Float64Array 坐标数组、国家/地区映射，以及分词文本搜索索引

• 对坐标数组进行暴力 haversine 最近邻搜索——在 8.5 万个机场中达到亚毫秒级，无空间索引依赖

• CSV 按表头名称而非列位置解析，因此上游列顺序调整不会静默导致字段错位

对 Agent 友好的输出：

• 诚实的稀疏性——上游缺失的字段（无 IATA、无海拔、跑道尺寸为 null）以 null 呈现，绝不伪造

• 自纠错解析——每条机场记录都会回显完整的代码集以及 resolvedVia / resolutionNote，并对共享的国家代码给出歧义警告

• 截断与空结果披露——包括总数、已应用的上限和恢复指引，调用方无需解析文字即可扩大、缩小范围或重新查询

快速开始

公共托管实例

公共实例位于 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.3.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 并重新构建。若要在不重新构建的情况下指向现有的本地数据包，请设置 OURAIRPORTS_DATA_DIR。

配置

完整的可选覆盖项列表请参阅 .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 -e MCP_TRANSPORT_TYPE=stdio ourairports-mcp-server

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

项目结构

开发指南

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

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

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

• 通过 src/mcp-server/*/definitions/index.ts 中的 barrel 文件注册新工具和资源

• 按原样呈现上游数据：缺失字段报告为 null，绝不伪造缺失值

致谢

机场、跑道、导航台和频率数据来自 OurAirports，已奉献给公有领域。署名是出于礼貌，并非强制要求。源 CSV 每日发布在 davidmegginson.github.io/ourairports-data。

贡献

欢迎提交 issue 和 pull request。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

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