imprint-mcp 0.2.1 → 0.3.1

package/examples/google-flights/lookup_airport/parser.ts

@@ -0,0 +1,66 @@
+import { extractRpcPayload } from '../_shared/batchexecute.ts';
+
+// Parse the tDoGIe (airport/place resolution) batchexecute response.
+//
+// Decoded payload shape (seq 69):
+//   [ [null,null,0,"<token>"],
+//     [  // <- payload[1]: array of matches
+//       [ ["SJC",0], "San Jose Mineta International Airport",
+//         ["/m/0f04v","San Jose",[[img],[img]]], [37.3627778,-121.92917],
+//         "US", false, "United States" ],
+//       [ ["/m/0f04v",4], "San Jose", ["/m/0f04v","San Jose",...], [37.33874,-121.8852525], ... ]
+//     ] ]
+// Each match item: [0][0]=code (IATA or /m/ entity id), [1]=name,
+//   [2][1]=associated city, [3]=[lat,lng], [4]=country code, [6]=country name.
+
+interface AirportMatch {
+  code: string | null;
+  name: string | null;
+  city: string | null;
+  lat: number | null;
+  lng: number | null;
+  country: string | null;
+  countryName: string | null;
+}
+
+function parseItem(item: unknown): AirportMatch | null {
+  if (!Array.isArray(item)) return null;
+  const code = Array.isArray(item[0]) ? (item[0][0] ?? null) : null;
+  const name = typeof item[1] === 'string' ? item[1] : null;
+  const city = Array.isArray(item[2]) && typeof item[2][1] === 'string' ? item[2][1] : null;
+  const coords = item[3];
+  const lat = Array.isArray(coords) && typeof coords[0] === 'number' ? coords[0] : null;
+  const lng = Array.isArray(coords) && typeof coords[1] === 'number' ? coords[1] : null;
+  const country = typeof item[4] === 'string' ? item[4] : null;
+  const countryName = typeof item[6] === 'string' ? item[6] : null;
+  const m: AirportMatch = { code, name, city, lat, lng, country, countryName };
+  // Drop content-less placeholder records (API no-match sentinel).
+  if (m.code == null && m.name == null) return null;
+  return m;
+}
+
+export function extract(
+  rawResponse: unknown,
+  context?: { params: Record<string, string | number | boolean>; responses: unknown[] },
+): unknown {
+  const raw = typeof rawResponse === 'string' ? rawResponse : JSON.stringify(rawResponse);
+  const payload = extractRpcPayload(raw, 'tDoGIe');
+
+  const matchesRaw = Array.isArray(payload) && Array.isArray(payload[1]) ? payload[1] : [];
+  const matches = matchesRaw
+    .map(parseItem)
+    .filter((m): m is AirportMatch => m !== null);
+
+  const primary = matches[0] ?? null;
+  return {
+    query: context?.params?.query ?? null,
+    matchCount: matches.length,
+    matches,
+    // Convenience: hoist the best (first) match to the top level.
+    code: primary?.code ?? null,
+    name: primary?.name ?? null,
+    city: primary?.city ?? null,
+    lat: primary?.lat ?? null,
+    lng: primary?.lng ?? null,
+  };
+}

package/examples/google-flights/lookup_airport/playbook.yaml

