hotelzero 1.1.0 → 1.3.0

package/dist/browser.d.ts

@@ -1,3 +1,19 @@
+export declare class HotelSearchError extends Error {
+    code: string;
+    retryable: boolean;
+    constructor(message: string, code: string, retryable?: boolean);
+}
+export declare const ErrorCodes: {
+    readonly BROWSER_NOT_INITIALIZED: "BROWSER_NOT_INITIALIZED";
+    readonly NAVIGATION_FAILED: "NAVIGATION_FAILED";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly CAPTCHA_DETECTED: "CAPTCHA_DETECTED";
+    readonly NO_RESULTS: "NO_RESULTS";
+    readonly DESTINATION_NOT_FOUND: "DESTINATION_NOT_FOUND";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly BLOCKED: "BLOCKED";
+};
 export interface HotelSearchParams {
     destination: string;
     checkIn: string;
@@ -6,6 +22,8 @@ export interface HotelSearchParams {
     rooms: number;
     currency?: string;
     sortBy?: "popularity" | "price_lowest" | "price_highest" | "rating" | "distance";
+    limit?: number;
+    offset?: number;
 }
 export interface HotelFilters {
     minRating?: number;
@@ -110,9 +128,14 @@ export interface HotelResult {
 export declare class HotelBrowser {
     private browser;
     private page;
+    private lastRequestTime;
+    private minRequestIntervalMs;
     init(headless?: boolean): Promise<void>;
     close(): Promise<void>;
     private buildBookingUrl;
+    private enforceRateLimit;
+    private checkForBlocking;
+    private checkForNoResults;
     searchHotels(params: HotelSearchParams, filters?: HotelFilters): Promise<HotelResult[]>;
     private dismissPopups;
     private scrollToLoadMore;

package/dist/browser.js

@@ -1,4 +1,62 @@
 import { chromium } from "playwright";
+// Custom error types for better error handling
+export class HotelSearchError extends Error {
+    code;
+    retryable;
+    constructor(message, code, retryable = false) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.name = "HotelSearchError";
+    }
+}
+export const ErrorCodes = {
+    BROWSER_NOT_INITIALIZED: "BROWSER_NOT_INITIALIZED",
+    NAVIGATION_FAILED: "NAVIGATION_FAILED",
+    RATE_LIMITED: "RATE_LIMITED",
+    CAPTCHA_DETECTED: "CAPTCHA_DETECTED",
+    NO_RESULTS: "NO_RESULTS",
+    DESTINATION_NOT_FOUND: "DESTINATION_NOT_FOUND",
+    NETWORK_ERROR: "NETWORK_ERROR",
+    TIMEOUT: "TIMEOUT",
+    BLOCKED: "BLOCKED",
+};
+const DEFAULT_RETRY_CONFIG = {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 10000,
+};
+// Sleep helper
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+// Retry with exponential backoff
+async function retryWithBackoff(fn, config = DEFAULT_RETRY_CONFIG, onRetry) {
+    let lastError = null;
+    for (let attempt = 1; attempt <= config.maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            // Don't retry non-retryable errors
+            if (error instanceof HotelSearchError && !error.retryable) {
+                throw error;
+            }
+            // Don't retry on last attempt
+            if (attempt === config.maxRetries) {
+                break;
+            }
+            // Calculate delay with exponential backoff + jitter
+            const exponentialDelay = config.baseDelayMs * Math.pow(2, attempt - 1);
+            const jitter = Math.random() * 1000;
+            const delay = Math.min(exponentialDelay + jitter, config.maxDelayMs);
+            if (onRetry) {
+                onRetry(attempt, lastError, delay);
+            }
+            await sleep(delay);
+        }
+    }
+    throw lastError;
+}
 // Booking.com filter code mappings
 const FILTER_CODES = {
     // Property Types
@@ -172,6 +230,8 @@ const FILTER_CODES = {
 export class HotelBrowser {
     browser = null;
     page = null;
+    lastRequestTime = 0;
+    minRequestIntervalMs = 2000; // Minimum 2 seconds between requests
     async init(headless = true) {
         this.browser = await chromium.launch({
             headless,
@@ -191,7 +251,7 @@ export class HotelBrowser {
         }
     }
     buildBookingUrl(params, filters) {
-        const { destination, checkIn, checkOut, guests, rooms, currency, sortBy } = params;
+        const { destination, checkIn, checkOut, guests, rooms, currency, sortBy, offset } = params;
         const url = new URL("https://www.booking.com/searchresults.html");
         url.searchParams.set("ss", destination);
         url.searchParams.set("checkin", checkIn);
@@ -199,6 +259,10 @@ export class HotelBrowser {
         url.searchParams.set("group_adults", guests.toString());
         url.searchParams.set("no_rooms", rooms.toString());
         url.searchParams.set("selected_currency", currency || "USD");
+        // Pagination offset
+        if (offset && offset > 0) {
+            url.searchParams.set("offset", offset.toString());
+        }
         // Sort order
         if (sortBy) {
             const sortMap = {
@@ -413,23 +477,126 @@ export class HotelBrowser {
         }
         return url.toString();
     }
-    async searchHotels(params, filters) {
+    // Rate limiting: ensure minimum time between requests
+    async enforceRateLimit() {
+        const now = Date.now();
+        const timeSinceLastRequest = now - this.lastRequestTime;
+        if (timeSinceLastRequest < this.minRequestIntervalMs) {
+            const waitTime = this.minRequestIntervalMs - timeSinceLastRequest;
+            await sleep(waitTime);
+        }
+        this.lastRequestTime = Date.now();
+    }
+    // Check for CAPTCHA or blocking pages
+    async checkForBlocking() {
         if (!this.page)
-            throw new Error("Browser not initialized");
-        const url = this.buildBookingUrl(params, filters);
-        await this.page.goto(url, { waitUntil: "networkidle" });
-        await this.page.waitForTimeout(2000);
-        // Close any popups/modals
-        await this.dismissPopups();
-        // Scroll to load more results
-        await this.scrollToLoadMore();
-        // Extract detailed hotel info
-        const hotels = await this.extractHotelDetails();
-        // Apply client-side filtering and scoring if we have preferences
-        if (filters) {
-            return this.scoreAndFilterHotels(hotels, filters);
+            return;
+        const pageContent = await this.page.content();
+        const pageUrl = this.page.url();
+        // Check for CAPTCHA
+        const captchaIndicators = [
+            "captcha",
+            "recaptcha",
+            "hcaptcha",
+            "challenge-running",
+            "challenge-form",
+            "px-captcha",
+        ];
+        const hasCaptcha = captchaIndicators.some(indicator => pageContent.toLowerCase().includes(indicator));
+        if (hasCaptcha) {
+            throw new HotelSearchError("CAPTCHA detected. Please wait a few minutes before retrying.", ErrorCodes.CAPTCHA_DETECTED, false // Not retryable automatically
+            );
+        }
+        // Check for rate limiting / blocking
+        const blockIndicators = [
+            "access denied",
+            "too many requests",
+            "rate limit",
+            "blocked",
+            "forbidden",
+            "error 403",
+            "error 429",
+        ];
+        const isBlocked = blockIndicators.some(indicator => pageContent.toLowerCase().includes(indicator));
+        if (isBlocked || pageUrl.includes("blocked") || pageUrl.includes("error")) {
+            throw new HotelSearchError("Request blocked by Booking.com. Please wait a few minutes before retrying.", ErrorCodes.BLOCKED, true // Retryable with backoff
+            );
         }
-        return hotels;
+    }
+    // Check if destination was found
+    async checkForNoResults() {
+        if (!this.page)
+            return;
+        const pageContent = await this.page.content();
+        // Check for "no results" or "destination not found" messages
+        const noResultsIndicators = [
+            "no properties found",
+            "no results",
+            "0 properties",
+            "we couldn't find",
+            "try different dates",
+        ];
+        const hasNoResults = noResultsIndicators.some(indicator => pageContent.toLowerCase().includes(indicator));
+        if (hasNoResults) {
+            // Check if it's a destination issue or just no matching filters
+            const destinationIssue = pageContent.toLowerCase().includes("destination") &&
+                (pageContent.toLowerCase().includes("not found") ||
+                    pageContent.toLowerCase().includes("couldn't find"));
+            if (destinationIssue) {
+                throw new HotelSearchError("Destination not found. Please check the spelling and try again.", ErrorCodes.DESTINATION_NOT_FOUND, false);
+            }
+            // No results but destination is valid - this is not an error, just empty results
+        }
+    }
+    async searchHotels(params, filters) {
+        if (!this.page) {
+            throw new HotelSearchError("Browser not initialized. Call init() first.", ErrorCodes.BROWSER_NOT_INITIALIZED, false);
+        }
+        const url = this.buildBookingUrl(params, filters);
+        // Use retry with exponential backoff for the main search operation
+        return await retryWithBackoff(async () => {
+            // Enforce rate limiting
+            await this.enforceRateLimit();
+            try {
+                await this.page.goto(url, {
+                    waitUntil: "networkidle",
+                    timeout: 30000
+                });
+            }
+            catch (error) {
+                const err = error;
+                if (err.message.includes("timeout") || err.message.includes("Timeout")) {
+                    throw new HotelSearchError("Page load timed out. The server may be slow or unavailable.", ErrorCodes.TIMEOUT, true);
+                }
+                if (err.message.includes("net::") || err.message.includes("Network")) {
+                    throw new HotelSearchError("Network error occurred. Please check your connection.", ErrorCodes.NETWORK_ERROR, true);
+                }
+                throw new HotelSearchError(`Navigation failed: ${err.message}`, ErrorCodes.NAVIGATION_FAILED, true);
+            }
+            await this.page.waitForTimeout(2000);
+            // Check for blocking/CAPTCHA before proceeding
+            await this.checkForBlocking();
+            // Check for no results / destination issues
+            await this.checkForNoResults();
+            // Close any popups/modals
+            await this.dismissPopups();
+            // Scroll to load more results (pass limit to control how many to load)
+            const targetResults = params.limit || 25;
+            await this.scrollToLoadMore(targetResults);
+            // Extract detailed hotel info
+            let hotels = await this.extractHotelDetails();
+            // Apply limit to cap results
+            if (params.limit && params.limit > 0) {
+                hotels = hotels.slice(0, params.limit);
+            }
+            // Apply client-side filtering and scoring if we have preferences
+            if (filters) {
+                return this.scoreAndFilterHotels(hotels, filters);
+            }
+            return hotels;
+        }, DEFAULT_RETRY_CONFIG, (attempt, error, delayMs) => {
+            console.error(`Search attempt ${attempt} failed: ${error.message}. Retrying in ${Math.round(delayMs / 1000)}s...`);
+        });
     }
     async dismissPopups() {
         if (!this.page)
@@ -455,15 +622,31 @@ export class HotelBrowser {
             }
         }
     }
-    async scrollToLoadMore() {
+    async scrollToLoadMore(targetResults = 25) {
         if (!this.page)
             return;
-        // Scroll down a few times to load more results
-        for (let i = 0; i < 3; i++) {
+        // Calculate how many scroll iterations needed
+        // Each scroll typically loads ~15-25 more results
+        // We start with ~25, so to get to targetResults we need (targetResults - 25) / 20 more scrolls
+        const scrollsNeeded = Math.max(1, Math.ceil((targetResults - 25) / 20));
+        const maxScrolls = Math.min(scrollsNeeded, 5); // Cap at 5 scrolls to avoid excessive loading
+        // Scroll down to load more results
+        for (let i = 0; i < maxScrolls; i++) {
             await this.page.evaluate(() => {
                 window.scrollBy(0, window.innerHeight);
             });
             await this.page.waitForTimeout(1000);
+            // Check if "Load more" button exists and click it
+            try {
+                const loadMoreBtn = await this.page.$('button[data-testid="load-more-results"]');
+                if (loadMoreBtn) {
+                    await loadMoreBtn.click();
+                    await this.page.waitForTimeout(1500);
+                }
+            }
+            catch {
+                // Ignore if button not found
+            }
         }
         // Scroll back to top
         await this.page.evaluate(() => {
@@ -727,32 +910,53 @@ export class HotelBrowser {
             .sort((a, b) => (b.matchScore || 0) - (a.matchScore || 0));
     }
     async getHotelDetails(hotelUrl) {
-        if (!this.page)
-            throw new Error("Browser not initialized");
-        await this.page.goto(hotelUrl, { waitUntil: "networkidle" });
-        await this.page.waitForTimeout(2000);
-        await this.dismissPopups();
-        // Extract detailed information from hotel page
-        return await this.page.evaluate(() => {
-            const details = {};
-            // Hotel name
-            const nameEl = document.querySelector('h2[class*="pp-header"]');
-            details.name = nameEl?.textContent?.trim();
-            // Description
-            const descEl = document.querySelector('[data-testid="property-description"]');
-            details.description = descEl?.textContent?.trim();
-            // All facilities
-            const facilityEls = document.querySelectorAll('[data-testid="property-section-facilities"] li');
-            details.facilities = Array.from(facilityEls).map((el) => el.textContent?.trim());
-            // Photos
-            const photoEls = document.querySelectorAll('[data-testid="gallery-image"] img');
-            details.photos = Array.from(photoEls)
-                .slice(0, 5)
-                .map((el) => el.src);
-            // Popular facilities highlighted
-            const popularFacilities = document.querySelectorAll('[data-testid="property-most-popular-facilities"] span');
-            details.popularFacilities = Array.from(popularFacilities).map((el) => el.textContent?.trim());
-            return details;
+        if (!this.page) {
+            throw new HotelSearchError("Browser not initialized. Call init() first.", ErrorCodes.BROWSER_NOT_INITIALIZED, false);
+        }
+        return await retryWithBackoff(async () => {
+            // Enforce rate limiting
+            await this.enforceRateLimit();
+            try {
+                await this.page.goto(hotelUrl, {
+                    waitUntil: "networkidle",
+                    timeout: 30000
+                });
+            }
+            catch (error) {
+                const err = error;
+                if (err.message.includes("timeout") || err.message.includes("Timeout")) {
+                    throw new HotelSearchError("Page load timed out. The server may be slow or unavailable.", ErrorCodes.TIMEOUT, true);
+                }
+                throw new HotelSearchError(`Navigation failed: ${err.message}`, ErrorCodes.NAVIGATION_FAILED, true);
+            }
+            await this.page.waitForTimeout(2000);
+            // Check for blocking/CAPTCHA
+            await this.checkForBlocking();
+            await this.dismissPopups();
+            // Extract detailed information from hotel page
+            return await this.page.evaluate(() => {
+                const details = {};
+                // Hotel name
+                const nameEl = document.querySelector('h2[class*="pp-header"]');
+                details.name = nameEl?.textContent?.trim();
+                // Description
+                const descEl = document.querySelector('[data-testid="property-description"]');
+                details.description = descEl?.textContent?.trim();
+                // All facilities
+                const facilityEls = document.querySelectorAll('[data-testid="property-section-facilities"] li');
+                details.facilities = Array.from(facilityEls).map((el) => el.textContent?.trim());
+                // Photos
+                const photoEls = document.querySelectorAll('[data-testid="gallery-image"] img');
+                details.photos = Array.from(photoEls)
+                    .slice(0, 5)
+                    .map((el) => el.src);
+                // Popular facilities highlighted
+                const popularFacilities = document.querySelectorAll('[data-testid="property-most-popular-facilities"] span');
+                details.popularFacilities = Array.from(popularFacilities).map((el) => el.textContent?.trim());
+                return details;
+            });
+        }, DEFAULT_RETRY_CONFIG, (attempt, error, delayMs) => {
+            console.error(`Get details attempt ${attempt} failed: ${error.message}. Retrying in ${Math.round(delayMs / 1000)}s...`);
         });
     }
     async takeScreenshot(path) {

package/dist/index.js

@@ -3,7 +3,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
-import { HotelBrowser } from "./browser.js";
+import { HotelBrowser, HotelSearchError, ErrorCodes } from "./browser.js";
 // Property type enum
 const PropertyTypeEnum = z.enum([
     "hotel", "apartment", "resort", "villa", "vacation_home", "hostel", "bnb",
@@ -40,6 +40,9 @@ const FindHotelsSchema = z.object({
     // Currency & Sorting
     currency: z.string().optional().describe("Currency code (USD, EUR, GBP, JPY, etc.)"),
     sortBy: z.enum(["popularity", "price_lowest", "price_highest", "rating", "distance"]).optional().describe("Sort results by"),
+    // Pagination
+    limit: z.number().min(1).max(100).optional().describe("Maximum number of results to return (default: 25, max: 100)"),
+    offset: z.number().min(0).optional().describe("Number of results to skip for pagination (default: 0)"),
     // Rating & Price
     minRating: z.number().optional().describe("Minimum rating (6=Pleasant, 7=Good, 8=Very Good, 9=Wonderful)"),
     minPrice: z.number().optional().describe("Minimum price per night"),
@@ -165,7 +168,7 @@ function formatHotelResult(hotel, index) {
 // Create MCP server
 const server = new Server({
     name: "hotelzero",
-    version: "1.1.0",
+    version: "1.3.0",
 }, {
     capabilities: {
         tools: {},
@@ -192,6 +195,9 @@ const findHotelsInputSchema = {
             description: "Sort results by",
             enum: ["popularity", "price_lowest", "price_highest", "rating", "distance"]
         },
+        // Pagination
+        limit: { type: "number", description: "Maximum results to return (default: 25, max: 100)", default: 25 },
+        offset: { type: "number", description: "Number of results to skip for pagination", default: 0 },
         // Property Type
         propertyType: {
             type: "string",
@@ -353,11 +359,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     rooms: parsed.rooms,
                     currency: parsed.currency,
                     sortBy: parsed.sortBy,
+                    limit: parsed.limit,
+                    offset: parsed.offset,
                 };
                 // Build filters object from all parsed parameters
                 const filters = {};
-                // Copy all filter properties
-                const filterKeys = Object.keys(parsed).filter(k => !['destination', 'checkIn', 'checkOut', 'guests', 'rooms', 'currency', 'sortBy'].includes(k));
+                // Copy all filter properties (exclude search params)
+                const filterKeys = Object.keys(parsed).filter(k => !['destination', 'checkIn', 'checkOut', 'guests', 'rooms', 'currency', 'sortBy', 'limit', 'offset'].includes(k));
                 for (const key of filterKeys) {
                     const value = parsed[key];
                     if (value !== undefined && value !== null) {
@@ -428,15 +436,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const filtersLine = activeFilters.length > 0
                     ? `Filters: ${activeFilters.join(", ")}\n\n`
                     : "\n";
+                // Pagination info
+                const offset = parsed.offset || 0;
+                const displayLimit = parsed.limit || 25;
+                const paginationLine = offset > 0
+                    ? `Showing results ${offset + 1}-${offset + results.length} of available hotels\n\n`
+                    : "";
                 const hotelList = results
-                    .slice(0, 15) // Top 15 results
-                    .map((h, i) => formatHotelResult(h, i))
+                    .map((h, i) => formatHotelResult(h, i + offset))
                     .join("\n\n");
                 return {
                     content: [
                         {
                             type: "text",
-                            text: header + filtersLine + hotelList,
+                            text: header + filtersLine + paginationLine + hotelList,
                         },
                     ],
                 };
@@ -481,6 +494,38 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
     }
     catch (error) {
+        // Handle custom HotelSearchError with structured error info
+        if (error instanceof HotelSearchError) {
+            let helpText = "";
+            switch (error.code) {
+                case ErrorCodes.CAPTCHA_DETECTED:
+                    helpText = "\n\nTip: Wait 5-10 minutes before trying again.";
+                    break;
+                case ErrorCodes.RATE_LIMITED:
+                case ErrorCodes.BLOCKED:
+                    helpText = "\n\nTip: The server is rate-limiting requests. Wait a few minutes before trying again.";
+                    break;
+                case ErrorCodes.DESTINATION_NOT_FOUND:
+                    helpText = "\n\nTip: Check the destination spelling. Try a more specific location like 'Paris, France' instead of just 'Paris'.";
+                    break;
+                case ErrorCodes.TIMEOUT:
+                    helpText = "\n\nTip: The request timed out. This may be due to slow network or server issues. Try again.";
+                    break;
+                case ErrorCodes.NETWORK_ERROR:
+                    helpText = "\n\nTip: Check your internet connection and try again.";
+                    break;
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error [${error.code}]: ${error.message}${helpText}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Handle generic errors
         const errorMessage = error instanceof Error ? error.message : String(error);
         return {
             content: [
@@ -512,7 +557,7 @@ process.on("SIGTERM", async () => {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("HotelZero v1.1.0 running on stdio");
+    console.error("HotelZero v1.3.0 running on stdio");
 }
 main().catch((error) => {
     console.error("Fatal error:", error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hotelzero",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "MCP server for searching hotels on Booking.com with 80+ filters",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",