travel-assistant-mcp 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Forgemesh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# Travel Assistant MCP
+
+Public MCP server for travel search workflows. It gives agents a small set of tools for airport lookup, route comparison, travel timing guidance, and external booking links.
+
+## Features
+
+- Search workflow responses using generic travel search providers
+- Airport metadata lookup by IATA code
+- Basic route comparison for provider integrations
+- External booking links for booking partners
+- Commission-eligible links disclosed in tool output
+
+## Install
+
+```bash
+pnpm install
+pnpm build
+```
+
+## Run
+
+```bash
+pnpm start
+```
+
+## MCP Client Example
+
+```json
+{
+  "mcpServers": {
+    "travel-assistant": {
+      "command": "travel-assistant-mcp"
+    }
+  }
+}
+```
+
+## Tools
+
+- `search_travel_options`
+- `get_airport_info`
+- `compare_routes`
+- `build_booking_link`
+- `explain_travel_timing`
+
+## Public Data Boundary
+
+This package uses generic language for provider integrations. Tool responses may include external booking links and commission-eligible links. Booking completion happens with booking partners outside this MCP server.

package/dist/airports.d.ts

@@ -0,0 +1,9 @@
+export interface Airport {
+    code: string;
+    name: string;
+    city: string;
+    country: string;
+    timezone: string;
+}
+export declare const AIRPORTS: Record<string, Airport>;
+export declare function getAirport(code: string): Airport | null;

package/dist/airports.js

