imprint-mcp 0.2.1 → 0.3.1

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

@@ -0,0 +1,184 @@
+toolName: search_flights
+summary: "Search Google Flights for itineraries between two airports on given dates and trip type, returning the GetShoppingResults batchexecute payload."
+parameters:
+  - name: origin
+    type: string
+    description: "Origin airport/city code, e.g. SJC"
+  - name: destination
+    type: string
+    description: "Destination airport/city code, e.g. SAN"
+  - name: departure_date
+    type: string
+    description: "Outbound date in YYYY-MM-DD"
+  - name: return_date
+    type: string
+    description: "Return date in YYYY-MM-DD (omit/ignore for one-way)"
+  - name: trip_type
+    type: string
+    description: "Visible ticket-type label to select: 'Round trip', 'One way', or 'Multi-city' (workflow encodes 1/2/3)"
+  - name: max_stops
+    type: number
+    description: "Max stops filter: 0 nonstop, 1, 2, or 3 any (best-effort via filter bar)"
+  - name: airlines
+    type: string
+    description: "Alliance (Oneworld/SkyTeam/Star Alliance) or carrier name to include (best-effort via filter bar)"
+  - name: max_price
+    type: number
+    description: "Maximum total price in USD (best-effort via filter bar)"
+  - name: outbound_times
+    type: string
+    description: "Outbound departure/arrival time window in hours (best-effort via filter bar)"
+  - name: return_times
+    type: string
+    description: "Return departure/arrival time window in hours (best-effort via filter bar)"
+  - name: max_duration
+    type: number
+    description: "Maximum total trip duration in minutes (best-effort via filter bar)"
+  - name: carry_on_bags
+    type: number
+    description: "Number of carry-on bags to filter/price by (best-effort via filter bar)"
+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_pattern: "Where (from\\?|else\\?)"
+      - by: css
+        value: 'div.cQnuXe.k0gFV input.II2One.j0Ppje'
+    value: ${origin}
+    wait_for:
+      sleep_ms: 500
+  - action: click
+    locators:
+      - by: aria_label
+        value_pattern: ${origin}
+      - by: text
+        value_pattern: ${origin}
+    wait_for: visible
+  - action: click
+    locators:
+      - by: aria_label
+        value: "Where to? "
+      - by: css
+        value: 'div.wUiEcc.SOcuWe input.II2One.j0Ppje'
+    wait_for:
+      sleep_ms: 300
+  - action: type
+    locators:
+      - by: aria_label
+        value_pattern: "Where (to\\? ?|else\\?)"
+      - by: css
+        value: 'div.wUiEcc.SOcuWe input.II2One.j0Ppje'
+    value: ${destination}
+    wait_for:
+      sleep_ms: 500
+  - action: click
+    locators:
+      - by: aria_label
+        value_pattern: ${destination}
+      - by: text
+        value_pattern: ${destination}
+    wait_for: visible
+  - action: click
+    locators:
+      - by: aria_label
+        value: "Select your ticket type."
+      - by: css
+        value: 'div.TQYpgc.gInvKb div.VfPpkd-aPP78e'
+    wait_for:
+      sleep_ms: 300
+  - action: click
+    locators:
+      - by: role
+        value: option
+        name: ${trip_type}
+      - by: text
+        value_pattern: ${trip_type}
+    wait_for: visible
+  - action: click
+    locators:
+      - by: aria_label
+        value: "Departure"
+      - by: css
+        value: 'div.GYgkab.YICvqf input.TP4Lpb.eoY5cb'
+    wait_for:
+      sleep_ms: 300
+  - action: type
+    locators:
+      - by: aria_label
+        value: "Departure"
+      - by: css
+        value: 'div.GYgkab.YICvqf input.TP4Lpb.eoY5cb'
+    value: ${departure_date}
+    wait_for:
+      sleep_ms: 400
+  - action: type
+    locators:
+      - by: aria_label
+        value: "Return"
+    value: ${return_date}
+    wait_for:
+      sleep_ms: 400
+  - action: click
+    locators:
+      - by: text
+        value: Done
+      - by: aria_label
+        value_pattern: "Done"
+    wait_for:
+      sleep_ms: 300
+  - action: click
+    locators:
+      - by: role
+        value: button
+        name: Search
+      - by: text
+        value: Search
+      - by: aria_label
+        value_pattern: "Search"
+    wait_for:
+      xhr: /FlightsFrontendService/GetShoppingResults
+result:
+  source: xhr
+  url_pattern: /FlightsFrontendService/GetShoppingResults
+  extract: "2"
+  return_as: itineraries
+notes: >
+  Google Flights is a batchexecute RPC app. The result-bearing XHR is
+  GetShoppingResults (POST to /_/FlightsFrontendUi/data/travel.frontend.flights.FlightsFrontendService/GetShoppingResults);
+  the largest/last GetShoppingResults response after the Search click carries the
+  full itinerary set. The response is NOT plain JSON: it is prefixed with )]}' and
+  chunked into length-prefixed lines. The parser must strip the )]}' prefix, split
+  on the numeric length markers, JSON.parse each line to find the ["wrb.fr",null,"<json-string>"]
+  envelope, then JSON.parse the index-2 element (the double-encoded payload). Flight
+  itineraries live in deeply nested positional arrays inside that payload — each
+  itinerary exposes carrier code+name, flight number, origin/destination codes,
+  [hour,minute] depart/arrive, duration minutes, stops, layover info, and price in
+  USD (the integer like 88008 = $880.08 scaled, or the [[null,337],...] cents-ish
+  marker). The extract path "2" denotes the wrb.fr payload slot and requires the
+  custom decoding above — a plain dot-path cannot traverse the stringified inner JSON.
+  DOM-locator caveats: this site uses auto-generated class names (e.g. VfPpkd-*,
+  II2One) and react-style ids (#c7293, #c115604) that change every deploy and per
+  session — prefer the aria_label/text/role locators; the css fallbacks are brittle.
+  The origin/destination editable field re-labels itself to "Where else?" while
+  focused, hence the regex aria_label patterns.
+  trip_type must be passed as the visible label ("Round trip" / "One way" /
+  "Multi-city"), not the 1/2/3 encoding used by the API workflow.
+  For one-way searches the "Return" type step is a no-op/absent — skip or expect it
+  to be ignored. Multi-city requires per-leg origin/destination entry not captured
+  as discrete linear steps here.
+  Filter parameters (max_stops, airlines, max_price, outbound_times, return_times,
+  max_duration, carry_on_bags) are applied via the chip filter bar (Stops/Airlines/
+  Bags/Price/Times/Duration buttons) which open popovers with obfuscated controls;
+  they are best applied through the API workflow rather than DOM steps. They are
+  listed here only to keep params 1:1 with workflow.json for cron/MCP fallback.

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

@@ -0,0 +1,119 @@
+// Adapter around the shared FlightsFrontendService body builder.
+// The tool exposes flat snake_case params (origin, destination, departure_date,
+// max_stops, …); the shared encoder consumes a structured camelCase shape
+// ({ tripType, legs:[{origin,dest,date,times,stops,alliances,carriers,duration}],
+// maxPrice, bags }). We map between them here and delegate the byte-for-byte
+// positional encoding to the shared module (required reuse).
+import { transform as sharedTransform } from '../_shared/flights_request.ts';
+
+type Params = Record<string, string | number | boolean | undefined | null>;
+
+const ALLIANCES = new Set(['ONEWORLD', 'SKYTEAM', 'STAR_ALLIANCE']);
+
+function mapTripType(v: unknown): number {
+  if (v == null || v === '') return 1;
+  if (typeof v === 'number') return v;
+  const s = String(v).toLowerCase();
+  if (s === 'one_way' || s === 'oneway' || s === '2') return 2;
+  if (s === 'multi_city' || s === 'multicity' || s === '3') return 3;
+  return 1; // round_trip
+}
+
+// User semantics (per likelyParam): 0=nonstop, 1=≤1 stop, 2=≤2 stops, 3=any.
+// Google wire encoding: 1=nonstop, 2=≤1, 3=≤2, 0=any.
+function mapStops(v: unknown): number {
+  switch (Number(v)) {
+    case 0:
+      return 1;
+    case 1:
+      return 2;
+    case 2:
+      return 3;
+    default:
+      return 0; // any (default / 3)
+  }
+}
+
+// "6-23" -> [depMin, depMax, arrMin, arrMax]; arrival defaults to full day.
+function parseTimes(v: unknown): number[] | null {
+  if (v == null || v === '') return null;
+  const m = /^(\d{1,2})-(\d{1,2})$/.exec(String(v).trim());
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), 0, 23];
+}
+
+function parseAirlines(v: unknown): { alliances: string[] | null; carriers: string[] | null } {
+  if (v == null || v === '') return { alliances: null, carriers: null };
+  const parts = String(v)
+    .split(',')
+    .map((x) => x.trim())
+    .filter(Boolean);
+  const alliances = parts.filter((p) => ALLIANCES.has(p.toUpperCase())).map((p) => p.toUpperCase());
+  const carriers = parts.filter((p) => !ALLIANCES.has(p.toUpperCase()));
+  return {
+    alliances: alliances.length ? alliances : null,
+    carriers: carriers.length ? carriers : null,
+  };
+}
+
+function num(v: unknown): number | undefined {
+  if (v == null || v === '') return undefined;
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+export function transform(
+  method: string,
+  url: string,
+  responses: Record<string, any>,
+  params?: Params,
+): { url: string; body: string } {
+  const p: Params = params ?? {};
+  const tripType = mapTripType(p.trip_type);
+  const stops = p.max_stops != null && p.max_stops !== '' ? mapStops(p.max_stops) : 0;
+  const { alliances, carriers } = parseAirlines(p.airlines);
+  const maxDur = num(p.max_duration);
+  const duration = maxDur != null ? [maxDur] : null;
+
+  const origin = p.origin != null ? String(p.origin) : '';
+  const destination = p.destination != null ? String(p.destination) : '';
+
+  const legs: any[] = [
+    {
+      origin,
+      dest: destination,
+      date: p.departure_date ? String(p.departure_date) : null,
+      times: parseTimes(p.outbound_times),
+      stops,
+      alliances,
+      carriers,
+      duration,
+    },
+  ];
+
+  // Append a return leg for round-trip / multi-city when a return date exists.
+  if (tripType !== 2 && p.return_date) {
+    legs.push({
+      origin: destination,
+      dest: origin,
+      date: String(p.return_date),
+      times: parseTimes(p.return_times),
+      stops,
+      alliances,
+      carriers,
+      duration,
+    });
+  }
+
+  const carryOn = num(p.carry_on_bags);
+  const mapped: Record<string, any> = {
+    tripType,
+    legs,
+    maxPrice: num(p.max_price),
+    // CONFIG[10] wire form is [1, <carry-on count>]; shared builder emits
+    // [carryOn, checked], so map count -> checked slot, constant 1 -> first.
+    bags: carryOn != null ? { carryOn: 1, checked: carryOn } : undefined,
+  };
+
+  return sharedTransform(method, url, responses, mapped);
+}

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

@@ -0,0 +1,143 @@
+{
+  "toolName": "search_flights",
+  "site": "google-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"
+    }
+  ],
+  "bootstrap": {
+    "url": "https://www.google.com/travel/flights",
+    "waitUntil": "domcontentloaded",
+    "timeoutMs": 30000,
+    "captures": [
+      {
+        "source": "html_regex",
+        "name": "f_sid",
+        "pattern": "\"FdrFJe\":\"([^\"]+)\"",
+        "group": 1,
+        "required": false,
+        "capability": "browser_bootstrap"
+      },
+      {
+        "source": "html_regex",
+        "name": "bl",
+        "pattern": "\"cfb2h\":\"([^\"]+)\"",
+        "group": 1,
+        "required": false,
+        "capability": "browser_bootstrap"
+      }
+    ]
+  },
+  "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"
+    }
+  ],
+  "requestTransformModule": "./request-transform.ts",
+  "parserModule": "./parser.ts",
+  "liveVerified": true
+}

