mcp-travelcode 1.0.0

package/README.md

@@ -0,0 +1,133 @@
+# MCP TravelCode
+
+MCP server for the [TravelCode](https://travel-code.com) corporate travel API. Enables AI assistants (Claude Desktop, Cursor, Claude Code) to search flights & hotels, manage bookings, and track flight status.
+
+## Quick Start
+
+```bash
+# 1. Authenticate (opens browser, one-time)
+npx mcp-travelcode-auth auth
+
+# 2. Add to Claude Desktop (claude_desktop_config.json):
+```
+
+```json
+{
+  "mcpServers": {
+    "travelcode": {
+      "command": "npx",
+      "args": ["mcp-travelcode"]
+    }
+  }
+}
+```
+
+```bash
+# 3. Restart Claude Desktop — done!
+```
+
+### Claude Code
+
+```bash
+claude mcp add travelcode -- npx mcp-travelcode
+```
+
+## Tools (19)
+
+### Flight Search & Reference Data
+
+| Tool | Description |
+|------|-------------|
+| `search_airports` | Find airports by name, city, or IATA code |
+| `get_airport` | Get details for a specific airport |
+| `search_airlines` | Find airlines by name or IATA code |
+| `search_flights` | Search for flights (handles async polling automatically) |
+| `get_flight_results` | Filter/sort/paginate existing search results |
+
+### Flight Statistics (AeroDataBox)
+
+| Tool | Description |
+|------|-------------|
+| `get_flight_status` | Real-time flight status (delays, gates, terminals, aircraft) |
+| `get_airport_flights` | Airport departure/arrival board for a time window |
+| `get_flight_delay_stats` | Historical delay statistics for a flight number |
+| `get_airport_delay_stats` | Airport delay and cancellation stats for a date |
+
+### Hotel Search
+
+| Tool | Description |
+|------|-------------|
+| `search_hotel_locations` | Find cities, regions, or hotels by name (returns location IDs) |
+| `get_hotel_location` | Get location details by ID |
+| `search_hotels` | Search hotels with filters (stars, price, meal plan, refundability) via SSE stream |
+
+### Order Management
+
+| Tool | Description |
+|------|-------------|
+| `list_orders` | List orders with filtering and pagination |
+| `get_order` | Get full order details |
+| `create_order` | Book a flight from search results |
+| `check_order_cancellation` | Check cancellation conditions and refund estimate |
+| `cancel_order` | Cancel an order |
+| `check_order_modification` | Check what modifications are allowed |
+| `modify_order` | Modify an order (contacts, passport, rebook, baggage) |
+
+## Authentication
+
+MCP TravelCode uses OAuth 2.1 with PKCE. No API keys to manage — just sign in with your TravelCode account.
+
+```bash
+# Sign in (opens browser)
+npx mcp-travelcode-auth auth
+
+# Check token status
+npx mcp-travelcode-auth status
+
+# Sign out
+npx mcp-travelcode-auth logout
+```
+
+Tokens are stored in `~/.travelcode/tokens.json` and auto-refresh when expired.
+
+**Legacy mode:** You can also set `TRAVELCODE_API_TOKEN` environment variable to use a static API token.
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `TRAVELCODE_API_TOKEN` | No | — | Static API token (skips OAuth) |
+| `TRAVELCODE_API_BASE_URL` | No | `https://api.travel-code.com/v1` | API base URL |
+| `TRAVELCODE_POLL_INTERVAL_MS` | No | 2000 | Flight search polling interval (ms) |
+| `TRAVELCODE_POLL_TIMEOUT_MS` | No | 90000 | Flight search timeout (ms) |
+
+## Example Conversations
+
+> "Find hotels in Dubai for April 15-18, 2 adults, 4-5 stars, all inclusive"
+
+Uses `search_hotel_locations` → `search_hotels` with star rating and meal plan filters.
+
+> "Search flights from London to Barcelona on March 15, economy, 2 adults"
+
+Uses `search_airports` → `search_flights` → returns formatted flight options.
+
+> "Show my orders" / "Cancel order 12345"
+
+Uses `list_orders`, `check_order_cancellation` → `cancel_order`.
+
+> "Is flight LO776 on time today?"
+
+Uses `get_flight_status` to check real-time status.
+
+## Development
+
+```bash
+npm run dev         # Run with tsx (hot reload)
+npm run build       # Compile TypeScript
+npm run inspect     # Test with MCP Inspector
+npm run start:http  # Run HTTP transport (OAuth for browser clients)
+```
+
+## License
+
+MIT

package/build/auth/cli-auth.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * CLI OAuth flow for obtaining TravelCode API tokens.
+ *
+ * Usage: npx mcp-travelcode auth
+ *
+ * Flow:
+ * 1. Register client via DCR (if not already registered)
+ * 2. Generate PKCE code_verifier + code_challenge
+ * 3. Open browser to /oauth/authorize
+ * 4. Start local HTTP server to catch redirect callback
+ * 5. Exchange code for tokens
+ * 6. Save tokens to ~/.travelcode/tokens.json
+ */
+export {};
+//# sourceMappingURL=cli-auth.d.ts.map

package/build/auth/cli-auth.js

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+/**
+ * CLI OAuth flow for obtaining TravelCode API tokens.
+ *
+ * Usage: npx mcp-travelcode auth
+ *
+ * Flow:
+ * 1. Register client via DCR (if not already registered)
+ * 2. Generate PKCE code_verifier + code_challenge
+ * 3. Open browser to /oauth/authorize
+ * 4. Start local HTTP server to catch redirect callback
+ * 5. Exchange code for tokens
+ * 6. Save tokens to ~/.travelcode/tokens.json
+ */
+import { createServer } from "node:http";
+import { randomBytes, createHash } from "node:crypto";
+import { URL, URLSearchParams } from "node:url";
+import { loadClient, saveClient, saveTokens, loadTokens, clearTokens, } from "./token-store.js";
+const DEFAULT_ISSUER = "https://travel-code.com";
+const CALLBACK_PORT = 19284; // random-ish port unlikely to conflict
+const REDIRECT_URI = `http://localhost:${CALLBACK_PORT}/callback`;
+const SCOPES = [
+    "flights:search",
+    "flights:status",
+    "flights:stats",
+    "airports:read",
+    "airlines:read",
+    "orders:read",
+    "orders:write",
+].join(" ");
+// --- PKCE ---
+function generateCodeVerifier() {
+    return randomBytes(32).toString("base64url");
+}
+function generateCodeChallenge(verifier) {
+    return createHash("sha256").update(verifier).digest("base64url");
+}
+function generateState() {
+    return randomBytes(16).toString("base64url");
+}
+// --- DCR ---
+async function registerClient(issuer) {
+    const existing = await loadClient(issuer);
+    if (existing) {
+        console.log(`Using existing client: ${existing.client_id}`);
+        return existing;
+    }
+    console.log("Registering OAuth client...");
+    const response = await fetch(`${issuer}/oauth/register`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            client_name: "MCP TravelCode CLI",
+            redirect_uris: [REDIRECT_URI],
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+        }),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Client registration failed (${response.status}): ${text}`);
+    }
+    const data = (await response.json());
+    const client = {
+        client_id: data.client_id,
+        client_name: data.client_name,
+        redirect_uris: data.redirect_uris,
+        issuer,
+    };
+    await saveClient(client);
+    console.log(`Client registered: ${client.client_id}`);
+    return client;
+}
+// --- Token exchange ---
+async function exchangeCodeForTokens(issuer, clientId, code, codeVerifier) {
+    const response = await fetch(`${issuer}/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: REDIRECT_URI,
+            client_id: clientId,
+            code_verifier: codeVerifier,
+        }),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Token exchange failed (${response.status}): ${text}`);
+    }
+    const data = (await response.json());
+    const now = Math.floor(Date.now() / 1000);
+    return {
+        access_token: data.access_token,
+        refresh_token: data.refresh_token,
+        expires_at: now + data.expires_in,
+        scope: data.scope,
+        client_id: clientId,
+        issuer,
+    };
+}
+// --- Open browser ---
+async function openBrowser(url) {
+    const { platform } = await import("node:os");
+    const { exec } = await import("node:child_process");
+    const os = platform();
+    let command;
+    if (os === "darwin") {
+        command = `open "${url}"`;
+    }
+    else if (os === "win32") {
+        command = `start "${url}"`;
+    }
+    else {
+        command = `xdg-open "${url}"`;
+    }
+    exec(command, (error) => {
+        if (error) {
+            console.log(`\nCould not open browser automatically. Please open this URL manually:\n${url}\n`);
+        }
+    });
+}
+// --- Callback server ---
+function waitForCallback(expectedState) {
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            server.close();
+            reject(new Error("Authorization timed out (5 minutes). Please try again."));
+        }, 5 * 60 * 1000);
+        const server = createServer((req, res) => {
+            const url = new URL(req.url || "/", `http://localhost:${CALLBACK_PORT}`);
+            if (url.pathname !== "/callback") {
+                res.writeHead(404);
+                res.end("Not found");
+                return;
+            }
+            const error = url.searchParams.get("error");
+            const errorDescription = url.searchParams.get("error_description");
+            const code = url.searchParams.get("code");
+            const state = url.searchParams.get("state");
+            if (error) {
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                res.end(`
+          <html><body style="font-family: sans-serif; text-align: center; margin-top: 50px;">
+            <h2>Authorization failed</h2>
+            <p>${errorDescription || error}</p>
+            <p>You can close this window.</p>
+          </body></html>
+        `);
+                clearTimeout(timeout);
+                server.close();
+                reject(new Error(`Authorization denied: ${errorDescription || error}`));
+                return;
+            }
+            if (!code || state !== expectedState) {
+                res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+                res.end(`
+          <html><body style="font-family: sans-serif; text-align: center; margin-top: 50px;">
+            <h2>Invalid callback</h2>
+            <p>Missing code or state mismatch.</p>
+          </body></html>
+        `);
+                clearTimeout(timeout);
+                server.close();
+                reject(new Error("Invalid callback: missing code or state mismatch"));
+                return;
+            }
+            res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+            res.end(`
+        <html><body style="font-family: sans-serif; text-align: center; margin-top: 50px;">
+          <h2>Authorization successful!</h2>
+          <p>You can close this window and return to the terminal.</p>
+        </body></html>
+      `);
+            clearTimeout(timeout);
+            server.close();
+            resolve({ code });
+        });
+        server.listen(CALLBACK_PORT, () => {
+            // server ready
+        });
+        server.on("error", (err) => {
+            clearTimeout(timeout);
+            reject(new Error(`Failed to start callback server on port ${CALLBACK_PORT}: ${err.message}`));
+        });
+    });
+}
+// --- Main ---
+async function authCommand() {
+    const issuer = process.env.OAUTH_ISSUER || DEFAULT_ISSUER;
+    console.log("TravelCode OAuth Authorization");
+    console.log(`Issuer: ${issuer}`);
+    console.log("");
+    // 1. Register client (or reuse existing)
+    const client = await registerClient(issuer);
+    // 2. Generate PKCE
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = generateCodeChallenge(codeVerifier);
+    const state = generateState();
+    // 3. Build authorization URL
+    const authUrl = new URL(`${issuer}/oauth/authorize`);
+    authUrl.searchParams.set("response_type", "code");
+    authUrl.searchParams.set("client_id", client.client_id);
+    authUrl.searchParams.set("redirect_uri", REDIRECT_URI);
+    authUrl.searchParams.set("scope", SCOPES);
+    authUrl.searchParams.set("state", state);
+    authUrl.searchParams.set("code_challenge", codeChallenge);
+    authUrl.searchParams.set("code_challenge_method", "S256");
+    // 4. Start callback server and open browser
+    console.log("Opening browser for authorization...");
+    const callbackPromise = waitForCallback(state);
+    await openBrowser(authUrl.toString());
+    console.log("Waiting for authorization...\n");
+    // 5. Wait for callback
+    const { code } = await callbackPromise;
+    console.log("Authorization code received. Exchanging for tokens...");
+    // 6. Exchange code for tokens
+    const tokens = await exchangeCodeForTokens(issuer, client.client_id, code, codeVerifier);
+    await saveTokens(tokens);
+    console.log("");
+    console.log("Authentication successful!");
+    console.log(`  Access token expires: ${new Date(tokens.expires_at * 1000).toLocaleString()}`);
+    console.log(`  Scopes: ${tokens.scope}`);
+    console.log(`  Tokens saved to: ~/.travelcode/tokens.json`);
+    console.log("");
+    console.log("You can now use the MCP server. It will automatically use the saved token.");
+}
+async function statusCommand() {
+    const tokens = await loadTokens();
+    if (!tokens) {
+        console.log("Not authenticated. Run: npx mcp-travelcode auth");
+        return;
+    }
+    const now = Math.floor(Date.now() / 1000);
+    const expired = tokens.expires_at <= now;
+    const expiresIn = tokens.expires_at - now;
+    console.log("TravelCode Auth Status");
+    console.log(`  Issuer:    ${tokens.issuer}`);
+    console.log(`  Client ID: ${tokens.client_id}`);
+    console.log(`  Scopes:    ${tokens.scope}`);
+    console.log(`  Expires:   ${new Date(tokens.expires_at * 1000).toLocaleString()}`);
+    console.log(`  Status:    ${expired ? "EXPIRED" : `valid (${Math.floor(expiresIn / 60)} min left)`}`);
+    console.log(`  Has refresh token: ${tokens.refresh_token ? "yes" : "no"}`);
+}
+async function logoutCommand() {
+    await clearTokens();
+    console.log("Tokens cleared. Run 'npx mcp-travelcode auth' to re-authenticate.");
+}
+// --- Entry point ---
+const command = process.argv[2];
+switch (command) {
+    case "auth":
+    case "login":
+        authCommand().catch((err) => {
+            console.error("Auth error:", err.message);
+            process.exit(1);
+        });
+        break;
+    case "status":
+        statusCommand().catch((err) => {
+            console.error("Error:", err.message);
+            process.exit(1);
+        });
+        break;
+    case "logout":
+        logoutCommand().catch((err) => {
+            console.error("Error:", err.message);
+            process.exit(1);
+        });
+        break;
+    default:
+        console.log("Usage: mcp-travelcode <command>");
+        console.log("");
+        console.log("Commands:");
+        console.log("  auth     Authenticate with TravelCode (opens browser)");
+        console.log("  status   Show current auth status");
+        console.log("  logout   Clear saved tokens");
+        break;
+}
+//# sourceMappingURL=cli-auth.js.map

