airbnb_search

Instructions

Implementation Reference

• index.ts:36-93 (schema)

  Tool schema and definition for 'airbnb_search', specifying input parameters including location, dates, guest counts, price range, pagination cursor, and robots.txt ignore flag.

  const AIRBNB_SEARCH_TOOL: Tool = {
    name: "airbnb_search",
    description: "Search for Airbnb listings with various filters and pagination. Provide direct links to the user",
    inputSchema: {
      type: "object",
      properties: {
        location: {
          type: "string",
          description: "Location to search for (city, state, etc.)"
        },
        placeId: {
          type: "string",
          description: "Google Maps Place ID (overrides the location parameter)"
        },
        checkin: {
          type: "string",
          description: "Check-in date (YYYY-MM-DD)"
        },
        checkout: {
          type: "string",
          description: "Check-out date (YYYY-MM-DD)"
        },
        adults: {
          type: "number",
          description: "Number of adults"
        },
        children: {
          type: "number",
          description: "Number of children"
        },
        infants: {
          type: "number",
          description: "Number of infants"
        },
        pets: {
          type: "number",
          description: "Number of pets"
        },
        minPrice: {
          type: "number",
          description: "Minimum price for the stay"
        },
        maxPrice: {
          type: "number",
          description: "Maximum price for the stay"
        },
        cursor: {
          type: "string",
          description: "Base64-encoded string used for Pagination"
        },
        ignoreRobotsText: {
          type: "boolean",
          description: "Ignore robots.txt rules for this request"
        }
      },
      required: ["location"]
    }
  };

