imprint-mcp 0.2.0

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

@@ -0,0 +1,130 @@
+toolName: search_google_flights
+summary: Search Google Flights for round-trip flights between two airports on specific dates.
+parameters:
+  - name: origin_airport
+    type: string
+    description: Origin airport or city code, e.g. SJC
+  - name: destination_airport
+    type: string
+    description: Destination airport or city code, e.g. SAN
+  - name: depart_date
+    type: string
+    description: Departure date in YYYY-MM-DD format
+  - name: return_date
+    type: string
+    description: Return date in YYYY-MM-DD format
+steps:
+  - action: navigate
+    url: https://www.google.com/travel/flights
+    wait_for: networkidle
+  - action: type
+    locators:
+      - by: role
+        value: textbox
+        name: Where from?
+      - by: aria_label
+        value: Where from?
+      - by: css
+        value: input[aria-label="Where from?"]
+    value: ${origin_airport}
+    wait_for:
+      sleep_ms: 500
+  - action: click
+    locators:
+      - by: role
+        value: option
+        name: ${origin_airport}
+      - by: aria_label
+        value_pattern: ${origin_airport}
+      - by: text
+        value_pattern: ${origin_airport}
+      - by: css
+        value: ul li
+    wait_for: visible
+  - action: type
+    locators:
+      - by: role
+        value: textbox
+        name: Where to?
+      - by: aria_label
+        value: "Where to? "
+      - by: css
+        value: input[aria-label="Where to? "]
+    value: ${destination_airport}
+    wait_for:
+      sleep_ms: 500
+  - action: click
+    locators:
+      - by: role
+        value: option
+        name: ${destination_airport}
+      - by: aria_label
+        value_pattern: ${destination_airport}
+      - by: text
+        value_pattern: ${destination_airport}
+      - by: css
+        value: ul li
+    wait_for: visible
+  - action: type
+    locators:
+      - by: role
+        value: textbox
+        name: Departure
+      - by: aria_label
+        value: Departure
+      - by: css
+        value: input[aria-label="Departure"]
+    value: ${depart_date}
+    wait_for:
+      sleep_ms: 300
+  - action: type
+    locators:
+      - by: role
+        value: textbox
+        name: Return
+      - by: aria_label
+        value: Return
+      - by: css
+        value: input[aria-label="Return"]
+    value: ${return_date}
+    wait_for:
+      sleep_ms: 300
+  - action: click
+    locators:
+      - by: role
+        value: button
+        name: Search
+      - by: aria_label
+        value_pattern: Search
+      - by: css
+        value: button
+    wait_for:
+      xhr: /FlightsFrontendService/GetShoppingResults
+  - action: click
+    locators:
+      - by: aria_label
+        value: Nonstop flight.
+      - by: text
+        value: Nonstop
+      - by: css
+        value: div.OgQvJf.nKlB3b
+    wait_for:
+      xhr: /FlightsFrontendService/GetShoppingResults
+  - action: click
+    locators:
+      - by: aria_label
+        value: Nonstop flight.
+      - by: text
+        value: Nonstop
+      - by: css
+        value: div.OgQvJf.nKlB3b
+    wait_for:
+      xhr: /FlightsFrontendService/GetBookingResults
+result:
+  source: dom
+  locators:
+    - by: css
+      value: a[href*="/travel/clk/f"]
+  extract: href
+  return_as: booking_links
+notes: Assumes Google Flights opens in round-trip Economy (include Basic) by default and selects the first visible outbound and return flight cards, which in the captured session were nonstop Southwest options.

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

