@furlpay/travel-mcp 0.1.0

package/src/server.ts

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * 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": "..." }
+ *       }
+ *     }
+ *   }
+ */
+import { buildTools } from "./tools";
+import { TravelClient } from "./travel";
+
+const client = new TravelClient();
+const tools = buildTools(client);
+
+function send(msg: unknown): void {
+  process.stdout.write(JSON.stringify(msg) + "\n");
+}
+
+async function handle(line: string): Promise<void> {
+  let req: any;
+  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 as Error).message } });
+  }
+}
+
+let buffer = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buffer += chunk;
+  let idx: number;
+  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/src/tools.ts

@@ -0,0 +1,102 @@
+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 function buildTools(client: TravelClient): McpTool[] {
+  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/src/travala.ts

@@ -0,0 +1,169 @@
+import { Flight, Stay } from "./types";
+
+/**
+ * Thin client for the Travala Travel MCP (search side of the composition).
+ *
+ * Travala's Agentic AI Travel Protocol exposes 2.2M+ hotels (Marriott, Hilton,
+ * IHG, …) — expanding to flights — to AI agents, settling in gasless USDC over
+ * x402 on Base. This wrapper is search-only; payment/settlement is FurlPay's job.
+ *
+ * With no key set it returns deterministic demo inventory so the whole
+ * search → pay → book loop runs offline.
+ */
+
+const DEFAULT_MCP = "https://travel-mcp.travala.com/mcp";
+const round2 = (n: number) => Math.round(n * 100) / 100;
+
+function hash(s: string): number {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+
+const HOTEL_BRANDS = ["Marriott", "Hilton", "IHG", "Accor", "Hyatt"];
+
+function nightsBetween(checkIn: string, checkOut: string): number {
+  const a = Date.parse(checkIn);
+  const b = Date.parse(checkOut);
+  if (isNaN(a) || isNaN(b) || b <= a) return 1;
+  return Math.max(1, Math.round((b - a) / 86_400_000));
+}
+
+export class TravalaClient {
+  constructor(
+    private readonly url: string = process.env.TRAVALA_MCP_URL || DEFAULT_MCP,
+    private readonly apiKey?: string,
+    private readonly fetchImpl: typeof fetch = globalThis.fetch,
+  ) {}
+
+  get live(): boolean {
+    return Boolean(this.apiKey);
+  }
+
+  async searchStays(params: {
+    city: string;
+    checkIn: string;
+    checkOut: string;
+    maxNightlyUsd?: number;
+    guests?: number;
+  }): Promise<Stay[]> {
+    const nights = nightsBetween(params.checkIn, params.checkOut);
+    if (!this.live) return this.demoStays(params, nights);
+    try {
+      const rows = await this.call("search_stays", { ...params });
+      const stays = (rows as any[]).map((r) => normaliseStay(r, params, nights));
+      return params.maxNightlyUsd ? stays.filter((s) => s.nightlyUsd <= params.maxNightlyUsd!) : stays;
+    } catch {
+      return this.demoStays(params, nights);
+    }
+  }
+
+  async searchFlights(params: { from: string; to: string; date: string }): Promise<Flight[]> {
+    if (!this.live) return this.demoFlights(params);
+    try {
+      const rows = await this.call("search_flights", { ...params });
+      return (rows as any[]).map((r) => normaliseFlight(r, params));
+    } catch {
+      return this.demoFlights(params);
+    }
+  }
+
+  // -- transport (Travala MCP is JSON-RPC over HTTP) ----------------------
+
+  private async call(tool: string, args: Record<string, unknown>): Promise<unknown> {
+    const res = await this.fetchImpl(this.url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
+      },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: tool, arguments: args } }),
+    });
+    if (!res.ok) throw new Error(`Travala MCP HTTP ${res.status}`);
+    const json: any = await res.json();
+    if (json.error) throw new Error(json.error.message || "Travala MCP error");
+    const content = json.result?.content?.[0];
+    const text = content?.text ?? "[]";
+    return typeof text === "string" ? JSON.parse(text) : text;
+  }
+
+  // -- deterministic demo inventory ---------------------------------------
+
+  private demoStays(
+    params: { city: string; checkIn: string; checkOut: string; maxNightlyUsd?: number; guests?: number },
+    nights: number,
+  ): Stay[] {
+    const seed = hash(params.city.toLowerCase());
+    const stays: Stay[] = Array.from({ length: 5 }, (_, i) => {
+      const brand = HOTEL_BRANDS[(seed + i) % HOTEL_BRANDS.length];
+      const nightly = round2(80 + ((seed >> (i + 1)) % 260)); // ~$80–$340
+      return {
+        quoteId: `tvl_demo_${(seed % 0xffff).toString(16)}_${i}`,
+        name: `${brand} ${titleCase(params.city)} ${["Central", "Riverside", "Airport", "Old Town", "Bay"][i]}`,
+        brand,
+        city: titleCase(params.city),
+        stars: 3 + (i % 3),
+        checkIn: params.checkIn,
+        checkOut: params.checkOut,
+        nights,
+        nightlyUsd: nightly,
+        totalUsd: round2(nightly * nights),
+        source: "demo" as const,
+      };
+    });
+    return params.maxNightlyUsd ? stays.filter((s) => s.nightlyUsd <= params.maxNightlyUsd!) : stays;
+  }
+
+  private demoFlights(params: { from: string; to: string; date: string }): Flight[] {
+    const seed = hash(params.from + params.to);
+    const carriers = ["BA", "LH", "AF", "EK", "QR"];
+    return Array.from({ length: 3 }, (_, i) => ({
+      quoteId: `tvlf_demo_${(seed % 0xffff).toString(16)}_${i}`,
+      carrier: carriers[(seed + i) % carriers.length],
+      from: params.from.toUpperCase(),
+      to: params.to.toUpperCase(),
+      date: params.date,
+      cabin: ["economy", "premium", "business"][i % 3],
+      totalUsd: round2(180 + ((seed >> (i + 2)) % 900)),
+      source: "demo" as const,
+    }));
+  }
+}
+
+function normaliseStay(r: any, p: { city: string; checkIn: string; checkOut: string }, nights: number): Stay {
+  const nightly = Number(r.nightlyUsd ?? r.price ?? 0);
+  return {
+    quoteId: String(r.quoteId ?? r.id ?? ""),
+    name: String(r.name ?? "Hotel"),
+    brand: String(r.brand ?? "Independent"),
+    city: String(r.city ?? p.city),
+    stars: Number(r.stars ?? 3),
+    checkIn: p.checkIn,
+    checkOut: p.checkOut,
+    nights,
+    nightlyUsd: nightly,
+    totalUsd: Number(r.totalUsd ?? nightly * nights),
+    source: "travala",
+  };
+}
+
+function normaliseFlight(r: any, p: { from: string; to: string; date: string }): Flight {
+  return {
+    quoteId: String(r.quoteId ?? r.id ?? ""),
+    carrier: String(r.carrier ?? "XX"),
+    from: p.from.toUpperCase(),
+    to: p.to.toUpperCase(),
+    date: p.date,
+    cabin: String(r.cabin ?? "economy"),
+    totalUsd: Number(r.totalUsd ?? r.price ?? 0),
+    source: "travala",
+  };
+}
+
+function titleCase(s: string): string {
+  return s.replace(/\w\S*/g, (t) => t.charAt(0).toUpperCase() + t.slice(1).toLowerCase());
+}

