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가 없는 경우)는 404가 아니라 null로 보고됩니다.

• 대권 거리 기준 최근접 이웃. 좌표 조회는 모든 공항(또는 무선 항행 시설) 위치의 평면 Float64Array에 대해 하버사인 스캔을 실행하고 거리순으로 정렬된 최근접 결과를 각각의 방위각과 함께 반환합니다 — 이 규모에서 서브 밀리초이며 공간 인덱스가 필요 없습니다.

• 정직한 희소성. 상위 데이터에 없는 필드(고도 없음, 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

기준점 도구 — 위도/경도를 가장 가까운 공항으로 변환합니다.

• 대권(하버사인) 순위, 가까운 순서 우선, 각 결과는 쿼리 지점으로부터의 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 맵, 우선순위 순서의 통합 코드 인덱스, 활주로 및 주파수용 airport-ref 조인, ident 키 기반 navaid 조인, 좌표의 1차원 Float64Array, 국가/지역 맵, 토큰화된 텍스트 검색 인덱스

• 좌표 배열에 대한 브루트포스 haversine 최근접 이웃 — 85,000개 공항에서 1밀리초 미만, 공간 인덱스 의존성 없음

• CSV는 열 위치가 아닌 헤더 이름으로 파싱되므로, 업스트림에서 열 순서가 바뀌어도 필드가 조용히 어긋나지 않음

에이전트 친화적 출력:

• 정직한 희소성 — 업스트림에 없는 필드(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의 배럴을 통해 등록

• 업스트림 데이터를 있는 그대로 노출: 누락된 필드는 null로 보고하고, 누락된 값을 임의로 만들지 않음

출처 표기

공항, 활주로, navaid 및 주파수 데이터는 OurAirports에서 제공하며 퍼블릭 도메인으로 기증되었습니다. 출처 표기는 의무가 아닌 예의입니다. 소스 CSV는 davidmegginson.github.io/ourairports-data에서 매일 게시됩니다.

기여

이슈와 풀 리퀘스트를 환영합니다. 제출 전에 검사와 테스트를 실행하세요:

bun run devcheck
bun run test

라이선스

Apache-2.0 — 자세한 내용은 LICENSE를 참조하세요.