google-flights-mcp-server 0.1.1

package/shared/resources.js

@@ -0,0 +1,43 @@
+import { ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { getAllToolNames } from './tools.js';
+export function registerResources(server) {
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        return {
+            resources: [
+                {
+                    uri: 'google-flights://config',
+                    name: 'Server Configuration',
+                    description: 'Current server configuration and available tools.',
+                    mimeType: 'application/json',
+                },
+            ],
+        };
+    });
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        if (uri === 'google-flights://config') {
+            const config = {
+                server: {
+                    name: 'google-flights-mcp-server',
+                    transport: 'stdio',
+                },
+                availableTools: getAllToolNames(),
+                notes: [
+                    'No API key required — uses public Google Flights data.',
+                    'Rate limiting is applied automatically (1.5s between requests).',
+                    'Prices may vary based on currency and region.',
+                ],
+            };
+            return {
+                contents: [
+                    {
+                        uri: 'google-flights://config',
+                        mimeType: 'application/json',
+                        text: JSON.stringify(config, null, 2),
+                    },
+                ],
+            };
+        }
+        throw new Error(`Resource not found: ${uri}`);
+    });
+}

package/shared/server.d.ts

@@ -0,0 +1,54 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { SearchFlightsOptions, SearchFlightsResult, GetDateGridOptions, DateGridResult, AirportResult } from './flights-client/types.js';
+export interface IFlightsClient {
+    searchFlights(options: SearchFlightsOptions): Promise<SearchFlightsResult>;
+    getDateGrid(options: GetDateGridOptions): Promise<DateGridResult>;
+    findAirportCode(query: string): Promise<AirportResult[]>;
+}
+export type FlightsClientFactory = () => IFlightsClient;
+export declare class GoogleFlightsClient implements IFlightsClient {
+    searchFlights(options: SearchFlightsOptions): Promise<SearchFlightsResult>;
+    getDateGrid(options: GetDateGridOptions): Promise<DateGridResult>;
+    findAirportCode(query: string): Promise<AirportResult[]>;
+}
+export interface CreateMCPServerOptions {
+    version: string;
+}
+export declare function createMCPServer(options: CreateMCPServerOptions): {
+    server: Server<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    registerHandlers: (server: Server, clientFactory?: FlightsClientFactory) => Promise<void>;
+};
+//# sourceMappingURL=server.d.ts.map

package/shared/server.js

@@ -0,0 +1,33 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { registerResources } from './resources.js';
+import { createRegisterTools } from './tools.js';
+import { searchFlights, getDateGrid, findAirportCode } from './flights-client/flights-client.js';
+export class GoogleFlightsClient {
+    async searchFlights(options) {
+        return searchFlights(options);
+    }
+    async getDateGrid(options) {
+        return getDateGrid(options);
+    }
+    async findAirportCode(query) {
+        return findAirportCode(query);
+    }
+}
+export function createMCPServer(options) {
+    const server = new Server({
+        name: 'google-flights-mcp-server',
+        version: options.version,
+    }, {
+        capabilities: {
+            resources: {},
+            tools: {},
+        },
+    });
+    const registerHandlers = async (server, clientFactory) => {
+        const factory = clientFactory || (() => new GoogleFlightsClient());
+        registerResources(server);
+        const registerTools = createRegisterTools(factory);
+        registerTools(server);
+    };
+    return { server, registerHandlers };
+}

