CuddlyNest Search & Listings — MCP Server

A Model Context Protocol (MCP) server for searching CuddlyNest hotels and retrieving listing details, including room options, prices, availability and cancellation policies.

Read-only by design: search and listing details only. No booking, no payment.

How it gets the data

This server reads that data the same way a visitor does: it opens the real, public listing page in a headless browser (Playwright/Chromium), lets the page's own JavaScript load the rooms, waits for them to render, and reads the result out of the DOM.

The DOM extraction, and how it breaks

extractRoomsFromDom() walks every price-shaped text node (COL$742,637), then walks up its React fiber tree to the nearest ancestor component whose props carry both unit_price and roomGroups. Those props are the room offer the page already rendered.

This is coupled to CuddlyNest's current frontend internals (a React prop shape, not a stable contract). If they ship a frontend change it can start returning zero rooms even though the public page still shows prices. The single place to update is the detector condition 'unit_price' in p && 'roomGroups' in p in scrape-listing.ts. npm run e2e:sansiraka is meant to catch that early (non-zero exit, not a silent empty result).

The fromPriceText ("From COL$…") field uses a looser heuristic and can come back null even on a healthy scrape; rooms.fromPrice (cheapest extracted unit) is the reliable figure.

Requirements

• Node.js 18+
• A Chromium build for Playwright. npm install runs playwright install chromium automatically (postinstall); if that is blocked in your environment, run npx playwright install chromium once by hand.

Installation

Published as cuddlynest-mcp on npm and listed in the official MCP registry as io.github.mafedelahoz/cuddlynest-mcp.

{
  "mcpServers": {
    "cuddlynest": {
      "command": "npx",
      "args": ["-y", "cuddlynest-mcp"]
    }
  }
}

Add "--ignore-robots-txt" to args to bypass robots.txt for the listing-page fetches. CUDDLYNEST_SCRAPE_TIMEOUT_MS (default 35000) caps how long the browser waits for prices to render.

An MCPB bundle (.mcpb) for Claude Desktop is attached to each GitHub release — note it does not bundle Chromium, so run npx playwright install chromium once after installing it that way.

Remote / Streamable HTTP

Default transport is stdio. For a hosted deployment, run it over Streamable HTTP:

node dist/index.js --http 8080      # or: MCP_TRANSPORT=http PORT=8080 node dist/index.js
#   POST  http://<host>:8080/mcp    — JSON-RPC (stateless, no sessions)
#   GET   http://<host>:8080/health — liveness

Tools

Both tools are annotated readOnlyHint: true — they never write, book, or pay.

cuddlynest_search

Search a destination and the top hotels there, from public CuddlyNest APIs (autosuggestion-2-0 for the fuzzy match, discovery-pages geo pages for the broader city list). Prices are not here — pass a hotel's productId to cuddlynest_listing_details.

Returns: { query, guests, places[], city, hotelSource, hotelCount, hotels[], note }. Each hotels[] entry: productId, name, url, slug, propertyType, starRating, guestRating (/10) + guestRatingText, reviewCount, and — from the geo page — images[], distanceFromCenterKm, featuredAmenities[]. hotelSource is "autosuggest" or "autosuggest+geopage". The list is top-matches scale, not full inventory — CuddlyNest's real results page (/sr/…) is bot-blocked and Disallowed in robots.txt.

cuddlynest_listing_details

Static basics and rooms/pricing for one hotel.

Returns: { productId, hotelUrl, guests, staticListing, staticError, rooms, roomsError, notes }. rooms.units[] is the extracted room offers, each with title, partnerName, unitPrice, currency, remainingRooms, guests, cancellationPolicyType, cancellationPolicyText, priceBreakdown, roomFilters. rooms also carries fromPrice, partnersSeen, listingUrl, scrapedAt.

Development

npm install          # installs deps + Chromium (postinstall)
npm run build        # sync-version + tsc -> dist/
npm run typecheck
npm test             # offline: smoke test (stdio) + scraper tests
npm run e2e:sansiraka # ONLINE: real scrape of cuddlynest.com, structural asserts
npm run watch

Architecture

• index.ts — MCP server, tool schemas, stdio and Streamable HTTP transports, robots.txt handling
• cuddlynest.ts — hotel-URL parsing, static-listing ld+json parse, destination autosuggestion, result shaping
• scrape-listing.ts — resolveListingPath, buildListingUrl, scrapeListing (headless browser), extractRoomsFromDom (React-fiber walk)
• util.ts — generic object/JSON helpers

License

MIT — see LICENSE.