@@ -0,0 +1,47 @@
+toolName: lookup_airport
+summary: Resolve a city or airport query (e.g. "SJC" or "san jose") into structured airport matches via Google Flights' autocomplete RPC.
+parameters:
+  - name: query
+    type: string
+    description: City or airport search text, e.g. "san jose" or "SJC".
+steps:
+  - action: navigate
+    url: https://www.google.com/travel/flights
+    wait_for: networkidle
+  - action: click
+    locators:
+      - by: aria_label
+        value: "Where from?"
+      - by: css
+        value: "div.cQnuXe.k0gFV input.II2One.j0Ppje"
+    wait_for:
+      sleep_ms: 300
+  - action: type
+    locators:
+      - by: aria_label
+        value: "Where else?"
+      - by: aria_label
+        value: "Where from?"
+      - by: css
+        value: "input.II2One.j0Ppje"
+    value: ${query}
+    wait_for:
+      xhr: "batchexecute?rpcids=tDoGIe"
+      method: POST
+result:
+  source: xhr
+  url_pattern: "rpcids=tDoGIe"
+  extract: "1[]"
+  return_as: airports
+notes: >-
+  The tDoGIe response is a Google batchexecute payload, not plain JSON. The
+  downstream parser must: (1) strip the )]}' prefix and the numeric length-prefixed
+  chunk markers, (2) locate the ["wrb.fr","tDoGIe", <payload-string>, ...] envelope,
+  (3) JSON.parse the double-encoded <payload-string>. After decoding, the parsed
+  array's index [1] is the list of matches (the `extract` path "1[]" above). Each
+  match is positional: code = [0][0] (e.g. "SJC"), name = [1] (e.g. "San Jose Mineta
+  International Airport"), city = [2][1], lat = [3][0], lng = [3][1], country = [6].
+  Return one {code, name, city, lat, lng} object per match. The XHR is authorized by
+  the page-bootstrap session id (f.sid) and X-Goog-BatchExecute-Bgr header, which are
+  session-bound — they must come from a freshly loaded page (handled by the navigate
+  step), not parameterized. No login/auth is required.

package/examples/google-flights/lookup_airport/request-transform.ts

@@ -0,0 +1,20 @@
+// Builds the tDoGIe (airport lookup) batchexecute POST body.
+//
+// The body is a single form field `f.req` whose value is a doubly-encoded JSON
+// array: f.req=[[["tDoGIe","[null,[[\"<query>\",0]]]",null,"generic"]]]
+// The inner element is itself a JSON STRING (JSON-in-JSON), so we build it with
+// two JSON.stringify passes, then URL-encode the whole thing. Recorded seq 69
+// used query="SJC". This is the tool's own transform (the shared flights_request
+// module targets the FlightsFrontendService RPCs, not tDoGIe).
+export function transform(
+  _method: string,
+  url: string,
+  _responses: unknown[],
+  params?: Record<string, string | number | boolean>,
+): { url: string; body: string } {
+  const query = String(params?.query ?? '').trim();
+  const inner = JSON.stringify([null, [[query, 0]]]);
+  const outer = JSON.stringify([[['tDoGIe', inner, null, 'generic']]]);
+  const body = 'f.req=' + encodeURIComponent(outer) + '&';
+  return { url, body };
+}

package/examples/google-flights/lookup_airport/workflow.json

@@ -0,0 +1,57 @@
+{
+  "toolName": "lookup_airport",
+  "intent": {
+    "description": "Resolve a city or airport query into airport codes and structured airport details.",
+    "userSaid": "multi city from SJC to SAN to LAX to SFO"
+  },
+  "site": "google-flights",
+  "parameters": [
+    {
+      "name": "query",
+      "type": "string",
+      "description": "City or airport search text, e.g. 'san jose' or 'SJC'",
+      "verified": true
+    }
+  ],
+  "bootstrap": {
+    "url": "https://www.google.com/travel/flights",
+    "waitUntil": "domcontentloaded",
+    "timeoutMs": 30000,
+    "captures": [
+      {
+        "source": "html_regex",
+        "name": "f_sid",
+        "pattern": "\"FdrFJe\":\"([^\"]+)\"",
+        "group": 1,
+        "required": true,
+        "capability": "browser_bootstrap"
+      },
+      {
+        "source": "html_regex",
+        "name": "bl",
+        "pattern": "\"cfb2h\":\"([^\"]+)\"",
+        "group": 1,
+        "required": true,
+        "capability": "browser_bootstrap"
+      }
+    ]
+  },
+  "requests": [
+    {
+      "method": "POST",
+      "url": "https://www.google.com/_/FlightsFrontendUi/data/batchexecute?rpcids=tDoGIe&source-path=%2Ftravel%2Fflights&f.sid=${state.f_sid}&bl=${state.bl}&hl=en-US&soc-app=162&soc-platform=1&soc-device=1&_reqid=608023&rt=c",
+      "headers": {
+        "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8",
+        "X-Same-Domain": "1",
+        "Referer": "https://www.google.com/travel/flights",
+        "Accept-Language": "en-US,en;q=0.9",
+        "x-goog-ext-259736195-jspb": "[\"en-US\",\"US\",\"USD\",2,null,[420],null,null,7,[]]"
+      },
+      "body": "f.req=%5B%5B%5B%22tDoGIe%22%2C%22%5Bnull%2C%5B%5B%5C%22${param.query}%5C%22%2C0%5D%5D%5D%22%2Cnull%2C%22generic%22%5D%5D%5D&",
+      "effect": "safe"
+    }
+  ],
+  "parserModule": "./parser.ts",
+  "requestTransformModule": "./request-transform.ts",
+  "liveVerified": true
+}

package/examples/google-flights/search_flights/index.ts

@@ -0,0 +1,219 @@
+/**
+ * GENERATED by `imprint emit` — DO NOT EDIT BY HAND.
+ *
+ * Tool: search_flights
+ * Site: google-flights
+ * Intent: Search Google Flights for itineraries between two airports with dates, trip type, and filters (stops, airlines, price, times, duration, bags).
+ *
+ * To regenerate: imprint emit ~/.imprint/google-flights/search_flights/workflow.json --force
+ */
+
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import {
+  executeWorkflow,
+  type CredentialStore,
+} from 'imprint/runtime';
+import type { ToolResult, Workflow } from 'imprint/types';
+
+const WORKFLOW: Workflow = {
+  "toolName": "search_flights",
+  "intent": {
+    "description": "Search Google Flights for itineraries between two airports with dates, trip type, and filters (stops, airlines, price, times, duration, bags).",
+    "userSaid": "searched for a round trip flight; searched for a one way flight; played with the stops and the airlines filters; added bags; played with the price and time filters; played with the duration filter; did a multi city flight query"
+  },
+  "parameters": [
+    {
+      "name": "origin",
+      "type": "string",
+      "description": "Origin airport/city IATA code, e.g. SJC",
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "destination",
+      "type": "string",
+      "description": "Destination airport/city IATA code, e.g. SAN",
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "departure_date",
+      "type": "string",
+      "description": "Outbound date in YYYY-MM-DD",
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "return_date",
+      "type": "string",
+      "description": "Return date in YYYY-MM-DD (omit/empty for one way)",
+      "default": "",
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "trip_type",
+      "type": "string",
+      "description": "round_trip, one_way, or multi_city",
+      "default": "round_trip",
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "max_stops",
+      "type": "number",
+      "description": "Max stops: 0=nonstop, 1=<=1 stop, 2=<=2 stops, 3=any",
+      "default": 3,
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "airlines",
+      "type": "string",
+      "description": "Comma-separated alliance (ONEWORLD/SKYTEAM/STAR_ALLIANCE) or 2-letter carrier codes (e.g. AS,WN). Empty = no filter",
+      "default": "",
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "max_price",
+      "type": "number",
+      "description": "Maximum total price in USD (0 = no filter)",
+      "default": 0,
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "outbound_times",
+      "type": "string",
+      "description": "Outbound departure window in hours, e.g. '6-23' (empty = no filter)",
+      "default": "",
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "return_times",
+      "type": "string",
+      "description": "Return departure window in hours, e.g. '6-23' (empty = no filter)",
+      "default": "",
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "max_duration",
+      "type": "number",
+      "description": "Maximum total trip duration in minutes, e.g. 540 (0 = no filter)",
+      "default": 0,
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "carry_on_bags",
+      "type": "number",
+      "description": "Number of carry-on bags to filter/price by (0 = no filter)",
+      "default": 0,
+      "verified": false,
+      "verifyNote": "annotated"
+    }
+  ],
+  "requests": [
+    {
+      "method": "POST",
+      "url": "https://www.google.com/_/FlightsFrontendUi/data/travel.frontend.flights.FlightsFrontendService/GetShoppingResults?f.sid=${state.f_sid}&bl=${state.bl}&hl=en-US&soc-app=162&soc-platform=1&soc-device=1&_reqid=1708023&rt=c",
+      "headers": {
+        "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8",
+        "X-Same-Domain": "1",
+        "Referer": "https://www.google.com/travel/flights",
+        "x-goog-ext-259736195-jspb": "[\"en-US\",\"US\",\"USD\",2,null,[420],null,null,7,[]]"
+      },
+      "body": "f.req=${param.origin}|${param.destination}|${param.departure_date}|${param.return_date}|${param.trip_type}|${param.max_stops}|${param.airlines}|${param.max_price}|${param.outbound_times}|${param.return_times}|${param.max_duration}|${param.carry_on_bags}&",
+      "effect": "safe"
+    }
+  ],
+  "site": "google-flights",
+  "bootstrap": {
+    "url": "https://www.google.com/travel/flights",
+    "waitUntil": "domcontentloaded",
+    "timeoutMs": 30000,
+    "captures": [
+      {
+        "name": "f_sid",
+        "required": false,
+        "capability": "browser_bootstrap",
+        "source": "html_regex",
+        "pattern": "\"FdrFJe\":\"([^\"]+)\"",
+        "group": 1
+      },
+      {
+        "name": "bl",
+        "required": false,
+        "capability": "browser_bootstrap",
+        "source": "html_regex",
+        "pattern": "\"cfb2h\":\"([^\"]+)\"",
+        "group": 1
+      }
+    ]
+  },
+  "parserModule": "./parser.ts",
+  "requestTransformModule": "./request-transform.ts",
+  "liveVerified": true
+};
+
+export interface SearchFlightsInput {
+  /** Origin airport/city IATA code, e.g. SJC */
+  origin: string;
+  /** Destination airport/city IATA code, e.g. SAN */
+  destination: string;
+  /** Outbound date in YYYY-MM-DD */
+  departure_date: string;
+  /** Return date in YYYY-MM-DD (omit/empty for one way) */
+  return_date?: string;
+  /** round_trip, one_way, or multi_city */
+  trip_type?: string;
+  /** Max stops: 0=nonstop, 1=<=1 stop, 2=<=2 stops, 3=any */
+  max_stops?: number;
+  /** Comma-separated alliance (ONEWORLD/SKYTEAM/STAR_ALLIANCE) or 2-letter carrier codes (e.g. AS,WN). Empty = no filter */
+  airlines?: string;
+  /** Maximum total price in USD (0 = no filter) */
+  max_price?: number;
+  /** Outbound departure window in hours, e.g. '6-23' (empty = no filter) */
+  outbound_times?: string;
+  /** Return departure window in hours, e.g. '6-23' (empty = no filter) */
+  return_times?: string;
+  /** Maximum total trip duration in minutes, e.g. 540 (0 = no filter) */
+  max_duration?: number;
+  /** Number of carry-on bags to filter/price by (0 = no filter) */
+  carry_on_bags?: number;
+}
+
+export async function searchFlights(
+  input: SearchFlightsInput,
+  opts: { credentials?: CredentialStore; fetchImpl?: typeof fetch; initialState?: Record<string, unknown> } = {},
+): Promise<ToolResult> {
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const params: Record<string, string | number | boolean> = {
+    return_date: input.return_date ?? "",
+    trip_type: input.trip_type ?? "round_trip",
+    max_stops: input.max_stops ?? 3,
+    airlines: input.airlines ?? "",
+    max_price: input.max_price ?? 0,
+    outbound_times: input.outbound_times ?? "",
+    return_times: input.return_times ?? "",
+    max_duration: input.max_duration ?? 0,
+    carry_on_bags: input.carry_on_bags ?? 0,
+    origin: input.origin,
+    destination: input.destination,
+    departure_date: input.departure_date,
+  };
+  return executeWorkflow({
+    workflow: WORKFLOW,
+    params,
+    credentials: opts.credentials,
+    fetchImpl: opts.fetchImpl,
+    initialState: opts.initialState,
+    workflowPath: join(__dirname, 'workflow.json'),
+  });
+}
+
+export { WORKFLOW };

package/examples/google-flights/search_flights/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "imprint-tool-google-flights",
+  "private": true,
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "latest",
+    "bun-types": "latest"
+  }
+}

