flexible-hotels-mcp-server

一个 MCP（Model Context Protocol）服务器，让 AI（Claude 或任何其他 MCP 客户端）能够按灵活日期范围内的住宿晚数搜索酒店房间，而不是按固定的入住/退房日期。

例如："特拉维夫 3 晚，9 月 1 日到 9 月 20 日之间的某个时间"——服务器会扫描该范围内所有可能的入住日期，为每个日期获取真实价格，并返回按价格排序的最优惠交易。

联盟营销模式：这只是一个比价工具——它不收集任何付款信息，也不执行预订。每条结果都包含一个链接（bookingUrl），指向用户可自行完成购买（如果愿意的话）的来源（目前是 Booking.com）。

数据来源：Amadeus for Developers——旅游领域领先的免费 API，提供完全免费的 test（沙盒）环境，无需信用卡。

这里有什么

四个暴露给 AI 的工具（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. 验证后，在 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 模式部署服务器，然后在客户端设置中将 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

服务器在设置 Amadeus 密钥之前也能启动（并通过健康检查）——搜索工具只会返回明确的错误，直到设置好真实密钥并自动重新部署。

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

商业模式：联盟营销

该服务器不执行预订，也不在任何阶段接触付款信息——这是有意为之，既出于简单/安全考虑，也因为应用商店（如 ChatGPT App Directory）要求"external checkout"并禁止通过工具本身收集信用卡号。

实际运作方式：

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    # בדיקת עשן שמפעילה את השרת האמיתי ומוודאת שכל הכלים נחשפים כראוי

未来可能的扩展

• 灵活的晚数范围（最小/最大晚数），而不仅仅是固定数字。

• 搜索结果的缓存以节省配额。

• 加入更多联盟计划（Expedia、Agoda 等），为每条结果显示多个不同来源的链接，而不仅仅是 Booking.com。

• 当产品增长时，切换到付费供应商（如 StayAPI / RapidAPI）以获得更广泛的供应商覆盖。

• 在 ChatGPT 应用商店（Apps SDK）中注册——一个独立项目，有自己的要求（OpenAI 开发者账户、隐私政策、用于测试的演示账户）；当前的联盟模式（不收集信用卡）已经符合他们的"external checkout"要求。