search_reservations

Find reservations in Hostaway using guest names, dates, listing IDs, or reservation numbers to manage bookings and retrieve details.

Instructions

Lookup reservations by guest name, date range, listing, or reservation id.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`reservationId`	No
`guestName`	No
`guestEmail`	No
`listingId`	No
`arrivalStartDate`	No
`arrivalEndDate`	No
`departureStartDate`	No
`departureEndDate`	No
`limit`	No

Implementation Reference

src/tools/search-reservations.ts:51-74 (handler)

The handler for the search_reservations tool, which fetches reservations based on the provided query parameters and returns a formatted result.

async ({ reservationId, guestName, guestEmail, listingId, arrivalStartDate, arrivalEndDate, departureStartDate, departureEndDate, limit }) => {
  const reservations = reservationId != null
    ? [await client.getReservation(reservationId)]
    : await client.listReservations({
        limit: limit ?? 10,
        ...(guestName ? { match: guestName } : {}),
        ...(guestEmail ? { guestEmail } : {}),
        ...(listingId != null ? { listingId } : {}),
        ...(arrivalStartDate ? { arrivalStartDate } : {}),
        ...(arrivalEndDate ? { arrivalEndDate } : {}),
        ...(departureStartDate ? { departureStartDate } : {}),
        ...(departureEndDate ? { departureEndDate } : {}),
        includeResources: 1
      });

  return toolResult({
    total: reservations.length,
    results: reservations.map((reservation) =>
      buildReservationSearchResult({
        reservation
      })
    )
  });
}

src/tools/search-reservations.ts:24-49 (schema)

The schema definition for the search_reservations tool input parameters and output structure.

inputSchema: {
  reservationId: z.union([z.string(), z.number()]).optional(),
  guestName: z.string().optional(),
  guestEmail: z.string().optional(),
  listingId: z.union([z.string(), z.number()]).optional(),
  arrivalStartDate: z.string().optional(),
  arrivalEndDate: z.string().optional(),
  departureStartDate: z.string().optional(),
  departureEndDate: z.string().optional(),
  limit: z.number().int().min(1).max(100).optional()
},
outputSchema: {
  total: z.number(),
  results: z.array(
    z.object({
      reservationId: z.string().nullable(),
      listingId: z.string().nullable(),
      listingName: z.string().nullable(),
      guestName: z.string(),
      channel: z.enum(["Airbnb", "Booking.com", "VRBO", "Direct"]),
      arrivalDate: z.string().nullable(),
      departureDate: z.string().nullable(),
      status: z.string().nullable()
    })
  )
}

src/tools/search-reservations.ts:19-76 (registration)

Registration function for the search_reservations tool.

export function registerSearchReservationsTool(server: McpServer, client: HostawayDataClient) {
  server.registerTool(
    "search_reservations",
    {
      description: "Lookup reservations by guest name, date range, listing, or reservation id.",
      inputSchema: {
        reservationId: z.union([z.string(), z.number()]).optional(),
        guestName: z.string().optional(),
        guestEmail: z.string().optional(),
        listingId: z.union([z.string(), z.number()]).optional(),
        arrivalStartDate: z.string().optional(),
        arrivalEndDate: z.string().optional(),
        departureStartDate: z.string().optional(),
        departureEndDate: z.string().optional(),
        limit: z.number().int().min(1).max(100).optional()
      },
      outputSchema: {
        total: z.number(),
        results: z.array(
          z.object({
            reservationId: z.string().nullable(),
            listingId: z.string().nullable(),
            listingName: z.string().nullable(),
            guestName: z.string(),
            channel: z.enum(["Airbnb", "Booking.com", "VRBO", "Direct"]),
            arrivalDate: z.string().nullable(),
            departureDate: z.string().nullable(),
            status: z.string().nullable()
          })
        )
      }
    },
    async ({ reservationId, guestName, guestEmail, listingId, arrivalStartDate, arrivalEndDate, departureStartDate, departureEndDate, limit }) => {
      const reservations = reservationId != null
        ? [await client.getReservation(reservationId)]
        : await client.listReservations({
            limit: limit ?? 10,
            ...(guestName ? { match: guestName } : {}),
            ...(guestEmail ? { guestEmail } : {}),
            ...(listingId != null ? { listingId } : {}),
            ...(arrivalStartDate ? { arrivalStartDate } : {}),
            ...(arrivalEndDate ? { arrivalEndDate } : {}),
            ...(departureStartDate ? { departureStartDate } : {}),
            ...(departureEndDate ? { departureEndDate } : {}),
            includeResources: 1
          });

      return toolResult({
        total: reservations.length,
        results: reservations.map((reservation) =>
          buildReservationSearchResult({
            reservation
          })
        )
      });
    }
  );
}

Hostaway MCP