package/shared/tools/find-airport-code.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { FlightsClientFactory } from '../server.js';
+export declare const FindAirportCodeSchema: z.ZodObject<{
+    query: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+}, {
+    query: string;
+}>;
+export declare function findAirportCodeTool(_server: Server, clientFactory: FlightsClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=find-airport-code.d.ts.map

package/shared/tools/find-airport-code.js

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+export const FindAirportCodeSchema = z.object({
+    query: z
+        .string()
+        .min(1)
+        .describe('Search query: city name, airport name, or partial IATA code (e.g., "San Francisco", "Heathrow", "LAX")'),
+});
+export function findAirportCodeTool(_server, clientFactory) {
+    return {
+        name: 'find_airport_code',
+        description: `Look up airport IATA codes by city name, airport name, or partial code.
+
+Use this to find the correct airport code before calling search_flights or get_date_grid.
+
+Returns matching airports with their IATA code, full name, city, and country.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'City name, airport name, or partial code (e.g., "San Francisco", "Heathrow", "LAX")',
+                },
+            },
+            required: ['query'],
+        },
+        handler: async (args) => {
+            try {
+                const parsed = FindAirportCodeSchema.parse(args);
+                const client = clientFactory();
+                const results = await client.findAirportCode(parsed.query);
+                if (results.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    query: parsed.query,
+                                    results: [],
+                                    message: `No airports found matching "${parsed.query}". Try a different spelling or a broader search.`,
+                                }),
+                            },
+                        ],
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ query: parsed.query, results }),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [{ type: 'text', text: `Error finding airport code: ${message}` }],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/get-date-grid.d.ts

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { FlightsClientFactory } from '../server.js';
+export declare const GetDateGridSchema: z.ZodObject<{
+    origin: z.ZodString;
+    destination: z.ZodString;
+    departure_date: z.ZodOptional<z.ZodString>;
+    trip_type: z.ZodDefault<z.ZodEnum<["one_way", "round_trip"]>>;
+    seat_class: z.ZodDefault<z.ZodEnum<["economy", "premium_economy", "business", "first"]>>;
+    adults: z.ZodDefault<z.ZodNumber>;
+    currency: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    currency: string;
+    origin: string;
+    destination: string;
+    trip_type: "one_way" | "round_trip";
+    seat_class: "economy" | "premium_economy" | "business" | "first";
+    adults: number;
+    departure_date?: string | undefined;
+}, {
+    origin: string;
+    destination: string;
+    currency?: string | undefined;
+    departure_date?: string | undefined;
+    trip_type?: "one_way" | "round_trip" | undefined;
+    seat_class?: "economy" | "premium_economy" | "business" | "first" | undefined;
+    adults?: number | undefined;
+}>;
+export declare function getDateGridTool(_server: Server, clientFactory: FlightsClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            origin: {
+                type: string;
+                description: string;
+            };
+            destination: {
+                type: string;
+                description: string;
+            };
+            departure_date: {
+                type: string;
+                description: string;
+            };
+            trip_type: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            seat_class: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            adults: {
+                type: string;
+                description: string;
+            };
+            currency: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=get-date-grid.d.ts.map

package/shared/tools/get-date-grid.js

@@ -0,0 +1,106 @@
+import { z } from 'zod';
+export const GetDateGridSchema = z.object({
+    origin: z.string().min(3).max(3).describe('Origin airport IATA code (e.g., "SFO")'),
+    destination: z.string().min(3).max(3).describe('Destination airport IATA code (e.g., "LAX")'),
+    departure_date: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
+        .optional()
+        .describe('Anchor date for the grid in YYYY-MM-DD. The grid shows prices around this date. Defaults to 7 days from now.'),
+    trip_type: z.enum(['one_way', 'round_trip']).default('one_way').describe('Trip type'),
+    seat_class: z
+        .enum(['economy', 'premium_economy', 'business', 'first'])
+        .default('economy')
+        .describe('Cabin class'),
+    adults: z.number().int().min(1).max(9).default(1).describe('Number of adult passengers'),
+    currency: z
+        .string()
+        .min(3)
+        .max(3)
+        .default('USD')
+        .describe('Currency code for prices (e.g., "USD", "EUR")'),
+});
+export function getDateGridTool(_server, clientFactory) {
+    return {
+        name: 'get_date_grid',
+        description: `Get a date-price grid for a route showing the lowest flight price for each day.
+
+Returns an array of dates with their lowest prices, plus the overall cheapest date. Great for deal-hunting when the user has flexibility on travel dates — call this first to find the cheapest day, then use search_flights on that date.
+
+The grid typically covers ~60 days around the anchor date.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                origin: { type: 'string', description: 'Origin airport IATA code (e.g., "SFO")' },
+                destination: {
+                    type: 'string',
+                    description: 'Destination airport IATA code (e.g., "LAX")',
+                },
+                departure_date: {
+                    type: 'string',
+                    description: 'Anchor date in YYYY-MM-DD. Grid shows prices around this date. Default: 7 days from now.',
+                },
+                trip_type: {
+                    type: 'string',
+                    enum: ['one_way', 'round_trip'],
+                    description: 'Trip type (default: one_way)',
+                },
+                seat_class: {
+                    type: 'string',
+                    enum: ['economy', 'premium_economy', 'business', 'first'],
+                    description: 'Cabin class (default: economy)',
+                },
+                adults: {
+                    type: 'number',
+                    description: 'Number of adult passengers (default: 1)',
+                },
+                currency: {
+                    type: 'string',
+                    description: 'Currency code for prices (default: USD)',
+                },
+            },
+            required: ['origin', 'destination'],
+        },
+        handler: async (args) => {
+            try {
+                const parsed = GetDateGridSchema.parse(args);
+                const client = clientFactory();
+                const result = await client.getDateGrid(parsed);
+                if (result.date_grid.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    query: { origin: parsed.origin, destination: parsed.destination },
+                                    date_grid: [],
+                                    cheapest: null,
+                                    currency: parsed.currency,
+                                    message: 'No date grid data available. This may happen for certain routes or date ranges.',
+                                }),
+                            },
+                        ],
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                query: { origin: parsed.origin, destination: parsed.destination },
+                                ...result,
+                            }),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [{ type: 'text', text: `Error getting date grid: ${message}` }],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

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

