mcp-southwest

Instructions

Implementation Reference

• src/tools/change-flight.ts:32-113 (handler)

  The main handler function 'changeFlight' that executes the change flight tool logic. It navigates to Southwest's manage reservation page, fills in confirmation number and passenger details, finds and clicks the change flight button, and allows updating departure/return dates and origin/destination airports.

  export async function changeFlight(input: ChangeFlightInput) {
    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(() => {});
  
    // Find and click the "Change Flight" button
    const changeButton = page.locator(
      '[data-qa="change-flight-btn"], [data-qa*="change"], a[href*="change"]'
    );
    const changeAvailable = await changeButton.isVisible().catch(() => false);
  
    if (!changeAvailable) {
      return {
        success: false,
        message:
          "Change flight option not found. The flight may be within 10 minutes of departure or may not be eligible for changes.",
      };
    }
  
    await changeButton.first().click();
    await page.waitForNavigation({ waitUntil: "networkidle" }).catch(() => {});
  
    // Fill in new flight search if dates provided
    if (input.newDepartureDate) {
      await page
        .fill(
          '[data-qa="new-departure-date"], [name*="departureDate"]',
          input.newDepartureDate
        )
        .catch(() => {});
    }
    if (input.newOriginAirport) {
      await page
        .fill(
          '[data-qa="origin-airport"], [name*="origin"]',
          input.newOriginAirport.toUpperCase()
        )
        .catch(() => {});
    }
    if (input.newDestinationAirport) {
      await page
        .fill(
          '[data-qa="destination-airport"], [name*="destination"]',
          input.newDestinationAirport.toUpperCase()
        )
        .catch(() => {});
    }
  
    // Search for new flights
    await page.click('[data-qa="search-button"], [data-qa="find-flights"]').catch(() => {});
    await page.waitForNavigation({ waitUntil: "networkidle" }).catch(() => {});
  
    const flightsAvailable = await page
      .locator('[data-qa="flight-card"]')
      .isVisible()
      .catch(() => false);
  
    return {
      success: true,
      confirmationNumber: input.confirmationNumber.toUpperCase(),
      message: flightsAvailable
        ? "Available flights for your change are now shown. Southwest charges no change fees — you only pay (or receive credit for) any fare difference."
        : "Change flight page loaded. Please review available options.",
      noChangeFee: true,
      note: "Southwest Airlines never charges change fees. If the new fare is lower, you'll receive a travel fund credit. If higher, you pay the difference.",
      currentUrl: page.url(),
    };
  }

• src/tools/change-flight.ts:4-30 (schema)

  The Zod schema 'changeFlightSchema' defining input validation with confirmation number, first/last name, optional new departure/return dates, and optional new origin/destination airport codes. Also exports the TypeScript type 'ChangeFlightInput'.

  export const changeFlightSchema = 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"),
    newDepartureDate: z
      .string()
      .optional()
      .describe("New departure date YYYY-MM-DD (for outbound flight change)"),
    newReturnDate: z
      .string()
      .optional()
      .describe("New return date YYYY-MM-DD (for return flight change)"),
    newOriginAirport: z
      .string()
      .length(3)
      .optional()
      .describe("New origin airport code (if changing route)"),
    newDestinationAirport: z
      .string()
      .length(3)
      .optional()
      .describe("New destination airport code (if changing route)"),
  });
  
  export type ChangeFlightInput = z.infer<typeof changeFlightSchema>;

• src/index.ts:133-138 (registration)

  Tool registration in the TOOLS array that defines 'change_flight' with its description about Southwest's no change fee policy and references the changeFlightSchema for input validation.

  {
    name: "change_flight",
    description:
      "Modify an existing Southwest booking. Southwest never charges change fees — you only pay/receive credit for fare differences.",
    inputSchema: zodToJsonSchema(changeFlightSchema),
  },

• src/index.ts:217-219 (handler)

  The switch case in the CallToolRequestSchema handler that dispatches 'change_flight' tool calls to the changeFlight function after parsing arguments with the schema.

  case "change_flight":
    result = await changeFlight(changeFlightSchema.parse(args));
    break;

• src/index.ts:29-29 (registration)

  Import statement that brings in the changeFlight handler and changeFlightSchema from the tools/change-flight.js module.

  import { changeFlight, changeFlightSchema } from "./tools/change-flight.js";