imprint-mcp 0.2.0

package/src/imprint/mcp-server.ts

@@ -0,0 +1,350 @@
+/**
+ * `imprint mcp-server` — exposes every generated tool under
+ * <IMPRINT_HOME>/<site>/ as an MCP tool. Stdio + Streamable HTTP transports.
+ * See docs/getting-started.md for Claude Desktop / mcp-inspector wire-up.
+ */
+
+import { existsSync } from 'node:fs';
+import { type IncomingMessage, type ServerResponse, createServer } from 'node:http';
+import { resolve as pathResolve } from 'node:path';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import {
+  CallToolRequestSchema,
+  type CallToolResult,
+  ListToolsRequestSchema,
+  type Tool,
+} from '@modelcontextprotocol/sdk/types.js';
+import { resolveLadder, runWithLadder } from './backend-ladder.ts';
+import { createLog } from './log.ts';
+import { imprintHomeDir } from './paths.ts';
+import { loadBackendsCache } from './probe-backends.ts';
+import { checkSiteCredentialsReady } from './runtime.ts';
+import { availableSitesHint } from './sites.ts';
+import type { StealthFetch } from './stealth-fetch.ts';
+import {
+  type ResolvedTool as DiscoveredTool,
+  buildZodValidator,
+  discoverTools,
+} from './tool-loader.ts';
+import type { ConcreteBackend, ToolResult, WorkflowParameter } from './types.ts';
+import { VERSION } from './version.ts';
+
+interface RunMcpServerOptions {
+  /** Site name. */
+  site: string;
+  /** Override generated asset root. Defaults to IMPRINT_HOME (~/.imprint). */
+  assetRoot?: string;
+  /** Use Streamable HTTP transport instead of stdio. */
+  http?: boolean;
+  /** Port for HTTP transport (default 8765). */
+  port?: number;
+  /** Hostname for HTTP transport (default 127.0.0.1). */
+  host?: string;
+  /** Server display name advertised to clients. */
+  name?: string;
+  /** Server version. */
+  version?: string;
+}
+
+interface ResolvedTool extends DiscoveredTool {
+  inputSchema: Tool['inputSchema'];
+  playbookPath?: string;
+  /** Probe-cached ladder; runtime starts here instead of the default. */
+  preferredOrder?: ConcreteBackend[];
+}
+
+/** Tool description shown to MCP clients. Includes the operator's
+ *  recorded narration when present — surprisingly load-bearing for the
+ *  LLM picking the right tool. */
+function buildToolDescription(w: ResolvedTool['workflow']): string {
+  const base = w.intent.description;
+  const said = w.intent.userSaid?.trim();
+  return said ? `${base}\n\nRecording context: "${said}"` : base;
+}
+
+/** MCP advertises tool input as JSON Schema; build it directly from
+ *  workflow parameters rather than going through Zod. */
+function buildJsonSchema(parameters: WorkflowParameter[]): Tool['inputSchema'] {
+  const properties: Record<string, { type: string; description: string }> = {};
+  const required: string[] = [];
+  for (const p of parameters) {
+    properties[p.name] = { type: p.type, description: p.description };
+    if (p.default === undefined) required.push(p.name);
+  }
+  return {
+    type: 'object',
+    properties,
+    required: required.length ? required : undefined,
+  };
+}
+
+const log = createLog('mcp');
+
+/** Build the MCP Server with all discovered tools registered. */
+function buildServer(
+  name: string,
+  version: string,
+  tools: ResolvedTool[],
+  assetRoot: string,
+): Server {
+  const server = new Server(
+    { name, version },
+    {
+      capabilities: { tools: {} },
+      instructions:
+        'Imprint runs deterministic workflows captured from real browser sessions. Tools prefer fetch API replay, may use gated fetch-bootstrap only for declared browser-minted state, then stealth-fetch for bot-defense state, and playbook only for full DOM interaction. Error codes: AUTH_EXPIRED (401, run `imprint login <site>`); STATE_MISSING (required cookie/state was unavailable or ambiguous); FORBIDDEN (403); RATE_LIMITED (429, back off); BAD_RESPONSE (other 4xx/5xx); NETWORK (fetch failed); UNKNOWN (everything else).',
+    },
+  );
+
+  const validators = new Map(
+    tools.map((t) => [t.workflow.toolName, buildZodValidator(t.workflow.parameters)] as const),
+  );
+
+  // Per-site stealth-fetch cache so the ~12s bootstrap runs once per site.
+  const stealthCache = new Map<string, StealthFetch>();
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => ({
+      name: t.workflow.toolName,
+      description: buildToolDescription(t.workflow),
+      inputSchema: t.inputSchema,
+    })),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (req): Promise<CallToolResult> => {
+    const tool = tools.find((t) => t.workflow.toolName === req.params.name);
+    if (!tool) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: `Unknown tool: ${req.params.name}` }],
+      };
+    }
+
+    const validator = validators.get(req.params.name);
+    const parsed = validator?.safeParse(req.params.arguments ?? {});
+    if (parsed && !parsed.success) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: 'text',
+            text: `Invalid arguments: ${parsed.error.errors.map((e) => `${e.path.join('.')}: ${e.message}`).join('; ')}`,
+          },
+        ],
+      };
+    }
+    const args = (parsed?.data ?? req.params.arguments ?? {}) as Record<
+      string,
+      string | number | boolean
+    >;
+
+    try {
+      const ladder = resolveLadder('auto', tool.preferredOrder);
+      const { result, usedBackend } = await runWithLadder(
+        ladder,
+        tool,
+        args,
+        assetRoot,
+        stealthCache,
+      );
+      if (!result.ok) {
+        const text = formatToolError(result);
+        return {
+          isError: true,
+          content: [{ type: 'text', text: `${text}\n(backend: ${usedBackend})` }],
+        };
+      }
+      const text =
+        typeof result.data === 'string' ? result.data : JSON.stringify(result.data, null, 2);
+      return { content: [{ type: 'text', text: `${text}\n\n(backend: ${usedBackend})` }] };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { isError: true, content: [{ type: 'text', text: `[INTERNAL] ${msg}` }] };
+    }
+  });
+
+  return server;
+}
+
+function formatToolError(result: Extract<ToolResult, { ok: false }>): string {
+  const lines = [`[${result.error}] ${result.message}`];
+  if (result.error === 'STATE_MISSING' && result.missing?.length) {
+    for (const item of result.missing) {
+      lines.push(
+        `  - ${item.name}: ${item.failure} (${item.capability})${item.message ? ` — ${item.message}` : ''}`,
+      );
+    }
+  }
+  if (result.remediation) lines.push(`  → ${result.remediation}`);
+  return lines.join('\n');
+}
+
+export async function runMcpServer(opts: RunMcpServerOptions): Promise<void> {
+  const assetRoot = opts.assetRoot ?? imprintHomeDir();
+  const discovered = await discoverTools(assetRoot, opts.site, '[imprint mcp]');
+  const tools: ResolvedTool[] = discovered.map((t) => {
+    const playbookPath = pathResolve(t.dir, 'playbook.yaml');
+    const cache = loadBackendsCache(t.site, assetRoot, t.dir);
+    return {
+      ...t,
+      inputSchema: buildJsonSchema(t.workflow.parameters),
+      playbookPath: existsSync(playbookPath) ? playbookPath : undefined,
+      preferredOrder: cache?.preferredOrder,
+    };
+  });
+  if (tools.length === 0) {
+    throw new Error(
+      `No generated tool found for site "${opts.site}"\n${availableSitesHint(assetRoot, opts.site)}\n→ run \`imprint teach ${opts.site}\` or \`imprint emit ~/.imprint/<site>/<toolName>/workflow.json\` to codegen a tool.`,
+    );
+  }
+
+  const name = opts.name ?? `imprint-${opts.site}`;
+  const version = opts.version ?? VERSION;
+
+  for (const t of tools) {
+    log(`registered ${t.workflow.toolName} (${t.site}) — ${t.workflow.parameters.length} param(s)`);
+    if (t.preferredOrder) {
+      log(`  preferred backend order (probed): ${t.preferredOrder.join(' → ')}`);
+    }
+    if (t.playbookPath) {
+      log('  playbook.yaml found (available as ladder fallback)');
+    }
+  }
+
+  // Pre-flight: warn loudly if any tool's site has a credentials manifest
+  // declaring secrets that aren't yet provisioned. We log instead of throw
+  // so the MCP server still comes up — the user might be intentionally
+  // running an unauthenticated subset of tools — but the warning gives them
+  // the exact commands to run before the first tool call fails.
+  const reportedSites = new Set<string>();
+  for (const t of tools) {
+    if (reportedSites.has(t.site)) continue;
+    reportedSites.add(t.site);
+    try {
+      const report = await checkSiteCredentialsReady(t.site);
+      if (!report.ok) {
+        // Two-line summary on the warning, then the full multi-line
+        // remediation block. The message is already formatted for humans.
+        log(
+          `  ⚠ site "${t.site}" is missing ${report.missing.length} credential(s) declared in credentials.manifest.json`,
+        );
+        for (const line of report.message.split('\n')) {
+          log(`    ${line}`);
+        }
+      }
+    } catch (err) {
+      log(
+        `  ⚠ credential pre-flight for "${t.site}" failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  if (opts.http) {
+    const port = opts.port ?? 8765;
+    const host = opts.host ?? '127.0.0.1';
+    await runHttp(name, version, tools, host, port, assetRoot);
+  } else {
+    await runStdio(name, version, tools, assetRoot);
+  }
+}
+
+/**
+ * Stdio transport. The SDK's StdioServerTransport just attaches data
+ * listeners to process.stdin and returns; if we let runMcpServer resolve
+ * here, cli.ts would call process.exit(0) and kill the server before any
+ * client request arrived. Block until the transport closes (client EOFs
+ * stdin) or we get SIGINT/SIGTERM.
+ */
+async function runStdio(
+  name: string,
+  version: string,
+  tools: ResolvedTool[],
+  assetRoot: string,
+): Promise<void> {
+  const server = buildServer(name, version, tools, assetRoot);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  log(`stdio transport ready (${tools.length} tool${tools.length === 1 ? '' : 's'})`);
+
+  await new Promise<void>((resolve) => {
+    const done = (reason: string): void => {
+      log(`stdio transport closing: ${reason}`);
+      resolve();
+    };
+    transport.onclose = () => done('client disconnected');
+    process.once('SIGINT', () => done('SIGINT'));
+    process.once('SIGTERM', () => done('SIGTERM'));
+  });
+}
+
+/**
+ * Streamable HTTP transport. We construct a tiny Node http server ourselves
+ * so we know exactly when the listen completes — fastmcp's wrapper has been
+ * unreliable about that under Bun.
+ *
+ * One transport instance + one Server instance handle every request. POST
+ * `/mcp` carries the JSON-RPC payload. The transport handles framing,
+ * accept-header negotiation (json vs SSE), and session id management.
+ */
+async function runHttp(
+  name: string,
+  version: string,
+  tools: ResolvedTool[],
+  host: string,
+  port: number,
+  assetRoot: string,
+): Promise<void> {
+  const server = buildServer(name, version, tools, assetRoot);
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: () => crypto.randomUUID(),
+  });
+  await server.connect(transport);
+
+  const httpServer = createServer(async (req: IncomingMessage, res: ServerResponse) => {
+    if (req.url?.startsWith('/mcp')) {
+      try {
+        // The transport reads the body itself when we pass undefined as the
+        // 3rd arg AND the request is a POST; for GET (SSE keep-alive) it
+        // pumps the response stream.
+        await transport.handleRequest(req, res);
+      } catch (err) {
+        res.writeHead(500, { 'content-type': 'application/json' });
+        res.end(
+          JSON.stringify({
+            error: err instanceof Error ? err.message : String(err),
+          }),
+        );
+      }
+      return;
+    }
+    if (req.url === '/health') {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ status: 'ok', tools: tools.length }));
+      return;
+    }
+    res.writeHead(404, { 'content-type': 'text/plain' });
+    res.end('Not found. POST /mcp for the MCP endpoint, GET /health for status.');
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    httpServer.once('error', reject);
+    httpServer.listen(port, host, () => {
+      httpServer.off('error', reject);
+      resolve();
+    });
+  });
+  log(`HTTP transport ready on http://${host}:${port}/mcp (health: /health)`);
+
+  // Keep the process alive until SIGINT/SIGTERM. Without this, bun
+  // sometimes exits even though the http server is listening.
+  await new Promise<void>((resolve) => {
+    const shutdown = (sig: NodeJS.Signals): void => {
+      log(`received ${sig}, shutting down`);
+      httpServer.close(() => resolve());
+    };
+    process.once('SIGINT', () => shutdown('SIGINT'));
+    process.once('SIGTERM', () => shutdown('SIGTERM'));
+  });
+}

package/src/imprint/multi-progress.ts

@@ -0,0 +1,69 @@
+/**
+ * In-place multi-line progress renderer for concurrent compile agents.
+ *
+ * Uses CSI CPL (\x1b[nF — cursor previous line) to move back to the
+ * first rendered line, then CSI ED (\x1b[J — erase to end of screen)
+ * before rewriting.  Everything is emitted in a single write() call
+ * so the terminal processes it atomically.
+ *
+ * Falls back to plain newline-per-update for non-TTY output.
+ */
+
+const isTTY = (): boolean => process.stderr.isTTY ?? false;
+
+export class MultiProgress {
+  private lines = new Map<string, string>();
+  private renderedCount = 0;
+  private paused = false;
+
+  update(key: string, message: string): void {
+    this.lines.set(key, message);
+    if (this.paused) return;
+    if (!isTTY()) {
+      process.stderr.write(`${message}\n`);
+      return;
+    }
+    this.redraw();
+  }
+
+  remove(key: string): void {
+    this.lines.delete(key);
+  }
+
+  /** Erase all rendered progress lines from the terminal. */
+  clear(): void {
+    if (!isTTY() || this.renderedCount === 0) return;
+    process.stderr.write(`\x1b[${this.renderedCount}F\x1b[J`);
+    this.renderedCount = 0;
+  }
+
+  /** Stop writing to the terminal. Updates are buffered in memory. */
+  pause(): void {
+    this.paused = true;
+  }
+
+  /** Resume writing. Redraws current state immediately. */
+  resume(): void {
+    this.paused = false;
+    if (isTTY() && this.lines.size > 0) this.redraw();
+  }
+
+  render(): void {
+    if (this.paused) return;
+    if (!isTTY() || this.lines.size === 0) return;
+    this.redraw();
+  }
+
+  private redraw(): void {
+    let buf = '';
+    if (this.renderedCount > 0) {
+      buf += `\x1b[${this.renderedCount}F`;
+    }
+    buf += '\x1b[J';
+    for (const [, msg] of this.lines) {
+      buf += `│  ${msg}\n`;
+    }
+    process.stderr.write(buf);
+    this.renderedCount = this.lines.size;
+  }
+}

package/src/imprint/notify.ts

@@ -0,0 +1,155 @@
+/**
+ * Notification hooks for the cron daemon. Two concerns:
+ *   - evaluateNotifyWhen: predicate engine ("price_below" etc).
+ *   - notify / providers: deliver to Pushover + ntfy in parallel.
+ *
+ * Every configured provider fires on each call; nothing configured is
+ * a silent no-op. Failures are caught and logged so a flaky provider
+ * can't crash the cron loop. See docs/notifications.md for setup.
+ */
+
+import { extractNumbers } from './json-path.ts';
+import { createLog } from './log.ts';
+import type { NotifyWhen } from './types.ts';
+
+const PUSHOVER_URL = 'https://api.pushover.net/1/messages.json';
+
+interface NotifyResult {
+  /** True if the provider was configured AND the API accepted the message. */
+  delivered: boolean;
+  /** Set when delivery was attempted-but-failed, OR provider was skipped. */
+  reason?: string;
+}
+
+interface NotifyDecision {
+  notify: boolean;
+  /** Used as the push title when notify=true. */
+  title?: string;
+  /** Used as the push body when notify=true. */
+  message?: string;
+}
+
+export function evaluateNotifyWhen(
+  pred: NotifyWhen,
+  data: unknown,
+  toolName = 'workflow',
+): NotifyDecision {
+  switch (pred.type) {
+    case 'price_below': {
+      const paths = Array.isArray(pred.pricePath) ? pred.pricePath : [pred.pricePath];
+      // Union the values from every path that matches — gracefully handles
+      // tools that return different shapes from different backends.
+      const prices: number[] = [];
+      for (const p of paths) {
+        try {
+          prices.push(...extractNumbers(data, p));
+        } catch {
+          // Path didn't match this shape — try the next one. If ALL paths
+          // throw, prices stays empty and we treat it as "no signal" below.
+        }
+      }
+      if (prices.length === 0) return { notify: false }; // empty / misconfigured path
+      const min = Math.min(...prices);
+      if (min < pred.threshold) {
+        return {
+          notify: true,
+          title: `imprint: price drop on ${toolName}`,
+          message: `Lowest price $${min} (under your $${pred.threshold} threshold) — ${prices.length} option${prices.length === 1 ? '' : 's'} found.`,
+        };
+      }
+      return { notify: false };
+    }
+  }
+}
+
+const log = createLog('notify');
+
+/** Push to every configured provider in parallel; returns per-provider results. */
+export async function notify(
+  title: string,
+  message: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<Record<string, NotifyResult>> {
+  const [pushover, ntfy] = await Promise.all([
+    notifyPushover(title, message, fetchImpl),
+    notifyNtfy(title, message, fetchImpl),
+  ]);
+  return { pushover, ntfy };
+}
+
+async function notifyPushover(
+  title: string,
+  message: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<NotifyResult> {
+  const token = process.env.PUSHOVER_TOKEN;
+  const user = process.env.PUSHOVER_USER;
+  if (!token || !user) {
+    return {
+      delivered: false,
+      reason:
+        'PUSHOVER_TOKEN / PUSHOVER_USER not set (or set NTFY_URL for free push — see docs/notifications.md)',
+    };
+  }
+
+  const body = new URLSearchParams({ token, user, title, message });
+  try {
+    const r = await fetchImpl(PUSHOVER_URL, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: body.toString(),
+    });
+    if (!r.ok) {
+      const text = await r.text().catch(() => '<no body>');
+      log(`Pushover rejected: ${r.status} ${text}`);
+      return { delivered: false, reason: `HTTP ${r.status}: ${text}` };
+    }
+    log(`notified Pushover: ${title}`);
+    return { delivered: true };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log(`Pushover request failed: ${msg}`);
+    return { delivered: false, reason: msg };
+  }
+}
+
+async function notifyNtfy(
+  title: string,
+  message: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<NotifyResult> {
+  const url = process.env.NTFY_URL;
+  if (!url) {
+    return {
+      delivered: false,
+      reason:
+        'NTFY_URL not set (e.g. https://ntfy.sh/your-secret-topic — see docs/notifications.md)',
+    };
+  }
+
+  // POST body to /<topic>; title + priority ride as headers; bearer auth
+  // only needed for protected topics on self-hosted instances.
+  const headers: Record<string, string> = {
+    'content-type': 'text/plain; charset=utf-8',
+    Title: title,
+    Priority: 'high',
+    Tags: 'warning',
+  };
+  const token = process.env.NTFY_TOKEN;
+  if (token) headers.Authorization = `Bearer ${token}`;
+
+  try {
+    const r = await fetchImpl(url, { method: 'POST', headers, body: message });
+    if (!r.ok) {
+      const text = await r.text().catch(() => '<no body>');
+      log(`ntfy rejected: ${r.status} ${text}`);
+      return { delivered: false, reason: `HTTP ${r.status}: ${text}` };
+    }
+    log(`notified ntfy: ${title}`);
+    return { delivered: true };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log(`ntfy request failed: ${msg}`);
+    return { delivered: false, reason: msg };
+  }
+}

package/src/imprint/paths.ts

@@ -0,0 +1,64 @@
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import {
+  isAbsolute as pathIsAbsolute,
+  join as pathJoin,
+  relative as pathRelative,
+  resolve as pathResolve,
+} from 'node:path';
+
+export function imprintHomeDir(): string {
+  const raw = process.env.IMPRINT_HOME ?? pathJoin(homedir(), '.imprint');
+  const resolved = pathResolve(raw);
+  if (!pathIsAbsolute(resolved)) {
+    throw new Error(`IMPRINT_HOME must resolve to an absolute path, got: ${raw}`);
+  }
+  return resolved;
+}
+
+function validatePathSegment(label: string, value: string): void {
+  if (value.includes('..') || value.includes('/') || value.includes('\\')) {
+    throw new Error(
+      `Invalid ${label}: "${value}". Must not contain path separators or ".." sequences.`,
+    );
+  }
+}
+
+export function localSiteDir(site: string): string {
+  validatePathSegment('site name', site);
+  return pathJoin(imprintHomeDir(), site);
+}
+
+export function localToolDir(site: string, toolName: string): string {
+  validatePathSegment('tool name', toolName);
+  return pathJoin(localSiteDir(site), toolName);
+}
+
+export function localSessionsDir(site: string): string {
+  return pathJoin(localSiteDir(site), 'sessions');
+}
+
+export function defaultSessionJsonlPath(site: string, timestamp: string): string {
+  return pathJoin(localSessionsDir(site), `${timestamp}.jsonl`);
+}
+
+export function resolveLocalSitePath(site: string, value: string): string {
+  return pathIsAbsolute(value) ? value : pathResolve(localSiteDir(site), value);
+}
+
+export function relativeToLocalSite(site: string, absolutePath: string): string | null {
+  let root: string;
+  let target: string;
+  try {
+    root = realpathSync(pathResolve(localSiteDir(site)));
+    target = realpathSync(pathResolve(absolutePath));
+  } catch {
+    root = pathResolve(localSiteDir(site));
+    target = pathResolve(absolutePath);
+  }
+  const relative = pathRelative(root, target);
+  if (relative === '' || (!relative.startsWith('..') && !pathIsAbsolute(relative))) {
+    return relative;
+  }
+  return null;
+}

package/src/imprint/playbook-parser.ts

@@ -0,0 +1,21 @@
+/** YAML → Playbook (Zod-validated). */
+
+import YAML from 'yaml';
+import { type Playbook, PlaybookSchema } from './types.ts';
+
+export function parsePlaybook(yaml: string): Playbook {
+  let raw: unknown;
+  try {
+    raw = YAML.parse(yaml);
+  } catch (err) {
+    throw new Error(
+      `Playbook YAML failed to parse: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  const parsed = PlaybookSchema.safeParse(raw);
+  if (!parsed.success) {
+    const issues = parsed.error.errors.map((e) => `  ${e.path.join('.')}: ${e.message}`).join('\n');
+    throw new Error(`Playbook failed schema validation:\n${issues}`);
+  }
+  return parsed.data;
+}