google-flights-mcp-server 0.1.2 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "google-flights-mcp-server",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "MCP server for searching Google Flights — flight search, date grid pricing, and airport lookup",
   "main": "build/index.js",
   "type": "module",

package/shared/flights-client/flights-client.js

@@ -244,51 +244,87 @@ function parseFareBrand(raw) {
     }
 }
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
+function parseRawOffer(raw, currency) {
+    const details = raw[0];
+    const priceData = raw[1];
+    const rankData = raw[5]; // [is_best (1/0), ?, ?]
+    if (!details || !priceData)
+        return null;
+    // Parse segments
+    const segments = [];
+    const legs = details[2];
+    if (Array.isArray(legs)) {
+        for (const leg of legs) {
+            const segment = parseSegment(leg);
+            if (segment)
+                segments.push(segment);
+        }
+    }
+    const price = priceData[0]?.[1];
+    if (price === undefined || price === null)
+        return null;
+    return {
+        price,
+        currency,
+        airline: details[1]?.[0] || '',
+        airline_code: details[0] || '',
+        is_best: rankData?.[0] === 1,
+        fare_brand: parseFareBrand(raw),
+        departure: formatTime(details[5]),
+        arrival: formatTime(details[8]),
+        departure_date: formatDate(details[4]),
+        arrival_date: formatDate(details[7]),
+        duration_minutes: details[9] || 0,
+        stops: segments.length > 0 ? segments.length - 1 : 0,
+        segments,
+        extensions: parseExtensions(raw),
+        booking_token: priceData[1] || '',
+    };
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 function parseFlightOffers(ds1, currency) {
     const offers = [];
-    if (!ds1?.[3]?.[0] || !Array.isArray(ds1[3][0]))
-        return offers;
-    const rawOffers = ds1[3][0];
-    for (const raw of rawOffers) {
-        try {
-            const details = raw[0];
-            const priceData = raw[1];
-            const rankData = raw[5]; // [is_best (1/0), ?, ?]
-            if (!details || !priceData)
-                continue;
-            // Parse segments
-            const segments = [];
-            const legs = details[2];
-            if (Array.isArray(legs)) {
-                for (const leg of legs) {
-                    const segment = parseSegment(leg);
-                    if (segment)
-                        segments.push(segment);
+    const seenTokens = new Set();
+    // Google Flights returns results in two sections:
+    // - ds1[2][0]: "Best flights" (featured/highlighted flights, typically 3)
+    // - ds1[3][0]: "Other flights" (the main results list)
+    // Both sections use the same offer structure. In practice flights are not
+    // duplicated between them, but we deduplicate by booking_token defensively
+    // since this is an undocumented scraped API that could change.
+    //
+    // The is_best flag comes from raw[5][0] (per-offer rankData), not from which
+    // section the offer appears in. Google sets this flag on all ds1[2][0] offers
+    // and sometimes on ds1[3][0] offers too.
+    // Parse "best flights" from ds1[2][0]
+    const bestFlights = ds1?.[2]?.[0];
+    if (Array.isArray(bestFlights)) {
+        for (const raw of bestFlights) {
+            try {
+                const offer = parseRawOffer(raw, currency);
+                if (offer && !seenTokens.has(offer.booking_token)) {
+                    seenTokens.add(offer.booking_token);
+                    offers.push(offer);
                 }
             }
-            const price = priceData[0]?.[1];
-            if (price === undefined || price === null)
-                continue;
-            offers.push({
-                price,
-                currency,
-                airline: details[1]?.[0] || '',
-                airline_code: details[0] || '',
-                is_best: rankData?.[0] === 1,
-                fare_brand: parseFareBrand(raw),
-                departure: formatTime(details[5]),
-                arrival: formatTime(details[8]),
-                departure_date: formatDate(details[4]),
-                arrival_date: formatDate(details[7]),
-                duration_minutes: details[9] || 0,
-                stops: segments.length > 0 ? segments.length - 1 : 0,
-                segments,
-                extensions: parseExtensions(raw),
-                booking_token: priceData[1] || '',
-            });
+            catch (e) {
+                logDebug('parseFlightOffers', `Skipping malformed best offer: ${e.message}`);
+            }
         }
-        catch (e) {
-            logDebug('parseFlightOffers', `Skipping malformed offer: ${e.message}`);
+    }
+    // Parse "other flights" from ds1[3][0]
+    const otherFlights = ds1?.[3]?.[0];
+    if (Array.isArray(otherFlights)) {
+        for (const raw of otherFlights) {
+            try {
+                const offer = parseRawOffer(raw, currency);
+                if (offer && !seenTokens.has(offer.booking_token)) {
+                    seenTokens.add(offer.booking_token);
+                    offers.push(offer);
+                }
+            }
+            catch (e) {
+                logDebug('parseFlightOffers', `Skipping malformed offer: ${e.message}`);
+            }
         }
     }
     return offers;
@@ -361,6 +397,10 @@ export async function searchFlights(options) {
     let allOffers = parseFlightOffers(ds1, options.currency);
     // Apply client-side stop filter (supplements the protobuf filter)
     allOffers = filterByStops(allOffers, options.max_stops);
+    // Filter out basic economy fares (fare_brand "Economy" = tier 1, the lowest/basic tier)
+    if (options.exclude_basic_economy) {
+        allOffers = allOffers.filter((o) => o.fare_brand !== 'Economy');
+    }
     // Sort
     allOffers = sortOffers(allOffers, options.sort_by);
     const totalResults = allOffers.length;

package/shared/flights-client/types.d.ts

@@ -67,6 +67,7 @@ export interface SearchFlightsOptions {
     max_results: number;
     offset: number;
     currency: string;
+    exclude_basic_economy: boolean;
 }
 export interface SearchFlightsResult {
     query: {

package/shared/tools/search-flights.d.ts

@@ -17,10 +17,11 @@ export declare const SearchFlightsSchema: z.ZodObject<{
     max_results: z.ZodDefault<z.ZodNumber>;
     offset: z.ZodDefault<z.ZodNumber>;
     currency: z.ZodDefault<z.ZodString>;
+    exclude_basic_economy: z.ZodDefault<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
+    currency: string;
     sort_by: "best" | "price" | "duration" | "departure" | "arrival";
     max_stops: "any" | "nonstop" | "1" | "2";
-    currency: string;
     origin: string;
     destination: string;
     departure_date: string;
@@ -32,14 +33,15 @@ export declare const SearchFlightsSchema: z.ZodObject<{
     infants_on_lap: number;
     max_results: number;
     offset: number;
+    exclude_basic_economy: boolean;
     return_date?: string | undefined;
 }, {
     origin: string;
     destination: string;
     departure_date: string;
+    currency?: string | undefined;
     sort_by?: "best" | "price" | "duration" | "departure" | "arrival" | undefined;
     max_stops?: "any" | "nonstop" | "1" | "2" | undefined;
-    currency?: string | undefined;
     return_date?: string | undefined;
     trip_type?: "one_way" | "round_trip" | undefined;
     seat_class?: "economy" | "premium_economy" | "business" | "first" | undefined;
@@ -49,6 +51,7 @@ export declare const SearchFlightsSchema: z.ZodObject<{
     infants_on_lap?: number | undefined;
     max_results?: number | undefined;
     offset?: number | undefined;
+    exclude_basic_economy?: boolean | undefined;
 }>;
 export declare function searchFlightsTool(_server: Server, clientFactory: FlightsClientFactory): {
     name: string;
@@ -120,6 +123,10 @@ export declare function searchFlightsTool(_server: Server, clientFactory: Flight
                 type: string;
                 description: string;
             };
+            exclude_basic_economy: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
     };

package/shared/tools/search-flights.js

@@ -57,6 +57,10 @@ export const SearchFlightsSchema = z.object({
         .max(3)
         .default('USD')
         .describe('Currency code for prices (e.g., "USD", "EUR", "GBP")'),
+    exclude_basic_economy: z
+        .boolean()
+        .default(true)
+        .describe('Exclude basic economy fares from results (default: true). Basic economy fares typically have restrictions like no carry-on, no seat selection, and no changes. Set to false to include all fare tiers.'),
 });
 export function searchFlightsTool(_server, clientFactory) {
     return {
@@ -67,6 +71,8 @@ Returns structured flight data including prices, airlines, times, durations, sto
 
 The fare_brand field indicates the fare tier: "Economy" (basic/lowest tier), "Economy+" (mid-tier with extras), or "Economy Flex" (higher tier with more flexibility). This is derived from Google's numeric fare tier data and may be null if unavailable. Use the extensions field (carry_on_included, checked_bags_included) for concrete amenity details.
 
+By default, basic economy fares (fare_brand "Economy") are excluded from results since they typically have significant restrictions (no carry-on, no seat selection, non-refundable). Set exclude_basic_economy to false to include all fare tiers.
+
 IMPORTANT — Handling large result sets: Popular routes often return 50-150+ flights. If total_results is high, recommend narrowing with filters (max_stops, sort_by, seat_class) rather than paginating through everything. For example, set max_stops to "nonstop" or sort_by to "price" to surface the most relevant options quickly.
 
 Pagination: The response includes has_more (boolean) and next_offset (number or null). To get the next page, call search_flights again with the same parameters but set offset to next_offset. Keep paginating while has_more is true. Each page returns up to max_results flights.
@@ -137,6 +143,10 @@ Use get_date_grid to find the cheapest dates before searching.`,
                     type: 'string',
                     description: 'Currency code for prices (default: USD)',
                 },
+                exclude_basic_economy: {
+                    type: 'boolean',
+                    description: 'Exclude basic economy fares (default: true). Set to false to include all fare tiers.',
+                },
             },
             required: ['origin', 'destination', 'departure_date'],
         },