Cuddlynest MCP

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:// :8080/mcp — JSON-RPC (stateless, no sessions)

GET http:// :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.