imprint-mcp 0.2.1 → 0.3.1

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

@@ -0,0 +1,81 @@
+/**
+ * GENERATED by `imprint emit` — DO NOT EDIT BY HAND.
+ *
+ * Tool: get_hotel_reviews
+ * Site: google-hotels
+ * Intent: Fetch aggregated reviews and reviewer snippets for a selected Google Hotels hotel.
+ *
+ * To regenerate: imprint emit ~/.imprint/google-hotels/get_hotel_reviews/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": "get_hotel_reviews",
+  "intent": {
+    "description": "Fetch aggregated reviews and reviewer snippets for a selected Google Hotels hotel.",
+    "userSaid": "clicked one of the offerings, saw booking options"
+  },
+  "parameters": [
+    {
+      "name": "hotel_id",
+      "type": "string",
+      "description": "Opaque hotel token (e.g. \"ChcI78-luoXdhoaIARoKL20vMDJ2cGdnMRAB\") obtained from the search_hotels tool's hotel_id output.",
+      "verified": true,
+      "sourcedFrom": {
+        "tool": "search_hotels",
+        "field": "hotel_id"
+      }
+    }
+  ],
+  "requests": [
+    {
+      "method": "POST",
+      "url": "https://www.google.com/_/TravelFrontendUi/data/batchexecute?rpcids=ocp93e&source-path=%2Ftravel%2Fsearch&f.sid=7513562915459271421&bl=boq_travel-frontend-ui_20260527.01_p0&hl=en-US&soc-app=162&soc-platform=1&soc-device=1&_reqid=3252256&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"
+      },
+      "body": "f.req=%5B%5B%5B%22ocp93e%22%2C%22%5Bnull%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2C%5C%22${param.hotel_id}%5C%22%2Cnull%2Cnull%2C%5B%5B%5D%5D%5D%22%2Cnull%2C%221%22%5D%5D%5D&",
+      "effect": "safe"
+    }
+  ],
+  "site": "google-hotels",
+  "parserModule": "./parser.ts",
+  "requestTransformModule": "./request-transform.ts",
+  "liveVerified": true
+};
+
+export interface GetHotelReviewsInput {
+  /** Opaque hotel token (e.g. "ChcI78-luoXdhoaIARoKL20vMDJ2cGdnMRAB") obtained from the search_hotels tool's hotel_id output. */
+  hotel_id: string;
+}
+
+export async function getHotelReviews(
+  input: GetHotelReviewsInput,
+  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> = {
+    hotel_id: input.hotel_id,
+
+  };
+  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/get_hotel_reviews/package.json

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

package/examples/google-hotels/get_hotel_reviews/parser.ts

@@ -0,0 +1,128 @@
+import { parseBatchExecute } from '../_shared/batchexecute.ts';
+
+// Shape of one review-source "entry" in the ocp93e inner JSON (recording seq 497):
+//   entry[0] = provider:  [ providerName, null, [iconUrl, w, h], code, count ]
+//   entry[1] = review:    [ [reviewerName, profileLink, [avatarUrl, w, h]],
+//                           dateText, [score, outOf], [[ [code, text, ...], ... ]],
+//                           sourceLink, ... ]
+// The entries list lives at root[0][0] (root = [[[ entry, entry, ... ]]]).
+
+interface ParsedReview {
+  reviewerName: string | null;
+  profileLink: string | null;
+  avatarUrl: string | null;
+  date: string | null;
+  ratingScore: number | null;
+  ratingOutOf: number | null;
+  texts: string[];
+  sourceLink: string | null;
+}
+
+interface ParsedEntry {
+  provider: {
+    name: string | null;
+    iconUrl: string | null;
+    count: number | null;
+  };
+  review: ParsedReview;
+}
+
+function asArray(v: unknown): any[] {
+  return Array.isArray(v) ? (v as any[]) : [];
+}
+
+function looksLikeEntry(e: unknown): boolean {
+  // entry[0] is the provider array whose first element is the provider name string.
+  return (
+    Array.isArray(e) &&
+    Array.isArray((e as any[])[0]) &&
+    typeof (e as any[])[0][0] === 'string'
+  );
+}
+
+// The entries-list nesting depth is the one value the recording does not fully
+// pin down, so locate the array whose elements have the entry shape rather than
+// hardcoding root[0][0]. Falls back to a recursive search if the expected path
+// does not match.
+function findEntriesList(root: unknown): any[] {
+  const direct = asArray(asArray(asArray(root)[0])[0]);
+  if (direct.length > 0 && direct.some(looksLikeEntry)) return direct;
+
+  let best: any[] = [];
+  const visit = (node: unknown, depth: number) => {
+    if (depth > 8 || !Array.isArray(node)) return;
+    const arr = node as any[];
+    if (arr.length > 0 && arr.every(looksLikeEntry)) {
+      if (arr.length > best.length) best = arr;
+      return;
+    }
+    for (const child of arr) visit(child, depth + 1);
+  };
+  visit(root, 0);
+  return best;
+}
+
+function parseEntry(entry: any[]): ParsedEntry {
+  const provider = asArray(entry[0]);
+  const review = asArray(entry[1]);
+  const reviewer = asArray(review[0]);
+  const rating = asArray(review[2]);
+
+  // review[3] = [[ [code, text, null, text, ...], ... ]] -> collect text strings.
+  const textGroups = asArray(asArray(review[3])[0]);
+  const texts: string[] = [];
+  for (const t of textGroups) {
+    if (Array.isArray(t) && typeof t[1] === 'string' && t[1].trim() !== '') {
+      texts.push(t[1]);
+    }
+  }
+
+  return {
+    provider: {
+      name: typeof provider[0] === 'string' ? provider[0] : null,
+      iconUrl: Array.isArray(provider[2]) && typeof provider[2][0] === 'string'
+        ? provider[2][0]
+        : null,
+      count: typeof provider[4] === 'number' ? provider[4] : null,
+    },
+    review: {
+      reviewerName: typeof reviewer[0] === 'string' ? reviewer[0] : null,
+      profileLink: typeof reviewer[1] === 'string' ? reviewer[1] : null,
+      avatarUrl: Array.isArray(reviewer[2]) && typeof reviewer[2][0] === 'string'
+        ? reviewer[2][0]
+        : null,
+      date: typeof review[1] === 'string' && review[1] !== '' ? review[1] : null,
+      ratingScore: typeof rating[0] === 'number' ? rating[0] : null,
+      ratingOutOf: typeof rating[1] === 'number' ? rating[1] : null,
+      texts,
+      sourceLink: typeof review[4] === 'string' && review[4] !== '' ? review[4] : null,
+    },
+  };
+}
+
+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 root = parseBatchExecute(raw, 'ocp93e');
+  if (root == null) return { reviews: [], count: 0 };
+
+  const entries = findEntriesList(root);
+  const reviews = entries
+    .filter(looksLikeEntry)
+    .map((e) => parseEntry(e as any[]))
+    // Drop content-less placeholder rows (API no-match sentinel).
+    .filter(
+      (e) =>
+        e.provider.name != null ||
+        e.review.reviewerName != null ||
+        e.review.texts.length > 0,
+    );
+
+  return { reviews, count: reviews.length };
+}

