imprint-mcp 0.3.0 → 0.4.0

package/README.md

@@ -29,6 +29,24 @@ imprint teach southwest --url https://www.southwest.com
 
 A browser opens. You drive the workflow and narrate what you're doing. Imprint records every request and interaction, then compiles a deterministic **MCP tool** your agent can call forever.
 
+Want to try a finished MCP before recording anything?
+
+```bash
+imprint install google-flights --source examples --platform claude-desktop
+```
+
+That registers the checked-in Google Flights example as an MCP server in your client. Swap `claude-desktop` for `claude-code`, `codex`, `openclaw`, or `hermes`, or add `--print` to see the config without changing anything.
+
+On a Hermes agent or Docker host, register the examples directly into Hermes:
+
+```bash
+for site in google-flights google-hotels southwest discoverandgo echo; do
+  imprint install "$site" --source examples --platform hermes --no-interactive
+done
+```
+
+When `HERMES_HOME` is set, Imprint writes Hermes MCP entries to `$HERMES_HOME/config.yaml`; outside Hermes it uses `~/.hermes/config.yaml`. For browser-backed MCPs, `imprint install` also installs Playwright Chromium into `$HERMES_HOME/.cache/ms-playwright` and writes `PLAYWRIGHT_BROWSERS_PATH` into the MCP config so Hermes can find it. Use `--skip-browser-install` only for offline builds where you preinstall the browser yourself. In a fresh Linux image that is missing browser system libraries, install those during image build with `bunx playwright install --with-deps chromium`.
+
 ---
 
 ## See It in Action
@@ -118,7 +136,7 @@ bun install && bun link
 
 <br>
 
-**Browser commands** (`teach`, `record`, `login`, `playbook`) need Playwright's Chromium:
+**Browser commands** (`teach`, `record`, `login`, `playbook`) and browser-backed `imprint install` targets auto-install Playwright Chromium when it is missing. For offline CI or prebuilt Linux images where you pass `--skip-browser-install`, preinstall it ahead of time:
 
 ```bash
 bunx playwright install chromium
@@ -207,6 +225,21 @@ Install any example into your MCP client:
 imprint install google-flights --source examples --platform claude-desktop
 ```
 
+Examples are real generated MCPs, not handwritten SDK samples. `imprint install <site> --source examples` points the MCP server at this repo's `examples/` directory with `IMPRINT_HOME`, ensures Playwright Chromium for browser-backed tools, and lets your client list and call the checked-in tools immediately:
+
+```bash
+imprint install google-hotels --source examples --platform codex
+imprint install southwest --source examples --platform claude-code
+imprint install echo --source examples --platform claude-desktop --print
+```
+
+For your own generated tools, leave off `--source examples`:
+
+```bash
+imprint install mysite --platform claude-code
+imprint install mysite --platform codex
+```
+
 ---
 
 ## CLI Reference
@@ -227,7 +260,14 @@ imprint <command> --help    # per-command options
 
 ## Sharing Skills
 