package/build/auth/token-store.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Token storage for CLI-obtained OAuth tokens.
+ *
+ * Tokens are stored in ~/.travelcode/tokens.json.
+ * Format:
+ * {
+ *   "access_token": "...",
+ *   "refresh_token": "...",
+ *   "expires_at": 1234567890,
+ *   "scope": "flights:search airports:read ...",
+ *   "client_id": "...",
+ *   "issuer": "https://api.travel-code.com"
+ * }
+ */
+export interface StoredTokens {
+    access_token: string;
+    refresh_token: string;
+    expires_at: number;
+    scope: string;
+    client_id: string;
+    issuer: string;
+}
+export interface StoredClient {
+    client_id: string;
+    client_name: string;
+    redirect_uris: string[];
+    issuer: string;
+}
+export declare function loadTokens(): Promise<StoredTokens | null>;
+export declare function saveTokens(tokens: StoredTokens): Promise<void>;
+export declare function clearTokens(): Promise<void>;
+/**
+ * Returns a valid access token, refreshing if expired.
+ * Returns null if no tokens stored or refresh fails.
+ */
+export declare function getValidToken(issuer: string): Promise<string | null>;
+export declare function loadClient(issuer: string): Promise<StoredClient | null>;
+export declare function saveClient(client: StoredClient): Promise<void>;
+//# sourceMappingURL=token-store.d.ts.map