package/examples/google-hotels/README.md

@@ -0,0 +1,29 @@
+# Google Hotels — `imprint-google-hotels`
+
+> **One-shot compiled, proof of concept.** Every file in this directory was generated by a single `imprint teach google-hotels` run against **one** recorded browser session — no hand-written request code, parsers, or selectors. It is committed here as a proof of concept of what the compiler produces, not as a maintained integration.
+
+A 4-tool MCP server for Google Hotels, compiled from a recording of a normal hotel search. Headless-claude differential audit: **91.7%** — every tool `liveVerified=true`.
+
+## Tools
+
+| Tool | What it does | Notes |
+|---|---|---|
+| `autocomplete_hotel_location` | Resolve a location query to a place token | |
+| `search_hotels` | Search hotels (location, dates, guests, rating, price, amenities, class, sort, property type) | the star tool |
+| `get_hotel_reviews` | Reviews for a hotel | **consumes** a `hotel_id` produced by `search_hotels` |
+| `get_hotel_booking_options` | Booking/price options for a hotel | **consumes** a `location_context` produced by `search_hotels` |
+
+## How it was compiled
+
+- **Protocol**: Google's `batchexecute` endpoint returns a nested-array payload; the compiler reverse-engineered the decoder into `_shared/batchexecute.ts` + per-tool `parser.ts`, and the request shape into per-tool `request-transform.ts`.
+- **Producer → consumer chaining**: `search_hotels` emits opaque ids that `get_hotel_reviews` / `get_hotel_booking_options` consume — the compiler detected the cross-tool token flow and wired it.
+- **Anti-bot**: calls run on the **cdp-replay** rung (inside a live trusted Chrome) with a **stealth-fetch** fallback.
+- **Artifacts per tool**: `workflow.json` (API replay), `playbook.yaml` (DOM fallback), `index.ts` (MCP tool), `parser.ts` + `request-transform.ts` (codecs).
+
+## Install
+
+```bash
+imprint install google-hotels --source examples --platform claude-desktop
+```
+
+*Recording-derived defaults (dates, the recorded location) age out — pass explicit values. See the repo [README](../../README.md) and [docs](../../docs/architecture.md).*

