ourairports-mcp-server

Servidor público alojado: https://ourairports.caseyjhand.com/mcp

Descripción general

ourairports-mcp-server es la capa de referencia estática de aviación para resolver identificadores de aeropuertos y anclar coordenadas. Responde a qué existe — el catálogo de aeropuertos, sus códigos, pistas, ayudas a la navegación y frecuencias de radio — para complementar los servicios de aviación en vivo que responden a qué está ocurriendo (clima, posiciones).

El conjunto de datos completo de OurAirports está dedicado al dominio público y se publica como archivos CSV planos. Esos seis archivos CSV — aeropuertos, pistas, ayudas a la navegación, frecuencias de aeropuerto, países y regiones (~178k filas, ~20 MB) — están incluidos en el paquete e integrados en la imagen de Docker en el momento de la compilación. Al iniciarse, el servidor los analiza e indexa en memoria; cada herramienta es entonces una consulta local. El resultado no tiene clave de API, ni límite de tasa, ni dependencia ascendente de la que heredar una caída.

Cómo encaja el modelo de funcionamiento:

• Resolución de códigos en cinco espacios de identificadores. Los aeropuertos tienen IATA, ICAO, GPS, local y el ident de OurAirports. Un único parámetro code se resuelve contra un índice unificado (prioridad: ident → ICAO → IATA → GPS → local), y la respuesta devuelve el conjunto completo de códigos para que un código nacional ambiguo se autocorrija. Un código ausente (sin IATA para un campo pequeño) se notifica como null, nunca como un 404.

• Vecino más cercano por distancia de círculo máximo. Las búsquedas por coordenadas ejecutan un escaneo haversine sobre un Float64Array plano con la posición de cada aeropuerto (o ayuda a la navegación) y devuelven los resultados más cercanos ordenados por distancia, cada uno con su rumbo — submilisegundo a esta escala, sin necesidad de índice espacial.

• Dispersión honesta. Los campos ascendentes ausentes (sin elevación, dimensiones de pista nulas) aparecen como desconocidos. Las listas de resultados limitadas revelan la truncación.

OurAirports se edita por la comunidad. Los datos se muestran tal cual y no son autoritativos para operaciones de vuelo reales — trátalos

• Conjunto de datos de dominio público integrado en el paquete y en la imagen Docker — sin API en tiempo de ejecución, sin clave, sin límite de peticiones, sin caídas del upstream

• Índices en memoria construidos una sola vez al arrancar: mapas de id, un índice de códigos unificado ordenado por prioridad, uniones por referencia de aeropuerto para pistas y frecuencias, una unión de navaids con clave ident, un Float64Array plano de coordenadas, mapas de país/región y un índice de búsqueda de texto tokenizado

• Búsqueda del vecino más cercano por fuerza bruta mediante haversine sobre el array de coordenadas — submilisegundo en 85k aeropuertos, sin dependencia de índice espacial

• Los CSV se parsean por nombre de encabezado, no por posición de columna, de modo que una reordenación de columnas del upstream no puede desalinear campos silenciosamente

Salida pensada para agentes:

• Escasez honesta — los campos ausentes del upstream (sin IATA, sin elevación, dimensiones de pista nulas) aparecen como null, nunca se inventan

• Resolución autocorrectiva — cada registro de aeropuerto refleja su conjunto completo de códigos y un resolvedVia / resolutionNote, con una advertencia de ambigüedad para códigos nacionales compartidos

• Información sobre truncamiento y resultados vacíos — recuentos totales, límites aplicados y orientación de recuperación para que los llamadores puedan ampliar, reducir o volver a consultar sin tener que interpretar prosa

Related MCP server: mcp-metar

Primeros pasos

Instancia pública alojada

Hay una instancia pública disponible en https://ourairports.caseyjhand.com/mcp — no requiere instalación. Apunta cualquier cliente MCP a ella mediante Streamable HTTP, con esta configuración de cliente:

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

Local / autohospedado

Añade lo siguiente al archivo de configuración de tu cliente MCP.

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

O con npx (no se requiere 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"
      }
    }
  }
}

O con 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"
      ]
    }
  }
}

No se requiere ninguna clave de API — el conjunto de datos se incluye con el paquete y la imagen.

Para Streamable HTTP, configura el transporte e inicia el servidor:

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

Requisitos previos

• Bun v1.3.0 o superior (o Node.js v24+).

• No se requiere clave de API, cuenta ni servicio externo — todos los datos están incluidos.

Instalación

1. Clona el repositorio:

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

2. Accede al directorio:

cd ourairports-mcp-server

3. Instala las dependencias:

bun install

4. Descarga y empaqueta el conjunto de datos (escribe los seis CSV en data/):

bun run build:data

Actualización de los datos

La instantánea incluida está tan actualizada como la última ejecución de build:data (o, para la imagen Docker, la última compilación). Para obtener la última descarga diaria del espejo de OurAirports, vuelve a ejecutar bun run build:data y reconstruye. Para apuntar a una descarga de datos local existente sin reconstruir, define OURAIRPORTS_DATA_DIR.

Configuración

Consulta .env.example para ver la lista completa de sobrescrituras opcionales.

Ejecutar el servidor

Desarrollo local

• Compila y ejecuta:

# 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

• Ejecuta las comprobaciones y pruebas:

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

La etapa de compilación ejecuta bun run build:data para que el conjunto de datos se descargue e integre en la imagen — el contenedor resultante es totalmente autónomo y no realiza ninguna llamada de red en tiempo de ejecución. El Dockerfile usa por defecto transporte HTTP, modo de sesión stateless y registra en /var/log/ourairports-mcp-server. Las dependencias pares de OpenTelemetry se instalan por defecto — compila con --build-arg OTEL_ENABLED=false para omitirlas.

Estructura del proyecto

Guía de desarrollo

Consulta CLAUDE.md/AGENTS.md para conocer las pautas de desarrollo y las reglas arquitectónicas. La versión resumida:

• Los manejadores lanzan excepciones, el framework las captura — no hay try/catch en la lógica de las herramientas

• Usa ctx.log para el registro con ámbito de petición y ctx.state para el almacenamiento con ámbito de inquilino

• Registra nuevas herramientas y recursos mediante los barrels en src/mcp-server/*/definitions/index.ts

• Expón los datos del upstream tal cual: informa de los campos ausentes como null, nunca inventes valores faltantes

Atribución

Los datos de aeropuertos, pistas, navaids y frecuencias provienen de OurAirports, dedicados al dominio público. La atribución es un gesto de cortesía, no un requisito. Los CSV de origen se publican diariamente en davidmegginson.github.io/ourairports-data.

Contribuciones

Las issues y las pull requests son bienvenidas. Ejecuta las comprobaciones y pruebas antes de enviarlas:

bun run devcheck
bun run test

Licencia

Apache-2.0 — consulta LICENSE para más detalles.