package/examples/google-hotels/get_hotel_reviews/playbook.yaml

@@ -0,0 +1,64 @@
+toolName: get_hotel_reviews
+summary: Open a hotel's detail panel on Google Hotels and capture its aggregated reviews (the ocp93e batchexecute response).
+parameters:
+  - name: location
+    type: string
+    description: Destination/area to search for hotels, e.g. "Chicago Loop". Used to populate the search box and pick the matching autocomplete suggestion.
+  - name: hotel_name
+    type: string
+    description: Display name of the hotel whose reviews are wanted, e.g. "Hyatt Regency Chicago". Used to click the matching result card.
+steps:
+  - action: navigate
+    url: https://www.google.com/travel/search
+    wait_for: networkidle
+  - action: click
+    locators:
+      - by: aria_label
+        value: Search for places, hotels and more
+      - by: css
+        value: input.II2One.j0Ppje
+    wait_for:
+      sleep_ms: 300
+  - action: type
+    locators:
+      - by: aria_label
+        value: Search for places, hotels and more
+      - by: css
+        value: input.II2One.j0Ppje
+    value: ${location}
+    wait_for:
+      sleep_ms: 600
+  - action: click
+    locators:
+      - by: text
+        value_pattern: ${location}
+      - by: css
+        value: ul.F3AVKd > li.Q1RWxd span.S5TdWc
+    wait_for:
+      xhr: rpcids=AtySUc
+  - action: click
+    locators:
+      - by: aria_label
+        value_pattern: ${hotel_name}
+      - by: text
+        value_pattern: ${hotel_name}
+      - by: css
+        value: a.PVOOXe
+    wait_for:
+      xhr: rpcids=ocp93e
+result:
+  source: xhr
+  url_pattern: rpcids=ocp93e
+  extract: "[0][0][0][]"
+  return_as: reviews
+notes: >-
+  The ocp93e response uses Google's anti-XSSI batchexecute envelope: strip the ")]}'" prefix and chunk-length lines,
+  JSON.parse the outer array, then JSON.parse the escaped inner string at ["wrb.fr","ocp93e", <innerJsonString>].
+  The inner JSON is positional (no object keys); the extract index path "[0][0][0][]" iterates the review-source entries.
+  Within each entry: index [0] = provider block [providerName, null, [iconUrl,w,h], type, id]; index [1] = reviewer block
+  [[reviewerName, profileUrl, [avatarUrl,w,h]], relativeDate, [ratingNum, ratingMax], [[ [sentiment, reviewText, ...] ]], reviewUrl, ...].
+  Reviews load automatically when the hotel detail panel opens (the same click also triggers M0CRd pricing) — opening the
+  Reviews tab is not required. Check-in/out dates were set during recording but do not affect the review payload, so they are
+  omitted as parameters. f.sid / bl / X-Goog-BatchExecute-Bgr are session-bound and are supplied by the live browser context,
+  not by this playbook. If the hotel result is not visible in the initial list, the agent may need to scroll the results column
+  before the ${hotel_name} click resolves.

