google-flights-mcp-server 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "google-flights-mcp-server",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "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

@@ -204,6 +204,46 @@ function parseSegment(leg) {
     };
 }
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
+function parseExtensions(raw) {
+    // offer[4][6] contains baggage amenity flags: [carry_on_flag, checked_bag_flag]
+    // carry_on_flag: 0 = included
+    // checked_bag_flag: 0 = not included, 1 = one bag included, 2 = two bags included
+    const amenityFlags = raw?.[4]?.[6];
+    const carryOnIncluded = Array.isArray(amenityFlags) ? amenityFlags[0] === 0 : true;
+    const checkedBagsIncluded = Array.isArray(amenityFlags) ? amenityFlags[1] || 0 : 0;
+    return {
+        carry_on_included: carryOnIncluded,
+        checked_bags_included: checkedBagsIncluded,
+    };
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function parseFareBrand(raw) {
+    // Google Flights does not include fare brand names (e.g. "Basic Economy", "Main Cabin")
+    // in the initial search results HTML. However, details[22][2] contains a numeric fare tier
+    // indicator that correlates with fare restrictions and amenity levels.
+    //
+    // Observed mapping from cross-referencing with amenity data and pricing patterns:
+    //   1 = Economy (lowest tier for the airline — often "Basic Economy" for US carriers)
+    //   2 = Economy+ / Standard (mid-tier with some extras like seat selection)
+    //   3 = Economy Flex / Full (higher tier with more flexibility, carry-on, etc.)
+    //
+    // This is a best-effort interpretation of undocumented numeric codes.
+    // Use the `extensions` field for concrete amenity details (carry-on, checked bags).
+    const fareTier = raw?.[0]?.[22]?.[2];
+    if (fareTier === undefined || fareTier === null)
+        return null;
+    switch (fareTier) {
+        case 1:
+            return 'Economy';
+        case 2:
+            return 'Economy+';
+        case 3:
+            return 'Economy Flex';
+        default:
+            return null;
+    }
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 function parseFlightOffers(ds1, currency) {
     const offers = [];
     if (!ds1?.[3]?.[0] || !Array.isArray(ds1[3][0]))
@@ -235,6 +275,7 @@ function parseFlightOffers(ds1, 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]),
@@ -242,6 +283,7 @@ function parseFlightOffers(ds1, currency) {
                 duration_minutes: details[9] || 0,
                 stops: segments.length > 0 ? segments.length - 1 : 0,
                 segments,
+                extensions: parseExtensions(raw),
                 booking_token: priceData[1] || '',
             });
         }
@@ -319,6 +361,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

@@ -15,12 +15,17 @@ export interface FlightSegment {
     duration_minutes: number;
     legroom: string | null;
 }
+export interface FlightExtensions {
+    carry_on_included: boolean;
+    checked_bags_included: number;
+}
 export interface FlightOffer {
     price: number;
     currency: string;
     airline: string;
     airline_code: string;
     is_best: boolean;
+    fare_brand: string | null;
     departure: string;
     arrival: string;
     departure_date: string;
@@ -28,6 +33,7 @@ export interface FlightOffer {
     duration_minutes: number;
     stops: number;
     segments: FlightSegment[];
+    extensions: FlightExtensions;
     booking_token: string;
 }
 export interface DateGridEntry {
@@ -61,6 +67,7 @@ export interface SearchFlightsOptions {
     max_results: number;
     offset: number;
     currency: string;
+    exclude_basic_economy: boolean;
 }
 export interface SearchFlightsResult {
     query: {

package/shared/index.d.ts

@@ -2,6 +2,6 @@ export { registerResources } from './resources.js';
 export { createRegisterTools, getAllToolNames } from './tools.js';
 export { createMCPServer, GoogleFlightsClient, type CreateMCPServerOptions, type FlightsClientFactory, type IFlightsClient, } from './server.js';
 export { searchFlights, getDateGrid, findAirportCode, buildTfsParam, } from './flights-client/flights-client.js';
-export type { FlightOffer, FlightSegment, DateGridEntry, DateGridResult, AirportResult, SearchFlightsOptions, SearchFlightsResult, GetDateGridOptions, SeatClass, TripType, } from './flights-client/types.js';
+export type { FlightOffer, FlightSegment, FlightExtensions, DateGridEntry, DateGridResult, AirportResult, SearchFlightsOptions, SearchFlightsResult, GetDateGridOptions, SeatClass, TripType, } from './flights-client/types.js';
 export { logServerStart, logError, logWarning, logInfo, logDebug } from './logging.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -17,6 +17,7 @@ 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, {
     sort_by: "best" | "price" | "duration" | "departure" | "arrival";
     max_stops: "any" | "nonstop" | "1" | "2";
@@ -32,6 +33,7 @@ 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;
@@ -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,13 +57,21 @@ 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 {
         name: 'search_flights',
         description: `Search for flights on Google Flights with full filtering and pagination.
 
-Returns structured flight data including prices, airlines, times, durations, stops, and individual flight segments with aircraft type and legroom.
+Returns structured flight data including prices, airlines, times, durations, stops, individual flight segments with aircraft type and legroom, fare brand (e.g. "Economy", "Economy+", "Economy Flex"), and fare extensions (carry-on and checked bag inclusion).
+
+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.
 
@@ -135,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'],
         },