mcp-cuddlynest

用途

mcp-cuddlynest 是一个 Model Context Protocol（MCP）服务器，用于搜索 CuddlyNest 酒店并检索房源详情，包括房型选项、价格、可用性和取消政策。它被明确设计为只读：仅做搜索与房源详情读取，不涉及预订，也不涉及支付。

主要能力

该服务器提供两个工具，二者均标注 readOnlyHint: true，即从不会写入、预订或付款。

• cuddlynest_search：从一个目的地搜索当地热门酒店，数据来自公开的 CuddlyNest API（autosuggestion-2-0 用于模糊匹配，discovery-pages 地理页用于更广泛的城市列表）。价格不在此返回，需将酒店的 productId 传给 cuddlynest_listing_details。 返回结构：{ query, guests, places[], city, hotelSource, hotelCount, hotels[], note }。其中每个 hotels[] 条目包含 productId、name、url、slug、propertyType、starRating、guestRating（/10）与 guestRatingText、reviewCount，以及来自地理页的 images[]、distanceFromCenterKm、featuredAmenities[]。hotelSource 取值为 "autosuggest" 或 "autosuggest+geopage"。注意该列表为顶部匹配规模，并非完整库存。

• cuddlynest_listing_details：返回单家酒店的静态基础信息与房间/价格。 返回结构：{ productId, hotelUrl, guests, staticListing, staticError, rooms, roomsError, notes }。rooms.units[] 为提取出的房型报价，每项包含 title、partnerName、unitPrice、currency、remainingRooms、guests、cancellationPolicyType、cancellationPolicyText、priceBreakdown、roomFilters。rooms 还包含 fromPrice、partnersSeen、listingUrl、scrapedAt。

使用方式与数据获取机制

该服务器以访客相同的方式读取数据：在无头浏览器（Playwright/Chromium）中打开真实、公开的房源页面，让页面自身的 JavaScript 加载房间，等待其渲染后，再从 DOM 中读取结果。

DOM 提取逻辑位于 extractRoomsFromDom()：遍历每个价格形态的文本节点（例如 COL$742,637），然后沿 React fiber 树向上找到最近的祖先组件，其 props 同时带有 unit_price 和 roomGroups。这些 props 即页面已渲染出的房型报价。

安装与运行要点：

• 需要用于 Playwright 的 Chromium 构建。npm install 会自动执行 playwright install chromium（postinstall）；若你的环境阻止该操作，可手动执行一次 npx playwright install chromium。
• 在 npm 上以 cuddlynest-mcp 发布，并在官方 MCP 注册表中登记为 io.github.mafedelahoz/cuddlynest-mcp。
• 可在 args 中添加 "--ignore-robots-txt" 以绕过 robots.txt 进行房源页抓取。CUDDLYNEST_SCRAPE_TIMEOUT_MS（默认 35000）限制浏览器等待价格渲染的时间。
• 每个 GitHub release 附带一个用于 Claude Desktop 的 MCPB 打包文件（.mcpb）；注意它不捆绑 Chromium，因此用这种方式安装后需再手动执行一次 npx playwright install chromium。
• 默认传输方式为 stdio。若要托管部署，可改用 Streamable HTTP 运行。

仓库文件说明：

• index.ts — MCP 服务器、工具 schema、stdio 与 Streamable HTTP 传输、robots.txt 处理
• cuddlynest.ts — 酒店 URL 解析、静态房源 ld+json 解析、目的地自动建议、结果整形
• scrape-listing.ts — resolveListingPath、buildListingUrl、scrapeListing（无头浏览器）、extractRoomsFromDom（React fiber 遍历）
• util.ts — 通用的对象/JSON 辅助函数

许可证为 MIT，详见 LICENSE。

适用场景

适用于通过 MCP 客户端（如 Claude Desktop 等支持 MCP 的环境）按目的地搜索 CuddlyNest 酒店，并读取某家酒店的实时房型、价格、可用性与取消政策。适合需要只读查询酒店公开信息、不进行交易流程的场景。

限制与已知风险

• 只读设计：仅搜索与房源详情，没有预订，也没有支付。
• DOM 提取耦合于 CuddlyNest 当前前端内部实现（一种 React prop 形态，并非稳定契约）。若其前端发生变更，即使公开页面仍显示价格，也可能开始返回零房间。需要更新的唯一位置是 scrape-listing.ts 中的检测条件 'unit_price' in p && 'roomGroups' in p。npm run e2e:sansiraka 旨在尽早发现该问题（以非零退出码，而非静默返回空结果）。
• fromPriceText（"From COL$…"）字段使用较宽松的启发式，即使在正常抓取下也可能返回 null；rooms.fromPrice（提取到的最便宜单元）是更可靠的数据。
• 搜索返回的是顶部匹配规模，并非完整库存；CuddlyNest 的真实结果页（/sr/…）存在机器人拦截，并在 robots.txt 中被 Disallow。
• 抓取依赖无头浏览器与 Chromium 构建，若环境阻止自动安装需手动安装。