search_flights

Implementation Reference

• src/server.ts:31-113 (registration)

  Registration of the 'search_flights' tool with inline handler that handles one-way, round-trip, and multi-city flight searches using Duffel API

    'search_flights',
    flightSearchSchema.shape,
    async (params: FlightSearch) => {
      try {
        const slices = [];
        
        // Build slices based on flight type
        if (params.type === 'one_way') {
          slices.push(flightClient.createSlice(
            params.origin, 
            params.destination, 
            params.departureDate,
            params.departureTime,
            params.arrivalTime
          ));
        } else if (params.type === 'round_trip') {
          if (!params.returnDate) {
            throw new Error('Return date required for round-trip flights');
          }
          
          slices.push(flightClient.createSlice(
            params.origin,
            params.destination,
            params.departureDate,
            params.departureTime,
            params.arrivalTime
          ));
          
          slices.push(flightClient.createSlice(
            params.destination,
            params.origin,
            params.returnDate,
            params.departureTime,
            params.arrivalTime
          ));
        } else if (params.type === 'multi_city') {
          if (!params.additionalStops || params.additionalStops.length === 0) {
            throw new Error('Additional stops required for multi-city flights');
          }
          
          // First leg
          slices.push(flightClient.createSlice(
            params.origin,
            params.destination,
            params.departureDate
          ));
          
          // Additional legs
          for (const stop of params.additionalStops) {
            slices.push(flightClient.createSlice(
              stop.origin,
              stop.destination,
              stop.departureDate
            ));
          }
        }
        
        // Create the offer request
        const response = await flightClient.createOfferRequest({
          slices,
          cabin_class: params.cabinClass,
          adult_count: params.adults,
          max_connections: params.maxConnections,
          return_offers: true,
          supplier_timeout: 15000 // 15 seconds
        });
        
        // Return formatted response
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(response, null, 2)
            }
          ]
        };
        
      } catch (error) {
        console.error(`Error searching flights: ${error}`);
        throw error;
      }
    }
  );

• src/server.ts:33-112 (handler)

  Handler function that constructs flight slices from input parameters and requests offers from Duffel API

  async (params: FlightSearch) => {
    try {
      const slices = [];
      
      // Build slices based on flight type
      if (params.type === 'one_way') {
        slices.push(flightClient.createSlice(
          params.origin, 
          params.destination, 
          params.departureDate,
          params.departureTime,
          params.arrivalTime
        ));
      } else if (params.type === 'round_trip') {
        if (!params.returnDate) {
          throw new Error('Return date required for round-trip flights');
        }
        
        slices.push(flightClient.createSlice(
          params.origin,
          params.destination,
          params.departureDate,
          params.departureTime,
          params.arrivalTime
        ));
        
        slices.push(flightClient.createSlice(
          params.destination,
          params.origin,
          params.returnDate,
          params.departureTime,
          params.arrivalTime
        ));
      } else if (params.type === 'multi_city') {
        if (!params.additionalStops || params.additionalStops.length === 0) {
          throw new Error('Additional stops required for multi-city flights');
        }
        
        // First leg
        slices.push(flightClient.createSlice(
          params.origin,
          params.destination,
          params.departureDate
        ));
        
        // Additional legs
        for (const stop of params.additionalStops) {
          slices.push(flightClient.createSlice(
            stop.origin,
            stop.destination,
            stop.departureDate
          ));
        }
      }
      
      // Create the offer request
      const response = await flightClient.createOfferRequest({
        slices,
        cabin_class: params.cabinClass,
        adult_count: params.adults,
        max_connections: params.maxConnections,
        return_offers: true,
        supplier_timeout: 15000 // 15 seconds
      });
      
      // Return formatted response
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(response, null, 2)
          }
        ]
      };
      
    } catch (error) {
      console.error(`Error searching flights: ${error}`);
      throw error;
    }
  }

• src/models/flightSearch.ts:21-33 (schema)

  Zod schema defining the input parameters for the search_flights tool

  export const flightSearchSchema = z.object({
    type: z.enum(['one_way', 'round_trip', 'multi_city']).describe('Type of flight'),
    origin: z.string().describe('Origin airport or city IATA code (e.g., SFO, NYC)'),
    destination: z.string().describe('Destination airport or city IATA code (e.g., LAX, LHR)'),
    departureDate: z.string().describe('Departure date in YYYY-MM-DD format'),
    returnDate: z.string().optional().describe('Return date in YYYY-MM-DD format (required for round-trip)'),
    departureTime: timeSpecSchema.optional().describe('Preferred departure time window'),
    arrivalTime: timeSpecSchema.optional().describe('Preferred arrival time window'),
    cabinClass: z.enum(['economy', 'premium_economy', 'business', 'first']).describe('Cabin class'),
    adults: z.number().min(1).default(1).describe('Number of adult passengers'),
    maxConnections: z.number().optional().describe('Maximum number of connections'),
    additionalStops: z.array(flightSegmentSchema).optional().describe('Additional stops for multi-city flights')
  });