package/examples/google-hotels/_shared/batchexecute.ts

@@ -0,0 +1,73 @@
+// Decodes the Google `batchexecute` anti-XSSI envelope and returns the inner
+// JSON payload for a given rpcid. Every TravelFrontendUi response shares this
+// framing:
+//
+//   )]}'                       <- anti-XSSI guard line
+//                              <- blank line
+//   <len>                      <- chunk length (UTF-8 BYTE count)
+//   [["wrb.fr","<rpcid>","<innerJsonString>",null,null,null,"<src>"]]
+//   <len>
+//   [["di",..],["af.httprm",..]]
+//   ...
+//
+// Key invariants proven by the recordings (seq 222, 229, 286, 300, 497, 525, 2429):
+//  - Each JSON chunk sits on ONE physical line; every newline inside string data
+//    is escaped (\n -> \\n), so splitting on "\n" cleanly separates length
+//    markers from JSON chunks.
+//  - A single chunk can carry MULTIPLE rows of mixed type (seq 2429 packs the
+//    wrb.fr row alongside ["di",..]/["af.httprm",..]), so we must filter rows by
+//    row[0] === "wrb.fr", never assume one row per chunk.
+//  - row[2] is the payload as a JSON STRING -> a second JSON.parse yields the
+//    result array. \u00xx / \u0026 escapes (Priceline URLs, seq 497) are valid
+//    JSON escapes resolved natively by JSON.parse -- no manual unescaping.
+//
+// We deliberately ignore the numeric chunk lengths: they are UTF-8 byte counts,
+// while JS string slicing is by UTF-16 code unit, so honoring them would
+// misalign on multibyte data (e.g. "Costa Rican Colón" in seq 229). Splitting on
+// "\n" is safe because chunks never contain a literal newline.
+
+// Collect every envelope row across all chunks. Kept as any[] on purpose:
+// JSON.parse returns `any`, and indexed access on `any` does NOT widen to
+// `T | undefined` under noUncheckedIndexedAccess, so r[0]/r[1]/r[2] stay clean.
+function collectRows(rawResponse: string): any[] {
+  const rows: any[] = [];
+  const lines = rawResponse.split('\n');
+  for (const line of lines) {
+    if (line === ")]}'" || line === '') continue; // guard line / blank separator
+    if (/^\d+$/.test(line)) continue; // numeric chunk-length marker (.test -> boolean, no capture)
+    if (!line.startsWith('[')) continue; // anything else is not a JSON chunk
+    let parsed: any;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue; // skip an unparseable / truncated chunk rather than throwing
+    }
+    if (Array.isArray(parsed)) {
+      for (const row of parsed) rows.push(row);
+    }
+  }
+  return rows;
+}
+
+export function parseBatchExecute(rawResponse: string, rpcid: string): any {
+  const rows = collectRows(rawResponse);
+  const hit = rows.find(
+    (r: any) => Array.isArray(r) && r[0] === 'wrb.fr' && r[1] === rpcid,
+  );
+  // Missing rpcid (or non-string payload) returns null per spec -- do not throw.
+  // The typeof guard also narrows hit[2] for the JSON.parse below.
+  if (!hit || typeof hit[2] !== 'string') return null;
+  return JSON.parse(hit[2]);
+}
+
+export function parseAllRpc(rawResponse: string): Record<string, any> {
+  const rows = collectRows(rawResponse);
+  const out: Record<string, any> = {};
+  for (const r of rows) {
+    if (Array.isArray(r) && r[0] === 'wrb.fr' && typeof r[2] === 'string') {
+      // Last write wins on duplicate rpcid (not observed in recordings).
+      out[r[1]] = JSON.parse(r[2]);
+    }
+  }
+  return out;
+}