@@ -0,0 +1,140 @@
+import { z } from 'zod';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { FlightsClientFactory } from '../server.js';
+export declare const SearchFlightsSchema: z.ZodObject<{
+    origin: z.ZodString;
+    destination: z.ZodString;
+    departure_date: z.ZodString;
+    return_date: z.ZodOptional<z.ZodString>;
+    trip_type: z.ZodDefault<z.ZodEnum<["one_way", "round_trip"]>>;
+    seat_class: z.ZodDefault<z.ZodEnum<["economy", "premium_economy", "business", "first"]>>;
+    adults: z.ZodDefault<z.ZodNumber>;
+    children: z.ZodDefault<z.ZodNumber>;
+    infants_in_seat: z.ZodDefault<z.ZodNumber>;
+    infants_on_lap: z.ZodDefault<z.ZodNumber>;
+    max_stops: z.ZodDefault<z.ZodEnum<["any", "nonstop", "1", "2"]>>;
+    sort_by: z.ZodDefault<z.ZodEnum<["best", "price", "duration", "departure", "arrival"]>>;
+    max_results: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
+    currency: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    sort_by: "best" | "price" | "duration" | "departure" | "arrival";
+    max_stops: "any" | "nonstop" | "1" | "2";
+    currency: string;
+    origin: string;
+    destination: string;
+    departure_date: string;
+    trip_type: "one_way" | "round_trip";
+    seat_class: "economy" | "premium_economy" | "business" | "first";
+    adults: number;
+    children: number;
+    infants_in_seat: number;
+    infants_on_lap: number;
+    max_results: number;
+    offset: number;
+    return_date?: string | undefined;
+}, {
+    origin: string;
+    destination: string;
+    departure_date: string;
+    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;
+    adults?: number | undefined;
+    children?: number | undefined;
+    infants_in_seat?: number | undefined;
+    infants_on_lap?: number | undefined;
+    max_results?: number | undefined;
+    offset?: number | undefined;
+}>;
+export declare function searchFlightsTool(_server: Server, clientFactory: FlightsClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            origin: {
+                type: string;
+                description: string;
+            };
+            destination: {
+                type: string;
+                description: string;
+            };
+            departure_date: {
+                type: string;
+                description: string;
+            };
+            return_date: {
+                type: string;
+                description: string;
+            };
+            trip_type: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            seat_class: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            adults: {
+                type: string;
+                description: string;
+            };
+            children: {
+                type: string;
+                description: string;
+            };
+            infants_in_seat: {
+                type: string;
+                description: string;
+            };
+            infants_on_lap: {
+                type: string;
+                description: string;
+            };
+            max_stops: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            sort_by: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            max_results: {
+                type: string;
+                description: string;
+            };
+            offset: {
+                type: string;
+                description: string;
+            };
+            currency: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    }>;
+};
+//# sourceMappingURL=search-flights.d.ts.map