✈️ Flight MCP Server — SQLite Demo

완전한 기능을 갖춘 Model Context Protocol (MCP) 데모 서버로, 시레이션된 항공편 검색 및 예약 기능을 제공합니다.

[!WARNING] 시레이션 전용: 이 시스템의 모든 항공편, 재고, 예약은 가상/샘플 데이터를 사용하는 순수 시레이션입니다. 이 프로젝트는 실제 항 част공사 API와 연동하지 않으며, 실제 항공편을 예약하지 않습니다.

이 프로젝트는 무엇인가요?

이 프로젝트는 Model Context Protocol (MCP)의 기초를 익히기 위해 설계된 간결하고 모듈라인 Python 애플리케이션입니다. 로컬 백엔드 서버로 동작하여 Claude Desktop에 원활하게 연결되며, AI가 로컬 SQLite 데이터베이스에 안전하고 제어된 접근을 통해 데모 항공편을 탐색하고 예약할 수 있게 합니다.

Related MCP server: SQLite MCP Server

MCP란 무엇인가요?

**Model Context Protocol (MCP)**는 AI 모델(예: Claude)이 로컬 또는 원격 데이터 소스, 도구, 서비스에 안전하게 연결할 수 있게 하는 오린 표준입니다. MCP는 LLM?지 데터를 추측하거나 환각하는 대신, 결정론적인 백엔드 시스템을 조의할 수 있게 합니다.

Architecture

아키텍처

시스템 아키텍처는 깔끄하고 계층화된 접근법을 따ȅ니다:

Claude Desktop (Client)
        ↓ (stdio JSON-RPC)
Python Flight MCP Server
        ↓
Services Layer (Business Logic)
        ↓
SQLite Database (Data Store)

기술 스택

• Language: Python 3.11+

• 패키지 관리자: uv

• 프레임워크: MCP 공식 Python SDK (mcp)

• 데이터베이스: SQLite (로컬 파일)

• 클라이언트: Claude Desktop

6가지 Available tools

서버는 AI에게 정확히 여섯 가지 안정한 MCP 도구를 노출합니다:

• search_flights: 출발지, 목적지, 날짜로 이용 가능한 항공편을 검색합니다.

• get_flight: 특정 항공편의 전체 정보와 메타데이터를 조회합니다.

• check_seats: 항공편의 실시간 좌석 가능 여부를 조회합니다.

• book_flight: 새 시레이션 예약을 생성합니다(사용자 확정이 필요).

• get_booking: PNR `참조로 기존 예약 정보를 조회합니다.

• cancel_book: 예약 예약을 취소하고 좌석 매대를 회복합니다.

SQLite DB Demo

시스템은 로컬 SQLite 데이더베이스 (조지/data/flightmcp.db)을 사용하여 항공편 재고와 예약 상태를 저장합니다.

참고: 실제 .db 파일은 버전 관리에서 제외되어, 나중에 발생할 "stale state" 이슈를 방지합니다.

데이터베이스를 데모 데이터로 초기화하려면:

uv run python scripts/seed_database.py

설치 및 설정

q가 설치되어 있는지 확인하고, 의존성을 동기화하려면:

uv sync

테스트 실행

프로젝트를 포함한 강력한 pytest로 하여 백엔드를 검증합니다.

uv run pytest

Running MCP Server

서버가 정확하게 실행되는지 수동으로 확정하려면(서버는 차단되고 stdio 신호를 대비):

uv run flight-mcp

(애플리케이션 로고는 stdout의 MCP 프로토콜 출력이 깨끄하게 할 수 있도록 반드시 stderr로 라우팅됩니다.)

Configuration of Claude

이 MCP 서버를 Claude Desktop에 연결하려면, Claude Desktop 구성 파일(macOS에서 일반 ~/Library/Application Support/Claude/claude_desktop_config.json 위치)을 수명해야 합니다.

프로젝트 "Claude Desktop" 설정 예시:

{
  "mcpServers": {
    "flight-mcp": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "run",
        "--directory",
        "/Users/baratharjun/Desktop/medai",
        "flight-mcp"
      ],
      "cwd": "/Users/baratharjun/Desktop/medai"
    }
  }
}

참고: 절대 경로를 로컬 프로젝트 디렉토리와 uv 설치 경로에 맞게 조정하세요.

시용 예시

Claude Desktop에 연결되어 있으면 자연 중:

사용자: "2026-09-05에 Chennai에서 델리가는 항공편을 찾아 주세요." Claude가 search_flights를 호출하고 SQLite 데이터베이스에서 영는 합니다.

사용자: "1번 항공편에 남은 좌성이 다음 몇 개인가요?" Claude가 check_seats를 호출합니다.

사용자: "1번 항공편 예약하고 시프다. 제 이름은 Test User, 이메일 test@example.com, 전화번호 9999999999입니다." Claude는 요청을 요약하며 명확하게 자인을 요청합니다.

사용자: "확인했습니다." Claude가 book_flight를 호출하고, 가상[가상]의 booking "예: FLM-XXXXXX" 를 반환합니다.