package/examples/google-hotels/get_hotel_reviews/request-transform.ts

@@ -0,0 +1,42 @@
+// Per-tool request-transform for get_hotel_reviews. Builds the ocp93e inner
+// payload from the hotel_id param and delegates envelope/URL construction to the
+// shared google-hotels batchexecute helpers.
+import { buildFreqBody, buildBatchExecuteUrl } from '../_shared/freq.ts';
+
+export function transform(
+  method: string,
+  url: string,
+  responses: Record<string, any>,
+  params?: Record<string, any>,
+): { url: string; body: string } {
+  void method;
+  void responses;
+
+  const hotelId = String(params?.hotel_id ?? '');
+
+  // Recorded inner payload (seq 497): positions 0-7 null, [8] = hotel token,
+  // 9 & 10 null, [11] = constant [[]].
+  const innerPayload = [
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    hotelId,
+    null,
+    null,
+    [[]],
+  ];
+
+  const u = new URL(url);
+  const fSid = u.searchParams.get('f.sid') ?? '';
+  const bl = u.searchParams.get('bl') ?? '';
+
+  return {
+    url: buildBatchExecuteUrl('ocp93e', { f_sid: fSid, bl }),
+    body: buildFreqBody('ocp93e', innerPayload, '1'),
+  };
+}

package/examples/google-hotels/get_hotel_reviews/workflow.json