@@ -0,0 +1,20 @@
+export const AIRPORTS = {
+    JFK: { code: "JFK", name: "John F. Kennedy International Airport", city: "New York", country: "US", timezone: "America/New_York" },
+    LGA: { code: "LGA", name: "LaGuardia Airport", city: "New York", country: "US", timezone: "America/New_York" },
+    EWR: { code: "EWR", name: "Newark Liberty International Airport", city: "Newark", country: "US", timezone: "America/New_York" },
+    LAX: { code: "LAX", name: "Los Angeles International Airport", city: "Los Angeles", country: "US", timezone: "America/Los_Angeles" },
+    SFO: { code: "SFO", name: "San Francisco International Airport", city: "San Francisco", country: "US", timezone: "America/Los_Angeles" },
+    ORD: { code: "ORD", name: "O'Hare International Airport", city: "Chicago", country: "US", timezone: "America/Chicago" },
+    ATL: { code: "ATL", name: "Hartsfield-Jackson Atlanta International Airport", city: "Atlanta", country: "US", timezone: "America/New_York" },
+    DFW: { code: "DFW", name: "Dallas/Fort Worth International Airport", city: "Dallas", country: "US", timezone: "America/Chicago" },
+    IAH: { code: "IAH", name: "George Bush Intercontinental Airport", city: "Houston", country: "US", timezone: "America/Chicago" },
+    HOU: { code: "HOU", name: "William P. Hobby Airport", city: "Houston", country: "US", timezone: "America/Chicago" },
+    MIA: { code: "MIA", name: "Miami International Airport", city: "Miami", country: "US", timezone: "America/New_York" },
+    LAS: { code: "LAS", name: "Harry Reid International Airport", city: "Las Vegas", country: "US", timezone: "America/Los_Angeles" },
+    SEA: { code: "SEA", name: "Seattle-Tacoma International Airport", city: "Seattle", country: "US", timezone: "America/Los_Angeles" },
+    BOS: { code: "BOS", name: "Boston Logan International Airport", city: "Boston", country: "US", timezone: "America/New_York" },
+    DEN: { code: "DEN", name: "Denver International Airport", city: "Denver", country: "US", timezone: "America/Denver" },
+};
+export function getAirport(code) {
+    return AIRPORTS[code.toUpperCase()] ?? null;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { getAirport } from "./airports.js";
+import { buildExternalBookingLink } from "./links.js";
+import { getTravelTimingAdvice, isInternationalRoute } from "./timing.js";
+const RESPONSE_BASE = {
+    source: "travel-assistant-mcp",
+    provider_language: "travel search providers",
+    integration_language: "provider integrations",
+    booking_language: "booking partners",
+};
+function textResponse(payload, isError = false) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+        isError,
+    };
+}
+const server = new Server({ name: "travel-assistant-mcp", version: "0.1.1" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "search_travel_options",
+            description: "Prepare a travel search workflow for two airports. Returns generic provider guidance and external booking links.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    origin: { type: "string", description: "Origin airport IATA code" },
+                    destination: { type: "string", description: "Destination airport IATA code" },
+                    departure_date: { type: "string", description: "Departure date YYYY-MM-DD" },
+                    return_date: { type: "string", description: "Return date YYYY-MM-DD" },
+                    currency: { type: "string", description: "Currency code" },
+                },
+                required: ["origin", "destination"],
+            },
+        },
+        {
+            name: "get_airport_info",
+            description: "Get basic metadata for an airport by IATA code.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    code: { type: "string", description: "IATA airport code" },
+                },
+                required: ["code"],
+            },
+        },
+        {
+            name: "compare_routes",
+            description: "Compare several airport pairs using generic route metadata.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    routes: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                origin: { type: "string" },
+                                destination: { type: "string" },
+                            },
+                            required: ["origin", "destination"],
+                        },
+                    },
+                },
+                required: ["routes"],
+            },
+        },
+        {
+            name: "build_booking_link",
+            description: "Build an external booking link for a route.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    origin: { type: "string", description: "Origin airport code" },
+                    destination: { type: "string", description: "Destination airport code" },
+                    departure_date: { type: "string", description: "Departure date YYYY-MM-DD" },
+                    return_date: { type: "string", description: "Return date YYYY-MM-DD" },
+                    currency: { type: "string", description: "Currency code" },
+                },
+                required: [],
+            },
+        },
+        {
+            name: "explain_travel_timing",
+            description: "Return general timing guidance for domestic or international routes.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    origin: { type: "string", description: "Origin airport code" },
+                    destination: { type: "string", description: "Destination airport code" },
+                },
+                required: [],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    switch (name) {
+        case "search_travel_options": {
+            const origin = String(args.origin ?? "").toUpperCase();
+            const destination = String(args.destination ?? "").toUpperCase();
+            const departureDate = args.departure_date ? String(args.departure_date) : undefined;
+            const returnDate = args.return_date ? String(args.return_date) : undefined;
+            const currency = args.currency ? String(args.currency).toUpperCase() : "USD";
+            if (!origin || !destination) {
+                return textResponse({ ok: false, error: "origin and destination are required" }, true);
+            }
+            return textResponse({
+                ok: true,
+                ...RESPONSE_BASE,
+                results: {
+                    route: { origin, destination },
+                    trip_type: returnDate ? "round_trip" : "one_way",
+                    departure_date: departureDate ?? null,
+                    return_date: returnDate ?? null,
+                    currency,
+                    provider_integrations: "travel search providers",
+                    booking_partners: "external booking links",
+                    link_disclosure: "Results can include commission-eligible links.",
+                    external_booking_link: buildExternalBookingLink({
+                        origin,
+                        destination,
+                        departure_date: departureDate,
+                        return_date: returnDate,
+                        currency,
+                    }),
+                },
+            });
+        }
+        case "get_airport_info": {
+            const code = String(args.code ?? "").toUpperCase();
+            if (!code)
+                return textResponse({ ok: false, error: "code is required" }, true);
+            const airport = getAirport(code);
+            if (!airport)
+                return textResponse({ ok: false, ...RESPONSE_BASE, results: null, error: `Airport ${code} not found` }, true);
+            return textResponse({ ok: true, ...RESPONSE_BASE, results: airport });
+        }
+        case "compare_routes": {
+            const routes = Array.isArray(args.routes) ? args.routes : [];
+            if (routes.length === 0)
+                return textResponse({ ok: false, error: "routes array is required" }, true);
+            const comparisons = routes.map((route) => {
+                const origin = String(route.origin ?? "").toUpperCase();
+                const destination = String(route.destination ?? "").toUpperCase();
+                return {
+                    route: `${origin}-${destination}`,
+                    origin,
+                    destination,
+                    route_type: isInternationalRoute(origin, destination) ? "international" : "domestic",
+                    external_booking_link: buildExternalBookingLink({ origin, destination }),
+                };
+            });
+            return textResponse({
+                ok: true,
+                ...RESPONSE_BASE,
+                results: {
+                    comparisons,
+                    link_disclosure: "Comparison results can include commission-eligible links from booking partners.",
+                },
+            });
+        }
+        case "build_booking_link": {
+            const origin = args.origin ? String(args.origin).toUpperCase() : undefined;
+            const destination = args.destination ? String(args.destination).toUpperCase() : undefined;
+            const departureDate = args.departure_date ? String(args.departure_date) : undefined;
+            const returnDate = args.return_date ? String(args.return_date) : undefined;
+            const currency = args.currency ? String(args.currency).toUpperCase() : "USD";
+            return textResponse({
+                ok: true,
+                ...RESPONSE_BASE,
+                results: {
+                    external_booking_link: buildExternalBookingLink({
+                        origin,
+                        destination,
+                        departure_date: departureDate,
+                        return_date: returnDate,
+                        currency,
+                    }),
+                    link_disclosure: "This may be a commission-eligible link from booking partners.",
+                },
+            });
+        }
+        case "explain_travel_timing": {
+            const origin = args.origin ? String(args.origin).toUpperCase() : "";
+            const destination = args.destination ? String(args.destination).toUpperCase() : "";
+            const routeType = isInternationalRoute(origin, destination);
+            return textResponse({
+                ok: true,
+                ...RESPONSE_BASE,
+                results: {
+                    route: origin && destination ? { origin, destination } : null,
+                    timing_advice: getTravelTimingAdvice(routeType),
+                },
+            });
+        }
+        default:
+            return textResponse({ ok: false, error: `Unknown tool: ${name}` }, true);
+    }
+});
+const transport = new StdioServerTransport();
+void server.connect(transport);