package/src/travel.ts

@@ -0,0 +1,184 @@
+import { FurlPayPay, MCC } from "./furlpay";
+import { TravalaClient } from "./travala";
+import {
+  Booking,
+  BookingSource,
+  Flight,
+  RebateAccrual,
+  Stay,
+  TravelOptions,
+} from "./types";
+
+export { MCC } from "./furlpay";
+export * from "./types";
+
+// Travala pays a 10% cbBTC developer rebate on MCP-driven bookings. We split it
+// 7% to the integrating developer, 3% to the FurlPay treasury.
+const REBATE_RATE = 0.1;
+const DEVELOPER_SHARE = 0.7;
+
+/**
+ * FurlPay Travels — composes Travala's Travel MCP (search) with FurlPay's payment
+ * rails (pay). An agent searches inventory, FurlPay checks the spend budget and
+ * issues a credential (x402 proof for the Travala/Base route, or a single-use
+ * MCC-locked Visa VCN for legacy merchants), and the booking accrues the 10%
+ * cbBTC rebate.
+ *
+ * Clone-and-run: with no keys, search and payment simulate end-to-end.
+ */
+export class TravelClient {
+  private readonly travala: TravalaClient;
+  private readonly pay: FurlPayPay;
+  private readonly developerWallet?: string;
+  private readonly bookings = new Map<string, Booking>();
+  /** Per-agent USDC spend caps for autonomous booking. */
+  private readonly budgets = new Map<string, { limit: number; spent: number }>();
+
+  constructor(opts: TravelOptions = {}) {
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    this.travala = new TravalaClient(
+      opts.travalaMcpUrl || process.env.TRAVALA_MCP_URL,
+      process.env.TRAVALA_API_KEY,
+      fetchImpl,
+    );
+    this.pay = new FurlPayPay(
+      opts.furlpayApiKey || process.env.FURLPAY_API_KEY,
+      opts.furlpayBaseUrl,
+      fetchImpl,
+    );
+    this.developerWallet = opts.developerWallet || process.env.FURLPAY_DEVELOPER_WALLET;
+  }
+
+  get live(): boolean {
+    return this.pay.live;
+  }
+
+  // -- search -------------------------------------------------------------
+
+  searchStays(p: { city: string; checkIn: string; checkOut: string; maxNightlyUsd?: number; guests?: number }): Promise<Stay[]> {
+    return this.travala.searchStays(p);
+  }
+
+  searchFlights(p: { from: string; to: string; date: string }): Promise<Flight[]> {
+    return this.travala.searchFlights(p);
+  }
+
+  // -- budget policy ------------------------------------------------------
+
+  setAgentBudget(agentId: string, limitUsd: number): void {
+    const existing = this.budgets.get(agentId);
+    this.budgets.set(agentId, { limit: limitUsd, spent: existing?.spent ?? 0 });
+  }
+
+  getAgentBudget(agentId: string): { limit: number; spent: number; remaining: number } {
+    const b = this.budgets.get(agentId) ?? { limit: Infinity, spent: 0 };
+    return { limit: b.limit, spent: b.spent, remaining: b.limit - b.spent };
+  }
+
+  // -- book ---------------------------------------------------------------
+
+  /**
+   * Authorize a booking. `source: "travala"` pays via x402/USDC on Base; any other
+   * merchant uses `source: "legacy"` → a single-use MCC-locked Visa VCN.
+   * Enforces the agent budget before authorizing.
+   */
+  async authorizeBooking(params: {
+    amountUsd: number;
+    source: BookingSource;
+    currency?: string;
+    mcc?: string;
+    agentId?: string;
+    reference?: string;
+  }): Promise<Booking> {
+    if (params.amountUsd <= 0) throw new Error("amountUsd must be > 0");
+
+    const agentId = params.agentId ?? "agent_default";
+    const budget = this.budgets.get(agentId);
+    if (budget && budget.spent + params.amountUsd > budget.limit) {
+      throw new Error(
+        `booking $${params.amountUsd} exceeds remaining budget $${(budget.limit - budget.spent).toFixed(2)} for ${agentId}`,
+      );
+    }
+
+    const authorization = await this.pay.authorize({
+      route: params.source,
+      amountUsd: params.amountUsd,
+      currency: params.currency,
+      mcc: params.mcc ?? (params.source === "legacy" ? MCC.LODGING : undefined),
+    });
+
+    const booking: Booking = {
+      id: "bk_" + Math.random().toString(36).slice(2, 10),
+      source: params.source,
+      reference: params.reference ?? "(unassigned)",
+      amountUsd: params.amountUsd,
+      status: "authorized",
+      authorization,
+      rebate: params.source === "travala" ? this.accrueRebate("", params.amountUsd) : undefined,
+      createdAt: new Date().toISOString(),
+    };
+    if (booking.rebate) booking.rebate.bookingId = booking.id;
+
+    if (budget) budget.spent += params.amountUsd;
+    this.bookings.set(booking.id, booking);
+    return booking;
+  }
+
+  /** Mark an authorized booking confirmed (after passkey step-up in a real flow). */
+  confirmBooking(id: string): Booking {
+    const b = this.require(id);
+    if (b.status === "cancelled") throw new Error(`booking ${id} is cancelled`);
+    b.status = "confirmed";
+    return b;
+  }
+
+  cancelBooking(id: string): Booking {
+    const b = this.require(id);
+    b.status = "cancelled";
+    const budget = this.budgets.get("agent_default");
+    return b;
+  }
+
+  getBooking(id: string): Booking | undefined {
+    return this.bookings.get(id);
+  }
+
+  // -- rebates ------------------------------------------------------------
+
+  /** All cbBTC rebate accruals to date and the developer's cumulative share. */
+  listRebates(): { developerWallet?: string; accruals: RebateAccrual[]; developerTotalUsd: number; treasuryTotalUsd: number } {
+    const accruals = [...this.bookings.values()]
+      .filter((b) => b.rebate && b.status !== "cancelled")
+      .map((b) => b.rebate!) as RebateAccrual[];
+    return {
+      developerWallet: this.developerWallet,
+      accruals,
+      developerTotalUsd: round2(accruals.reduce((s, r) => s + r.developerUsd, 0)),
+      treasuryTotalUsd: round2(accruals.reduce((s, r) => s + r.treasuryUsd, 0)),
+    };
+  }
+
+  private accrueRebate(bookingId: string, amountUsd: number): RebateAccrual {
+    const total = round2(amountUsd * REBATE_RATE);
+    const developerUsd = round2(total * DEVELOPER_SHARE);
+    return {
+      bookingId,
+      currency: "cbBTC",
+      totalUsd: total,
+      developerUsd,
+      treasuryUsd: round2(total - developerUsd),
+    };
+  }
+
+  private require(id: string): Booking {
+    const b = this.bookings.get(id);
+    if (!b) throw new Error(`no booking ${id}`);
+    return b;
+  }
+}
+
+function round2(n: number): number {
+  return Math.round(n * 100) / 100;
+}
+
+export default TravelClient;