@@ -0,0 +1,37 @@
+{
+  "toolName": "get_hotel_reviews",
+  "intent": {
+    "description": "Fetch aggregated reviews and reviewer snippets for a selected Google Hotels hotel.",
+    "userSaid": "clicked one of the offerings, saw booking options"
+  },
+  "site": "google-hotels",
+  "parameters": [
+    {
+      "name": "hotel_id",
+      "type": "string",
+      "description": "Opaque hotel token (e.g. \"ChcI78-luoXdhoaIARoKL20vMDJ2cGdnMRAB\") obtained from the search_hotels tool's hotel_id output.",
+      "verified": true,
+      "sourcedFrom": {
+        "tool": "search_hotels",
+        "field": "hotel_id"
+      }
+    }
+  ],
+  "requestTransformModule": "./request-transform.ts",
+  "parserModule": "./parser.ts",
+  "requests": [
+    {
+      "method": "POST",
+      "url": "https://www.google.com/_/TravelFrontendUi/data/batchexecute?rpcids=ocp93e&source-path=%2Ftravel%2Fsearch&f.sid=7513562915459271421&bl=boq_travel-frontend-ui_20260527.01_p0&hl=en-US&soc-app=162&soc-platform=1&soc-device=1&_reqid=3252256&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"
+      },
+      "body": "f.req=%5B%5B%5B%22ocp93e%22%2C%22%5Bnull%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2C%5C%22${param.hotel_id}%5C%22%2Cnull%2Cnull%2C%5B%5B%5D%5D%5D%22%2Cnull%2C%221%22%5D%5D%5D&",
+      "effect": "safe"
+    }
+  ],
+  "liveVerified": true
+}

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

