Hopper MCP Server

Instructions

Implementation Reference

• src/index.ts:447-544 (handler)

  The 'getBookings' function implements the logic to retrieve booking information from the Hopper website. It navigates to the trips page, checks for authentication, and extracts booking data.

  async function getBookings(params: GetBookingsParams): Promise<string> {
    const page = await session.newPage();
    try {
      await page.goto("https://www.hopper.com/trips", { waitUntil: "domcontentloaded", timeout: 30000 });
      await page.waitForTimeout(2000);
  
      const requiresAuth = await page.evaluate(() =>
        !!document.querySelector("[class*='login'], [class*='signin'], [href*='/login'], [data-testid*='login']")
      );
  
      if (requiresAuth) {
        return JSON.stringify({
          status: "authentication_required",
          email: params.email,
          booking_type: params.booking_type ?? "all",
          message: "Viewing bookings requires signing in to your Hopper account.",
          next_steps: [
            "1. Sign in at https://www.hopper.com/login with your email",
            "2. Navigate to 'Trips' to see all current and past bookings",
            "3. Each booking shows status, itinerary details, and any applicable credits",
          ],
          hopper_trips_url: "https://www.hopper.com/trips",
        }, null, 2);
      }
  
      const bookings = await page.evaluate((bookingType: string) => {
        const items: Array<{
          id: string;
          type: string;
          status: string;
          summary: string;
          date: string;
          price: string;
        }> = [];
  
        document.querySelectorAll("[class*='trip'], [class*='booking'], [class*='itinerary']").forEach((el, i) => {
          const text = el.textContent ?? "";
          if (!text.trim()) return;
  
          const isFlight = text.match(/flight|airline|airport/i);
          const isHotel = text.match(/hotel|check-in|check-out/i);
  
          if (bookingType === "flight" && !isFlight) return;
          if (bookingType === "hotel" && !isHotel) return;
  
          items.push({
            id: `booking_${i + 1}`,
            type: isFlight ? "flight" : isHotel ? "hotel" : "other",
            status: text.match(/cancelled|canceled/i) ? "cancelled"
              : text.match(/upcoming|confirmed/i) ? "confirmed"
              : text.match(/completed|past/i) ? "completed"
              : "unknown",
            summary: text.slice(0, 150).trim(),
            date: el.querySelector("[class*='date'], time")?.textContent?.trim() ?? "",
            price: text.match(/\$[\d,]+/)?.[0] ?? "",
          });
        });
  
        return items;
      }, params.booking_type ?? "all");
  
      return JSON.stringify({
        email: params.email,
        booking_type: params.booking_type ?? "all",
        bookings,
        total_found: bookings.length,
        source_url: page.url(),
        retrieved_at: new Date().toISOString(),
      }, null, 2);
    } finally {
      await page.close();
    }
  }
  
  // ── Helpers ──────────────────────────────────────────────────────────────────
  
  function deriveRecommendation(prices: number[]): string {
    if (prices.length === 0) return "watch";
    const avg = prices.reduce((a, b) => a + b, 0) / prices.length;
    const min = Math.min(...prices);
    return min < avg * 0.9 ? "buy now" : min > avg * 1.1 ? "wait" : "watch";
  }
  
  function buildAnalysis(params: PriceForecastParams, avgPrice: number | null, recommendation: string | null): string {
    const rec = recommendation ?? "watch";
    const price = avgPrice ? `$${avgPrice}` : "current market rates";
    if (rec.includes("buy")) {
      return `Prices for ${params.trip_type === "flight" ? `flights to ${params.destination}` : `hotels in ${params.destination}`} on ${params.travel_date} are currently at ${price}, which is below average. Hopper recommends booking now.`;
    }
    if (rec.includes("wait")) {
      return `Prices at ${price} are elevated. Hopper's AI predicts they may drop closer to the travel date. Consider watching for a few more days.`;
    }
    return `Prices at ${price} are near average. Monitor daily — Hopper will alert you when the optimal booking window opens.`;
  }
  
  function generateMockFlights(params: FlightSearchParams) {
    const airlines = ["United", "Delta", "American", "Southwest", "JetBlue"];
    return airlines.slice(0, 3).map((airline, i) => ({

• src/index.ts:708-724 (registration)

  Tool definition and registration for 'get_bookings' in the 'TOOLS' array.

  {
    name: "get_bookings",
    description:
      "View current and past bookings from a Hopper account. Returns flight and hotel booking history with status, itinerary details, and pricing.",
    inputSchema: {
      type: "object",
      properties: {
        email: { type: "string", description: "Email address associated with the Hopper account" },
        booking_type: {
          type: "string",
          enum: ["flight", "hotel", "all"],
          description: "Filter by booking type (default: all)",
        },
      },
      required: ["email"],
    },
  },

• src/index.ts:69-72 (schema)

  Type definition for 'GetBookingsParams'.

  interface GetBookingsParams {
    email: string;
    booking_type?: "flight" | "hotel" | "all";
  }