flexible-hotels-mCP-server

AI(Claude 또는 기타 MCP 클라이언트)가 고정된 체크인/체크아웃 날짜 대신 유연한 날짜 범위 내의 숙박 일수 기준으로 호텔 객실을 검색할 수 있게 해주는 MCP(Model Context Protocol) 서버입니다.

예: "텔아비브에서 3박, 9월 1일에서 9월 20일 사이 아무 때나" — 서버는 범위 내 모든 가능한 체크인 날짜를 스캔하고, 각 날짜의 실제 가격을 가져와 가격순으로 정렬된 가장 저렴한 거래를 반환합니다.

제휴(Affiliate) 모델: 이 도구는 가격 비교 도구일 뿐입니다 — 결제 정보를 수집하지 않으며 예약을 수행하지 않습니다. 각 결과에는 사용자가 직접 구매를 완료할 수 있는 소스(현재는 Booking.com)로 연결되는 링크(bookingUrl)가 포함되어 있습니다.

데이터 소스: Amadeus for Developers — 관광 분야 최고의 무료 API로, 완전히 무료이며 신용카드가 필요 없는 테스트(test) 환경을 제공합니다.

구성 요소

AI에 노출되는 4가지 도구(tools):

"유연한 검색" 로직은 src/services/hotelSearch.ts에 구현되어 있습니다: Amadeus(및 기타 모든 공급업체)는 호출당 고정된 날짜 범위 하나만 지원하므로, 서버가 정의된 창(window) 내의 모든 가능한 체크인 날짜를 직접 스캔하고 그에 따라 API를 호출한 후 결과를 집계합니다. 각 결과에 대한 링크는 src/services/affiliateLink.ts에서 생성됩니다.

Related MCP server: AigoHotel MCP Server

설치

1. 무료 API 키 받기 (2분, 신용카드 불필요):

1. https://developers.amadeus.com/register에서 가입

2. 인증 후 My Self-Service Workspace에서 "New App" 생성

3. API Key와 API Secret을 받게 됩니다 — 이것이 AMADEUS_CLIENT_ID 및 AMADEUS_CLIENT_SECRET입니다

이것은 test(샌드박스) 환경입니다 — 완전히 무료이며, 넉넉한 월별 할당량과 초당 약 10회의 요청 속도 제한이 있습니다. 전 세계 수십만 개 호텔의 실제 데이터(때로는 부분적/캐시된 데이터)를 포함합니다. 향후 완전한 실시간 데이터로 전환하려면 Amadeus에 production 액세스를 요청(유료)하고 AMADEUS_ENV=production으로 변경하면 됩니다.

2. 로컬 설치:

npm install
cp .env.example .env
# ערכו את .env והכניסו את המפתחות שקיבלתם
npm run build

3. 모든 것이 작동하는지 확인 (할당량 소진 없이 — Amadeus에 실제 요청을 보내지 않음):

npm test

실행

npm start

기본적으로 서버는 stdio를 통해 실행됩니다(Claude Desktop과 같은 클라이언트에 로컬 연결에 적합). HTTP를 통한 원격 서버로 실행하려면(Claude.ai / Cowork에서 "custom connector"로 연결하거나 다른 원격 MCP 클라이언트에서 연결):

TRANSPORT=http PORT=3000 npm start

AI "플러그인"으로 연결

Claude Desktop (로컬)

claude_desktop_config.json 설정 파일에 추가:

{
  "mcpServers": {
    "flexible-hotels": {
      "command": "node",
      "args": ["/נתיב-מלא/ל/flexible-hotels-mcp-server/dist/index.js"],
      "env": {
        "AMADEUS_CLIENT_ID": "המפתח-שלכם",
        "AMADEUS_CLIENT_SECRET": "הסוד-שלכם"
      }
    }
  }
}

Claude Desktop을 재시작하면 AI가 대화에서 이러한 도구를 직접 호출할 수 있습니다.

원격 연결 (Claude.ai / Cowork / 기타 클라이언트)

제품을 여러 사용자가 각자 로컬에서 코드를 실행하지 않고 "플러그인"으로 사용할 수 있게 하려면, 서버를 TRANSPORT=http 모드로 서버/호스트에 배포(deploy)한 다음 https://your-domain/mcp 주소를 클라이언트 설정에서 custom MCP connector로 연결합니다.

Railway (이미 계정 + CLI가 설치된 경우 권장):

cd flexible-hotels-mcp-server
railway login          # רק אם עוד לא מחוברים — פותח דפדפן לאישור
railway up --new -y --detach --json   # יוצר פרויקט חדש, מעלה את הקוד ומפעיל build מה-Dockerfile
railway variable set AMADEUS_CLIENT_ID=המפתח-שלכם --skip-deploys
railway variable set AMADEUS_CLIENT_SECRET=הסוד-שלכם --skip-deploys
railway variable set AMADEUS_ENV=test
railway domain          # מפיק כתובת ציבורית כמו https://xxx.up.railway.app

서버는 Amadeus 키를 설정하기 전에도 시작됩니다(그리고 health check를 통과합니다) — 검색 도구는 실제 키가 설정되고 자동 재배포가 이루어질 때까지 명확한 오류를 반환할 뿐입니다.

Render: 프로젝트 루트의 render.yaml 파일이 Blueprint로 준비되어 있습니다 — repo를 Render에 연결하고, "New" -> "Blueprint"를 선택한 후 인터페이스에서 AMADEUS_CLIENT_ID/AMADEUS_CLIENT_SECRET을 입력합니다(파일 내 주석 참조).

