@furlpay/travel-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Furlpay
+
+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,116 @@
+# @furlpay/travel-mcp — FurlPay Travels
+
+The payment & orchestration layer for **agentic travel**. This MCP server composes
+[Travala's Travel MCP](https://www.travala.com/blog/introducing-travalas-agentic-ai-travel-protocol/)
+(search 2.2M+ hotels + flights) with [FurlPay](https://furlpay.com)'s payment rails
+(pay), so an AI agent can **search, budget-check, pay, and book travel autonomously.**
+
+Two payment routes, chosen per booking:
+
+- **Travala / crypto-native** → an **x402 payment proof**, settled in gasless
+  **USDC on Base**. Accrues the **10% cbBTC developer rebate** Travala pays on
+  MCP-driven bookings.
+- **Legacy Web2 merchant** (Airbnb, Skyscanner…) → a **single-use Visa virtual
+  card**, **MCC-locked** to travel and limited to the booking total.
+
+**Clone-and-run**: with no keys, search and payment simulate end-to-end (no
+network) so you can drive the whole loop offline. Zero runtime dependencies.
+
+Maintained by [FurlPay](https://furlpay.com) · MIT licensed.
+
+## Use as an MCP server
+
+```jsonc
+{
+  "mcpServers": {
+    "furlpay-travels": {
+      "command": "npx",
+      "args": ["-y", "@furlpay/travel-mcp"],
+      "env": {
+        "FURLPAY_API_KEY": "fp_live_sk_...",     // omit for demo mode
+        "TRAVALA_API_KEY": "...",                // omit for demo inventory
+        "FURLPAY_DEVELOPER_WALLET": "0xYourWallet" // receives the 7% cbBTC split
+      }
+    }
+  }
+}
+```
+
+### Tools
+
+| Tool | What it does |
+| --- | --- |
+| `travel_search_stays` | Search Travala hotels for a city + date range |
+| `travel_search_flights` | Search flights for a route + date |
+| `travel_set_agent_budget` | Cap an agent's USDC travel spend |
+| **`travel_authorize_booking`** | Pay a booking — x402/USDC (Travala) **or** single-use MCC-locked Visa VCN (legacy) |
+| `travel_confirm_booking` | Confirm after passkey step-up |
+| `travel_cancel_booking` | Cancel & void the authorization |
+| `travel_list_rebates` | Accumulated 10% cbBTC rebates (7% dev / 3% treasury) |
+
+## Use as a library
+
+```ts
+import { TravelClient, MCC } from "@furlpay/travel-mcp";
+
+const travel = new TravelClient({ developerWallet: "0xDev" });
+
+const stays = await travel.searchStays({
+  city: "London", checkIn: "2026-08-01", checkOut: "2026-08-04", maxNightlyUsd: 200,
+});
+
+travel.setAgentBudget("agent_1", 1000);
+
+// Crypto-native route → x402/USDC on Base + 10% cbBTC rebate
+const booking = await travel.authorizeBooking({
+  amountUsd: stays[0].totalUsd, source: "travala", agentId: "agent_1", reference: stays[0].quoteId,
+});
+// booking.authorization.x402  ·  booking.rebate.developerUsd
+
+// Legacy merchant route → single-use MCC-locked Visa VCN
+const legacy = await travel.authorizeBooking({ amountUsd: 130, source: "legacy", mcc: MCC.LODGING });
+// legacy.authorization.card = { last4, mccWhitelist, singleUse, limitUsd }
+
+travel.listRebates();   // { developerTotalUsd, treasuryTotalUsd, accruals }
+```
+
+## How the routes map to reality
+
+| Route | Rail | Why |
+| --- | --- | --- |
+| `travala` | x402 → gasless USDC on **Base**, ~$0.01/booking | The rail Travala's protocol accepts directly; earns the cbBTC rebate |
+| `legacy` | Single-use **Visa VCN**, MCC-locked (7011 lodging, 4511 airlines, 7512 car rental) | Reaches Web2 travel merchants Travala doesn't cover; card can only spend on travel, up to the booking total |
+
+FurlPay's value here is the layer Travala doesn't provide: **agent spend budgets,
+multi-token funding, VCN issuing for legacy merchants, and rebate accounting.**
+
+## Run the demo
+
+```sh
+npm run example        # full search → pay → book → rebate flow, demo mode
+npm start              # run the MCP server on stdio
+```
+
+## Test
+
+```sh
+npm test               # tsc build + node --test (demo mode, no network)
+```
+
+The suite pins the contract: deterministic search, the x402 route's proof + exact
+10%/(7/3) rebate math, the legacy route's single-use MCC-locked VCN, budget
+enforcement, the confirm/cancel lifecycle, rebate aggregation (excluding
+cancellations), and well-formed MCP tools.
+
+## Scope
+
+This server orchestrates Travala search and FurlPay payments — it does not custody
+funds or settle on-chain itself; x402 settlement and card issuing happen in the
+FurlPay API, and inventory/fulfilment in Travala. Point it at your own accounts and
+it books on your behalf. Issuing travel cards and handling refunds carries
+money-transmission/merchant-compliance obligations — wire in FurlPay's compliance
+engine before going live.
+
+## License
+
+MIT

package/dist/furlpay.d.ts

@@ -0,0 +1,24 @@
+import { Authorization, BookingSource } from "./types";
+export declare const MCC: {
+    readonly LODGING: "7011";
+    readonly AIRLINES: "4511";
+    readonly CAR_RENTAL: "7512";
+    readonly TRAVEL_AGENCY: "4722";
+};
+export declare class FurlPayPay {
+    private readonly apiKey?;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(apiKey?: string | undefined, baseUrl?: string, fetchImpl?: typeof fetch);
+    get live(): boolean;
+    /** Authorize a booking on the chosen route, returning the payment credential. */
+    authorize(params: {
+        route: BookingSource;
+        amountUsd: number;
+        currency?: string;
+        mcc?: string;
+    }): Promise<Authorization>;
+    private authorizeX402;
+    private issueVirtualCard;
+    private post;
+}

package/dist/furlpay.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FurlPayPay = exports.MCC = void 0;
+/**
+ * FurlPay payment side of the composition. Produces the credential a booking
+ * needs, per route:
+ *
+ *   - travala (crypto-native): an x402 payment proof, settled in gasless USDC on
+ *     Base — the rail Travala's protocol accepts directly.
+ *   - legacy (Web2 merchants like Airbnb/Skyscanner): a single-use Visa virtual
+ *     card number, MCC-locked to travel and limited to the booking total.
+ *
+ * With no FurlPay key set, both routes simulate (no network) so the flow is fully
+ * runnable offline. Card PANs are never real in demo mode.
+ */
+const DEFAULT_BASE = "https://api.furlpay.com/v1";
+// Common travel MCCs. 7011 = Lodging/Hotels, 4511 = Airlines, 7512 = Car Rental,
+// 4722 = Travel Agencies.
+exports.MCC = { LODGING: "7011", AIRLINES: "4511", CAR_RENTAL: "7512", TRAVEL_AGENCY: "4722" };
+function rid(prefix) {
+    return prefix + Math.random().toString(36).slice(2, 10);
+}
+class FurlPayPay {
+    constructor(apiKey, baseUrl = process.env.FURLPAY_API_BASE || DEFAULT_BASE, fetchImpl = globalThis.fetch) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+        this.fetchImpl = fetchImpl;
+    }
+    get live() {
+        return Boolean(this.apiKey);
+    }
+    /** Authorize a booking on the chosen route, returning the payment credential. */
+    async authorize(params) {
+        const currency = (params.currency ?? "USDC").toUpperCase();
+        if (params.route === "travala")
+            return this.authorizeX402(params.amountUsd, currency);
+        return this.issueVirtualCard(params.amountUsd, currency, params.mcc ?? exports.MCC.LODGING);
+    }
+    async authorizeX402(amountUsd, currency) {
+        if (!this.live) {
+            return {
+                route: "travala",
+                amount: amountUsd,
+                currency,
+                x402: { proof: rid("x402_sim_"), network: "base", token: "USDC", settlementTx: rid("tx_sim_") },
+                simulated: true,
+            };
+        }
+        const settled = await this.post("/x402/settle", { amount: amountUsd, token: "USDC", destination: "travala" });
+        return {
+            route: "travala",
+            amount: amountUsd,
+            currency,
+            x402: {
+                proof: settled.payment_header || settled.proof,
+                network: settled.network || "base",
+                token: "USDC",
+                settlementTx: settled.tx,
+            },
+        };
+    }
+    async issueVirtualCard(amountUsd, currency, mcc) {
+        if (!this.live) {
+            const last4 = String(1000 + Math.floor(Math.random() * 9000)).slice(-4);
+            return {
+                route: "legacy",
+                amount: amountUsd,
+                currency,
+                card: {
+                    id: rid("card_sim_"),
+                    last4,
+                    expMonth: 12,
+                    expYear: new Date().getUTCFullYear() + 3,
+                    mccWhitelist: [mcc],
+                    singleUse: true,
+                    limitUsd: amountUsd,
+                },
+                simulated: true,
+            };
+        }
+        const card = await this.post("/cards", {
+            type: "virtual",
+            currency,
+            limit: amountUsd,
+            mcc_whitelist: [mcc],
+            single_use: true,
+        });
+        return {
+            route: "legacy",
+            amount: amountUsd,
+            currency,
+            card: {
+                id: card.id,
+                last4: card.last4,
+                expMonth: card.exp_month,
+                expYear: card.exp_year,
+                mccWhitelist: card.mcc_whitelist ?? [mcc],
+                singleUse: true,
+                limitUsd: amountUsd,
+            },
+        };
+    }
+    async post(path, body) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${this.apiKey}`, "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        const text = await res.text();
+        const json = text ? JSON.parse(text) : {};
+        if (!res.ok)
+            throw new Error(json.error || `FurlPay HTTP ${res.status}`);
+        return json;
+    }
+}
+exports.FurlPayPay = FurlPayPay;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { TravelClient, MCC } from "./travel";
+export { TravalaClient } from "./travala";
+export { FurlPayPay } from "./furlpay";
+export { buildTools } from "./tools";
+export type { McpTool } from "./tools";
+export * from "./types";

package/dist/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTools = exports.FurlPayPay = exports.TravalaClient = exports.MCC = exports.TravelClient = void 0;
+var travel_1 = require("./travel");
+Object.defineProperty(exports, "TravelClient", { enumerable: true, get: function () { return travel_1.TravelClient; } });
+Object.defineProperty(exports, "MCC", { enumerable: true, get: function () { return travel_1.MCC; } });
+var travala_1 = require("./travala");
+Object.defineProperty(exports, "TravalaClient", { enumerable: true, get: function () { return travala_1.TravalaClient; } });
+var furlpay_1 = require("./furlpay");
+Object.defineProperty(exports, "FurlPayPay", { enumerable: true, get: function () { return furlpay_1.FurlPayPay; } });
+var tools_1 = require("./tools");
+Object.defineProperty(exports, "buildTools", { enumerable: true, get: function () { return tools_1.buildTools; } });
+__exportStar(require("./types"), exports);

package/dist/server.d.ts

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

package/dist/server.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * FurlPay Travels MCP server (stdio transport, JSON-RPC 2.0).
+ *
+ * Composes Travala's Travel MCP (search) with FurlPay's payment rails (pay) and
+ * exposes them as MCP tools for Claude, Cursor, and AI agents. Runs on demo data
+ * with no keys.
+ *
+ * Configure in an MCP client:
+ *   {
+ *     "mcpServers": {
+ *       "furlpay-travels": {
+ *         "command": "npx", "args": ["-y", "@furlpay/travel-mcp"],
+ *         "env": { "FURLPAY_API_KEY": "fp_live_sk_...", "TRAVALA_API_KEY": "..." }
+ *       }
+ *     }
+ *   }
+ */
+const tools_1 = require("./tools");
+const travel_1 = require("./travel");
+const client = new travel_1.TravelClient();
+const tools = (0, tools_1.buildTools)(client);
+function send(msg) {
+    process.stdout.write(JSON.stringify(msg) + "\n");
+}
+async function handle(line) {
+    let req;
+    try {
+        req = JSON.parse(line);
+    }
+    catch {
+        return;
+    }
+    const { id, method, params } = req;
+    try {
+        if (method === "initialize") {
+            return send({
+                jsonrpc: "2.0",
+                id,
+                result: {
+                    protocolVersion: "2024-11-05",
+                    capabilities: { tools: {} },
+                    serverInfo: { name: "furlpay-travels", version: "0.1.0" },
+                },
+            });
+        }
+        if (method === "tools/list") {
+            return send({
+                jsonrpc: "2.0",
+                id,
+                result: { tools: tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) },
+            });
+        }
+        if (method === "tools/call") {
+            const tool = tools.find((t) => t.name === params?.name);
+            if (!tool)
+                throw new Error(`Unknown tool: ${params?.name}`);
+            const result = await tool.handler(params.arguments || {});
+            return send({
+                jsonrpc: "2.0",
+                id,
+                result: { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] },
+            });
+        }
+        if (typeof method === "string" && method.startsWith("notifications/"))
+            return;
+        throw new Error(`Method not found: ${method}`);
+    }
+    catch (e) {
+        send({ jsonrpc: "2.0", id, error: { code: -32000, message: e.message } });
+    }
+}
+let buffer = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+    buffer += chunk;
+    let idx;
+    while ((idx = buffer.indexOf("\n")) >= 0) {
+        const line = buffer.slice(0, idx).trim();
+        buffer = buffer.slice(idx + 1);
+        if (line)
+            void handle(line);
+    }
+});
+process.stderr.write(`furlpay-travels MCP ready (${client.live ? "live" : "demo"} mode)\n`);

package/dist/tools.d.ts

@@ -0,0 +1,9 @@
+import { TravelClient } from "./travel";
+export interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: (args: any) => Promise<unknown> | unknown;
+}
+/** Build the MCP toolset bound to a TravelClient. */
+export declare function buildTools(client: TravelClient): McpTool[];

package/dist/tools.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTools = buildTools;
+/** Build the MCP toolset bound to a TravelClient. */
+function buildTools(client) {
+    return [
+        {
+            name: "travel_search_stays",
+            description: "Search Travala's 2.2M+ hotels (Marriott, Hilton, IHG, …) for a city and date range. Returns quotes with a quoteId to book.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    city: { type: "string" },
+                    checkIn: { type: "string", description: "YYYY-MM-DD" },
+                    checkOut: { type: "string", description: "YYYY-MM-DD" },
+                    maxNightlyUsd: { type: "number", description: "Optional nightly price cap in USD" },
+                    guests: { type: "number" },
+                },
+                required: ["city", "checkIn", "checkOut"],
+            },
+            handler: (a) => client.searchStays(a),
+        },
+        {
+            name: "travel_search_flights",
+            description: "Search flights via Travala for a route and date. Returns quotes with a quoteId.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    from: { type: "string", description: "Origin IATA code" },
+                    to: { type: "string", description: "Destination IATA code" },
+                    date: { type: "string", description: "YYYY-MM-DD" },
+                },
+                required: ["from", "to", "date"],
+            },
+            handler: (a) => client.searchFlights(a),
+        },
+        {
+            name: "travel_set_agent_budget",
+            description: "Set a USDC spend cap for an agent before it books autonomously.",
+            inputSchema: {
+                type: "object",
+                properties: { agentId: { type: "string" }, limitUsd: { type: "number" } },
+                required: ["agentId", "limitUsd"],
+            },
+            handler: (a) => {
+                client.setAgentBudget(a.agentId, a.limitUsd);
+                return client.getAgentBudget(a.agentId);
+            },
+        },
+        {
+            name: "travel_authorize_booking",
+            description: "Authorize payment for a booking within the agent's budget. source='travala' pays via x402/USDC on Base and accrues the 10% cbBTC rebate; source='legacy' issues a single-use, MCC-locked Visa virtual card for Web2 merchants (Airbnb, Skyscanner).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    amountUsd: { type: "number" },
+                    source: { type: "string", enum: ["travala", "legacy"] },
+                    currency: { type: "string", description: "Default USDC" },
+                    mcc: { type: "string", description: "Merchant Category Code lock for the legacy route, e.g. 7011 (lodging)" },
+                    agentId: { type: "string" },
+                    reference: { type: "string", description: "Quote/booking reference" },
+                },
+                required: ["amountUsd", "source"],
+            },
+            handler: (a) => client.authorizeBooking(a),
+        },
+        {
+            name: "travel_confirm_booking",
+            description: "Confirm an authorized booking (after passkey step-up in a real flow).",
+            inputSchema: {
+                type: "object",
+                properties: { bookingId: { type: "string" } },
+                required: ["bookingId"],
+            },
+            handler: (a) => client.confirmBooking(a.bookingId),
+        },
+        {
+            name: "travel_cancel_booking",
+            description: "Cancel a booking and void its authorization.",
+            inputSchema: {
+                type: "object",
+                properties: { bookingId: { type: "string" } },
+                required: ["bookingId"],
+            },
+            handler: (a) => client.cancelBooking(a.bookingId),
+        },
+        {
+            name: "travel_list_rebates",
+            description: "List accumulated 10% cbBTC developer rebates from Travala-routed bookings (7% developer / 3% treasury split).",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            handler: () => client.listRebates(),
+        },
+    ];
+}

package/dist/travala.d.ts

@@ -0,0 +1,23 @@
+import { Flight, Stay } from "./types";
+export declare class TravalaClient {
+    private readonly url;
+    private readonly apiKey?;
+    private readonly fetchImpl;
+    constructor(url?: string, apiKey?: string | undefined, fetchImpl?: typeof fetch);
+    get live(): boolean;
+    searchStays(params: {
+        city: string;
+        checkIn: string;
+        checkOut: string;
+        maxNightlyUsd?: number;
+        guests?: number;
+    }): Promise<Stay[]>;
+    searchFlights(params: {
+        from: string;
+        to: string;
+        date: string;
+    }): Promise<Flight[]>;
+    private call;
+    private demoStays;
+    private demoFlights;
+}