TravelAgentMCP 🌍✈️

TVA OTA 플랫폼을 위한 MCP(Model Context Protocol) 서버의 모노레포: 항공편 및 호텔 검색 및 예약, 비자 및 이민 요건 및 예약 추적, 사용자 계정 관리 — AI 여행 에이전트를 위해 구축되었습니다.

아키텍처

TravelAgentMCP/
├── mcps/
│   ├── shared/            @travelagent-mcp/shared — HTTP client, config, guardrails, tool helper (not a server)
│   ├── flight-mcp/        tva-flight-mcp   — search, pricing, seatmaps, booking lifecycle
│   ├── hotel-mcp/         tva-hotel-mcp    — search, availability, booking lifecycle
│   ├── visa-mcp/          tva-visa-mcp     — country requirements + booking tracking
│   ├── immigration-mcp/   tva-immigration-mcp — service info + booking tracking
│   └── account-mcp/       tva-account-mcp  — auth, profile, promo codes, notifications
└── src/index.ts           travelagent-mcp  — gateway that mounts all five servers' tools in one process

각 mcps/* 패키지는 자체 bin을 가진 독립적으로 실행 가능한 stdio MCP 서버입니다. 필요한 서버만 실행하거나(예: 예약 위젯의 경우 tva-flight-mcp + tva-hotel-mcp만, 또는 조언 봇의 경우 tva-visa-mcp + tva-immigration-mcp만), 또는 루트 게이트웨이 (travelagent-mcp)를 실행하여 모든 것을 하나의 프로세스로 가져올 수 있습니다. 이것이 게시된 npm 패키지가 항상 그래왔던 것이며, 이전 버전과의 호환성을 위해 유지됩니다.

하나의 업스트림 API, 두 가지 인증 모드:

• TVA OTA 백엔드 (TVA_BASE_URL) — 항공편, 호텔, 예약, 계정, 그리고 비자/이민 예약 추적의 "클라이언트" 측(업데이트, 알림, 트랜잭션). 대부분의 예약 관리 엔드포인트는 bearer 토큰이 필요합니다. 게스트 체크아웃 흐름(예약, UUID로 취소, 확인, 티켓 재전송)은 필요하지 않습니다.

• 비자/이민 콘텐츠 (동일한 TVA_BASE_URL, bearer 토큰 대신 CONTENT_API_KEY로 인증) — 국가 요구 사항, 비자 유형, 수수료 및 FAQ로, GET_VISA_INFO_BY_COUNTRY / GET_IMMIGRATION_INFO_BY_COUNTRY에서만 사용됩니다.

Related MCP server: orizn-visa-mcp

보호 장치

• 최소 권한: 사용자 대상 엔드포인트만 노출됩니다. 관리자/운영 엔드포인트(예약 관리, 환불, 수익 통계)는 의도적으로 도구로 래핑되지 않았습니다 — 대화형 에이전트에 적합하지 않습니다.

• 명시적 확인: 비용이 발생하거나 되돌릴 수 없는 모든 도구(BOOK_FLIGHT, BOOK_HOTEL, CANCEL_FLIGHT_BOOKING, CANCEL_HOTEL_BOOKING, CONFIRM_FLIGHT_PAYMENT, CONFIRM_HOTEL_PAYMENT, SELECT_FLIGHT_SEAT, CHANGE_PASSWORD, CLOSE_ACCOUNT)는 confirm: true가 필요하며, 호출 에이전트는 사용자에게 특정 세부 정보를 다시 읽어준 후에만 이 값을 설정해야 합니다.

• LLM 컨텍스트에 비밀 정보 없음: TVA_ACCESS_TOKEN은 절대 도구 매개변수가 아닙니다. 프로세스 환경에서 읽히며, 이러한 서버를 생성하는 에이전트가 사용자 세션별로 주입합니다. LOGIN_USER / SOCIAL_AUTH_LOGIN은 토큰을 생성 에이전트가 가로채서 대역 외에 저장할 수 있는 __session 래퍼에 담아 반환합니다. 모델은 일반 확인 메시지만 볼 수 있습니다. 계약에 대해서는 mcps/account-mcp/src/lib/session.ts를 참조하십시오.

• 원시 제공 정보 재생 없음: Amadeus 항공편 제공 정보는 크고 불투명한 JSON 블롭입니다. SEARCH_FLIGHTS는 각 제공 정보를 서버 측(SQLite, mcps/flight-mcp/src/lib/offerCache.ts 참조)에 캐시하고 대신 모델에 짧은 offerRef를 전달합니다. 모델은 제공 정보 JSON을 수동으로 재구성하지 않으며, 이는 토큰 블로트나 가격/요금 무음 손상을 초래할 수 있습니다.

• 편집: 비밀번호, 토큰, OTP 및 카드 번호는 로깅 전에 마스킹됩니다(mcps/shared/src/guardrails.ts 참조).

• 알려진 위험 — 호텔 결제: BOOK_HOTEL은 현재 원시 카드 세부 정보를 직접 받습니다(TVA 호텔 API에는 아직 토큰화된 체크아웃 단계가 없습니다). 이는 보안 및 PCI 규격을 갖춘 표면을 통해 카드 세부 정보를 수집한 클라이언트에서만 호출해야 하며, 사용자에게 채팅에 카드 번호를 입력하도록 프롬프트를 표시해서는 안 됩니다. 자세한 내용은 도구 설명을 참조하십시오.

• 속도 제한: 각 도구 호출은 프로세스별로 제한됩니다(폭주 함수 호출 루프에 대한 방어). 이는 지속적인 교차 턴 속도 제한을 대체하지 않습니다. 실제 보호가 필요한 경우 세션 계층에서 지속적으로 남용을 추적하십시오.

설정

pnpm install
cp .env.example .env   # fill in TVA_BASE_URL and content-API keys
pnpm build              # builds mcps/shared first, then every domain server, then the gateway

게이트웨이 실행(모든 도구를 하나의 프로세스로):

pnpm start

또는 단일 도메인 서버를 직접 실행:

node mcps/flight-mcp/dist/index.js

도구 참조

항공편 (tva-flight-mcp)

SEARCH_FLIGHTS, GET_POPULAR_FLIGHT_ROUTES, GET_FLIGHT_PRICE_ANALYSIS, GET_MOST_TRAVELED_DESTINATIONS, GET_MOST_BOOKED_DESTINATIONS, GET_BUSIEST_TRAVEL_PERIOD, GET_FLIGHT_SEATMAP_BY_OFFER, GET_FLIGHT_SEATMAP_BY_ORDER, GET_FLIGHT_FARE_UPSELL, PREDICT_FLIGHT_CHOICE, CONFIRM_FLIGHT_PRICE, BOOK_FLIGHT, LIST_MY_FLIGHT_BOOKINGS, GET_FLIGHT_BOOKING, VERIFY_FLIGHT_BOOKING, CANCEL_FLIGHT_BOOKING, GET_FLIGHT_SEAT_PRICE, SELECT_FLIGHT_SEAT, RESEND_FLIGHT_TICKET, GET_FLIGHT_TICKET_DOWNLOAD_LINK, CONFIRM_FLIGHT_PAYMENT

호텔 (tva-hotel-mcp)

SEARCH_HOTELS, SEARCH_HOTEL_CITIES, CHECK_HOTEL_AVAILABILITY, BOOK_HOTEL, LIST_MY_HOTEL_BOOKINGS, GET_HOTEL_BOOKING, CONFIRM_HOTEL_PAYMENT, CANCEL_HOTEL_BOOKING

비자 (tva-visa-mcp)

GET_VISA_INFO_BY_COUNTRY, LIST_MY_VISA_BOOKINGS, GET_VISA_BOOKING, GET_VISA_BOOKING_BY_APPLICATION_UUID, GET_VISA_UPDATES, GET_VISA_UPDATES_BY_BOOKING, GET_VISA_FOLLOWUP_QUESTIONS, ANSWER_VISA_FOLLOWUP, GET_VISA_NOTIFICATIONS, MARK_VISA_NOTIFICATION_READ, GET_VISA_TRANSACTIONS, GET_VISA_TRANSACTION_DETAIL

이민 (tva-immigration-mcp)

GET_IMMIGRATION_INFO_BY_COUNTRY, LIST_MY_IMMIGRATION_BOOKINGS, GET_IMMIGRATION_BOOKING, GET_IMMIGRATION_UPDATES, GET_IMMIGRATION_UPDATES_BY_BOOKING, GET_IMMIGRATION_NOTIFICATIONS, MARK_IMMIGRATION_NOTIFICATION_READ, GET_IMMIGRATION_TRANSACTIONS, GET_IMMIGRATION_TRANSACTION_DETAIL

계정 (tva-account-mcp)

REGISTER_USER, LOGIN_USER, SOCIAL_AUTH_LOGIN, FORGOT_PASSWORD, RESEND_OTP, VERIFY_OTP, LOGOUT_USER, GET_CURRENT_USER, GET_USER_PROFILE, EDIT_USER_PROFILE, CHANGE_PASSWORD, CHECK_DISCOUNT_PROMO, GET_USER_NOTIFICATIONS, CLOSE_ACCOUNT

사용처

MegaMind의 NomadSage 여행 에이전트는 이러한 서버(stdio를 통해, 도메인당 하나씩)를 지식 베이스 검색 및 social-mcp 답변 도구와 함께 생성합니다. 해당 저장소의 travel-agent/src/lib/tva-client.ts 및 travel-agent/src/lib/tva-session.ts를 참조하십시오.