@@ -0,0 +1,48 @@
+{
+  "toolName": "search_google_flights",
+  "intent": {
+    "description": "Search Google Flights for round-trip flights between two airports on specific dates.",
+    "userSaid": "i searched for a sample flight the default mode is economy (include basic) now i changed to economy (exclude basic) now i searched for premium economy now i searched for business now i searched for first class now im going to start messing with all the filters available i played with all the filters now i clicked one of the departure flights, and now it's showing me a list of the return flights i selected the return flight, and now it's showing me the booking options"
+  },
+  "parameters": [
+    {
+      "name": "origin_airport",
+      "type": "string",
+      "description": "Origin airport IATA code.",
+      "default": "SJC"
+    },
+    {
+      "name": "destination_airport",
+      "type": "string",
+      "description": "Destination airport IATA code.",
+      "default": "SAN"
+    },
+    {
+      "name": "depart_date",
+      "type": "string",
+      "description": "Outbound departure date in YYYY-MM-DD format.",
+      "default": "2026-07-10"
+    },
+    {
+      "name": "return_date",
+      "type": "string",
+      "description": "Return departure date in YYYY-MM-DD format.",
+      "default": "2026-07-16"
+    }
+  ],
+  "requests": [
+    {
+      "method": "POST",
+      "url": "https://www.google.com/_/FlightsFrontendUi/data/travel.frontend.flights.FlightsFrontendService/GetShoppingResults?f.sid=-1290970187393889182&bl=boq_travel-frontend-flights-ui_20260506.02_p0&hl=en-US&soc-app=162&soc-platform=1&soc-device=1&_reqid=4008662&rt=c",
+      "headers": {
+        "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8",
+        "Referer": "https://www.google.com/travel/flights",
+        "X-Same-Domain": "1",
+        "x-goog-ext-259736195-jspb": "[\"en-US\",\"US\",\"USD\",2,null,[420],null,null,7,[]]"
+      },
+      "body": "f.req=%5Bnull%2C%22%5B%5B%5D%2C%5Bnull%2Cnull%2C1%2Cnull%2C%5B%5D%2C1%2C%5B1%2C0%2C0%2C0%5D%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2C%5B%5B%5B%5B%5B%5C%22${param.origin_airport}%5C%22%2C0%5D%5D%5D%2C%5B%5B%5B%5C%22${param.destination_airport}%5C%22%2C0%5D%5D%5D%2Cnull%2C0%2Cnull%2Cnull%2C%5C%22${param.depart_date}%5C%22%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2C690%2Cnull%2C3%5D%2C%5B%5B%5B%5B%5C%22${param.destination_airport}%5C%22%2C0%5D%5D%5D%2C%5B%5B%5B%5C%22${param.origin_airport}%5C%22%2C0%5D%5D%5D%2Cnull%2C0%2Cnull%2Cnull%2C%5C%22${param.return_date}%5C%22%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2C690%2Cnull%2C3%5D%5D%2Cnull%2Cnull%2Cnull%2C1%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2C0%5D%2C0%2C0%2C0%2C1%5D%22%5D&"
+    }
+  ],
+  "site": "google-flights",
+  "parserModule": "./parser.ts"
+}

package/examples/google-hotels/search_google_hotels/index.ts

