flexible-hotels-mcp-server

MCP-сервер (Model Context Protocol), который позволяет ИИ (Claude или любому другому MCP-клиенту) искать гостиничные номера по количеству ночей в гибком диапазоне дат, а не по фиксированной дате заезда/выезда.

Например: «3 ночи в Тель-Авиве, где-то между 1.9 и 20.9» — сервер сканирует все возможные даты заезда в диапазоне, получает реальные цены для каждой из них и возвращает самые выгодные предложения, отсортированные по цене.

Партнёрская модель: это исключительно инструмент сравнения цен — он не собирает платёжные данные и не выполняет бронирование. Каждый результат содержит ссылку (bookingUrl), ведущую на источник (сейчас Booking.com), где пользователь может самостоятельно завершить покупку, если вообще захочет.

Источник данных: Amadeus for Developers — ведущее бесплатное API в сфере туризма, с полностью бесплатной тестовой средой (test) без необходимости вводить банковскую карту.

Что здесь есть

Четыре инструмента (tools), доступных ИИ:

Логика «гибкого поиска» реализована в src/services/hotelSearch.ts: поскольку Amadeus (как и любой другой провайдер) поддерживает только один фиксированный диапазон дат на запрос, сервер сам перебирает каждую возможную дату заезда в заданном окне, вызывает API соответствующим образом и объединяет результаты. Ссылка для каждого результата формируется в src/services/affiliateLink.ts.

Related MCP server: AigoHotel MCP Server

Установка

1. Получите бесплатный API-ключ (2 минуты, без банковской карты):

1. Зарегистрируйтесь на https://developers.amadeus.com/register

2. После подтверждения создайте «New App» в My Self-Service Workspace

3. Вы получите API Key и API Secret — это будут AMADEUS_CLIENT_ID и AMADEUS_CLIENT_SECRET

Это среда test (sandbox) — полностью бесплатная, с щедрой месячной квотой и ограничением скорости около 10 запросов в секунду. Она охватывает сотни тысяч отелей по всему миру с реальными данными (хотя иногда частичными/кэшированными). Чтобы перейти на полные живые данные в будущем, можно запросить production-доступ у Amadeus (платный) и изменить 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

Подключение как «плагина» к ИИ

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 ИИ сможет напрямую вызывать эти инструменты в диалоге.

Удалённое подключение (Claude.ai / Cowork / любой другой клиент)

Чтобы продукт был доступен как «плагин» для нескольких пользователей без необходимости каждому запускать код локально, нужно развернуть (deploy) сервер в режиме TRANSPORT=http на каком-либо сервере/хосте, а затем подключить адрес https://ваш-домен/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

Сервер запускается (и проходит health check) также до настройки ключей Amadeus — инструменты поиска просто будут возвращать понятную ошибку, пока не будут заданы реальные ключи и не произойдёт автоматический редеплой.

Render: файл render.yaml в корне проекта готов как Blueprint — подключаете repo к Render, «New» -> «Blueprint» и заполняете AMADEUS_CLIENT_ID/AMADEUS_CLIENT_SECRET в интерфейсе (см. комментарии внутри файла).

Обратите внимание во всех вариантах: AMADEUS_CLIENT_ID/AMADEUS_CLIENT_SECRET должны быть переменными окружения, заданными на хост-сервере, и никогда не должны быть записаны в коде.

Пример использования (что «видит» ИИ)

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="...")
  -> מחיר מעודכן + קישור לחיצה שמעביר את המשתמש להשלים את ההזמנה באתר המקורי

Бизнес-модель: партнёрская программа

Этот сервер не выполняет бронирования и не касается платёжных данных ни на каком этапе — это намеренно, как из соображений простоты/безопасности, так и потому, что так работают магазины приложений (например, ChatGPT App Directory), которые требуют «external checkout» и запрещают сбор номеров банковских карт через сам инструмент.

Как это работает на практике:

1. Сервер находит реальные цены через Amadeus (бесплатно).

2. Для каждого результата формируется ссылка на страницу поиска на Booking.com с уже заполненными названием отеля и датами (src/services/affiliateLink.ts).

3. Если вы зарегистрируетесь в Booking.com Affiliate Partner Program (бесплатно, самостоятельная регистрация, без специального одобрения) и получите aid, его можно задать как переменную окружения BOOKING_AFFILIATE_ID — тогда каждая ссылка будет содержать ваш партнёрский идентификатор, и вы сможете получать комиссию за бронирования, совершённые по ссылке.

4. Без BOOKING_AFFILIATE_ID ссылки по-прежнему полностью работают — просто не приносят вознаграждения.

Это именно то «просто зарегистрироваться», о котором вы просили: однократная регистрация в партнёрской программе Booking.com (не в Amadeus, не в Railway) — всё, что нужно, чтобы ссылки начали приносить доход.

Известные ограничения

• Бесплатная квота: среда test Amadeus ограничена месячной квотой и скоростью запросов (~10/сек). Гибкий поиск по окну из N дней отправляет до N запросов (с небольшой задержкой между ними) — большое окно = более медленный поиск. Окно ограничено 30 днями на один поиск для защиты квоты.

• Количество отелей: по умолчанию проверяется до 15 отелей в городе на каждую дату (можно увеличить до 30 через max_hotels или сузить до конкретных hotelIds).

• Данные sandbox: в среде test наиболее надёжное покрытие — в крупных городах (например, NYC, LON, PAR). В небольших городах может возвращаться мало отелей или ничего — это решается переходом на production.

• Ссылки на бронирование формируют поиск на Booking.com по названию отеля и датам — это не прямая глубокая ссылка (deep link) на конкретный номер, потому что 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».