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 installrunsplaywright install chromiumautomatically (postinstall); if that is blocked in your environment, runnpx playwright install chromiumonce 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.txthandlingcuddlynest.ts— hotel-URL parsing, static-listingld+jsonparse, destination autosuggestion, result shapingscrape-listing.ts—resolveListingPath,buildListingUrl,scrapeListing(headless browser),extractRoomsFromDom(React-fiber walk)util.ts— generic object/JSON helpers
License
MIT — see LICENSE.