mcp-southwest

Instructions

Implementation Reference

• src/tools/add-early-bird.ts:14-105 (handler)

  The main handler function `addEarlyBird` that implements the tool logic. It navigates to Southwest's manage reservation page, fills in confirmation number and passenger name, checks if Early Bird is available or already added, and completes the purchase if possible.

  export async function addEarlyBird(input: AddEarlyBirdInput) {
    const page = await getPage();
    await ensureLoggedIn(page);
  
    // Navigate to manage reservation for Early Bird
    await page.goto(
      `https://www.southwest.com/air/manage-reservation/index.html`,
      { waitUntil: "networkidle" }
    );
  
    // Fill in the look-up form
    await page.fill(
      '[data-qa="confirmation-number"], [name="confirmationNumber"]',
      input.confirmationNumber.toUpperCase()
    );
    await page.fill(
      '[data-qa="first-name"], [name="firstName"]',
      input.firstName
    );
    await page.fill(
      '[data-qa="last-name"], [name="lastName"]',
      input.lastName
    );
  
    await page.click(
      '[data-qa="search-button"], [data-qa="retrieve-button"]'
    );
    await page.waitForNavigation({ waitUntil: "networkidle" }).catch(() => {});
  
    // Look for Early Bird option
    const earlyBirdButton = page.locator(
      '[data-qa="early-bird-add"], [data-qa*="early-bird"], .early-bird-btn'
    );
    const available = await earlyBirdButton.isVisible().catch(() => false);
  
    if (!available) {
      // Check if already added
      const alreadyAdded = await page
        .locator(
          '[data-qa="early-bird-added"], .early-bird-confirmed'
        )
        .isVisible()
        .catch(() => false);
  
      if (alreadyAdded) {
        return {
          success: false,
          message:
            "Early Bird Check-In is already added to this reservation.",
          alreadyAdded: true,
        };
      }
  
      return {
        success: false,
        message:
          "Early Bird Check-In is not available for this reservation. It may not be offered for this fare type or the flight is too close to departure.",
      };
    }
  
    // Get pricing before adding
    const price = await page
      .locator('[data-qa="early-bird-price"], .early-bird-price')
      .textContent()
      .catch(() => null);
  
    await earlyBirdButton.click();
    await page.waitForNavigation({ waitUntil: "networkidle" }).catch(() => {});
  
    // Complete purchase if required
    const purchaseButton = page.locator('[data-qa="purchase-button"], [data-qa="confirm-early-bird"]');
    if (await purchaseButton.isVisible().catch(() => false)) {
      await purchaseButton.click();
      await page.waitForNavigation({ waitUntil: "networkidle" }).catch(() => {});
    }
  
    const confirmed = await page
      .locator('[data-qa="early-bird-confirmed"], .confirmation-message')
      .isVisible()
      .catch(() => false);
  
    return {
      success: confirmed,
      confirmationNumber: input.confirmationNumber.toUpperCase(),
      passengerName: `${input.firstName} ${input.lastName}`,
      price: price || "See receipt",
      message: confirmed
        ? "Early Bird Check-In added successfully. You'll automatically be checked in 36 hours before departure."
        : "Early Bird Check-In may have been added — please verify your reservation.",
      note: "Early Bird Check-In automatically checks you in 36 hours before departure, giving you a better boarding position.",
    };
  }

• src/tools/add-early-bird.ts:4-12 (schema)

  Zod schema `addEarlyBirdSchema` defining input validation with confirmationNumber (6-char string), firstName, and lastName fields, plus the TypeScript type `AddEarlyBirdInput` derived from the schema.

  export const addEarlyBirdSchema = z.object({
    confirmationNumber: z
      .string()
      .describe("Booking confirmation number (6 characters)"),
    firstName: z.string().describe("Passenger first name"),
    lastName: z.string().describe("Passenger last name"),
  });
  
  export type AddEarlyBirdInput = z.infer<typeof addEarlyBirdSchema>;

• src/index.ts:116-120 (registration)

  Tool registration in the TOOLS array defining the MCP tool with name "add_early_bird", a description explaining Early Bird Check-In functionality, and the inputSchema mapped from the Zod schema.

    name: "add_early_bird",
    description:
      "Add Early Bird Check-In to an existing reservation. Southwest automatically checks you in 36 hours before departure for a better boarding position (~$15-25 per person per flight).",
    inputSchema: zodToJsonSchema(addEarlyBirdSchema),
  },

• src/index.ts:208-210 (registration)

  The switch case handler that routes "add_early_bird" tool calls to the `addEarlyBird` function, parsing arguments with the schema before execution.

  case "add_early_bird":
    result = await addEarlyBird(addEarlyBirdSchema.parse(args));
    break;