package/build/auth/token-store.js

@@ -0,0 +1,113 @@
+/**
+ * Token storage for CLI-obtained OAuth tokens.
+ *
+ * Tokens are stored in ~/.travelcode/tokens.json.
+ * Format:
+ * {
+ *   "access_token": "...",
+ *   "refresh_token": "...",
+ *   "expires_at": 1234567890,
+ *   "scope": "flights:search airports:read ...",
+ *   "client_id": "...",
+ *   "issuer": "https://api.travel-code.com"
+ * }
+ */
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const TOKEN_DIR = join(homedir(), ".travelcode");
+const TOKEN_FILE = join(TOKEN_DIR, "tokens.json");
+const CLIENT_FILE = join(TOKEN_DIR, "client.json");
+async function ensureDir() {
+    await mkdir(TOKEN_DIR, { recursive: true });
+}
+// --- Tokens ---
+export async function loadTokens() {
+    try {
+        const data = await readFile(TOKEN_FILE, "utf-8");
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveTokens(tokens) {
+    await ensureDir();
+    await writeFile(TOKEN_FILE, JSON.stringify(tokens, null, 2), "utf-8");
+}
+export async function clearTokens() {
+    try {
+        const { unlink } = await import("node:fs/promises");
+        await unlink(TOKEN_FILE);
+    }
+    catch {
+        // ignore if file doesn't exist
+    }
+}
+/**
+ * Returns a valid access token, refreshing if expired.
+ * Returns null if no tokens stored or refresh fails.
+ */
+export async function getValidToken(issuer) {
+    const tokens = await loadTokens();
+    if (!tokens)
+        return null;
+    if (tokens.issuer !== issuer)
+        return null;
+    const now = Math.floor(Date.now() / 1000);
+    // Token still valid (with 60s buffer)
+    if (tokens.expires_at > now + 60) {
+        return tokens.access_token;
+    }
+    // Try to refresh
+    if (!tokens.refresh_token || !tokens.client_id)
+        return null;
+    try {
+        const response = await fetch(`${issuer}/oauth/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "refresh_token",
+                refresh_token: tokens.refresh_token,
+                client_id: tokens.client_id,
+            }),
+        });
+        if (!response.ok) {
+            console.error("Token refresh failed, please re-authenticate: npx mcp-travelcode auth");
+            return null;
+        }
+        const data = (await response.json());
+        const refreshedTokens = {
+            access_token: data.access_token,
+            refresh_token: data.refresh_token,
+            expires_at: now + data.expires_in,
+            scope: data.scope,
+            client_id: tokens.client_id,
+            issuer: tokens.issuer,
+        };
+        await saveTokens(refreshedTokens);
+        return refreshedTokens.access_token;
+    }
+    catch (error) {
+        console.error("Token refresh error:", error.message);
+        return null;
+    }
+}
+// --- Client registration ---
+export async function loadClient(issuer) {
+    try {
+        const data = await readFile(CLIENT_FILE, "utf-8");
+        const client = JSON.parse(data);
+        if (client.issuer !== issuer)
+            return null;
+        return client;
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveClient(client) {
+    await ensureDir();
+    await writeFile(CLIENT_FILE, JSON.stringify(client, null, 2), "utf-8");
+}
+//# sourceMappingURL=token-store.js.map

package/build/client/api-client.d.ts

@@ -0,0 +1,42 @@
+import { TravelCodeConfig } from "../config.js";
+export declare class TravelCodeAuthError extends Error {
+    constructor(message: string);
+}
+export declare class TravelCodeNotFoundError extends Error {
+    constructor(message: string);
+}
+export declare class TravelCodeValidationError extends Error {
+    constructor(message: string);
+}
+export declare class TravelCodeServerError extends Error {
+    constructor(message: string);
+}
+export declare class TravelCodeApiClient {
+    private baseUrl;
+    private token;
+    private issuer;
+    constructor(config: TravelCodeConfig);
+    /**
+     * Ensures the token is still valid, refreshing via OAuth if needed.
+     * Falls back to the current token if refresh is not available.
+     */
+    private ensureValidToken;
+    get<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    post<T>(path: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<T>;
+    getAerodatabox<T>(aerodataboxPath: string, params?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    /**
+     * POST request that returns an SSE stream.
+     * Collects events and returns them as an array of {event, data} objects.
+     */
+    postSSE(path: string, body: Record<string, unknown>, timeoutMs?: number): Promise<Array<{
+        event: string;
+        data: unknown;
+    }>>;
+    /**
+     * GET with accessToken as query parameter (used by hotel location endpoints).
+     */
+    getWithTokenParam<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    private headers;
+    private handleResponse;
+}
+//# sourceMappingURL=api-client.d.ts.map