@@ -0,0 +1,194 @@
+/**
+ * GENERATED by `imprint emit` — DO NOT EDIT BY HAND.
+ *
+ * Tool: search_google_hotels
+ * Site: google-hotels
+ * Intent: Search Google Hotels for lodging in a destination over a given date range and party composition, returning the list of nearby hotels with star rating, guest rating, nightly + total prices, and Google identifiers.
+ *
+ * To regenerate: imprint emit ~/.imprint/google-hotels/search_google_hotels/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_google_hotels",
+  "intent": {
+    "description": "Search Google Hotels for lodging in a destination over a given date range and party composition, returning the list of nearby hotels with star rating, guest rating, nightly + total prices, and Google identifiers.",
+    "userSaid": "i just searched for htoels in tahoe city from june 19 to june 27 for 2 people | i added some adutls and some children | i clicked one of hte hotels | i clicked hte box that shows the stay total price (not nightly prices before taxes and fees) | i played around with all the filters | i played around with the brands"
+  },
+  "parameters": [
+    {
+      "name": "query",
+      "type": "string",
+      "description": "Free-text destination query the user typed into the search box (e.g. 'tahoe city').",
+      "default": "tahoe city"
+    },
+    {
+      "name": "place_mid",
+      "type": "string",
+      "description": "Google Knowledge Graph machine ID for the destination (the '/m/0gyvmkl' style identifier returned by the autocomplete request). Required to anchor the search to a specific place.",
+      "default": "/m/0gyvmkl"
+    },
+    {
+      "name": "place_ftid",
+      "type": "string",
+      "description": "Google Maps feature ID for the destination, of the form '0xHEX:0xHEX'. Comes from the autocomplete response alongside the place_mid.",
+      "default": "0x809bd62ecf1fa721:0x2a98b230816c9ed1"
+    },
+    {
+      "name": "place_name",
+      "type": "string",
+      "description": "Display name for the destination (e.g. 'Tahoe City').",
+      "default": "Tahoe City"
+    },
+    {
+      "name": "check_in_year",
+      "type": "number",
+      "description": "Check-in year (e.g. 2026).",
+      "default": 2026
+    },
+    {
+      "name": "check_in_month",
+      "type": "number",
+      "description": "Check-in month (1–12).",
+      "default": 6
+    },
+    {
+      "name": "check_in_day",
+      "type": "number",
+      "description": "Check-in day of month (1–31).",
+      "default": 19
+    },
+    {
+      "name": "check_out_year",
+      "type": "number",
+      "description": "Check-out year.",
+      "default": 2026
+    },
+    {
+      "name": "check_out_month",
+      "type": "number",
+      "description": "Check-out month (1–12).",
+      "default": 6
+    },
+    {
+      "name": "check_out_day",
+      "type": "number",
+      "description": "Check-out day of month (1–31).",
+      "default": 27
+    },
+    {
+      "name": "nights",
+      "type": "number",
+      "description": "Length of stay in nights. Must equal check_out - check_in.",
+      "default": 8
+    },
+    {
+      "name": "child_age_1",
+      "type": "number",
+      "description": "Age of the first child (omit by leaving default; the workflow currently always sends two children to mirror the recorded request).",
+      "default": 3
+    },
+    {
+      "name": "child_age_2",
+      "type": "number",
+      "description": "Age of the second child.",
+      "default": 3
+    },
+    {
+      "name": "currency",
+      "type": "string",
+      "description": "ISO currency code for displayed prices.",
+      "default": "USD"
+    }
+  ],
+  "requests": [
+    {
+      "method": "POST",
+      "url": "https://www.google.com/_/TravelFrontendUi/data/batchexecute?rpcids=AtySUc&source-path=%2Ftravel%2Fsearch&hl=en-US&soc-app=162&soc-platform=1&soc-device=1&rt=c",
+      "headers": {
+        "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8",
+        "X-Same-Domain": "1",
+        "Origin": "https://www.google.com",
+        "Referer": "https://www.google.com/travel/search?q=${param.query}",
+        "Accept-Language": "en-US,en;q=0.9",
+        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36",
+        "x-goog-ext-259736195-jspb": "[\"en-US\",\"US\",\"${param.currency}\",2,null,[420],null,null,7,[]]"
+      },
+      "body": "f.req=%5B%5B%5B%22AtySUc%22%2C%22%5B%5C%22${param.query}%5C%22%2C%5B1%2C%5B%5B%5B${param.child_age_1}%5D%2C%5B${param.child_age_2}%5D%5D%2C0%5D%2C%5B%5Bnull%2C%5B%5B%5C%22${param.place_mid}%5C%22%2Cnull%2Cnull%2Cnull%2Cnull%2C%5C%22${param.place_ftid}%5C%22%2C%5C%22${param.place_name}%5C%22%5D%5D%2C%5B%5D%5D%2C%5Bnull%2C%5B%5B${param.check_in_year}%2C${param.check_in_month}%2C${param.check_in_day}%5D%2C%5B${param.check_out_year}%2C${param.check_out_month}%2C${param.check_out_day}%5D%2C${param.nights}%5D%2Cnull%2Cnull%2Cnull%2C%5B1%5D%5D%5D%2Cnull%2C%5B%5Bnull%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2C%5C%22${param.currency}%5C%22%5D%2Cnull%2C%5B%5D%5D%5D%2C%5B1%2Cnull%2Cnull%2C0%2C0%2Cnull%2C13%2Cnull%2C0%5D%5D%22%2Cnull%2C%221%22%5D%5D%5D&"
+    }
+  ],
+  "site": "google-hotels",
+  "parserModule": "./parser.ts"
+};
+
+export interface SearchGoogleHotelsInput {
+  /** Free-text destination query the user typed into the search box (e.g. 'tahoe city'). */
+  query?: string;
+  /** Google Knowledge Graph machine ID for the destination (the '/m/0gyvmkl' style identifier returned by the autocomplete request). Required to anchor the search to a specific place. */
+  place_mid?: string;
+  /** Google Maps feature ID for the destination, of the form '0xHEX:0xHEX'. Comes from the autocomplete response alongside the place_mid. */
+  place_ftid?: string;
+  /** Display name for the destination (e.g. 'Tahoe City'). */
+  place_name?: string;
+  /** Check-in year (e.g. 2026). */
+  check_in_year?: number;
+  /** Check-in month (1–12). */
+  check_in_month?: number;
+  /** Check-in day of month (1–31). */
+  check_in_day?: number;
+  /** Check-out year. */
+  check_out_year?: number;
+  /** Check-out month (1–12). */
+  check_out_month?: number;
+  /** Check-out day of month (1–31). */
+  check_out_day?: number;
+  /** Length of stay in nights. Must equal check_out - check_in. */
+  nights?: number;
+  /** Age of the first child (omit by leaving default; the workflow currently always sends two children to mirror the recorded request). */
+  child_age_1?: number;
+  /** Age of the second child. */
+  child_age_2?: number;
+  /** ISO currency code for displayed prices. */
+  currency?: string;
+}
+
+export async function searchGoogleHotels(
+  input: SearchGoogleHotelsInput,
+  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> = {
+    query: input.query ?? "tahoe city",
+    place_mid: input.place_mid ?? "/m/0gyvmkl",
+    place_ftid: input.place_ftid ?? "0x809bd62ecf1fa721:0x2a98b230816c9ed1",
+    place_name: input.place_name ?? "Tahoe City",
+    check_in_year: input.check_in_year ?? 2026,
+    check_in_month: input.check_in_month ?? 6,
+    check_in_day: input.check_in_day ?? 19,
+    check_out_year: input.check_out_year ?? 2026,
+    check_out_month: input.check_out_month ?? 6,
+    check_out_day: input.check_out_day ?? 27,
+    nights: input.nights ?? 8,
+    child_age_1: input.child_age_1 ?? 3,
+    child_age_2: input.child_age_2 ?? 3,
+    currency: input.currency ?? "USD",
+
+  };
+  return executeWorkflow({
+    workflow: WORKFLOW,
+    params,
+    credentials: opts.credentials,
+    fetchImpl: opts.fetchImpl,
+    initialState: opts.initialState,
+    workflowPath: join(__dirname, 'workflow.json'),
+  });
+}
+
+export { WORKFLOW };