모든 옵션에서 주의: AMADEUS_CLIENT_ID/AMADEUS_CLIENT_SECRET은 호스팅 서버에 정의된 환경 변수여야 하며, 코드에 절대 하드코딩하지 마세요.

사용 예시 (AI가 "보는" 것)

User: תמצא לי 3 לילות בתל אביב, איפשהו בין ה-1 ל-20 בספטמבר, לזוג.

AI calls: flexible_hotels_resolve_city_code(keyword="Tel Aviv")
  -> TLV

AI calls: flexible_hotels_search_flexible_offers(
  city_code="TLV", nights=3,
  earliest_check_in="2026-09-01", latest_check_in="2026-09-20",
  adults=2
)
  -> רשימת עסקאות ממוינת מהזולה ביותר, עם תאריך צ'ק-אין/אאוט מדויק וקישור הזמנה לכל אחת

User: מעולה, תראה לי את הפרטים המלאים של האופציה הכי זולה.

AI calls: flexible_hotels_get_offer_details(offer_id="...")
  -> מחיר מעודכן + קישור לחיצה שמעביר את המשתמש להשלים את ההזמנה באתר המקורי

비즈니스 모델: 제휴(Affiliate)

이 서버는 예약을 수행하지 않으며 어떤 단계에서도 결제 정보를 다루지 않습니다 — 이는 의도적인 설계로, 단순성/안전성 때문이기도 하고 "external checkout"을 요구하고 도구 자체를 통한 신용카드 번호 수집을 금지하는 앱 스토어(예: ChatGPT App Directory)의 방식이기도 합니다.

실제 작동 방식:

1. 서버는 Amadeus(무료)를 통해 실제 가격을 찾습니다.

2. 각 결과에 대해 호텔 이름과 날짜가 미리 채워진 Booking.com 검색 페이지 링크가 생성됩니다(src/services/affiliateLink.ts).

3. Booking.com Affiliate Partner Program(무료, 자체 가입, 특별 승인 불필요)에 등록하고 aid를 받으면, 이를 환경 변수 BOOKING_AFFILIATE_ID로 설정할 수 있습니다 — 그러면 모든 링크에 파트너 ID가 포함되어 링크를 통한 예약에 대해 커미션을 받을 수 있습니다.

4. BOOKING_AFFILIATE_ID가 없어도 링크는 완전히 작동합니다 — 단지 보상이 없을 뿐입니다.

이것이 바로 요청하신 "그냥 등록만 하면 되는" 것입니다: Booking.com 파트너 프로그램에 일회성 등록(Amadeus나 Railway가 아닌)만 하면 링크가 수익을 창출하기 시작합니다.

알려진 제한 사항

• 무료 할당량: Amadeus test 환경은 월별 할당량과 요청 속도(~10/초)가 제한됩니다. N일 창에 대한 유연한 검색은 최대 N개의 요청을 보냅니다(요청 사이에 약간의 지연 포함) — 창이 클수록 검색이 느려집니다. 할당량 보호를 위해 창은 검색당 30일로 제한됩니다.

• 호텔 수: 기본적으로 날짜별로 도시에서 최대 15개 호텔이 확인됩니다(max_hotels를 통해 최대 30개까지 늘리거나 특정 hotelIds로 줄일 수 있음).

• 샌드박스 데이터: test 환경에서 가장 안정적인 커버리지는 대도시(예: NYC, LON, PAR)입니다. 더 작은 도시는 호텔이 거의 없거나 전혀 반환되지 않을 수 있습니다 — production으로 전환하면 해결됩니다.

• 예약 링크는 호텔 이름과 날짜를 기준으로 Booking.com 검색을 구성합니다 — 특정 객실에 대한 직접 딥 링크가 아닙니다. Amadeus가 이를 제공하지 않기 때문입니다. 대부분의 경우 관련 호텔이 결과에서 첫 번째로 나타납니다.

프로젝트 구조

src/
├── index.ts              # נקודת כניסה, רישום השרת והכלים
├── constants.ts           # קבועים (URLs, מגבלות)
├── types.ts                # טיפוסי TypeScript משותפים
├── services/
│   ├── amadeusClient.ts   # קליינט HTTP מאומת ל-Amadeus (OAuth2, endpoints)
│   ├── hotelSearch.ts     # הלוגיקה של חיפוש גמיש (הליבה)
│   ├── affiliateLink.ts   # בניית קישור ההזמנה (Booking.com + aid אופציונלי)
│   └── format.ts           # פורמט markdown לתשובות
├── schemas/
│   └── schemas.ts          # סכמות Zod לכל כלי
├── tools/                  # רישום כל כלי MCP
└── test/
    └── hotelSearch.test.ts # בדיקות יחידה ללוגיקת החיפוש (ללא צורך במפתח API)
scripts/
└── smoke-test-tools.mjs    # בדיקת עשן שמפעילה את השרת האמיתי ומוודאת שכל הכלים נחשפים כראוי

향후 확장 가능성

• 고정 일수 대신 유연한 숙박 일수 범위(min/max nights).

• 할당량 절약을 위한 검색 결과 캐싱.

• 추가 제휴 프로그램(Expedia, Agoda 등) 가입 및 각 결과에 대해 Booking.com뿐만 아니라 여러 소스 링크 표시.

• 제품이 성장함에 따라 더 넓은 공급업체 커버리지를 위한 유료 제공업체(StayAPI / RapidAPI 등)로 전환.

• ChatGPT 앱 스토어(Apps SDK) 등록 — 자체 요구 사항(OpenAI 개발자 계정, 개인정보 처리방침, 테스트용 데모 계정)이 있는 별도 프로젝트; 현재 제휴 모델(신용카드 수집 없음)은 이미 "external checkout" 요구 사항을 충족합니다.