Jinko Hotel Booking MCP Server

Instructions

Implementation Reference

• src/hotel-mcp/tools/standard/search.ts:23-120 (handler)

  The main handler function for the 'search-hotels' tool. It constructs the API request for hotel availability, handles responses, stores hotels in session state, formats summaries, records telemetry metrics, and returns YAML-formatted results with pagination info.

  export async function searchHotels(params: {
    latitude: number;
    longitude: number;
    name?: string;
    check_in_date: string;
    check_out_date: string;
    adults: number;
    children: number;
    facilities?: number[];
  }) {
    const requestBody = {
      check_in_date: params.check_in_date,
      check_out_date: params.check_out_date,
      guests: [
        {
          adults: params.adults,
          children: Array(params.children).fill(8),
          infant: 0,
        },
      ],
      location: {
        latitude: params.latitude.toString(),
        longitude: params.longitude.toString(),
      },
      facility_ids: params.facilities ? params.facilities : [],
      max_results: 50,
    };
  
    // Calculate metrics data
    const nights = calculateNights(params.check_in_date, params.check_out_date);
    const totalTravelers = params.adults + params.children;
    const metrics = getMetrics();
  
    // Make API request to search for hotels
    const availabilityResult = await makeApiRequest<any>(
      "/api/v1/hotels/availability",
      "POST",
      requestBody
    );
  
    if (!availabilityResult) {
      // Record failed search call
      metrics.recordHotelSearchCall({
        location_name: params.name,
        check_in_date: params.check_in_date,
        nights: nights,
        total_travelers: totalTravelers,
        status: 'error'
      });
  
      return createYamlResponse({
        status: "error",
        message: "Failed to retrieve hotel availability data. Please try again later."
      });
    }
  
    const { session_id=null, has_more=false, hotels = [], total = 0 } = availabilityResult;
  
    // Record hotel search metrics
    metrics.recordHotelSearchResults(hotels.length);
    metrics.recordHotelSearchCall({
      location_name: params.name,
      check_in_date: params.check_in_date,
      nights: nights,
      total_travelers: totalTravelers,
      status: hotels.length === 0 ? 'empty' : 'success'
    });
  
    if (hotels.length === 0) {
      return createYamlResponse({
        status: "empty",
        message: "No hotels found matching your criteria. Please try different search parameters."
      });
    }
  
    // Store hotels in session for later retrieval
    hotels.forEach((hotel: Hotel) => {
      session.hotels[hotel.id.toString()] = hotel;
    });
  
    // Format results for response
    const hotelSummaries = hotels.map((hotel: Hotel) => formatHotelToSummaryObject(hotel));
  
    var message = `Found ${hotels.length} available hotels matching the search criteria.`;
    if (has_more) {
      message = message + " Additional hotels are available. If the user needs more options or if the current results don't meet their preferences, use the load-more-hotels tool with the provided session_id to retrieve more options."
    } else {
      message = message + " These are all available hotels matching the search criteria. If the user isn't satisfied with these options, consider suggesting modifications to their search parameters (dates, location, facilities, etc.)."
    }
  
    return createYamlResponse({
      status: "success",
      total_hotels: total,
      hotels: hotelSummaries,
      session_id: session_id,
      message: message,
    });
  }

• src/hotel-mcp/server/standard.ts:65-90 (registration)

  Registers the 'search-hotels' tool with the MCP server, including detailed description, Zod input schema for validation, and the instrumented searchHotels handler function.

  server.tool(
    "search-hotels",
    `Search for available hotels based on location coordinates and booking requirements.
  This tool returns a paginated list of hotels with their key details including name, address, 
  star rating, price range, and available room types. Each hotel includes summary information 
  about amenities and available rates.
  
  The results are limited to 50 hotels per request. If more results are available, you can 
  retrieve them using the load-more-hotels tool with the returned session_id.
  `,
    {
      latitude: z.number().describe("Latitude of the location"),
      longitude: z.number().describe("Longitude of the location"),
      name: z.string().optional().describe("Optional location name or hotel name."),
      check_in_date: z.string().default("2025-06-25").describe("Check-in date (YYYY-MM-DD)"),
      check_out_date: z.string().default("2025-06-26").describe("Check-out date (YYYY-MM-DD)"),
      adults: z.number().min(1).default(2).describe("Number of adults"),
      children: z.number().min(0).default(0).describe("Number of children"),
      search_context: z.string().optional().describe(
        "A summary of the search context which will be used by the server to better make the recommendation"),
      facilities: z.array(z.number()).optional().describe(
        "Facility IDs to filter hotels by, the IDs can be inferred with facilities resource."
      ),
    },
    getTelemetry().telemetryMiddleware.instrumentTool("search-hotels", searchHotels)
  );

• src/hotel-mcp/server/standard.ts:75-88 (schema)

  Zod schema object defining the input parameters and validation rules for the 'search-hotels' tool, including defaults and descriptions.

  {
    latitude: z.number().describe("Latitude of the location"),
    longitude: z.number().describe("Longitude of the location"),
    name: z.string().optional().describe("Optional location name or hotel name."),
    check_in_date: z.string().default("2025-06-25").describe("Check-in date (YYYY-MM-DD)"),
    check_out_date: z.string().default("2025-06-26").describe("Check-out date (YYYY-MM-DD)"),
    adults: z.number().min(1).default(2).describe("Number of adults"),
    children: z.number().min(0).default(0).describe("Number of children"),
    search_context: z.string().optional().describe(
      "A summary of the search context which will be used by the server to better make the recommendation"),
    facilities: z.array(z.number()).optional().describe(
      "Facility IDs to filter hotels by, the IDs can be inferred with facilities resource."
    ),
  },

• src/hotel-mcp/tools/standard/search.ts:13-18 (helper)

  Helper function used by searchHotels to calculate the number of nights between check-in and check-out dates for metrics recording.

  function calculateNights(checkInDate: string, checkOutDate: string): number {
    const checkIn = new Date(checkInDate);
    const checkOut = new Date(checkOutDate);
    const timeDiff = checkOut.getTime() - checkIn.getTime();
    return Math.ceil(timeDiff / (1000 * 3600 * 24));
  }