• index.ts:247-450 (handler)

  Core handler function for executing 'airbnb_search'. Constructs Airbnb search URL with filters, respects robots.txt, fetches HTML, parses embedded client data JSON using Cheerio, extracts listings with details like ID, description, price, ratings, and generates direct room URLs, supports pagination.

  async function handleAirbnbSearch(params: any) {
    const {
      location,
      placeId,
      checkin,
      checkout,
      adults = 1,
      children = 0,
      infants = 0,
      pets = 0,
      minPrice,
      maxPrice,
      cursor,
      ignoreRobotsText = false,
    } = params;
  
    // Build search URL
    const searchUrl = new URL(`${BASE_URL}/s/${encodeURIComponent(location)}/homes`);
    
    // Add placeId
    if (placeId) searchUrl.searchParams.append("place_id", placeId);
    
    // Add query parameters
    if (checkin) searchUrl.searchParams.append("checkin", checkin);
    if (checkout) searchUrl.searchParams.append("checkout", checkout);
    
    // Add guests
    const adults_int = parseInt(adults.toString());
    const children_int = parseInt(children.toString());
    const infants_int = parseInt(infants.toString());
    const pets_int = parseInt(pets.toString());
    
    const totalGuests = adults_int + children_int;
    if (totalGuests > 0) {
      searchUrl.searchParams.append("adults", adults_int.toString());
      searchUrl.searchParams.append("children", children_int.toString());
      searchUrl.searchParams.append("infants", infants_int.toString());
      searchUrl.searchParams.append("pets", pets_int.toString());
    }
    
    // Add price range
    if (minPrice) searchUrl.searchParams.append("price_min", minPrice.toString());
    if (maxPrice) searchUrl.searchParams.append("price_max", maxPrice.toString());
    
    // Add room type
    // if (roomType) {
    //   const roomTypeParam = roomType.toLowerCase().replace(/\s+/g, '_');
    //   searchUrl.searchParams.append("room_types[]", roomTypeParam);
    // }
  
    // Add cursor for pagination
    if (cursor) {
      searchUrl.searchParams.append("cursor", cursor);
    }
  
    // Check if path is allowed by robots.txt
    const path = searchUrl.pathname + searchUrl.search;
    if (!ignoreRobotsText && !isPathAllowed(path)) {
      log('warn', 'Search blocked by robots.txt', { path, url: searchUrl.toString() });
      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            error: robotsErrorMessage,
            url: searchUrl.toString(),
            suggestion: "Consider enabling 'ignore_robots_txt' in extension settings if needed for testing"
          }, null, 2)
        }],
        isError: true
      };
    }
  
    const allowSearchResultSchema: Record<string, any> = {
      demandStayListing : {
        id: true,
        description: true,
        location: true,
      },
      badges: {
        text: true,
      },
      structuredContent: {
        mapCategoryInfo: {
          body: true
        },
        mapSecondaryLine: {
          body: true
        },
        primaryLine: {
          body: true
        },
        secondaryLine: {
          body: true
        },
      },
      avgRatingA11yLabel: true,
      listingParamOverrides: true,
      structuredDisplayPrice: {
        primaryLine: {
          accessibilityLabel: true,
        },
        secondaryLine: {
          accessibilityLabel: true,
        },
        explanationData: {
          title: true,
          priceDetails: {
            items: {
              description: true,
              priceString: true
            }
          }
        }
      },
      // contextualPictures: {
      //   picture: true
      // }
    };
  
    try {
      log('info', 'Performing Airbnb search', { location, checkin, checkout, adults, children });
      
      const response = await fetchWithUserAgent(searchUrl.toString());
      const html = await response.text();
      const $ = cheerio.load(html);
      
      let staysSearchResults: any = {};
      
      try {
        const scriptElement = $("#data-deferred-state-0").first();
        if (scriptElement.length === 0) {
          throw new Error("Could not find data script element - page structure may have changed");
        }
        
        const scriptContent = $(scriptElement).text();
        if (!scriptContent) {
          throw new Error("Data script element is empty");
        }
        
        const clientData = JSON.parse(scriptContent).niobeClientData[0][1];
        const results = clientData.data.presentation.staysSearch.results;
        cleanObject(results);
        
        staysSearchResults = {
          searchResults: results.searchResults
            .map((result: any) => flattenArraysInObject(pickBySchema(result, allowSearchResultSchema)))
            .map((result: any) => {
              const id = atob(result.demandStayListing.id).split(":")[1];
              return {id, url: `${BASE_URL}/rooms/${id}`, ...result }
            }),
          paginationInfo: results.paginationInfo
        }
        
        log('info', 'Search completed successfully', { 
          resultCount: staysSearchResults.searchResults?.length || 0 
        });
      } catch (parseError) {
        log('error', 'Failed to parse search results', {
          error: parseError instanceof Error ? parseError.message : String(parseError),
          url: searchUrl.toString()
        });
        
        return {
          content: [{
            type: "text",
            text: JSON.stringify({
              error: "Failed to parse search results from Airbnb. The page structure may have changed.",
              details: parseError instanceof Error ? parseError.message : String(parseError),
              searchUrl: searchUrl.toString()
            }, null, 2)
          }],
          isError: true
        };
      }
  
      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            searchUrl: searchUrl.toString(),
            ...staysSearchResults
          }, null, 2)
        }],
        isError: false
      };
    } catch (error) {
      log('error', 'Search request failed', {
        error: error instanceof Error ? error.message : String(error),
        url: searchUrl.toString()
      });
      
      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            error: error instanceof Error ? error.message : String(error),
            searchUrl: searchUrl.toString(),
            timestamp: new Date().toISOString()
          }, null, 2)
        }],
        isError: true
      };
    }
  }

• index.ts:138-141 (registration)

  Registration of the 'airbnb_search' tool in the AIRBNB_TOOLS array, which is returned by the listTools MCP request handler.

  const AIRBNB_TOOLS = [
    AIRBNB_SEARCH_TOOL,
    AIRBNB_LISTING_DETAILS_TOOL,
  ] as const;

• index.ts:661-663 (registration)

  MCP listTools request handler that returns the registered tools including 'airbnb_search'.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: AIRBNB_TOOLS,
  }));

• index.ts:690-692 (registration)

  Dispatch logic in the MCP callTool request handler that routes 'airbnb_search' calls to the handleAirbnbSearch function.

  case "airbnb_search": {
    result = await handleAirbnbSearch(request.params.arguments);
    break;