letsfg-mcp 1.0.0

package/README.md

@@ -0,0 +1,343 @@
+# boostedtravel-mcp
+
+The largest open flight-search MCP server. 73 ready-to-run airline connectors fire in parallel on your machine — Ryanair, EasyJet, Wizz Air, Southwest, AirAsia, and 68 more — plus enterprise GDS/NDC providers (Amadeus, Duffel, Sabre) through the BoostedTravel backend. One tool call scans the entire world for flights, including airlines your agent didn't know existed.
+
+**Your agent doesn't need to build a flight integration. It doesn't need to scrape. Just add this MCP server and it can search and book flights in seconds — what would take 30+ minutes of integration work becomes a single tool call.**
+
+Works with OpenClaw, Perplexity Computer, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.
+
+> 🎥 **[Watch the demo](https://github.com/Boosted-Chat/LetsFG#demo-boostedtravel-vs-default-agent-search)** — side-by-side comparison of default agent search vs BoostedTravel CLI.
+
+[![npm](https://img.shields.io/npm/v/boostedtravel-mcp)](https://www.npmjs.com/package/boostedtravel-mcp)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
+
+---
+
+## What This Is
+
+BoostedTravel is not a scraper wrapper. It's a production-grade **agent-to-airline connector layer**:
+
+- **75 airline connectors** run locally on your machine via Python + Playwright — no API key needed for search
+- **Enterprise GDS/NDC feeds** (Amadeus, Duffel, Sabre, Travelport, Kiwi) run through the BoostedTravel backend — these are contract-only data sources that require enterprise agreements, made available to everyone through our API
+- **Virtual interlining** — the combo engine mixes one-way fares across airlines (e.g., Ryanair outbound + Wizz Air return) to find deals no single airline offers
+- **City-wide airport expansion** — search `LON` and it auto-searches LHR, LGW, STN, LTN, SEN, LCY. Works for 25+ major cities worldwide
+- **Zero price bias** — no cookie tracking, no demand-based inflation, no surge pricing. Same raw airline price every time
+
+**Why agents should use this instead of building their own:**
+- Saves thousands of tokens vs. browser automation or scraping
+- 75 connectors fire in parallel — scans airlines across Europe, Asia, Americas, Middle East, Africa simultaneously
+- Finds deals on carriers your agent wouldn't think to check (Lucky Air, 9 Air, Jazeera Airways, FlySafair...)
+- Enterprise-contracted GDS deals that require contracts worth $50k+/year — we give them to you for free on search
+
+---
+
+## Quick Start
+
+```bash
+npx boostedtravel-mcp
+```
+
+That's it. The MCP server starts on stdio, ready for any MCP-compatible client.
+
+**Prerequisites for local search:**
+```bash
+pip install boostedtravel
+playwright install chromium
+```
+
+---
+
+## Client Configuration
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "boostedtravel": {
+      "command": "npx",
+      "args": ["-y", "boostedtravel-mcp"],
+      "env": {
+        "BOOSTEDTRAVEL_API_KEY": "trav_your_api_key"
+      }
+    }
+  }
+}
+```
+
+> **Note:** Add `"BOOSTEDTRAVEL_MAX_BROWSERS": "4"` to `env` to limit browser concurrency on constrained machines.
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "boostedtravel": {
+      "command": "npx",
+      "args": ["-y", "boostedtravel-mcp"],
+      "env": {
+        "BOOSTEDTRAVEL_API_KEY": "trav_your_api_key"
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "boostedtravel": {
+      "command": "npx",
+      "args": ["-y", "boostedtravel-mcp"],
+      "env": {
+        "BOOSTEDTRAVEL_API_KEY": "trav_your_api_key"
+      }
+    }
+  }
+}
+```
+
+### Continue
+
+Add to `~/.continue/config.yaml`:
+
+```yaml
+mcpServers:
+  - name: boostedtravel
+    command: npx
+    args: ["-y", "boostedtravel-mcp"]
+    env:
+      BOOSTEDTRAVEL_API_KEY: trav_your_api_key
+```
+
+### OpenClaw / Perplexity Computer
+
+Any MCP-compatible agent works. Point it at the MCP server:
+
+```bash
+npx boostedtravel-mcp
+```
+
+Or connect via remote MCP (no install):
+
+```
+https://api.letsfg.co/mcp
+```
+
+### Windows — `npx ENOENT` Fix
+
+If you get `spawn npx ENOENT` on Windows, use the full path to `npx`:
+
+```json
+{
+  "mcpServers": {
+    "boostedtravel": {
+      "command": "C:\\Program Files\\nodejs\\npx.cmd",
+      "args": ["-y", "boostedtravel-mcp"],
+      "env": {
+        "BOOSTEDTRAVEL_API_KEY": "trav_your_api_key"
+      }
+    }
+  }
+}
+```
+
+Or use `node` directly:
+
+```json
+{
+  "mcpServers": {
+    "boostedtravel": {
+      "command": "node",
+      "args": ["C:\\Users\\YOU\\AppData\\Roaming\\npm\\node_modules\\boostedtravel-mcp\\dist\\index.js"],
+      "env": {
+        "BOOSTEDTRAVEL_API_KEY": "trav_your_api_key"
+      }
+    }
+  }
+}
+```
+
+### Pin a Specific Version
+
+To avoid unexpected updates:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "boostedtravel-mcp@0.2.4"]
+}
+```
+
+---
+
+## Available Tools
+
+| Tool | Description | Cost | Side Effects |
+|------|-------------|------|--------------|
+| `search_flights` | Search 400+ airlines worldwide | FREE | None (read-only) |
+| `resolve_location` | City name → IATA code | FREE | None (read-only) |
+| `unlock_flight_offer` | Confirm live price, reserve 30 min | $1 | Charges $1 |
+| `book_flight` | Create real airline reservation (PNR) | FREE | Creates booking |
+| `setup_payment` | Attach payment card (once) | FREE | Updates payment |
+| `get_agent_profile` | Usage stats & payment status | FREE | None (read-only) |
+| `system_info` | System resources & concurrency tier | FREE | None (read-only) |
+
+### Booking Flow
+
+```
+search_flights  →  unlock_flight_offer  →  book_flight
+   (free)              ($1 quote)           (free, creates PNR)
+```
+
+1. `search_flights("LON", "BCN", "2026-06-15")` — returns offers with prices from 75 airlines
+2. `unlock_flight_offer("off_xxx")` — confirms live price with airline, reserves for 30 min, costs $1
+3. `book_flight("off_xxx", passengers, email)` — creates real booking, airline sends e-ticket
+
+The `search_flights` tool accepts an optional `max_browsers` parameter (1–32) to limit concurrent browser instances. Omit it to auto-detect based on system RAM.
+
+The `system_info` tool returns your system profile (RAM, CPU, tier, recommended max browsers) — useful for agents to decide concurrency before searching.
+
+The agent has native tools — no API docs needed, no URL building, no token-burning browser automation.
+
+---
+
+## Get an API Key
+
+**Search is free and works without a key.** An API key is needed for unlock, book, and enterprise GDS sources.
+
+```bash
+curl -X POST https://api.letsfg.co/api/v1/agents/register \
+  -H "Content-Type: application/json" \
+  -d '{"agent_name": "my-agent", "email": "agent@example.com"}'
+```
+
+Or via CLI:
+```bash
+pip install boostedtravel
+boostedtravel register --name my-agent --email you@example.com
+```
+
+---
+
+## Architecture & Data Flow
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  MCP Client  (Claude Desktop / Cursor / Windsurf / etc.)     │
+│     ↕ stdio (JSON-RPC, local only)                           │
+├──────────────────────────────────────────────────────────────┤
+│  boostedtravel-mcp  (this package, runs on YOUR machine)     │
+│     │                                                        │
+│     ├─→ Python subprocess (local connectors)                 │
+│     │     75 airline connectors via Playwright + httpx        │
+│     │     Data goes: your machine → airline website → back    │
+│     │                                                        │
+│     └─→ HTTPS to api.letsfg.co (backend)               │
+│           unlock, book, payment, enterprise GDS search        │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### What data goes where
+
+| Operation | Where data flows | What is sent |
+|-----------|-----------------|--------------|
+| `search_flights` (local) | Your machine → airline websites | Route, date, passenger count |
+| `search_flights` (GDS) | Your machine → api.letsfg.co → GDS providers | Route, date, passenger count, API key |
+| `resolve_location` | Your machine → api.letsfg.co | City/airport name |
+| `unlock_flight_offer` | Your machine → api.letsfg.co → airline | Offer ID, payment token |
+| `book_flight` | Your machine → api.letsfg.co → airline | Passenger name, DOB, email, phone |
+| `setup_payment` | Your machine → api.letsfg.co → Stripe | Payment token (card handled by Stripe) |
+
+---
+
+## Security & Privacy
+
+- **TLS everywhere** — all backend communication uses HTTPS. Local connectors connect to airline websites over HTTPS.
+- **No card storage** — payment cards are tokenized by Stripe. BoostedTravel never sees or stores raw card numbers.
+- **API key scoping** — `BOOSTEDTRAVEL_API_KEY` grants access only to your agent's account. Keys are prefixed `trav_` for easy identification and revocation.
+- **PII handling** — passenger names, emails, and DOBs are sent to the airline for booking (required by airlines). BoostedTravel does not store passenger PII after forwarding to the airline.
+- **No tracking** — no cookies, no session-based pricing, no fingerprinting. Every search returns the same raw airline price.
+- **Local search is fully local** — when searching without an API key, zero data leaves your machine except direct HTTPS requests to airline websites. The MCP server and Python connectors run entirely on your hardware.
+- **Open source** — all connector code is MIT-licensed and auditable at [github.com/Boosted-Chat/LetsFG](https://github.com/Boosted-Chat/LetsFG).
+
+---
+
+## Sandbox / Test Mode
+
+Use Stripe's test token for payment setup without real charges:
+
+```
+setup_payment with token: "tok_visa"
+```
+
+This attaches a test Visa card. Unlock calls will show `$1.00` but use Stripe test mode — no real money is charged. Useful for agent development and testing the full search → unlock → book flow.
+
+---
+
+## FAQ
+
+### `spawn npx ENOENT` on Windows
+
+Windows can't find `npx` in PATH. Use the full path:
+```json
+"command": "C:\\Program Files\\nodejs\\npx.cmd"
+```
+Or install globally and use `node` directly (see Windows config above).
+
+### Search returns 0 results
+
+- Check IATA codes are correct — use `resolve_location` first
+- Try a date 2+ weeks in the future (airlines don't sell last-minute on all routes)
+- Ensure `pip install boostedtravel && playwright install chromium` completed successfully
+- Check Python is available: the MCP server spawns a Python subprocess for local search
+
+### How do I search without an API key?
+
+Just omit `BOOSTEDTRAVEL_API_KEY` from your config. Local search (75 airline connectors) works without any key. You'll only miss the enterprise GDS/NDC sources (Amadeus, Duffel, etc.).
+
+### Can I use this for commercial projects?
+
+Yes. MIT license. The local connectors and SDK are fully open source. The backend API (unlock/book/GDS) is a hosted service with usage-based pricing ($1 per unlock).
+
+### How do I pin a version?
+
+```json
+"args": ["-y", "boostedtravel-mcp@0.2.4"]
+```
+
+### MCP server hangs on start
+
+Ensure Node.js 18+ is installed. The server communicates via stdio (stdin/stdout JSON-RPC) — it doesn't open a port or print a "ready" message. MCP clients handle the lifecycle automatically.
+
+---
+
+## Supported Airlines (75 connectors)
+
+| Region | Airlines |
+|--------|----------|
+| **Europe** | Ryanair, Wizz Air, EasyJet, Norwegian, Vueling, Eurowings, Transavia, Pegasus, Turkish Airlines, Condor, SunExpress, Volotea, Smartwings, Jet2, LOT Polish Airlines |
+| **Middle East & Africa** | Emirates, Etihad, Qatar Airways, flydubai, Air Arabia, flynas, Salam Air, Air Peace, FlySafair |
+| **Asia-Pacific** | AirAsia, IndiGo, SpiceJet, Akasa Air, Air India Express, VietJet, Cebu Pacific, Scoot, Jetstar, Peach, Spring Airlines, Lucky Air, 9 Air, Nok Air, Batik Air, Jeju Air, T'way Air, ZIPAIR, Singapore Airlines, Cathay Pacific, Malaysian Airlines, Thai Airways, Korean Air, ANA, US-Bangla, Biman Bangladesh |
+| **Americas** | American Airlines, Delta, United, Southwest, JetBlue, Alaska Airlines, Hawaiian Airlines, Sun Country, Frontier, Volaris, VivaAerobus, Allegiant, Avelo, Breeze, Flair, GOL, Azul, JetSmart, Flybondi, Porter, WestJet, LATAM, Copa, Avianca |
+| **Aggregator** | Kiwi.com (virtual interlining + LCC fallback) |
+
+---
+
+## Also Available As
+
+- **Python SDK + CLI**: `pip install boostedtravel` — [PyPI](https://pypi.org/project/boostedtravel/)
+- **JavaScript/TypeScript SDK + CLI**: `npm install boostedtravel` — [npm](https://www.npmjs.com/package/boostedtravel)
+- **Agent docs**: [AGENTS.md](../../AGENTS.md) — complete reference for AI agents
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,370 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/index.ts
+var readline = __toESM(require("readline"));
+var import_child_process = require("child_process");
+var BASE_URL = (process.env.LETSFG_BASE_URL || process.env.BOOSTEDTRAVEL_BASE_URL || "https://api.letsfg.co").replace(/\/$/, "");
+var API_KEY = process.env.LETSFG_API_KEY || process.env.BOOSTEDTRAVEL_API_KEY || "";
+var PYTHON = process.env.LETSFG_PYTHON || process.env.BOOSTEDTRAVEL_PYTHON || "python3";
+var VERSION = "1.0.0";
+function searchLocal(params) {
+  return new Promise((resolve) => {
+    const input = JSON.stringify(params);
+    const pythonCmd = process.platform === "win32" ? "python" : PYTHON;
+    const child = (0, import_child_process.spawn)(pythonCmd, ["-m", "letsfg.local"], {
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 18e4
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => {
+      stdout += d.toString();
+    });
+    child.stderr.on("data", (d) => {
+      stderr += d.toString();
+    });
+    child.on("close", (code) => {
+      if (stderr) process.stderr.write(`[letsfg] ${stderr}
+`);
+      try {
+        resolve(JSON.parse(stdout));
+      } catch {
+        resolve({ error: `Python search failed (code ${code}): ${stdout || stderr}` });
+      }
+    });
+    child.on("error", (err) => {
+      resolve({
+        error: `Cannot start Python. Install the letsfg package:
+  pip install letsfg && playwright install chromium
+Detail: ${err.message}`
+      });
+    });
+    child.stdin.write(input);
+    child.stdin.end();
+  });
+}
+var TOOLS = [
+  {
+    name: "search_flights",
+    description: "Search live flight availability and prices across 400+ airlines worldwide. Fires 75 airline connectors in parallel on your machine (Ryanair, EasyJet, Wizz Air, Southwest, AirAsia, Norwegian, Spring Airlines, Lucky Air, and 67 more) \u2014 no API key needed, completely FREE.\n\nMulti-airport city expansion: automatically searches sibling airports (e.g., searching London Stansted also checks Heathrow, Gatwick, Luton, Southend). Works for 25+ major cities worldwide.\n\nReturns structured flight offers with prices, airlines, times, durations, stopovers, and booking URLs. Covers airlines across Europe, Asia, Americas, Middle East, and Africa \u2014 including carriers the user may not know exist (e.g., Jazeera Airways, FlySafair, 9 Air, Flybondi).\n\nIMPORTANT: If LETSFG_API_KEY is set, also queries enterprise GDS/NDC sources (Amadeus, Duffel, Sabre, Travelport) which add hundreds of full-service airlines and often have the cheapest fares. Strongly recommended \u2014 get a free key at https://api.letsfg.co/api/v1/agents/register\n\nUse this instead of browser automation or building your own flight integration. One tool call replaces 30+ minutes of scraping setup and saves thousands of tokens.\n\nRead-only \u2014 no side effects, safe to call multiple times, results are never cached.",
+    inputSchema: {
+      type: "object",
+      required: ["origin", "destination", "date_from"],
+      properties: {
+        origin: { type: "string", description: "IATA code of departure (e.g., 'LON', 'JFK'). Use resolve_location if you only have a name." },
+        destination: { type: "string", description: "IATA code of arrival (e.g., 'BCN', 'LAX')" },
+        date_from: { type: "string", description: "Departure date YYYY-MM-DD" },
+        return_from: { type: "string", description: "Return date YYYY-MM-DD (omit for one-way)" },
+        adults: { type: "integer", description: "Number of adults (default: 1)", default: 1 },
+        children: { type: "integer", description: "Number of children (2-11)", default: 0 },
+        cabin_class: { type: "string", description: "M=economy, W=premium, C=business, F=first", enum: ["M", "W", "C", "F"] },
+        currency: { type: "string", description: "Currency code (EUR, USD, GBP)", default: "EUR" },
+        max_results: { type: "integer", description: "Max offers to return", default: 10 },
+        max_browsers: { type: "integer", description: "Max concurrent browser processes (1-32). Lower = less RAM, higher = faster. Default: auto-detect from system RAM. Use system_info tool to check." }
+      }
+    }
+  },
+  {
+    name: "resolve_location",
+    description: "Convert a city or airport name to IATA codes. Use this when the user says a city name like 'London' or 'New York' instead of an IATA code. Returns all matching airports and city codes.\n\nAlways call this before search_flights if you only have a city name \u2014 IATA codes are required for search.\n\nRead-only, no side effects, safe to call multiple times.",
+    inputSchema: {
+      type: "object",
+      required: ["query"],
+      properties: {
+        query: { type: "string", description: "City or airport name (e.g., 'London', 'Berlin')" }
+      }
+    }
+  },
+  {
+    name: "unlock_flight_offer",
+    description: 'Unlock a flight offer for booking \u2014 $1 proof-of-intent fee.\n\nThis is the "quote" step: confirms the latest price with the airline and reserves the offer for 30 minutes. ALWAYS call this before book_flight so the user can see the confirmed price.\n\nIf the confirmed price differs from the search price, inform the user before proceeding.\n\nRequires payment method (call setup_payment first).\n\nSAFETY: Charges $1. Not idempotent \u2014 calling twice on the same offer will charge twice.',
+    inputSchema: {
+      type: "object",
+      required: ["offer_id"],
+      properties: {
+        offer_id: { type: "string", description: "Offer ID from search results (off_xxx)" }
+      }
+    }
+  },
+  {
+    name: "book_flight",
+    description: "Book an unlocked flight \u2014 creates real airline reservation with PNR. FREE after unlock.\n\nFLOW: search_flights \u2192 unlock_flight_offer (quote) \u2192 book_flight\nRequirements: 1) Offer must be unlocked first 2) passenger_ids from search 3) Full passenger details\n\nSAFETY: Always provide idempotency_key to prevent double-bookings if this call is retried. Use any unique string (e.g., UUID). If the same key is sent twice, returns the original booking.\n\nERROR HANDLING: Errors include error_code and error_category fields.\n  transient (SUPPLIER_TIMEOUT, RATE_LIMITED) \u2192 safe to retry after short delay\n  validation (INVALID_IATA, INVALID_DATE) \u2192 fix input, then retry\n  business (OFFER_EXPIRED, PAYMENT_DECLINED) \u2192 requires human decision",
+    inputSchema: {
+      type: "object",
+      required: ["offer_id", "passengers", "contact_email"],
+      properties: {
+        offer_id: { type: "string", description: "Unlocked offer ID (off_xxx)" },
+        passengers: {
+          type: "array",
+          description: "Passengers with 'id' from search passenger_ids",
+          items: {
+            type: "object",
+            required: ["id", "given_name", "family_name", "born_on", "email"],
+            properties: {
+              id: { type: "string", description: "Passenger ID from search (pas_xxx)" },
+              given_name: { type: "string", description: "First name (passport)" },
+              family_name: { type: "string", description: "Last name (passport)" },
+              born_on: { type: "string", description: "DOB YYYY-MM-DD" },
+              gender: { type: "string", description: "m or f", default: "m" },
+              title: { type: "string", description: "mr, ms, mrs, miss", default: "mr" },
+              email: { type: "string", description: "Email" },
+              phone_number: { type: "string", description: "Phone with country code" }
+            }
+          }
+        },
+        contact_email: { type: "string", description: "Booking contact email" },
+        idempotency_key: { type: "string", description: "Unique key to prevent double-bookings on retry (e.g., UUID). Strongly recommended." }
+      }
+    }
+  },
+  {
+    name: "setup_payment",
+    description: "Set up payment method. Required before unlock/book. For testing use token 'tok_visa'. Only needed once.\n\nIdempotent \u2014 safe to call multiple times (updates the payment method).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        token: { type: "string", description: "Payment token (e.g., 'tok_visa' for testing)" },
+        payment_method_id: { type: "string", description: "Payment method ID (pm_xxx)" }
+      }
+    }
+  },
+  {
+    name: "get_agent_profile",
+    description: "Get agent profile, payment status, and usage stats (searches, unlocks, bookings, fees).\n\nRead-only. Safe to call multiple times.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "start_checkout",
+    description: "Automate airline checkout up to the payment page \u2014 NEVER submits payment.\n\nFLOW: search_flights \u2192 unlock_flight_offer ($1) \u2192 start_checkout\n\nUses Playwright to drive the airline website: selects flights, fills passenger details, skips extras/seats, and stops at the payment form. Returns a screenshot and booking URL so the user can complete manually in their browser.\n\nSupported airlines: Ryanair, Wizz Air, EasyJet. Other airlines return booking URL only.\n\nSAFETY: Uses fake test data by default. Never enters payment info. The checkout_token from unlock_flight_offer is required \u2014 prevents unauthorized usage.\n\nRuns locally via Python subprocess (pip install letsfg && playwright install chromium).",
+    inputSchema: {
+      type: "object",
+      required: ["offer_id", "checkout_token"],
+      properties: {
+        offer_id: { type: "string", description: "Offer ID from search results (off_xxx)" },
+        checkout_token: { type: "string", description: "Token from unlock_flight_offer response" },
+        passengers: {
+          type: "array",
+          description: "Passenger details. If omitted, uses safe test data (John Doe, test@example.com)",
+          items: {
+            type: "object",
+            properties: {
+              given_name: { type: "string" },
+              family_name: { type: "string" },
+              born_on: { type: "string", description: "DOB YYYY-MM-DD" },
+              gender: { type: "string", description: "m or f" },
+              title: { type: "string", description: "mr, ms, mrs" },
+              email: { type: "string" },
+              phone_number: { type: "string" }
+            }
+          }
+        }
+      }
+    }
+  },
+  {
+    name: "system_info",
+    description: "Get system resource info (RAM, CPU cores) and recommended concurrency settings.\n\nUse this to determine optimal max_browsers value for search_flights. Returns RAM total/available, CPU cores, recommended max browsers, and performance tier.\n\nTiers: minimal (<2GB, max 2), low (2-4GB, max 3), moderate (4-8GB, max 5), standard (8-16GB, max 8), high (16-32GB, max 12), maximum (32+GB, max 16).\n\nRead-only, no side effects, instant response.",
+    inputSchema: { type: "object", properties: {} }
+  }
+];
+async function apiRequest(method, path, body) {
+  const headers = {
+    "Content-Type": "application/json",
+    "User-Agent": "letsfg-mcp/1.0.0"
+  };
+  if (API_KEY) headers["X-API-Key"] = API_KEY;
+  const resp = await fetch(`${BASE_URL}${path}`, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : void 0
+  });
+  const data = await resp.json();
+  if (resp.status >= 400) {
+    return { error: true, status_code: resp.status, detail: data.detail || JSON.stringify(data) };
+  }
+  return data;
+}
+async function callTool(name, args) {
+  switch (name) {
+    case "search_flights": {
+      const params = {
+        origin: args.origin,
+        destination: args.destination,
+        date_from: args.date_from,
+        adults: args.adults ?? 1,
+        children: args.children ?? 0,
+        currency: args.currency ?? "EUR",
+        limit: args.max_results ?? 10
+      };
+      if (args.return_from) params.return_from = args.return_from;
+      if (args.cabin_class) params.cabin_class = args.cabin_class;
+      if (args.max_browsers) params.max_browsers = args.max_browsers;
+      const result = await searchLocal(params);
+      if (result.error) return JSON.stringify(result, null, 2);
+      const offers = result.offers || [];
+      const sourceTiers = result.source_tiers;
+      const hasBackend = sourceTiers ? Object.keys(sourceTiers).some((t) => t === "paid") : false;
+      const summary = {
+        total_offers: offers.length,
+        source: hasBackend ? "local_connectors (75 airlines) + backend (Amadeus, Duffel, Sabre)" : "local_connectors (75 airlines) \u2014 set LETSFG_API_KEY to also query Amadeus/Duffel/Sabre for more results",
+        offers: offers.map((o) => ({
+          offer_id: o.id,
+          price: `${o.price} ${o.currency}`,
+          airlines: o.airlines,
+          source: o.source,
+          booking_url: o.booking_url,
+          outbound: (() => {
+            const ob = o.outbound;
+            const segs = ob?.segments || [];
+            return segs.length ? {
+              from: segs[0].origin,
+              to: segs[segs.length - 1].destination,
+              departure: segs[0].departure,
+              flight: segs[0].flight_no,
+              airline: segs[0].airline_name || segs[0].airline,
+              stops: ob?.stopovers
+            } : null;
+          })()
+        }))
+      };
+      return JSON.stringify(summary, null, 2);
+    }
+    case "resolve_location": {
+      const result = await apiRequest("GET", `/api/v1/flights/locations/${encodeURIComponent(args.query)}`);
+      return JSON.stringify(result, null, 2);
+    }
+    case "unlock_flight_offer": {
+      const result = await apiRequest("POST", "/api/v1/bookings/unlock", { offer_id: args.offer_id });
+      return JSON.stringify(result, null, 2);
+    }
+    case "book_flight": {
+      const body = {
+        offer_id: args.offer_id,
+        booking_type: "flight",
+        passengers: args.passengers,
+        contact_email: args.contact_email
+      };
+      if (args.idempotency_key) body.idempotency_key = args.idempotency_key;
+      const result = await apiRequest("POST", "/api/v1/bookings/book", body);
+      return JSON.stringify(result, null, 2);
+    }
+    case "setup_payment": {
+      const body = {};
+      if (args.token) body.token = args.token;
+      if (args.payment_method_id) body.payment_method_id = args.payment_method_id;
+      const result = await apiRequest("POST", "/api/v1/agents/setup-payment", body);
+      return JSON.stringify(result, null, 2);
+    }
+    case "get_agent_profile": {
+      const result = await apiRequest("GET", "/api/v1/agents/me");
+      return JSON.stringify(result, null, 2);
+    }
+    case "system_info": {
+      const result = await searchLocal({ __system_info: true });
+      return JSON.stringify(result, null, 2);
+    }
+    case "start_checkout": {
+      const result = await searchLocal({
+        __checkout: true,
+        offer_id: args.offer_id,
+        passengers: args.passengers || null,
+        checkout_token: args.checkout_token,
+        api_key: API_KEY,
+        base_url: BASE_URL
+      });
+      if (result.error) return JSON.stringify(result, null, 2);
+      const summary = {
+        status: result.status,
+        step: result.step,
+        airline: result.airline,
+        message: result.message,
+        total_price: result.total_price ? `${result.total_price} ${result.currency}` : void 0,
+        booking_url: result.booking_url,
+        can_complete_manually: result.can_complete_manually,
+        elapsed_seconds: result.elapsed_seconds
+      };
+      if (result.screenshot_b64) {
+        summary.screenshot = "(base64 screenshot attached \u2014 render with image tool if available)";
+      }
+      return JSON.stringify(summary, null, 2);
+    }
+    default:
+      return JSON.stringify({ error: `Unknown tool: ${name}` });
+  }
+}
+function send(msg) {
+  process.stdout.write(JSON.stringify(msg) + "\n");
+}
+var rl = readline.createInterface({ input: process.stdin, terminal: false });
+rl.on("line", async (line) => {
+  let msg;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    return;
+  }
+  const method = msg.method;
+  const id = msg.id;
+  switch (method) {
+    case "initialize":
+      send({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          protocolVersion: "2024-11-05",
+          capabilities: { tools: {} },
+          serverInfo: { name: "letsfg", version: VERSION }
+        }
+      });
+      break;
+    case "notifications/initialized":
+      break;
+    case "tools/list":
+      send({ jsonrpc: "2.0", id, result: { tools: TOOLS } });
+      break;
+    case "tools/call": {
+      const params = msg.params;
+      const toolName = params.name;
+      const toolArgs = params.arguments || {};
+      try {
+        const text = await callTool(toolName, toolArgs);
+        send({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text }] } });
+      } catch (e) {
+        send({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text: `Error: ${e}` }], isError: true } });
+      }
+      break;
+    }
+    case "ping":
+      send({ jsonrpc: "2.0", id, result: {} });
+      break;
+    default:
+      if (id) {
+        send({ jsonrpc: "2.0", id, error: { code: -32601, message: `Method not found: ${method}` } });
+      }
+  }
+});
+process.stderr.write(`LetsFG MCP v${VERSION} | local connectors: 75 airlines | api: ${API_KEY ? "key set" : "search-only (no key)"}
+`);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "letsfg-mcp",
+  "version": "1.0.0",
+  "mcpName": "io.github.Efistoffeles/letsfg",
+  "description": "LetsFG MCP Server — 75 airline connectors run locally + enterprise GDS/NDC APIs. Flight search & booking for Claude, Cursor, Windsurf, and any MCP-compatible AI agent.",
+  "main": "dist/index.js",
+  "bin": {
+    "letsfg-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "cursor",
+    "ai-agent",
+    "flights",
+    "travel",
+    "booking"
+  ],
+  "author": "LetsFG",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LetsFG/LetsFG.git"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}