@@ -0,0 +1,207 @@
+/**
+ * GENERATED by `imprint emit` — DO NOT EDIT BY HAND.
+ *
+ * Tool: search_hotels
+ * Site: google-hotels
+ * Intent: Search Google Hotels for a location and date range with optional filters (price, rating, amenities, star class, brands, sort, property type).
+ *
+ * To regenerate: imprint emit ~/.imprint/google-hotels/search_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_hotels",
+  "intent": {
+    "description": "Search Google Hotels for a location and date range with optional filters (price, rating, amenities, star class, brands, sort, property type).",
+    "userSaid": "searched for hotels at chicago loop from july 3-6; filtered for > 4.0 rating; filtered min and max price; added amenities; added 2/4/5 star; added brand filters; sorted by lowest price, highest rating, most reviewed; changed property type to vacation rentals; changed location to tahoe city and denver downtown"
+  },
+  "parameters": [
+    {
+      "name": "location",
+      "type": "string",
+      "description": "Destination query, e.g. 'chicago loop', 'tahoe city', 'denver downtown'",
+      "default": "chicago loop",
+      "verified": true
+    },
+    {
+      "name": "check_in_date",
+      "type": "string",
+      "description": "Check-in date (YYYY-MM-DD)",
+      "default": "2026-07-03",
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "check_out_date",
+      "type": "string",
+      "description": "Check-out date (YYYY-MM-DD)",
+      "default": "2026-07-06",
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "adults",
+      "type": "number",
+      "description": "Number of adult travelers",
+      "default": 2,
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "children",
+      "type": "number",
+      "description": "Number of child travelers",
+      "default": 0,
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "min_rating",
+      "type": "number",
+      "description": "Minimum guest rating filter, e.g. 4.0 (0 = no filter)",
+      "default": 0,
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "min_price",
+      "type": "number",
+      "description": "Minimum nightly price filter (0 = no filter)",
+      "default": 0,
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "max_price",
+      "type": "number",
+      "description": "Maximum nightly price filter, e.g. 338 (0 = no filter)",
+      "default": 0,
+      "verified": true
+    },
+    {
+      "name": "amenities",
+      "type": "string",
+      "description": "Comma-separated amenity names or codes (e.g. 'free wi-fi,pool' or '6,9'); empty = no filter",
+      "default": "",
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "hotel_class",
+      "type": "string",
+      "description": "Comma-separated star classes, e.g. '2,3' or '4,5'; empty = no filter",
+      "default": "",
+      "verified": true
+    },
+    {
+      "name": "brands",
+      "type": "string",
+      "description": "Comma-separated brand codes ('parent:child' or numeric); empty = no filter",
+      "default": "",
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "sort_by",
+      "type": "string",
+      "description": "Sort order: relevance | lowest_price | highest_rating | most_reviewed",
+      "default": "relevance",
+      "verified": true
+    },
+    {
+      "name": "property_type",
+      "type": "string",
+      "description": "hotels | vacation_rentals",
+      "default": "hotels",
+      "verified": true
+    }
+  ],
+  "requests": [
+    {
+      "method": "POST",
+      "url": "https://www.google.com/_/TravelFrontendUi/data/batchexecute?rpcids=AtySUc&source-path=%2Ftravel%2Fsearch&f.sid=7513562915459271421&bl=boq_travel-frontend-ui_20260527.01_p0&hl=en-US&soc-app=162&soc-platform=1&soc-device=1&_reqid=2252256&rt=c",
+      "headers": {
+        "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8",
+        "X-Same-Domain": "1",
+        "x-goog-ext-259736195-jspb": "[\"en-US\",\"US\",\"USD\",2,null,[420],null,null,7,[]]",
+        "x-goog-ext-190139975-jspb": "[\"US\",\"ZZ\",\"x6c25Q==\"]",
+        "Referer": "https://www.google.com/travel/search"
+      },
+      "body": "f.req={\"location\":\"${param.location}\",\"check_in_date\":\"${param.check_in_date}\",\"check_out_date\":\"${param.check_out_date}\",\"adults\":\"${param.adults}\",\"children\":\"${param.children}\",\"min_rating\":\"${param.min_rating}\",\"min_price\":\"${param.min_price}\",\"max_price\":\"${param.max_price}\",\"amenities\":\"${param.amenities}\",\"hotel_class\":\"${param.hotel_class}\",\"brands\":\"${param.brands}\",\"sort_by\":\"${param.sort_by}\",\"property_type\":\"${param.property_type}\"}",
+      "effect": "safe"
+    }
+  ],
+  "site": "google-hotels",
+  "parserModule": "./parser.ts",
+  "requestTransformModule": "./request-transform.ts",
+  "liveVerified": true
+};
+
+export interface SearchHotelsInput {
+  /** Destination query, e.g. 'chicago loop', 'tahoe city', 'denver downtown' */
+  location?: string;
+  /** Check-in date (YYYY-MM-DD) */
+  check_in_date?: string;
+  /** Check-out date (YYYY-MM-DD) */
+  check_out_date?: string;
+  /** Number of adult travelers */
+  adults?: number;
+  /** Number of child travelers */
+  children?: number;
+  /** Minimum guest rating filter, e.g. 4.0 (0 = no filter) */
+  min_rating?: number;
+  /** Minimum nightly price filter (0 = no filter) */
+  min_price?: number;
+  /** Maximum nightly price filter, e.g. 338 (0 = no filter) */
+  max_price?: number;
+  /** Comma-separated amenity names or codes (e.g. 'free wi-fi,pool' or '6,9'); empty = no filter */
+  amenities?: string;
+  /** Comma-separated star classes, e.g. '2,3' or '4,5'; empty = no filter */
+  hotel_class?: string;
+  /** Comma-separated brand codes ('parent:child' or numeric); empty = no filter */
+  brands?: string;
+  /** Sort order: relevance | lowest_price | highest_rating | most_reviewed */
+  sort_by?: string;
+  /** hotels | vacation_rentals */
+  property_type?: string;
+}
+
+export async function searchHotels(
+  input: SearchHotelsInput,
+  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> = {
+    location: input.location ?? "chicago loop",
+    check_in_date: input.check_in_date ?? "2026-07-03",
+    check_out_date: input.check_out_date ?? "2026-07-06",
+    adults: input.adults ?? 2,
+    children: input.children ?? 0,
+    min_rating: input.min_rating ?? 0,
+    min_price: input.min_price ?? 0,
+    max_price: input.max_price ?? 0,
+    amenities: input.amenities ?? "",
+    hotel_class: input.hotel_class ?? "",
+    brands: input.brands ?? "",
+    sort_by: input.sort_by ?? "relevance",
+    property_type: input.property_type ?? "hotels",
+
+  };
+  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_hotels/package.json

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