# flexible-hotels-mcp-server

שרת MCP (Model Context Protocol) שמאפשר ל-AI (קלוד או כל לקוח MCP אחר) לחפש חדרי מלון **לפי מספר לילות בטווח תאריכים גמיש**, במקום לפי תאריך צ'ק-אין/צ'ק-אאוט קבוע.

> 🚀 **השרת כבר פרוס וחי**: `https://flexible-hotels-mcp-server.onrender.com` (Render, תוכנית חינמית). כתובת ה-MCP לחיבור: `https://flexible-hotels-mcp-server.onrender.com/mcp`. שימו לב: בתוכנית החינמית השרת "נרדם" אחרי 15 דקות ללא שימוש, והבקשה הראשונה אחרי שינה עלולה לקחת עד כ-50 שניות.
> >
> >> **השרת עובד כבר עכשיו, בלי שום מפתח API**, במצב "link-only" (ראו למטה) — קישורי חיפוש ב-Booking.com לכל תאריך, בלי השוואת מחירים אוטומטית. להשוואת מחירים חיה, צריך מפתח StayAPI חינמי — ראו "התקנה" למטה.
> >>
> >> לדוגמה: "3 לילות בתל אביב, איפשהו בין 1.9 ל-20.9" — השרת סורק את כל תאריכי הצ'ק-אין האפשריים בטווח ומחזיר קישורי חיפוש (או, במצב עם מפתח, מחירים אמיתיים ממוינים מהזול ליקר) לכל אחד מהם.
> >>
> >> **מודל אפיליאט**: זה כלי השוואת מחירים בלבד — הוא **לא** אוסף פרטי תשלום ולא מבצע הזמנה. כל תוצאה כוללת קישור (`bookingUrl`) שמפנה ל-Booking.com, שבו המשתמש יכול להשלים את הרכישה בעצמו, אם בכלל ירצה.
> >>
> >> > ⚠️ **הערה חשובה**: הגרסה המקורית של השרת הזה תוכננה סביב Amadeus for Developers (סביבת ה-`test` החינמית שלהם). ב-17 ביולי 2026 אמדאוס **סגרו לגמרי את פורטל ה-Self-Service** — אין יותר הרשמה עצמאית וחינמית, רק מסלול Enterprise מול אנשי מכירות. בעקבות זאת השרת עבר מיגרציה מלאה ל-[StayAPI](https://stayapi.com), אגרגטור נתוני מלונות (Booking.com ועוד) עם הרשמה חינמית ומיידית.
> >> >
> >> > ## מקור הנתונים: StayAPI
> >> >
> >> > מקור הנתונים: [StayAPI](https://stayapi.com) — אגרגטור נתוני אירוח שמרכז מחירים/זמינות/ביקורות מ-Booking.com, Expedia, TripAdvisor, Agoda, Vrbo, Trip.com ועוד. הרשמה חינמית, מיידית, **בלי כרטיס אשראי** — אבל המכסה החינמית היא **50 בקשות בסך הכול, חד-פעמי** (לא מתחדש מדי חודש). לכן השרת בנוי בשני מצבים:
> >> >
> >> > - **מצב חינמי ("link-only", ברירת המחדל)** — בלי שום מפתח API. במקום מחירים, כל תאריך מקבל קישור חיפוש ישיר ל-Booking.com עם התאריכים כבר ממולאים; המחיר האמיתי נראה אחרי לחיצה. **בלי הגבלת מכסה, לעולם לא נשבר.**
> >> > - - **מצב "priced" (אופציונלי)** — כשמוגדר `STAYAPI_KEY`, כל תאריך בטווח מפעיל קריאת API אמיתית ל-StayAPI ומחזיר מחירים אמיתיים ממוינים מהזול ליקר. כל חיפוש גמיש צורך כמה בקשות מהמכסה (חיפוש יעד אחד + בקשה אחת לכל תאריך שנסרק) — כדאי לצמצם את טווח התאריכים כדי לחסוך במכסה החד-פעמית של 50 הבקשות.
> >> >  
> >> >   - ## מה יש כאן
> >> >  
> >> >   - שני כלים (tools) חשופים ל-AI:
> >> >  
> >> >   - | כלי | מה הוא עושה |
> >> >   - |---|---|
> >> >   - | `flexible_hotels_resolve_destination` | (אופציונלי, למצב priced בלבד) פענוח/ניתוב שם יעד חופשי (למשל "תל אביב") למזהה יעד ב-Booking.com |
> >> >   - | `flexible_hotels_search_flexible_offers` | **הכלי המרכזי** — חיפוש גמיש לפי מספר לילות בטווח תאריכים, עם קישור הזמנה לכל תוצאה. עובד ישר, בלי צורך לקרוא לכלי אחר קודם |
> >> >
> >> >   - הלוגיקה של "חיפוש גמיש" ממומשת ב-`src/services/hotelSearch.ts`: מכיוון ש-StayAPI (וכל ספק אחר) תומך רק בטווח תאריכים קבוע אחד לכל קריאה, השרת סורק בעצמו כל תאריך צ'ק-אין אפשרי בחלון שהוגדר, קורא ל-API בהתאם (במצב priced) או בונה קישור (במצב link-only), ומאגד את התוצאות. הקישור לכל תוצאה נבנה ב-`src/services/affiliateLink.ts`.
> >> >
> >> >   - ## התקנה
> >> >
> >> >   - **השרת כבר עובד בלי שום התקנה, במצב link-only.** כדי לקבל מחירים אמיתיים:
> >> >
> >> >   - **1. השג מפתח StayAPI חינמי** (כ-2 דקות, בלי כרטיס אשראי):
> >> >
> >> >   - 1. הירשמו ב-<https://stayapi.com/users/sign_up>
> >> >     2. 2. אחרי ההרשמה תקבלו מפתח API בדשבורד — זה יהיה `STAYAPI_KEY`
> >> >        3. 3. שימו לב: זו מכסה **חד-פעמית של 50 בקשות בסך הכול**, לא מתחדשת מדי חודש
> >> >          
> >> >           4. **2. הזנת המפתח בשרת החי (Render):**
> >> >          
> >> >           5. 1. פתחו את [דף השירות ב-Render](https://dashboard.render.com/web/srv-da6j5f8u01pc738a4ij0)
> >> >              2. 2. בתפריט הצד לחצו על "Environment"
> >> >                 3. 3. הוסיפו משתנה סביבה בשם `STAYAPI_KEY` עם הערך שקיבלתם
> >> >                    4. 4. (אופציונלי) הוסיפו גם `BOOKING_AFFILIATE_ID` — ראו "המודל העסקי" למטה
> >> >                       5. 5. שמרו — Render יעשה דיפלוי מחדש אוטומטית תוך דקה-שתיים
> >> >                         
> >> >                          6. **התקנה מקומית (אופציונלי, להרצה על המחשב שלכם):**
> >> >                         
> >> >                          7. ```bash
> >> >                             npm install
> >> >                             cp .env.example .env
> >> >                             # ערכו את .env והכניסו את המפתח שקיבלתם (או השאירו ריק למצב link-only)
> >> >                             npm run build
> >> >                             ```
> >> >
> >> > **בדיקה שהכול עובד** (לא שולח בקשות אמיתיות ל-StayAPI, לא פוגע במכסה):
> >> >
> >> > ```bash
> >> > npm test
> >> > ```
> >> >
> >> > ## הרצה מקומית
> >> >
> >> > ```bash
> >> > npm start
> >> > ```
> >> >
> >> > כברירת מחדל השרת רץ דרך `stdio` (מתאים לחיבור מקומי ללקוחות כמו Claude Desktop). כדי להריץ כשרת מרוחק ב-HTTP (לחיבור מ-Claude.ai / Cowork כ"custom connector", או מכל לקוח MCP מרוחק אחר):
> >> >
> >> > ```bash
> >> > TRANSPORT=http PORT=3000 npm start
> >> > ```
> >> >
> >> > ## חיבור כ"פלאגין" ל-AI
> >> >
> >> > ### חיבור מרוחק (מומלץ — השרת כבר פרוס)
> >> >
> >> > השרת רץ כבר בכתובת:
> >> >
> >> > ```
> >> > https://flexible-hotels-mcp-server.onrender.com/mcp
> >> > ```
> >> >
> >> > חברו אותה כ-"Custom Connector" / "Remote MCP Server" בהגדרות הלקוח שלכם (Claude.ai, Cowork, ChatGPT וכו'). אין צורך בהתקנה מקומית, ואין צורך במפתח API כדי להתחיל (מצב link-only עובד מיד).
> >> >
> >> > ### Claude Desktop (מקומי, חלופה)
> >> >
> >> > הוסיפו לקובץ ההגדרות `claude_desktop_config.json`:
> >> >
> >> > ```json
> >> > {
> >> >   "mcpServers": {
> >> >     "flexible-hotels": {
> >> >       "command": "node",
> >> >       "args": ["/נתיב-מלא/ל/flexible-hotels-mcp-server/dist/index.js"],
> >> >       "env": {
> >> >         "STAYAPI_KEY": "המפתח-שלכם"
> >> >       }
> >> >     }
> >> >   }
> >> > }
> >> > ```
> >> >
> >> > `STAYAPI_KEY` אופציונלי — בלעדיו השרת רץ במצב link-only. לאחר הפעלה מחדש של Claude Desktop, ה-AI יוכל לקרוא לכלים האלה ישירות בשיחה.
> >> >
> >> > ### פריסה עצמאית (Render / Railway)
> >> >
> >> > אם תרצו לפרוס עותק משלכם: קובץ `render.yaml` בשורש הפרויקט מוכן כ-Blueprint עבור Render, וקובץ `railway.toml` מוכן ל-Railway. שני הקבצים בונים מה-`Dockerfile` ומחשפים `/healthz` לבדיקת תקינות (מחזיר גם את המצב הנוכחי: `"mode":"priced"` או `"mode":"link_only"`).
> >> >
> >> > שימו לב: `STAYAPI_KEY` צריך להיות משתנה סביבה מוגדר על השרת המארח, לעולם לא כתוב בקוד.
> >> >
> >> > ## דוגמת שימוש (מה ה-AI "רואה")
> >> >
> >> > ```
> >> > User: תמצא לי 3 לילות בתל אביב, איפשהו בין ה-1 ל-20 בספטמבר, לזוג.
> >> >
> >> > AI calls: flexible_hotels_search_flexible_offers(
> >> >   destination="Tel Aviv", nights=3,
> >> >   earliest_check_in="2026-09-01", latest_check_in="2026-09-20",
> >> >   adults=2
> >> > )
> >> >   -> במצב link-only: קישור חיפוש ל-Booking.com לכל תאריך מועמד בטווח
> >> >   -> במצב priced: רשימת עסקאות ממוינת מהזולה ביותר, עם מחיר, תאריך צ'ק-אין/אאוט מדויק וקישור הזמנה לכל אחת
> >> > ```
> >> >
> >> > ## המודל העסקי: אפיליאט
> >> >
> >> > השרת הזה **לא** מבצע הזמנות ולא נוגע בפרטי תשלום בשום שלב — זה בכוונה, גם מטעמי פשטות/בטיחות וגם כי ככה עובדות חנויות האפליקציות (כמו ChatGPT App Directory) שדורשות "external checkout" ואוסרות איסוף מספרי כרטיס אשראי דרך הכלי עצמו.
> >> >
> >> > איך זה עובד בפועל:
> >> >
> >> > 1. השרת מוצא (או מקשר ל-) מחירים ב-Booking.com.
> >> > 2. 2. לכל תוצאה נבנה קישור (`src/services/affiliateLink.ts`) — אם יש מחיר אמיתי (מצב priced), הקישור הוא ה-URL שהוחזר מ-StayAPI; אחרת קישור חיפוש כללי עם היעד והתאריכים ממולאים.
> >> >    3. 3. אם תרשמו ל-[Booking.com Affiliate Partner Program](https://www.booking.com/affiliate-program) (חינמי, הרשמה עצמאית, ללא אישור מיוחד) ותקבלו `aid`, אפשר להגדיר אותו כמשתנה סביבה `BOOKING_AFFILIATE_ID` באותו Environment ב-Render — אז כל קישור יכלול את מזהה השותף שלכם ותוכלו לקבל עמלה על הזמנות שמתבצעות דרך הקישור.
> >> >       4. 4. בלי `BOOKING_AFFILIATE_ID` הקישורים עדיין עובדים במלואם — הם פשוט לא מתוגמלים.
> >> >         
> >> >          5. ## מגבלות ידועות
> >> >         
> >> >          6. - **מכסה חינמית חד-פעמית**: StayAPI נותנת 50 בקשות בסך הכול (לא מתחדש מדי חודש). חיפוש גמיש על חלון של N ימים שולח עד N+1 בקשות במצב priced — חלון גדול יגמור את המכסה מהר. אין הגבלה כזו במצב link-only.
> >> >             - - **שינה בתוכנית החינמית**: Render מרדים את השרת אחרי 15 דקות ללא שימוש; הבקשה הראשונה אחרי שינה איטית (עד כ-50 שניות).
> >> >               - - **קישורי ההזמנה** במצב link-only הם קישורי חיפוש כלליים (לא deep link לחדר ספציפי) — המשתמש רואה את המחירים האמיתיים רק אחרי לחיצה.
> >> >                 - - **חלון תאריכים**: מוגבל ל-30 יום לכל חיפוש כדי להגן על המכסה (`MAX_WINDOW_DAYS` ב-`constants.ts`).
> >> >                  
> >> >                   - ## מבנה הפרויקט
> >> >                  
> >> >                   - ```
> >> >                     src/
> >> >                     ├── index.ts                 # נקודת כניסה, רישום השרת והכלים
> >> >                     ├── constants.ts              # קבועים (URLs, מגבלות)
> >> >                     ├── types.ts                  # טיפוסי TypeScript משותפים
> >> >                     ├── services/
> >> >                     │   ├── stayApiClient.ts      # קליינט HTTP מאומת ל-StayAPI (destination lookup + hotel search)
> >> >                     │   ├── hotelSearch.ts        # הלוגיקה של חיפוש גמיש (הליבה) — מצב link-only ומצב priced
> >> >                     │   ├── affiliateLink.ts      # בניית קישור ההזמנה (Booking.com + aid אופציונלי)
> >> >                     │   └── format.ts              # פורמט markdown לתשובות
> >> >                     ├── schemas/
> >> >                     │   └── schemas.ts             # סכמות Zod לכל כלי
> >> >                     ├── tools/                     # רישום כל כלי MCP (resolveDestination, searchFlexibleOffers)
> >> >                     └── test/
> >> >                         └── hotelSearch.test.ts    # בדיקות יחידה ללוגיקת החיפוש (ללא צורך במפתח API)
> >> >                     scripts/
> >> >                     └── smoke-test-tools.mjs       # בדיקת עשן שמפעילה את השרת האמיתי ומוודאת שכל הכלים נחשפים כראוי
> >> >                     ```
> >> >
> >> > ## הרחבות אפשריות להמשך
> >> >
> >> > - טווח לילות גמיש (min/max nights) ולא רק מספר קבוע.
> >> > - - קאשינג של תוצאות חיפוש כדי לחסוך במכסה החד-פעמית של StayAPI.
> >> >   - - מעבר לתוכנית בתשלום ב-StayAPI (או ספק נוסף) כשהמכסה החינמית נגמרת ויש שימוש אמיתי.
> >> >     - - הצטרפות לתוכניות אפיליאט נוספות (Expedia, Agoda וכו') והצגת כמה קישורים למקורות שונים לכל תוצאה, לא רק Booking.com.
> >> >       - - רישום בחנות האפליקציות של ChatGPT (Apps SDK) — פרויקט נפרד עם דרישות משלו (חשבון מפתחים ב-OpenAI, מדיניות פרטיות, חשבון דמו לבדיקה); המודל האפיליאט הנוכחי (בלי איסוף כרטיס אשראי) כבר תואם לדרישת ה-"external checkout" שלהם.
> >> >         -