package/examples/google-flights/search_flights/parser.ts

@@ -0,0 +1,169 @@
+// Parser for Google Flights GetShoppingResults (batchexecute RPC).
+// Decodes the envelope with the shared helper, then walks the deeply-nested
+// positional payload to find itinerary records and normalize them.
+import { decodeBatchExecute, extractRpcPayload } from '../_shared/batchexecute.ts';
+
+interface Itinerary {
+  airlines: string[];
+  flightNumbers: string[];
+  origin: string;
+  destination: string;
+  departDate: string | null;
+  departTime: string | null;
+  arriveDate: string | null;
+  arriveTime: string | null;
+  durationMinutes: number | null;
+  stops: number;
+  priceUSD: number | null;
+  co2Grams: number | null;
+  flight_token: string;
+}
+
+const AIRPORT = /^[A-Z]{3}$/;
+
+// A leg is [carrierCode, [carrierNames], [segments], originIATA, [departDate],
+// [departTime], destIATA, [arriveDate], [arriveTime], durationMinutes, ...].
+function isLeg(leg: unknown): leg is unknown[] {
+  if (!Array.isArray(leg)) return false;
+  return (
+    typeof leg[0] === 'string' &&
+    Array.isArray(leg[1]) &&
+    typeof leg[3] === 'string' &&
+    AIRPORT.test(leg[3] as string) &&
+    typeof leg[6] === 'string' &&
+    AIRPORT.test(leg[6] as string)
+  );
+}
+
+// node[0] is either a single leg or an array of legs; node[1] is
+// [[null, <priceUSD>], "<base64 flight token>"].
+function legsOf(node: unknown[]): unknown[][] {
+  const head = node[0];
+  if (isLeg(head)) return [head as unknown[]];
+  if (Array.isArray(head)) return head.filter(isLeg) as unknown[][];
+  return [];
+}
+
+function isItinerary(node: unknown): node is unknown[] {
+  if (!Array.isArray(node)) return false;
+  if (legsOf(node).length === 0) return false;
+  const priceTok = node[1];
+  if (!Array.isArray(priceTok)) return false;
+  const priceArr = priceTok[0];
+  const token = priceTok[1];
+  if (!Array.isArray(priceArr)) return false;
+  if (typeof token !== 'string' || token.length < 20) return false;
+  return true;
+}
+
+function fmtTime(t: unknown): string | null {
+  if (!Array.isArray(t) || t.length === 0) return null;
+  const h = typeof t[0] === 'number' ? t[0] : 0;
+  const m = typeof t[1] === 'number' ? t[1] : 0;
+  return `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}`;
+}
+
+function fmtDate(d: unknown): string | null {
+  if (!Array.isArray(d) || d.length < 3) return null;
+  const [y, mo, day] = d as number[];
+  if (typeof y !== 'number') return null;
+  return `${y}-${String(mo).padStart(2, '0')}-${String(day).padStart(2, '0')}`;
+}
+
+function walk(node: unknown, found: unknown[][]): void {
+  if (!Array.isArray(node)) return;
+  if (isItinerary(node)) {
+    found.push(node);
+    return; // don't recurse into a matched itinerary
+  }
+  for (const child of node) walk(child, found);
+}
+
+function normalize(it: unknown[]): Itinerary {
+  const legs = legsOf(it);
+  const priceTok = it[1] as unknown[];
+  const priceArr = priceTok[0] as unknown[];
+  const token = priceTok[1] as string;
+
+  const airlines = new Set<string>();
+  const flightNumbers: string[] = [];
+  let durationMinutes = 0;
+  let stops = 0;
+  let co2 = 0;
+
+  for (const leg of legs) {
+    const names = leg[1];
+    if (Array.isArray(names)) {
+      for (const n of names) if (typeof n === 'string') airlines.add(n);
+    }
+    if (typeof leg[9] === 'number') durationMinutes += leg[9] as number;
+    const segs = leg[2];
+    if (Array.isArray(segs)) {
+      stops += Math.max(0, segs.length - 1);
+      for (const seg of segs) {
+        if (!Array.isArray(seg)) continue;
+        const fn = seg[22];
+        if (Array.isArray(fn) && typeof fn[0] === 'string' && fn[1] != null) {
+          flightNumbers.push(`${fn[0]}${fn[1]}`);
+          if (typeof fn[3] === 'string') airlines.add(fn[3]);
+        }
+        // best-effort CO2 (grams): large numeric near the end of the segment.
+        const cand = seg[seg.length - 2];
+        if (typeof cand === 'number' && cand > 1000 && cand < 10_000_000) co2 += cand;
+      }
+    }
+  }
+
+  const firstLeg = legs[0] ?? [];
+  const lastLeg = legs[legs.length - 1] ?? [];
+  const price = priceArr.find((v) => typeof v === 'number') as number | undefined;
+
+  return {
+    airlines: [...airlines],
+    flightNumbers,
+    origin: typeof firstLeg[3] === 'string' ? (firstLeg[3] as string) : '',
+    destination: typeof lastLeg[6] === 'string' ? (lastLeg[6] as string) : '',
+    departDate: fmtDate(firstLeg[4]),
+    departTime: fmtTime(firstLeg[5]),
+    arriveDate: fmtDate(lastLeg[7]),
+    arriveTime: fmtTime(lastLeg[8]),
+    durationMinutes: durationMinutes || null,
+    stops,
+    priceUSD: price ?? null,
+    co2Grams: co2 || null,
+    flight_token: token,
+  };
+}
+
+export function extract(
+  rawResponse: unknown,
+  _context?: { params: Record<string, string | number | boolean>; responses: unknown[] },
+): unknown {
+  let payload: unknown;
+  if (typeof rawResponse === 'string') {
+    payload =
+      extractRpcPayload(rawResponse, 'GetShoppingResults') ?? extractRpcPayload(rawResponse);
+    if (payload == null) {
+      const frames = decodeBatchExecute(rawResponse);
+      payload = frames[0]?.payload;
+    }
+  } else {
+    payload = rawResponse;
+  }
+
+  const found: unknown[][] = [];
+  if (payload != null) walk(payload, found);
+
+  const byToken = new Map<string, Itinerary>();
+  for (const it of found) {
+    const norm = normalize(it);
+    if (!norm.flight_token) continue;
+    if (!byToken.has(norm.flight_token)) byToken.set(norm.flight_token, norm);
+  }
+
+  const itineraries = [...byToken.values()];
+  return {
+    count: itineraries.length,
+    itineraries,
+  };
+}