-Teach on your laptop, ship to a remote agent. Skill folders contain **zero plaintext credentials** — only `${credential.NAME}` placeholders and a manifest listing what the receiver must provision.
+Teach on your laptop, ship to a remote agent. Generated MCP folders contain the portable tool artifacts: `workflow.json`, `playbook.yaml`, `index.ts`, optional shared modules, and cron/backend metadata. Copy `~/.imprint/<site>` into the receiver's `~/.imprint/<site>` or commit it to a private repo, install Imprint there, then register it:
+
+```bash
+bun install -g imprint-mcp
+imprint install mysite --platform claude-code
+```
+
+Credentials stay separate. Skill folders contain **zero plaintext credentials** — only `${credential.NAME}` placeholders and a manifest listing what the receiver must provision.
 
 ```bash
 # Export (encrypted with libsodium + argon2id)

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

@@ -75,7 +75,7 @@ const WORKFLOW: Workflow = {
       {
         "name": "f_sid",
         "required": false,
-        "capability": "ordinary_http",
+        "capability": "browser_bootstrap",
         "source": "html_regex",
         "pattern": "\"FdrFJe\":\"([^\"]+)\"",
         "group": 1
@@ -83,7 +83,7 @@ const WORKFLOW: Workflow = {
       {
         "name": "bl",
         "required": false,
-        "capability": "ordinary_http",
+        "capability": "browser_bootstrap",
         "source": "html_regex",
         "pattern": "\"cfb2h\":\"([^\"]+)\"",
         "group": 1

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

@@ -44,14 +44,16 @@
         "name": "f_sid",
         "pattern": "\"FdrFJe\":\"([^\"]+)\"",
         "group": 1,
-        "required": false
+        "required": false,
+        "capability": "browser_bootstrap"
       },
       {
         "source": "html_regex",
         "name": "bl",
         "pattern": "\"cfb2h\":\"([^\"]+)\"",
         "group": 1,
-        "required": false
+        "required": false,
+        "capability": "browser_bootstrap"
       }
     ]
   },

package/examples/southwest/README.md

@@ -8,13 +8,14 @@
 - **`probe-backends` skipping the futile rung.** The cached `backends.json` orders the ladder `stealth-fetch → playbook` so cron doesn't burn 200ms on a fetch attempt every tick.
 - **`notifyWhen: price_below`** pushing only on real drops, with the `pricePath` extracting from real Southwest response shape.
 - **The fresh-UUID header trick** — Southwest rejects stale `X-User-Experience-ID`; stealth-fetch regenerates per call.
+- **Public bootstrap config capture.** The workflow fetches Southwest's public bootstrap `data.js` and captures the current `api-keys.prod` value, so installed examples do not require a `SOUTHWEST_API_KEY` environment variable.
 - **Multi-path `pricePath`** — `cron.json`'s notifyWhen lists both the raw API shape (when stealth-fetch wins) and the playbook's reshaped output, so the push fires regardless of which backend produced the result.
 
 ## Run it
 
 ```bash
-# One-time setup (if you haven't already)
-bunx playwright install chromium
+# One-time setup: registers the example MCP and installs Playwright Chromium if missing
+imprint install southwest --source examples --platform claude-desktop
 
 # Run a single tick (verifies everything still works)
 imprint cron southwest --once

package/examples/southwest/search_southwest_flights/index.ts