• src/api/duffelClient.ts:228-264 (helper)

  Helper method to create flight slice objects used in offer requests

  createSlice(
    origin: string, 
    destination: string, 
    date: string,
    departureTime?: TimeSpec,
    arrivalTime?: TimeSpec
  ): Slice {
    const slice: Slice = {
      origin,
      destination,
      departure_date: date,
      departure_time: {
        from: '00:00',
        to: '23:59'
      },
      arrival_time: {
        from: '00:00',
        to: '23:59'
      }
    };
    
    if (departureTime) {
      slice.departure_time = {
        from: departureTime.fromTime,
        to: departureTime.toTime
      };
    }
    
    if (arrivalTime) {
      slice.arrival_time = {
        from: arrivalTime.fromTime,
        to: arrivalTime.toTime
      };
    }
    
    return slice;
  }

• src/api/duffelClient.ts:93-205 (helper)

  Core helper that performs the Duffel API call to create flight offer requests and formats the response

  async createOfferRequest(params: OfferRequestParams): Promise<FormattedOfferResponse> {
    try {
      // Prepare the passengers array
      const passengers = Array(params.adult_count).fill({ type: 'adult' });
      
      // Create the request data
      const requestData = {
        data: {
          slices: params.slices,
          passengers,
          cabin_class: params.cabin_class
        }
      };
  
      if (params.max_connections !== undefined) {
        (requestData.data as any).max_connections = params.max_connections;
      }
  
      // Build query parameters
      const queryParams = {
        'return_offers': params.return_offers.toString(),
        'supplier_timeout': params.supplier_timeout.toString()
      };
  
      // Make the API call
      console.log(`Creating offer request with data: ${JSON.stringify(requestData)}`);
      
      const response = await this.client.post('/offer_requests', requestData, { 
        params: queryParams 
      });
      
      const responseData = response.data;
      
      const requestId = responseData.data.id;
      const offers = responseData.data.offers || [];
      
      console.log(`Created offer request with ID: ${requestId}`);
      console.log(`Received ${offers.length} offers`);
      
      // Format the response
      const formattedResponse: FormattedOfferResponse = {
        request_id: requestId,
        offers: []
      };
      
      // Process offers (limit to 50 to manage response size)
      formattedResponse.offers = offers.slice(0, 50).map((offer: any) => {
        const formattedOffer: FormattedOffer = {
          offer_id: offer.id,
          price: {
            amount: offer.total_amount,
            currency: offer.total_currency,
          },
          slices: []
        };
        
        // Process slices
        if (offer.slices) {
          formattedOffer.slices = offer.slices.map((slice: any) => {
            const segments = slice.segments || [];
            
            if (segments.length === 0) {
              return {
                origin: slice.origin.iata_code,
                destination: slice.destination.iata_code,
                departure: '',
                arrival: '',
                duration: slice.duration || '',
                carrier: '',
                stops: 0,
                stops_description: 'No segments available',
                connections: []
              };
            }
            
            const sliceDetails: SliceDetails = {
              origin: slice.origin.iata_code,
              destination: slice.destination.iata_code,
              departure: segments[0].departing_at || '',
              arrival: segments[segments.length - 1].arriving_at || '',
              duration: slice.duration || '',
              carrier: segments[0].marketing_carrier?.name || '',
              stops: segments.length - 1,
              stops_description: segments.length === 1 ? 'Non-stop' : `${segments.length - 1} stop${segments.length - 1 > 1 ? 's' : ''}`,
              connections: []
            };
            
            // Add connection information
            if (segments.length > 1) {
              for (let i = 0; i < segments.length - 1; i++) {
                sliceDetails.connections.push({
                  airport: segments[i].destination?.iata_code || '',
                  arrival: segments[i].arriving_at || '',
                  departure: segments[i + 1].departing_at || '',
                  duration: segments[i + 1].duration || ''
                });
              }
            }
            
            return sliceDetails;
          });
        }
        
        return formattedOffer;
      });
      
      return formattedResponse;
      
    } catch (error) {
      console.error(`Error creating offer request: ${error}`);
      throw error;
    }
  }