package/examples/google-hotels/search_google_hotels/parser.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { extract, parseEnvelope, type ExtractResult, type Hotel } from './parser.ts';
+
+const FIXTURE = readFileSync(
+  join(
+    import.meta.dir,
+    '../../../test/fixtures/examples/google-hotels/search_google_hotels/response-287.txt',
+  ),
+  'utf8',
+);
+
+describe('google-hotels parser (Tahoe City, AtySUc)', () => {
+  test('parseEnvelope returns the AtySUc payload', () => {
+    const env = parseEnvelope(FIXTURE) as { rpcid: string; payload: unknown } | null;
+    expect(env).not.toBeNull();
+    expect(env!.rpcid).toBe('AtySUc');
+    expect(Array.isArray(env!.payload)).toBe(true);
+  });
+
+  test('extract surfaces the searched destination and stay window', () => {
+    const result = extract(FIXTURE) as ExtractResult;
+    expect(result.destination).toBe('Tahoe City');
+    expect(result.checkInDate).toBe('2026-06-19');
+    expect(result.checkOutDate).toBe('2026-06-27');
+    expect(result.nights).toBe(8);
+    expect(result.currency).toBe('USD');
+    // The destination header carries a result count (107 hotels in the area).
+    expect(result.totalResults).toBeGreaterThan(0);
+  });
+
+  test('extract returns multiple Tahoe-City-area hotels', () => {
+    const result = extract(FIXTURE) as ExtractResult;
+    expect(result.hotels.length).toBeGreaterThanOrEqual(15);
+    expect(result.hotelCount).toBe(result.hotels.length);
+    for (const h of result.hotels) {
+      expect(typeof h.name).toBe('string');
+      expect(h.name.length).toBeGreaterThan(0);
+    }
+  });
+
+  test('extract finds the named hotels seen in the recording', () => {
+    const result = extract(FIXTURE) as ExtractResult;
+    const names = result.hotels.map((h) => h.name);
+    expect(names).toContain('Northstar California Resort');
+    expect(names).toContain('Franciscan Lakeside Lodge');
+    expect(names).toContain('The Ritz-Carlton, Lake Tahoe');
+    expect(names).toContain('Granlibakken Tahoe');
+    expect(names).toContain('Basecamp Tahoe City');
+    expect(names).toContain('The Cottage Inn at Lake Tahoe');
+    expect(names).toContain('evo Hotel Tahoe City');
+    expect(names).toContain('Pepper Tree Inn');
+  });
+
+  test('extract pulls correct details for The Ritz-Carlton, Lake Tahoe', () => {
+    const result = extract(FIXTURE) as ExtractResult;
+    const ritz = result.hotels.find((h) => h.name === 'The Ritz-Carlton, Lake Tahoe');
+    expect(ritz).toBeDefined();
+    expect(ritz!.starRating).toBe(5);
+    expect(ritz!.starDescription).toBe('5-star hotel');
+    expect(ritz!.nightlyPrice).toBe('$616');
+    expect(ritz!.nightlyPriceValue).toBeCloseTo(615.79, 1);
+    expect(ritz!.totalPrice).toBe('$4,926');
+    expect(ritz!.guestRating).toBeCloseTo(4.4, 1);
+    expect(ritz!.reviewCount).toBe(1705);
+    expect(ritz!.checkInDate).toBe('2026-06-19');
+    expect(ritz!.checkOutDate).toBe('2026-06-27');
+    expect(ritz!.nights).toBe(8);
+    expect(ritz!.hotelId).toBeTruthy();
+    expect(ritz!.mapsFeatureId).toMatch(/^0x[0-9a-f]+:0x[0-9a-f]+$/);
+  });
+
+  test('extract pulls correct details for Northstar California Resort', () => {
+    const result = extract(FIXTURE) as ExtractResult;
+    const northstar = result.hotels.find(
+      (h) => h.name === 'Northstar California Resort',
+    );
+    expect(northstar).toBeDefined();
+    expect(northstar!.starRating).toBe(3);
+    expect(northstar!.nightlyPrice).toBe('$189');
+    expect(northstar!.totalPrice).toBe('$1,514');
+    expect(northstar!.guestRating).toBeCloseTo(4.5, 1);
+    expect(northstar!.reviewCount).toBe(6251);
+    expect(northstar!.latitude).toBeCloseTo(39.2647, 3);
+    expect(northstar!.longitude).toBeCloseTo(-120.1332, 3);
+  });
+
+  test('extract pulls correct details for Everline Resort & Spa', () => {
+    const result = extract(FIXTURE) as ExtractResult;
+    const everline = result.hotels.find((h) =>
+      h.name.startsWith('Everline Resort'),
+    );
+    expect(everline).toBeDefined();
+    expect(everline!.starRating).toBe(4);
+    expect(everline!.nightlyPrice).toBe('$376');
+    expect(everline!.totalPrice).toBe('$3,007');
+    expect(everline!.reviewCount).toBe(2085);
+  });
+
+  test('every priced hotel has a positive nightly value and matching dates', () => {
+    const result = extract(FIXTURE) as ExtractResult;
+    const priced = result.hotels.filter((h) => h.nightlyPrice !== null);
+    expect(priced.length).toBeGreaterThanOrEqual(5);
+    for (const h of priced) {
+      expect(h.nightlyPrice!.startsWith('$')).toBe(true);
+      if (h.nightlyPriceValue !== null) {
+        expect(h.nightlyPriceValue).toBeGreaterThan(0);
+      }
+      expect(h.checkInDate).toBe('2026-06-19');
+      expect(h.checkOutDate).toBe('2026-06-27');
+      expect(h.nights).toBe(8);
+    }
+  });
+
+  test('every hotel carries identifiers, coordinates and a star or rating', () => {
+    const result = extract(FIXTURE) as ExtractResult;
+    let withCoords = 0;
+    let withRating = 0;
+    let withToken = 0;
+    for (const h of result.hotels) {
+      if (h.latitude !== null && h.longitude !== null) withCoords++;
+      if (h.guestRating !== null) withRating++;
+      if (h.hotelToken !== null) withToken++;
+    }
+    // Effectively all hotels in this fixture have coordinates + a guest
+    // rating + a hotel token; require ≥80 % to leave a little slack.
+    const n = result.hotels.length;
+    expect(withCoords).toBeGreaterThanOrEqual(Math.ceil(n * 0.8));
+    expect(withRating).toBeGreaterThanOrEqual(Math.ceil(n * 0.8));
+    expect(withToken).toBeGreaterThanOrEqual(Math.ceil(n * 0.8));
+  });
+
+  test('hotels are deduplicated by id (no name appears twice)', () => {
+    const result = extract(FIXTURE) as ExtractResult;
+    const ids: string[] = [];
+    for (const h of result.hotels) {
+      const id = h.hotelId ?? h.hotelToken ?? h.name;
+      ids.push(id);
+    }
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+});
+
+// Smoke type assertion: the public Hotel shape stays consistent.
+const _typecheck: Hotel = {
+  name: 'x',
+  latitude: 0,
+  longitude: 0,
+  starDescription: null,
+  starRating: null,
+  guestRating: null,
+  reviewCount: null,
+  nightlyPrice: null,
+  nightlyPriceValue: null,
+  totalPrice: null,
+  totalPriceValue: null,
+  description: null,
+  photoUrl: null,
+  hotelId: null,
+  hotelToken: null,
+  mapsFeatureId: null,
+  checkInDate: null,
+  checkOutDate: null,
+  nights: null,
+};
+void _typecheck;