@@ -55,13 +55,30 @@ const WORKFLOW: Workflow = {
     }
   ],
   "requests": [
+    {
+      "method": "GET",
+      "url": "https://www.southwest.com/swa-ui/bootstrap/landing-home-page-v2/1/data.js",
+      "headers": {
+        "Accept": "application/javascript, text/javascript, */*; q=0.01"
+      },
+      "captures": [
+        {
+          "name": "southwest_api_key",
+          "source": "text_regex",
+          "pattern": "\"swa-bootstrap-landing-home-page-v2/api-keys\":\\[function\\(require,module,exports\\)\\{\\s*module\\.exports = \\{[^}]*\"prod\":\"([^\"]+)\"",
+          "group": 1,
+          "required": true,
+          "capability": "ordinary_http"
+        }
+      ]
+    },
     {
       "method": "POST",
       "url": "https://www.southwest.com/api/air-booking/v1/air-booking/page/air/booking/shopping",
       "headers": {
         "Content-Type": "application/json",
         "Accept": "application/json, text/javascript, */*; q=0.01",
-        "X-API-Key": "${env.SOUTHWEST_API_KEY}",
+        "X-API-Key": "${state.southwest_api_key}",
         "X-App-ID": "air-booking",
         "X-Channel-ID": "southwest"
       },

package/examples/southwest/search_southwest_flights/workflow.json

@@ -37,13 +37,30 @@
     }
   ],
   "requests": [
+    {
+      "method": "GET",
+      "url": "https://www.southwest.com/swa-ui/bootstrap/landing-home-page-v2/1/data.js",
+      "headers": {
+        "Accept": "application/javascript, text/javascript, */*; q=0.01"
+      },
+      "captures": [
+        {
+          "name": "southwest_api_key",
+          "source": "text_regex",
+          "pattern": "\"swa-bootstrap-landing-home-page-v2/api-keys\":\\[function\\(require,module,exports\\)\\{\\s*module\\.exports = \\{[^}]*\"prod\":\"([^\"]+)\"",
+          "group": 1,
+          "required": true,
+          "capability": "ordinary_http"
+        }
+      ]
+    },
     {
       "method": "POST",
       "url": "https://www.southwest.com/api/air-booking/v1/air-booking/page/air/booking/shopping",
       "headers": {
         "Content-Type": "application/json",
         "Accept": "application/json, text/javascript, */*; q=0.01",
-        "X-API-Key": "${env.SOUTHWEST_API_KEY}",
+        "X-API-Key": "${state.southwest_api_key}",
         "X-App-ID": "air-booking",
         "X-Channel-ID": "southwest"
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imprint-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Teach an AI agent how to use any website. Once. Records a real browser session + narration; generates a deterministic MCP tool plus a DOM-replay playbook fallback.",
   "type": "module",
   "exports": {

package/src/cli.ts

@@ -62,6 +62,10 @@ INSTALL
   install [<site>]         Install an emitted MCP server into an AI platform.
   uninstall [<site>]       Remove an installed Imprint MCP server from an AI platform.
 
+SHARE
+  export <site> [<site2>]  Bundle site tools into a portable .tar.gz archive.
+  import <archive.tar.gz>  Unpack an archive into ~/.imprint and set up tools.
+
 RUN
   mcp-server <site>        Serve one site's tools as MCP (stdio default).
   cron <site>              Polling daemon for ~/.imprint/<site>/<toolName>/cron.json.
@@ -238,7 +242,7 @@ export const VERB_HELP: Record<string, VerbHelp> = {
     summary:
       'Install an already-emitted MCP server into Claude Code, Codex, Claude Desktop, OpenClaw, or Hermes.',
     usage: [
-      'imprint install [<site>] [--platform <name>] [--source local|examples] [--print] [--no-interactive]',
+      'imprint install [<site>] [--platform <name>] [--source local|examples] [--print] [--no-interactive] [--skip-browser-install]',
     ],
     flags: [
       {
@@ -257,6 +261,10 @@ export const VERB_HELP: Record<string, VerbHelp> = {
         name: '--no-interactive',
         description: 'Do not prompt; requires <site> and --platform.',
       },
+      {
+        name: '--skip-browser-install',
+        description: 'Do not auto-install Playwright Chromium for browser-backed tools.',
+      },
     ],
     example: 'imprint install google-flights --source examples --platform claude-desktop',
   },
@@ -280,6 +288,39 @@ export const VERB_HELP: Record<string, VerbHelp> = {
     ],
     example: 'imprint uninstall google-flights --platform claude-desktop',
   },
+  export: {
+    summary:
+      'Bundle one or more site tool sets into a portable .tar.gz archive for sharing across machines.',
+    usage: ['imprint export <site> [<site2> ...] [--out <path>] [--include-credentials]'],
+    flags: [
+      {
+        name: '--out <path>',
+        description:
+          'Output path. Defaults to ./imprint-export-<site>.tar.gz (single) or ./imprint-export-<timestamp>.tar.gz (multi).',
+      },
+      {
+        name: '--include-credentials',
+        description: 'Embed encrypted credential bundles (prompts for a passphrase per site).',
+      },
+    ],
+    example: 'imprint export avis southwest marriott --out tools.tar.gz --include-credentials',
+  },
+  import: {
+    summary: 'Unpack an imprint export archive into ~/.imprint and set up tools for use.',
+    usage: ['imprint import <archive.tar.gz> [--force] [--platform <name>]'],
+    flags: [
+      {
+        name: '--force',
+        description: 'Overwrite existing sites instead of skipping them.',
+      },
+      {
+        name: '--platform <name>',
+        description:
+          'Auto-install MCP servers after import: claude-code, codex, claude-desktop, openclaw, hermes.',
+      },
+    ],
+    example: 'imprint import tools.tar.gz --force --platform claude-code',
+  },
   login: {
     summary: 'Persist auth cookies for <site> from a captured session.',
     usage: ['imprint login <site> --from-session <session.json>'],
@@ -822,6 +863,7 @@ async function main(argv: string[]): Promise<number> {
           source: { type: 'string' },
           print: { type: 'boolean' },
           'no-interactive': { type: 'boolean' },
+          'skip-browser-install': { type: 'boolean' },
         },
         allowPositionals: false,
       });
@@ -850,6 +892,7 @@ async function main(argv: string[]): Promise<number> {
             source: values.source as (typeof sources)[number] | undefined,
             print: values.print,
             noInteractive: values['no-interactive'],
+            skipBrowserInstall: values['skip-browser-install'],
           });
       console.log(`[imprint] ${result.message}`);
       if ('source' in result)
@@ -890,6 +933,114 @@ async function main(argv: string[]): Promise<number> {
       return 0;
     }
 
+    case 'export': {
+      const sites: string[] = [];
+      let i = 1;
+      for (; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg || arg.startsWith('-')) break;
+        sites.push(arg);
+      }
+      if (sites.length === 0) {
+        console.error('error: `imprint export` requires at least one <site> argument.');
+        return 2;
+      }
+      const { values } = parseArgs({
+        args: argv.slice(i),
+        options: {
+          out: { type: 'string' },
+          'include-credentials': { type: 'boolean' },
+        },
+        allowPositionals: false,
+      });
+      const defaultOut =
+        sites.length === 1
+          ? `imprint-export-${sites[0]}.tar.gz`
+          : `imprint-export-${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)}.tar.gz`;
+      const out = values.out ?? defaultOut;
+      const { exportArchive } = await import('./imprint/export-archive.ts');
+      const result = await exportArchive({
+        sites,
+        out,
+        includeCredentials: values['include-credentials'],
+      });
+      console.log(`[imprint] exported → ${result.archivePath}`);
+      for (const s of result.sites) {
+        console.log(
+          `[imprint]   ${s.name}: ${s.tools.length} tool${s.tools.length === 1 ? '' : 's'} (${s.tools.join(', ')})`,
+        );
+      }
+      const kb = (result.byteSize / 1024).toFixed(1);
+      console.log(`[imprint] archive size: ${kb} KB`);
+      console.log('');
+      console.log('next step:');
+      console.log(`  imprint import ${out}    # on the target machine`);
+      return 0;
+    }
+
+    case 'import': {
+      const archivePath = requirePositional(argv, 'import', 'an <archive.tar.gz> argument');
+      if (archivePath === null) return 2;
+      const { values } = parseArgs({
+        args: argv.slice(2),
+        options: {
+          force: { type: 'boolean' },
+          platform: { type: 'string' },
+        },
+        allowPositionals: false,
+      });
+
+      if (values.platform) {
+        const { PLATFORMS } = await import('./imprint/integrations.ts');
+        if (!PLATFORMS.includes(values.platform as (typeof PLATFORMS)[number])) {
+          console.error(
+            `error: unknown platform '${values.platform}' — valid: ${PLATFORMS.join(', ')}`,
+          );
+          return 2;
+        }
+      }
+
+      const { importArchive } = await import('./imprint/export-archive.ts');
+      const result = await importArchive({
+        archivePath,
+        force: values.force,
+      });
+
+      for (const s of result.sites) {
+        if (s.skipped) {
+          console.log(`[imprint] ${s.name}: skipped (already exists)`);
+        } else {
+          console.log(
+            `[imprint] ${s.name}: imported ${s.tools.length} tool${s.tools.length === 1 ? '' : 's'} (${s.tools.join(', ')})${s.credentialsImported ? ' + credentials' : ''}`,
+          );
+        }
+      }
+
+      const imported = result.sites.filter((s) => !s.skipped);
+      if (imported.length > 0 && !values.platform) {
+        console.log('');
+        console.log('next steps:');
+        for (const s of imported) {
+          console.log(`  imprint install ${s.name}    # register MCP server`);
+        }
+      }
+
+      if (values.platform) {
+        const { install } = await import('./imprint/install.ts');
+        const { PLATFORMS } = await import('./imprint/integrations.ts');
+        for (const s of imported) {
+          const installResult = await install({
+            site: s.name,
+            platform: values.platform as (typeof PLATFORMS)[number],
+            noInteractive: true,
+          });
+          console.log(`[imprint] ${installResult.message}`);
+        }
+      }
+
+      return 0;
+    }
+
     case 'login': {
       const site = requirePositional(argv, 'login', 'a <site> argument');
       if (site === null) return 2;

package/src/imprint/cdp-browser-fetch.ts

@@ -283,7 +283,10 @@ export function createCdpBrowserFetch(opts: CdpBrowserFetchOptions): CdpBrowserF
           throw new Error('navigate timeout');
         }),
       ]);
-      await Page.loadEventFired().catch(() => {});
+      await Promise.race([
+        Page.loadEventFired(),
+        sleep(Math.min(abckWaitMs, 5000)).then(() => undefined),
+      ]).catch(() => {});
     } catch (err) {
       log(`navigation issue (continuing): ${err instanceof Error ? err.message : String(err)}`);
     }