@broberg/lens-daemon 0.0.0-stage → 0.1.0

package/src/mcp.ts

@@ -0,0 +1,562 @@
+// F074.5 — Lens MCP surface (daemon /mcp).
+//
+// The daemon hosts its OWN MCP server exposing only the lens_* tools. This is
+// the architecture that keeps "cloud runs no browser" AND "cc calls lens"
+// both true: the cloud MCP (services.cardmem.com) stays browser-free; the
+// browser-owning daemon is locally reachable, so cc adds this local endpoint
+// to its .mcp.json and calls lens_* directly. Stateless transport per request,
+// mirroring apps/server/src/mcp.ts.
+
+import { Hono } from 'hono';
+import { MANUSCRIPT_VERBS, STEP_TYPES } from './flow.ts';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import {
+  lensCapture,
+  lensVerify,
+  lensCaptureCatalogue,
+  lensApproveBaseline,
+  lensClearBaseline,
+  lensListRuns,
+  lensRunFlow,
+  lensRecord,
+  lensRunManuscript,
+  lensListFlowRuns,
+  type LensDeps,
+  promoteEvidence,
+  lensExport,
+} from './service.ts';
+
+const authSchema = {
+  type: 'object',
+  description:
+    'Optional auth pre-step. Secrets are read from the daemon env or a gitignored file by name/path — never the raw secret here. INHERITANCE IS FLOW/MANUSCRIPT ONLY: lens_run_flow and lens_run_manuscript take auth from the project lens.manifest.json when you pass local_path (they report auth.source "manifest"). lens_capture and lens_verify do NOT inherit — local_path only resolves RELATIVE paths inside an auth object you pass yourself. Omit auth on a capture of an authed page and you photograph the sign-in wall, which in viewport mode can still report pass. Pass auth explicitly there.',
+  properties: {
+    adapter: { type: 'string', enum: ['storageState', 'cookieJwt', 'mintEndpoint'] },
+    statePath: { type: 'string', description: 'storageState: path to a Playwright storageState JSON (relative → resolved against local_path/repo root). Preferred over stateEnv (no daemon restart).' },
+    stateEnv: { type: 'string', description: 'storageState: env var holding the storageState path/JSON (needs daemon restart to inject).' },
+    cookieName: { type: 'string' },
+    domain: { type: 'string' },
+    path: { type: 'string' },
+    tokenEnv: { type: 'string', description: 'cookieJwt: env var holding the token' },
+    url: { type: 'string', description: 'mintEndpoint: app endpoint that mints a short-lived storageState' },
+    method: { type: 'string' },
+    secretEnv: { type: 'string', description: 'mintEndpoint: env var with the bearer secret' },
+    secretPath: { type: 'string', description: 'mintEndpoint: gitignored file with the bearer secret (relative → repo root)' },
+    body: { type: 'object', description: 'mintEndpoint: optional JSON body for the POST mint call (e.g. {org, site}) so the endpoint mints a session for a SPECIFIC site on-demand, not a fixed env default. Validated by the endpoint; never a secret. Ignored for GET.' },
+  },
+} as const;
+
+// Declaring viewport as a typed object is the FIX: undeclared nested-object
+// params get stringified by the MCP harness → the daemon forwarded a string to
+// Playwright newContext ("expected object, got string" → capture hang).
+const viewportSchema = {
+  type: 'object',
+  description:
+    'Render viewport {width,height}, e.g. {"width":390,"height":844} for mobile. Default 1280×800.',
+  properties: {
+    width: { type: 'number' },
+    height: { type: 'number' },
+  },
+} as const;
+const deviceSchema = {
+  type: 'string',
+  description:
+    'Device preset (wins over viewport): iphone-15 | iphone-13 | iphone-15-pro-max | iphone-se | pixel-8 | ipad | mobile (390×844) | tablet | desktop.',
+} as const;
+// F098.9 — engine selection. Chromium-only Lens is BLIND to Safari/WebKit bugs
+// (it renders them fine → false GREEN). webkit/firefox close that gap.
+const engineSchema = {
+  type: 'string',
+  enum: ['chromium', 'webkit', 'firefox'],
+  description:
+    'Browser engine (default chromium). Use webkit to catch Safari-only bugs (backdrop-filter containing-block, -webkit quirks, 100vh/dvh, sticky) that chromium renders fine.',
+} as const;
+
+const localeSchema = {
+  type: 'string',
+  description:
+    'F074.57 — BCP-47 browser locale, e.g. "da-DK". Decides navigator.language, Accept-Language and every Intl/toLocaleString result (a Danish site otherwise photographs as 1,234.5 and 8/23/2026). Wins over the project lens.manifest.json "locale". OMITTED passes NOTHING to the browser, so an existing baseline cannot move.',
+} as const;
+const timezoneSchema = {
+  type: 'string',
+  description:
+    'F074.57 — IANA timezone, e.g. "Europe/Copenhagen". Omitted, the context inherits the HOST machine\'s zone, so the same page renders different dates on a Mac and on Cloud Lens. Declare it for machine-independent captures.',
+} as const;
+
+const reducedMotionSchema = {
+  type: 'string',
+  enum: ['reduce', 'no-preference'],
+  description:
+    "F074.59 — what this run reports for prefers-reduced-motion. DEFAULT 'reduce', which is what every Lens run has always done (we set it in F098.8 so a perpetual rAF loop cannot starve the page into a blank capture, and so pixel baselines are motion-stable) — omitting this cannot move an existing baseline. Pass 'no-preference' when you need the browser to actually ANIMATE: it is the only way expectAnimating can see anything, and it is how you prove a spinner/skeleton/loading indicator really moves rather than merely having a CSS rule. Pair it with a 'reduce' run over the same element to prove the reduced-motion branch really stops it.",
+} as const;
+
+const storageSchema = {
+  type: 'object',
+  description:
+    "F074.97 — localStorage/sessionStorage written BEFORE the first navigation, so the app's own FIRST RENDER already sees it. This is the only way to photograph a bug whose input is SAVED CLIENT STATE: a restored tab strip, a remembered filter, an unsent draft, a dismissed banner, a stale timestamp a prune reads. Shape: {\"local\":{\"key\":\"value\"},\"session\":{…}} — values are strings (a non-string is JSON-stringified, because the realistic payload is json). SCOPED TO THIS RUN'S OWN ORIGIN, derived from the url/base_url — you cannot name the origin, so a seed can never follow a redirect into a payment provider or a third-party iframe. OMITTED registers no init script at all, so an existing baseline cannot move. Writing after navigation would be the false green this exists to prevent: the app has already booted on an empty store, so the run photographs the DEFAULT state while reporting that it seeded the stale one.",
+  properties: {
+    local: { type: 'object', description: 'localStorage keys to write for this origin.' },
+    session: { type: 'object', description: 'sessionStorage keys to write for this origin.' },
+  },
+} as const;
+
+const captureProps = {
+  project: { type: 'string', description: 'Project slug — scopes all runs/baselines (required).' },
+  url: { type: 'string', description: 'Target URL (localhost dev-server or public).' },
+  mode: { type: 'string', enum: ['viewport', 'fullPage', 'element'] },
+  selector: { type: 'string', description: 'Required for element mode. Prefer [data-testid="…"].' },
+  waitFor: { description: 'Selector (string) or ms (number) to wait after navigation.' },
+  surface_key: { type: 'string', description: 'Stable name for this surface (groups runs).' },
+  extension: {
+    type: 'object',
+    description:
+      "F074.69 — load an UNPACKED browser extension and photograph its OWN pages. Point `path` at the built extension directory (the one holding manifest.json) and write the url as `extension://popup.html`; Lens substitutes the id Chromium generates at LOAD time, which a caller cannot know in advance and a manuscript must never hardcode. CHROMIUM ONLY — another engine is refused with a reason rather than failing oddly. Use this instead of serving dist/popup.html over http: the popup calls chrome.* on mount, throws where no extension APIs exist, and photographs blank or as a stub that LOOKS like the product — which on a store listing would be a fabricated screenshot. The response carries `extension.id`.",
+    properties: { path: { type: 'string', description: 'Absolute path to the unpacked extension build directory.' } },
+    required: ['path'],
+  },
+  viewport: viewportSchema,
+  device: deviceSchema,
+  engine: engineSchema,
+  locale: localeSchema,
+  timezone: timezoneSchema,
+  reduced_motion: reducedMotionSchema,
+  auth: authSchema,
+  storage: storageSchema,
+  critic: {
+    type: 'string',
+    enum: ['off', 'dom', 'vision', 'both'],
+    description:
+      'F126 composition critic: off (default) | dom (free geometry — overlap/occlusion/clipped/off-viewport/contrast) | vision (metered model judgement) | both. A high-severity finding folds status to fail (blocks Review→Done). The F095 gate sets this from the project\'s composition_critic.vision setting.',
+  },
+  critic_vision_model: {
+    type: 'string',
+    description: 'Catalog key for the critic vision pass: mistral-large (default, EU/GDPR-safe) | mistral-small (EU, cheapest) | haiku (US, sharp) | sonnet (US, sharpest). An unarmed key falls back to the cheapest available. The gate sets it from the project\'s composition_critic.vision_model setting; GET 127.0.0.1:7475/lens/vision-models lists the catalog + availability.',
+  },
+  scale: {
+    type: 'number',
+    description:
+      'Device pixel ratio for the screenshot (deviceScaleFactor). Default 1. Use 2 or 3 for retina / App-Store-quality shots — a 390×844 viewport at scale 2 renders a 780×1688-px image. Also sharpens pixel-diff baselines. (F252.1)',
+  },
+} as const;
+
+export const TOOLS = [
+  {
+    name: 'lens_capture',
+    description:
+      'Screenshot a surface (viewport / fullPage / element-via-[data-testid]) and record the run. Returns screenshot_url + run_id. Scoped to the given project.',
+    inputSchema: { type: 'object', required: ['project', 'url'], properties: captureProps },
+  },
+  {
+    name: 'lens_verify',
+    description:
+      'Verify a surface: capture + optional pixel-diff vs an approved baseline (by baseline_key) + optional assert.js DOM measurement. Returns status (pass/fail/no-baseline/error) + screenshot/diff URLs. The visual half of an AC gate.',
+    inputSchema: {
+      type: 'object',
+      required: ['project', 'url'],
+      properties: {
+        ...captureProps,
+        assert: { type: 'string', description: 'JS body run in the page; return boolean or {pass, detail}.' },
+        baseline_key: { type: 'string', description: 'Diff against the approved baseline for this key (auto-loaded).' },
+        diff_threshold: { type: 'number', description: 'Pass if diffRatio < threshold. Default 0.01.' },
+        video: {
+          type: 'object',
+          description:
+            'Video-liveness: drive a <video> and assert it actually PLAYS (currentTime advances + frames move + no MediaError) — presence/pixel-diff can\'t see playback. A not-playing verdict fails the verify. Returns a `video` block (playing, readyState, advancedSec, errorCode, frameMotionRatio, …). Audio is reported, never the verdict.',
+          properties: {
+            selector: { type: 'string', description: '[data-testid]/CSS of the <video> or a container holding one. Omit → first <video>.' },
+            playMs: { type: 'number', description: 'How long to let it play before re-sampling (ms). Default 1200.' },
+            requireMotion: { type: 'boolean', description: 'Require visible frame motion (default true) — catches a frozen/poster video whose time still ticks.' },
+          },
+        },
+      },
+    },
+  },
+  {
+    name: 'lens_approve_baseline',
+    description: 'Promote a run\'s screenshot to the approved baseline for its surface. Future verifies diff against it.',
+    inputSchema: {
+      type: 'object',
+      required: ['project', 'run_id'],
+      properties: {
+        project: { type: 'string' },
+        run_id: { type: 'string' },
+        baseline_key: { type: 'string', description: 'Defaults to the run\'s surface_key.' },
+      },
+    },
+  },
+  {
+    name: 'lens_capture_catalogue',
+    description:
+      'Verify a batch of surfaces against one base_url in a single call. Returns a per-surface verdict + aggregate pass/fail. Feed it a project\'s lens.manifest.json surfaces.',
+    inputSchema: {
+      type: 'object',
+      required: ['project', 'base_url', 'surfaces'],
+      properties: {
+        project: { type: 'string' },
+        base_url: { type: 'string' },
+        auth: authSchema,
+        diff_threshold: { type: 'number' },
+        surfaces: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['name', 'path'],
+            properties: {
+              name: { type: 'string' },
+              path: { type: 'string' },
+              mode: { type: 'string', enum: ['viewport', 'fullPage', 'element'] },
+              selector: { type: 'string' },
+              waitFor: {},
+              assert: { type: 'string' },
+              baseline_key: { type: 'string' },
+              viewport: viewportSchema,
+              device: deviceSchema,
+              engine: engineSchema,
+              locale: localeSchema,
+              timezone: timezoneSchema,
+              reduced_motion: reducedMotionSchema,
+              no_diff: { type: 'boolean', description: 'Smoke-only: never pixel-diff (live-data dashboards). Verify on render + anchor + assert.' },
+            },
+          },
+        },
+      },
+    },
+  },
+  {
+    name: 'lens_clear_baseline',
+    description: 'Unapprove a baseline: drop it so its surface returns to no-baseline (smoke), stopping the pixel-diff. Use when a live-data surface (a dashboard with changing counts/timestamps) was approved and now drifts to a false RED.',
+    inputSchema: {
+      type: 'object',
+      required: ['project', 'baseline_key'],
+      properties: {
+        project: { type: 'string' },
+        baseline_key: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'lens_list_runs',
+    description: 'List recent Lens runs for a project (most recent first), optionally filtered by status or surface_key.',
+    inputSchema: {
+      type: 'object',
+      required: ['project'],
+      properties: {
+        project: { type: 'string' },
+        status: { type: 'string', enum: ['pass', 'fail', 'no-baseline', 'error'] },
+        surface_key: { type: 'string' },
+        limit: { type: 'number' },
+      },
+    },
+  },
+  {
+    name: 'lens_record',
+    description:
+      'RECORD a surface for N seconds and measure what MOVED — for a defect that only exists in motion, which a screenshot cannot show. Returns the video AND the probe: defect_count (a move nobody caused THAT THE READER COULD SEE), every finding classified, plus detector_alive and exercise. READ THOSE TWO FIRST: zero findings from a blind probe and zero from a working product are the same number, and detector_alive/exercise are the only things that tell them apart — a run with exercise.exercised false is NO RESULT, not a pass. LOCAL ONLY: the daemon owns the browser, so this needs a running cardmem daemon; Cloud Lens has no recorder. Steps are optional on purpose — the reproduction for "it jumps and I did not touch it" is to open it and sit still.',
+    inputSchema: {
+      type: 'object',
+      required: ['project', 'url', 'seconds'],
+      properties: {
+        project: { type: 'string', description: 'Project slug — scopes the run.' },
+        url: { type: 'string', description: 'The surface to watch (localhost dev-server or public URL).' },
+        seconds: { type: 'number', description: 'How long to record. A motion defect needs a window it can occur in — 30–120s is typical, not 3.' },
+        selector: { type: 'string', description: 'The scrolling container to watch. Prefer [data-testid]. Omit → the page.' },
+        row_attr: {
+          type: 'string',
+          description:
+            'Attribute identifying the repeated ROWS inside the container (e.g. data-msg-id). It is what lets the probe say how far the PICTURE moved rather than how far scrollTop moved — different quantities, and conflating them reports correct behaviour as a defect.',
+        },
+        viewport: {
+          type: 'object',
+          description: 'Render viewport, e.g. {"width":390,"height":844}. Default 1280x800.',
+          properties: { width: { type: 'number' }, height: { type: 'number' } },
+        },
+        reduced_motion: {
+          type: 'string',
+          description: "'reduce' (default) or 'no-preference'. Pass no-preference when the thing you are recording IS an animation.",
+        },
+        scroll_up_px: {
+          type: 'number',
+          description:
+            'Scroll UP this far before watching. Load-bearing for a chat/feed: at the bottom, being dragged along by new content is CORRECT, so a run that stays there measures the one place the defect cannot exist.',
+        },
+        clicks: {
+          type: 'array',
+          description: 'Press controls DURING the recording, in order. Each press is reported with pressed true/false — a run that never exercised its own scenario must not read as a clean result.',
+          items: {
+            type: 'object',
+            properties: { testid: { type: 'string' }, at_ms: { type: 'number' } },
+          },
+        },
+        interval_ms: { type: 'number', description: 'Probe sampling interval. Default ~50ms.' },
+        min_delta_px: { type: 'number', description: 'Ignore moves smaller than this. Default 2.' },
+        fps: { type: 'number', description: 'Frames cut from the video for the timeline. 0 disables stills.' },
+        burst_fps: { type: 'number', description: 'Dense frames cut around each finding, so a jump can be read frame by frame.' },
+        local_path: { type: 'string', description: "Repo root — used to inherit the project's lens.manifest.json auth when `auth` is omitted." },
+        auth: {
+          type: 'object',
+          description: 'Auth pre-step, same adapters as lens_capture (storageState / cookieJwt / mintEndpoint). Omit on an authed page and you record the sign-in wall.',
+          properties: {
+            adapter: { type: 'string' },
+            statePath: { type: 'string' },
+            stateEnv: { type: 'string' },
+            tokenEnv: { type: 'string' },
+            cookieName: { type: 'string' },
+            domain: { type: 'string' },
+            url: { type: 'string' },
+            method: { type: 'string' },
+            secretEnv: { type: 'string' },
+            secretPath: { type: 'string' },
+            body: { type: 'object' },
+          },
+        },
+      },
+    },
+  },
+  {
+    name: 'lens_run_flow',
+    description:
+      // F074.55 — the verb list is INTERPOLATED from the parser's own vocabulary.
+      // A hand-written list in a tool description is the only thing most callers
+      // ever read, and ours had drifted to 9 of 26: three repos reported an
+      // existing verb as missing because of it.
+      `Run an E2E manuscript flow: drive a site step-by-step in one authed page. Steps (${[...STEP_TYPES].length}): ${[...STEP_TYPES].join(' / ')}. testid-anchored steps use [data-testid]; fillSelector/clickSelector use a raw CSS selector + optional cross-origin frame chain to reach a 3rd-party iframe a testid can\'t (e.g. Stripe PCI card fields), and waitForUrl asserts the redirect back to our origin. Stops + pins a screenshot on the first failing step. Returns a per-step report with screenshot_url per step. This is full End-to-End — it can create users, submit forms, complete a Stripe test payment, etc. (set mutates:true for write flows). Scoped to the project slug.`,
+    inputSchema: {
+      type: 'object',
+      required: ['project', 'flow'],
+      properties: {
+        project: { type: 'string', description: 'Project slug — scopes the flow run.' },
+        from: { type: 'number', description: 'Resume: skip flattened steps before this index (re-run a bulk flow from where it left off).' },
+        local_path: { type: 'string', description: 'Repo root. Resolves a relative auth statePath AND inherits the project lens.manifest.json auth when the flow has none — so authed routes work (not just /lens/gate).' },
+        viewport: viewportSchema,
+        device: deviceSchema,
+        engine: engineSchema,
+        locale: localeSchema,
+        timezone: timezoneSchema,
+        reduced_motion: reducedMotionSchema,
+        storage: storageSchema,
+        critic: {
+          type: 'string',
+          enum: ['off', 'dom', 'vision', 'both'],
+          description:
+            'F126 composition critic on each screenshot step: off (default) | dom (free geometry) | vision (metered) | both. A high-severity finding fails that step (and the flow).',
+        },
+        record: {
+          type: 'boolean',
+          description:
+            'F255.5 — record the whole driven run as a .webm and return it as video_url (alongside the per-step screenshots). Off by default. Kept even when the flow fails, which is when watching it matters most.',
+        },
+        flow: {
+          type: 'object',
+          required: ['name', 'base_url', 'steps'],
+          properties: {
+            name: { type: 'string' },
+            base_url: { type: 'string', description: 'http(s) prefix; goto paths resolve against it.' },
+            mutates: { type: 'boolean', description: 'true when the flow creates/changes data.' },
+            wait_for_build: {
+              type: ['string', 'boolean'],
+              description:
+                'F255.7 — do not start until the app is serving the build under test. A commit sha waits for THAT build; true waits for any change from the build live at run start. Polls GET /api/health for a `build` field (the fleet contract), from the runner with no-store, requiring 3 consecutive matching reads so a fleet mid-rollout cannot end the wait early. Fails loudly if the app exposes no marker. Use it right after a deploy — otherwise a green run may be verifying the build you just replaced.',
+            },
+            auth: authSchema,
+            steps: {
+              type: 'array',
+              description: 'Ordered steps. Each has a "type"; testid-anchored steps carry a "testid". fillSelector/clickSelector carry a CSS "selector" + optional "frame" (one iframe selector or an outer→inner string[] chain) to reach a cross-origin iframe; fillSelector also carries "value". waitForUrl carries a "url" substring. A "loop" step has data[] + steps[] and substitutes {{field}}/{{__index}}.',
+              items: { type: 'object', required: ['type'], properties: { type: { type: 'string' }, testid: { type: 'string' }, selector: { type: 'string' }, frame: { type: ['string', 'array'], items: { type: 'string' } }, url: { type: 'string' }, value: { type: 'string' }, text: { type: 'string' }, path: { type: 'string' }, js: { type: 'string' }, label: { type: 'string' }, timeout: { type: 'number' }, sha: { type: 'string', description: 'F255.7 — waitForBuild step: the commit sha to wait for. Omit to wait for any change from the build live when the step starts.' }, at: { type: 'string', description: 'F255.4 — click a POINT inside the element instead of its centre: "50%,28%" (fraction of the box) or "40,120" (css px). For canvas/3D surfaces where the centre hits nothing. Works on click + clickSelector.' }, activate: { type: 'string', enum: ['auto', 'click', 'enter'], description: 'F255.1 — how a button is fired. auto (default) clicks and falls back to focus+Enter only if nothing observable happened; enter forces focus+Enter (Angular/MDC forms); click keeps mouse-only.' } } },
+            },
+          },
+        },
+      },
+    },
+  },
+  {
+    name: 'lens_run_manuscript',
+    description:
+      `Compile a human-readable markdown manuscript (fmc-automation style: "# flow: name", "base: <url>", then one "- <verb> …" per line) into a flow and run it E2E. VERBS (${MANUSCRIPT_VERBS.length}, this is the complete list): ${MANUSCRIPT_VERBS.join(' / ')}. Shapes: "- goto /x" · "- fill [testid] = value" · "- click [testid]" · "- press Enter" (global) or "- press Enter [testid]" (on a focused element) · "- expectText [testid] ~ text" · "- drag [source] -> [target]" · "- upload [input-testid] = <fixture>" · "- assert: <js>" · "- screenshot label" · frame-aware "- fillSelector <css> = <value> @frame <iframe>" and "- clickSelector <css> @frame <iframe>" · "- waitForUrl <substring>". Click modifiers: "- click [testid] via enter" (F255.1, for Angular/MDC buttons a mouse click does not activate) and "- click [testid] @ 50%,28%" (F255.4, aim at a point inside a canvas/3D surface). A field that already HOLDS a value may no longer render an input — a combobox typically swaps to its selected state, so "fill" times out there while "press ArrowDown" / "press Enter" still drive it (fd-sundhed, 2026-08-21). The authoring shortcut — write prose, not JSON.`,
+    inputSchema: {
+      type: 'object',
+      required: ['project', 'manuscript'],
+      properties: {
+        project: { type: 'string' },
+        manuscript: { type: 'string', description: 'The markdown manuscript text.' },
+        auth: authSchema,
+        local_path: { type: 'string', description: 'Repo root. Resolves a relative auth statePath AND inherits the project lens.manifest.json auth when none is passed. The run always REPORTS what it used as `auth: {source, adapter, note}` — source "none" carries the reason, so an unauthenticated run is never something you have to infer from a confusing failure (F074.36).' },
+        viewport: viewportSchema,
+        device: deviceSchema,
+        engine: engineSchema,
+        locale: localeSchema,
+        timezone: timezoneSchema,
+        reduced_motion: reducedMotionSchema,
+        storage: storageSchema,
+        record: {
+          type: 'boolean',
+          description: 'F255.5 — record the whole driven run as a .webm and return it as video_url. Off by default.',
+        },
+      },
+    },
+  },
+  {
+    name: 'lens_list_flow_runs',
+    description: 'List recent E2E flow runs for a project (most recent first), optionally filtered by flow_name or status (pass/fail/error).',
+    inputSchema: {
+      type: 'object',
+      required: ['project'],
+      properties: {
+        project: { type: 'string' },
+        flow_name: { type: 'string' },
+        status: { type: 'string', enum: ['pass', 'fail', 'error'] },
+        limit: { type: 'number' },
+      },
+    },
+  },
+  {
+    name: 'lens_promote_evidence',
+    description:
+      "F272.2/F074.68 — Copy a Lens run's screenshots into the project's DURABLE artifact store, and return the evidence line to cite. Works for a FLOW run (flow_run_id) and for a plain CAPTURE run (run_id from lens_capture / lens_verify) — pass exactly one. Use this before citing a Lens run as proof for an acceptance criterion: a run's stills live on the daemon machine's disk behind 127.0.0.1, so the owner cannot open them and a disk wipe removes them silently while the AC still reads as proven. The promoted /api/artifacts/<id>/raw urls are the ONLY form cardmem_record_review can verify server-side — a run id alone can at best be judged 'unknown'. A capture that also has a baseline diff promotes BOTH, each named in the result (screenshot / diff) rather than left to a count. Bytes go daemon → cloud directly; they never pass through your context.",
+    inputSchema: {
+      type: 'object',
+      required: ['project'],
+      properties: {
+        project: { type: 'string', description: 'Project slug the run belongs to.' },
+        flow_run_id: { type: 'string', description: 'The flow_run_id from lens_run_flow / lens_list_flow_runs. Exactly one of flow_run_id / run_id.' },
+        run_id: { type: 'string', description: 'The run_id from lens_capture / lens_verify. Exactly one of flow_run_id / run_id.' },
+        step_indexes: {
+          type: 'array',
+          items: { type: 'number' },
+          description: 'Optional subset of step indexes. Omit to promote every step that HAS a screenshot.',
+        },
+      },
+    },
+  },
+  {
+    name: 'lens_export',
+    description:
+      "F074.63 — Render a URL to a VECTOR PDF, where text stays text. Use this for anything a HUMAN outside the fleet must be able to EDIT or PRINT: customer print material, a flyer, an A3 poster, a spec handed to a graphic designer. It is NOT the tool for verification — screenshots are still lens_capture/lens_verify. The difference from stitching lens_capture PNGs into a PDF is the whole point: that produces a picture of a document (one linked image, zero text objects in Illustrator) and no resolution is high enough to fix it, because the daemon's pixel limit caps A3 at ~257 DPI against a 300 DPI print spec. A vector PDF has no resolution at all. The response carries `editable_text` and a `content` block (text runs / fonts / images) measured FROM THE PRODUCED BYTES — check `editable_text: true` before you hand the file to anyone, because 'a PDF came back' is exactly the green a bitmap already passes. Chromium only. For SVG the response also carries `unsupported` (gradients, transforms, shadows — NAMED, never faked into a flat fill) and `lint.outOfBounds` (SVG has no line wrapping, so text wider than the sheet is otherwise discovered at the printer; measured on BOTH axes, because a guard that measures one is green on half the faults it is about).",
+    inputSchema: {
+      type: 'object',
+      required: ['project', 'url'],
+      properties: {
+        project: { type: 'string' },
+        url: { type: 'string' },
+        format: {
+          type: 'string',
+          enum: ['pdf', 'svg'],
+          description: "'pdf' (default) — a printable document. 'svg' (F074.64) — the file a DESIGNER edits: read from the LIVE DOM, so a heading is ONE <text> object with a named font, not 109 letter-positions, and the units are MILLIMETRES (viewBox 0 0 297 420 for A3). Use svg for anything going to a graphic designer, pdf for anything going to a printer. The svg response carries `unsupported` (what could not be represented, named rather than faked) and `lint.outOfBounds` (SVG does not wrap, so text wider than the sheet is only discovered at the printer unless something measures it).",
+        },
+        page_size: {
+          type: 'string',
+          description: "Paper size: 'A4' (default), 'A3', 'Letter', … Combine with landscape for an A3 poster.",
+        },
+        landscape: { type: 'boolean', description: 'Rotate the paper. Default false.' },
+        print_background: {
+          type: 'boolean',
+          description: 'Default TRUE — deliberately against the browser default of false. With it off, every background colour and image disappears and a poster comes out WHITE while the export still reports success. Only pass false if you actually want ink-saving output.',
+        },
+        margin: {
+          type: 'object',
+          description: "Page margins, e.g. { top: '0', right: '0', bottom: '0', left: '0' } for a full-bleed poster. CSS units.",
+          properties: {
+            top: { type: 'string' },
+            right: { type: 'string' },
+            bottom: { type: 'string' },
+            left: { type: 'string' },
+          },
+        },
+        media: {
+          type: 'string',
+          enum: ['screen', 'print'],
+          description: "Which CSS media to render. Default 'screen', deliberately against the browser default of 'print': a page designed for screen can lose its whole layout to an @media print rule, and NOTHING errors — you just get a confident, wrong PDF. Pass 'print' only when the page has a print stylesheet you want.",
+        },
+        selector: {
+          type: 'string',
+          description: "SVG ONLY (F074.64) — export ONE surface, e.g. '[data-testid=\"flade-a3-plakat\"]'. A print job is ONE SHEET and a mockup document usually holds several: measured on fd-sundhed's material, omitting this gave the whole documentation page (158 text blocks, 795mm tall) instead of the A3 poster (7 text blocks). Ignored by format:'pdf', which has no element mode.",
+        },
+        selector_index: {
+          type: 'number',
+          description: 'Which match to take when `selector` hits several — a bifold folder has two sheets under one class. Default 0. The error names how many DO match, because "matched nothing" and "matched 2, you asked for 5" need different fixes.',
+        },
+        engine: engineSchema,
+        viewport: viewportSchema,
+        device: deviceSchema,
+        scale: { type: 'number', description: 'Device pixel ratio while rendering. Affects raster images inside the page; the text stays vector regardless.' },
+        waitUntil: { type: 'string', enum: ['load', 'domcontentloaded', 'commit'] },
+        waitFor: { description: 'CSS selector or ms to wait before exporting.' },
+        auth: authSchema,
+        timeout_ms: { type: 'number' },
+        expect_text: {
+          type: 'array',
+          items: { type: 'string' },
+          description: "Strings you expect to find AS TEXT in the result. Answered as `text_found: {\"…\": true|false}` — checked on the produced bytes, whitespace-insensitively (a PDF stores no space where the page broke a line). This is how you PROVE a headline survived as editable text instead of becoming part of a picture. The extracted text itself is never returned: a poster's worth of it is thousands of tokens you cannot use.",
+        },
+      },
+    },
+  },
+] as const;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function dispatch(deps: LensDeps, name: string, args: any): Promise<unknown> {
+  switch (name) {
+    case 'lens_capture':
+      return lensCapture(deps, args);
+    case 'lens_verify':
+      return lensVerify(deps, args);
+    case 'lens_approve_baseline':
+      return lensApproveBaseline(deps, args);
+    case 'lens_clear_baseline':
+      return lensClearBaseline(deps, args);
+    case 'lens_capture_catalogue':
+      return lensCaptureCatalogue(deps, args);
+    case 'lens_list_runs':
+      return lensListRuns(deps, args);
+    case 'lens_record':
+      return lensRecord(deps, args);
+    case 'lens_run_flow':
+      return lensRunFlow(deps, args);
+    case 'lens_run_manuscript':
+      return lensRunManuscript(deps, args);
+    case 'lens_list_flow_runs':
+      return lensListFlowRuns(deps, args);
+    case 'lens_promote_evidence':
+      return promoteEvidence(deps, args);
+    case 'lens_export':
+      return lensExport(deps, args);
+    default:
+      throw new Error(`unknown tool: ${name}`);
+  }
+}
+
+export function createLensMcpRouter(deps: LensDeps): Hono {
+  const router = new Hono();
+  router.all('/', async (c) => {
+    const server = new Server(
+      { name: 'cardmem-lens', version: '0.1.0' },
+      {
+        capabilities: { tools: {} },
+        instructions:
+          'Lens is the cardmem daemon\'s visual-verification engine. Call lens_verify against a localhost dev-server (or public URL) to confirm a surface looks + behaves right before a card moves to Done. Capture-by-[data-testid] is the preferred, stable mode. All runs/baselines are scoped to the project slug you pass.',
+      },
+    );
+
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: TOOLS as unknown as Array<{ name: string; description: string; inputSchema: object }>,
+    }));
+
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+      try {
+        const result = await dispatch(deps, req.params.name, req.params.arguments ?? {});
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    });
+
+    const transport = new WebStandardStreamableHTTPServerTransport();
+    await server.connect(transport);
+    return transport.handleRequest(c.req.raw);
+  });
+  return router;
+}