package/dist/links.d.ts

@@ -0,0 +1 @@
+export declare function buildExternalBookingLink(params: Record<string, string | undefined>, baseUrl?: string): string;

package/dist/links.js

@@ -0,0 +1,9 @@
+const DEFAULT_BASE_URL = "https://travel.forgemesh.io";
+export function buildExternalBookingLink(params, baseUrl = DEFAULT_BASE_URL) {
+    const url = new URL(baseUrl);
+    for (const [key, value] of Object.entries(params)) {
+        if (value)
+            url.searchParams.set(key, value);
+    }
+    return url.toString();
+}

package/dist/timing.d.ts

@@ -0,0 +1,14 @@
+export interface TimingAdvice {
+    route_type: "domestic" | "international";
+    booking_window: {
+        min_weeks: number;
+        max_weeks: number;
+        sweet_spot: string;
+    };
+    lower_demand_days: string[];
+    lower_demand_months: string[];
+    data_source: string;
+    note: string;
+}
+export declare function getTravelTimingAdvice(international: boolean): TimingAdvice;
+export declare function isInternationalRoute(origin: string, destination: string): boolean;

package/dist/timing.js

@@ -0,0 +1,28 @@
+import { getAirport } from "./airports.js";
+export function getTravelTimingAdvice(international) {
+    const note = "General travel planning guidance based on broad public market patterns. " +
+        "Actual results vary by carrier, route, season, and provider integrations.";
+    if (international) {
+        return {
+            route_type: "international",
+            booking_window: { min_weeks: 8, max_weeks: 24, sweet_spot: "10 to 16 weeks before departure" },
+            lower_demand_days: ["Tuesday", "Wednesday"],
+            lower_demand_months: ["January", "February", "September", "October"],
+            data_source: "General public travel planning patterns",
+            note,
+        };
+    }
+    return {
+        route_type: "domestic",
+        booking_window: { min_weeks: 3, max_weeks: 10, sweet_spot: "4 to 8 weeks before departure" },
+        lower_demand_days: ["Tuesday", "Wednesday", "Saturday"],
+        lower_demand_months: ["January", "February", "September"],
+        data_source: "General public travel planning patterns",
+        note,
+    };
+}
+export function isInternationalRoute(origin, destination) {
+    const o = getAirport(origin);
+    const d = getAirport(destination);
+    return !(o && d && o.country === "US" && d.country === "US");
+}

package/examples/claude_desktop_config.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "travel-assistant": {
+      "command": "travel-assistant-mcp"
+    }
+  }
+}

package/examples/tool-calls.md

@@ -0,0 +1,24 @@
+# Example Tool Calls
+
+## Search Travel Options
+
+```json
+{
+  "origin": "JFK",
+  "destination": "LAX",
+  "departure_date": "2026-08-15",
+  "currency": "USD"
+}
+```
+
+## Build Booking Link
+
+```json
+{
+  "origin": "JFK",
+  "destination": "LAX",
+  "departure_date": "2026-08-15"
+}
+```
+
+Tool output uses generic provider integrations, booking partners, external booking links, and commission-eligible links.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "travel-assistant-mcp",
+  "version": "0.1.1",
+  "description": "Public MCP server for travel search workflows, airport lookup, route comparison, and external booking links.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "travel-assistant-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "examples"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "travel",
+    "flights",
+    "travel-search",
+    "travel-planning",
+    "booking-partners",
+    "forgemesh"
+  ],
+  "homepage": "https://github.com/forgemeshlabs/travel-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forgemeshlabs/travel-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/forgemeshlabs/travel-mcp/issues"
+  },
+  "author": "Forgemesh",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}