mcp-southwest

Instructions

Implementation Reference

• src/tools/cancel-flight.ts:20-118 (handler)

  The main handler function that executes the cancel_flight tool logic. Navigates to Southwest's manage reservation page, looks up the booking by confirmation number and passenger name, checks if cancellation is available, determines refund eligibility based on fare type, and either returns cancellation details or proceeds with cancellation if confirmed.

  export async function cancelFlight(input: CancelFlightInput) {
    const page = await getPage();
  
    // Navigate to manage reservation
    await page.goto(
      "https://www.southwest.com/air/manage-reservation/index.html",
      { waitUntil: "networkidle" }
    );
  
    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(() => {});
  
    // Get refund preview before cancelling
    const cancelButton = page.locator(
      '[data-qa="cancel-flight-btn"], [data-qa*="cancel"], a[href*="cancel"]'
    );
    const cancelAvailable = await cancelButton.isVisible().catch(() => false);
  
    if (!cancelAvailable) {
      return {
        success: false,
        message:
          "Cancel option not found. The flight may have already departed or is within the non-cancellable window.",
      };
    }
  
    // Get fare type to determine refund type
    const fareType = await page
      .locator('[data-qa="fare-type"], .fare-type-label')
      .first()
      .textContent()
      .catch(() => null);
  
    const isRefundable =
      fareType?.toLowerCase().includes("anytime") ||
      fareType?.toLowerCase().includes("business");
  
    const refundNote = isRefundable
      ? "This fare is refundable — you'll receive a full refund to your original payment method."
      : "Non-refundable fare — you'll receive Southwest travel funds valid for 12 months from original purchase date.";
  
    if (!input.confirm) {
      return {
        success: false,
        requiresConfirmation: true,
        confirmationNumber: input.confirmationNumber.toUpperCase(),
        passengerName: `${input.firstName} ${input.lastName}`,
        fareType: fareType?.trim() || "Unknown",
        isRefundable,
        refundNote,
        message: `To confirm cancellation, call this tool again with confirm: true. ${refundNote}`,
      };
    }
  
    // Proceed with cancellation
    await cancelButton.first().click();
    await page.waitForNavigation({ waitUntil: "networkidle" }).catch(() => {});
  
    // Confirm cancellation on the next page
    const confirmCancelButton = page.locator(
      '[data-qa="confirm-cancel"], [data-qa="cancel-confirm-btn"]'
    );
    if (await confirmCancelButton.isVisible().catch(() => false)) {
      await confirmCancelButton.click();
      await page.waitForNavigation({ waitUntil: "networkidle" }).catch(() => {});
    }
  
    const cancelled = await page
      .locator('[data-qa="cancellation-confirmed"], .cancellation-success')
      .isVisible()
      .catch(() => false);
  
    const travelFundsAmount = await page
      .locator('[data-qa="travel-funds-amount"], .travel-funds-value')
      .textContent()
      .catch(() => null);
  
    return {
      success: cancelled,
      confirmationNumber: input.confirmationNumber.toUpperCase(),
      passengerName: `${input.firstName} ${input.lastName}`,
      isRefundable,
      travelFundsIssued: !isRefundable,
      travelFundsAmount: travelFundsAmount?.trim() || null,
      refundNote,
      message: cancelled
        ? isRefundable
          ? "Flight cancelled. Refund will be processed to original payment method within 7 business days."
          : `Flight cancelled. Travel funds of ${travelFundsAmount || "the paid amount"} will be available in your account for 12 months.`
        : "Cancellation may have been processed — check your email for confirmation.",
    };
  }

• src/tools/cancel-flight.ts:4-18 (schema)

  Zod schema defining the input validation for cancel_flight tool. Requires confirmationNumber (6-char string), firstName, lastName, and an optional confirm boolean (defaults to false) that determines whether to actually cancel or just return cancellation details.

  export const cancelFlightSchema = z.object({
    confirmationNumber: z
      .string()
      .describe("6-character booking confirmation number"),
    firstName: z.string().describe("Passenger first name"),
    lastName: z.string().describe("Passenger last name"),
    confirm: z
      .boolean()
      .default(false)
      .describe(
        "Set to true to confirm cancellation. If false, returns cancellation details without actually cancelling."
      ),
  });
  
  export type CancelFlightInput = z.infer<typeof cancelFlightSchema>;

• src/index.ts:139-144 (registration)

  Tool registration in the TOOLS array, defining the tool name as 'cancel_flight', providing a description about cancellation policies for different fare types, and linking to the cancelFlightSchema for input validation.

  {
    name: "cancel_flight",
    description:
      "Cancel a Southwest reservation. Wanna Get Away fares receive travel funds (valid 12 months). Anytime/Business Select fares are fully refundable.",
    inputSchema: zodToJsonSchema(cancelFlightSchema),
  },

• src/index.ts:220-222 (registration)

  The case handler in the CallToolRequestSchema switch statement that routes 'cancel_flight' tool calls to the cancelFlight function, parsing input arguments with cancelFlightSchema.

  case "cancel_flight":
    result = await cancelFlight(cancelFlightSchema.parse(args));
    break;