package/src/types.ts

@@ -0,0 +1,79 @@
+export type BookingSource = "travala" | "legacy";
+
+export interface Stay {
+  quoteId: string;
+  name: string;
+  brand: string;
+  city: string;
+  stars: number;
+  checkIn: string;
+  checkOut: string;
+  nights: number;
+  nightlyUsd: number;
+  totalUsd: number;
+  source: "travala" | "demo";
+}
+
+export interface Flight {
+  quoteId: string;
+  carrier: string;
+  from: string;
+  to: string;
+  date: string;
+  cabin: string;
+  totalUsd: number;
+  source: "travala" | "demo";
+}
+
+/** A payment authorization FurlPay hands back for a booking. */
+export interface Authorization {
+  route: BookingSource;
+  amount: number;
+  currency: string;
+  /** Present on the crypto route: an x402 payment proof settled on Base. */
+  x402?: { proof: string; network: string; token: string; settlementTx?: string };
+  /** Present on the legacy route: a single-use Visa virtual card number, MCC-locked. */
+  card?: {
+    id: string;
+    last4: string;
+    expMonth: number;
+    expYear: number;
+    mccWhitelist: string[];
+    singleUse: boolean;
+    limitUsd: number;
+  };
+  simulated?: boolean;
+}
+
+export interface Booking {
+  id: string;
+  source: BookingSource;
+  reference: string;
+  amountUsd: number;
+  status: "authorized" | "confirmed" | "cancelled";
+  authorization: Authorization;
+  /** 10% cbBTC developer rebate accrued on Travala-routed bookings. */
+  rebate?: RebateAccrual;
+  createdAt: string;
+}
+
+export interface RebateAccrual {
+  bookingId: string;
+  currency: "cbBTC";
+  totalUsd: number; // 10% of booking, expressed in USD-equivalent
+  developerUsd: number; // 7%
+  treasuryUsd: number; // 3%
+}
+
+export interface TravelOptions {
+  /** FurlPay API key. Omit → demo mode (searches + payments simulate, no network). */
+  furlpayApiKey?: string;
+  /** FurlPay API base. Default https://api.furlpay.com/v1 */
+  furlpayBaseUrl?: string;
+  /** Travala Travel MCP endpoint. Default https://travel-mcp.travala.com/mcp */
+  travalaMcpUrl?: string;
+  /** Developer wallet that receives the 7% cbBTC rebate split. */
+  developerWallet?: string;
+  /** Override fetch (Node 18+ has a global fetch). */
+  fetchImpl?: typeof fetch;
+}