@lowdefy/server-dev 6.0.0 → 7.0.0

package/lib/docs/createDocsMcpServer.js

@@ -15,51 +15,63 @@
 */
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { z } from 'zod';
+import { createTraceId, type } from '@lowdefy/helpers';
+import { validateJourneyUser } from '@lowdefy/node-utils';
 
 import checkpointToMocks from './checkpointToMocks.js';
 import createConfigCheckpoint from './createConfigCheckpoint.js';
+import { subscribe as subscribeToDevEvents } from './devEventBus.js';
 import evalOperator from './evalOperator.js';
 import findConfig from './findConfig.js';
 import getAppMap from './getAppMap.js';
 import getBuildStatus from './getBuildStatus.js';
-import getCoreDoc from './getCoreDoc.js';
+import getBuildStatusAfterEdits from './getBuildStatusAfterEdits.js';
+import readJourneySession from './readJourneySession.js';
+import readProxyBuildWait from './readProxyBuildWait.js';
+import getDoc from './getDoc.js';
 import getExamples from './getExamples.js';
 import getOverview from './getOverview.js';
 import getPageConfig from './getPageConfig.js';
 import getPluginDoc from './getPluginDoc.js';
 import getSchema from './getSchema.js';
+import getStaleStatus from './getStaleStatus.js';
 import inspectState from './inspectState.js';
 import listConfigCheckpoints from './listConfigCheckpoints.js';
 import listPlugins from './listPlugins.js';
 import listTypes from './listTypes.js';
 import loadState from './loadState.js';
 import revertConfigCheckpoint from './revertConfigCheckpoint.js';
+import requestRestart from './requestRestart.js';
+import runCheck from './runCheck.js';
+import runEndpoint from './runEndpoint.js';
+import runJourney from './runJourney.js';
+import runJourneyAsUsers from './runJourneyAsUsers.js';
+import selectExercised from './selectExercised.js';
 import runRequest from './runRequest.js';
 import snapshotState from './snapshotState.js';
 import { listStateCheckpoints } from './checkpointStore.js';
 import createLogger from '../server/log/createLogger.js';
+import lowdefyConfig from '../build/config.js';
+import devToolDefinitions, { INSTRUCTIONS } from './devToolDefinitions.js';
 import scaffoldPage from './scaffoldPage.js';
 import screenshotPage from './screenshotPage.js';
 import searchDocs from './searchDocs.js';
+import searchIcons from './searchIcons.js';
 
 const logger = createLogger({ server: 'lowdefy-dev-mcp' });
 
-const INSTRUCTIONS = `Lowdefy documentation and feedback server for this project. Lowdefy apps are YAML config composing blocks (UI), operators (logic), actions (event handlers), and connections/requests (data).
-
-Discovery workflow: start with lowdefy_overview. Use lowdefy_list_types with a kind to discover ALL installed blocks/operators/actions/connections/requests — never guess type names. Then lowdefy_get_schema and lowdefy_get_examples for the exact contract of a type, and lowdefy_get_doc / lowdefy_search_docs for concept documentation. lowdefy_list_plugins and lowdefy_get_plugin_doc cover this project's local plugin packages.
-
-Feedback loop: after EVERY config edit, call lowdefy_build_status — the dev server rebuilds on file change and this returns the current build errors/warnings (with source file locations) plus recent browser runtime errors. Fix what it reports, then confirm the page builds with lowdefy_get_page_config, and visually verify with lowdefy_screenshot_page. Use lowdefy_find_config to locate where any id (page, block, request) is defined. lowdefy_scaffold_page creates a canonical new page file. Use lowdefy_app_map first to understand an existing app.
-
-Live state: lowdefy_inspect_state reads the ACTUAL state, request results, and event log of a running page — when the developer has the page open in their browser it reads THEIR live tab (ask them to interact, then inspect), otherwise it runs the page headless. lowdefy_eval_operator evaluates any operator expression against that live state — use it to debug _state/_request bindings. lowdefy_run_request executes a request with a test payload to verify data shape (read-only unless the app opts into writes).
-
-Role-gated pages: the headless renderer signs in as a roleless user, so a page or request gated on a role renders empty or refused. Pass user to lowdefy_screenshot_page, lowdefy_inspect_state, lowdefy_eval_operator or lowdefy_load_state to act as a specific caller — e.g. user {"roles":["admin"]} — and vary it per call to compare what different roles see.
-
-Safety: lowdefy_checkpoint snapshots the config files before risky multi-file changes; lowdefy_revert_checkpoint restores them.
-
-Visual feedback: developers can press Cmd/Ctrl+/ in the running app to point at elements, draw, and copy annotated feedback to their clipboard, then paste it to you. Pasted annotation blocks start with "Feedback:" and carry the blockId, the resolved config file:line, drawn shapes, and usually an "Annotated screenshot:" file path — READ that image to see exactly what the developer drew. Treat them as precise UI feedback and use lowdefy_inspect_state for the page's live state.
-
-State checkpoints (testing): lowdefy_snapshot_state captures a page's live state AND its request/api responses into .lowdefy/state-checkpoints/<name>/ (one file per part; gitignored — checkpoints contain user/session data). lowdefy_load_state puts the app back into that state: headless for your own verification, or registry-only which returns a ?_checkpoint URL the developer can open to manually test the app in that exact state (recorded request data is served automatically). lowdefy_checkpoint_to_mocks converts a checkpoint into e2e mocks.yaml fixtures — use it when asked to write e2e tests.`;
+// get_doc returns markdown rather than JSON, so hazards resolved for the
+// requested type are appended as a section instead of a sibling key.
+function appendHazards(doc) {
+  if (type.isNone(doc.hazards) || doc.hazards.length === 0) {
+    return doc.markdown;
+  }
+  const lines = doc.hazards.map((hazard) => {
+    const see = type.isNone(hazard.see) ? '' : ` (see \`${hazard.see}\`)`;
+    return `- **${hazard.id}**: ${hazard.message}${see}`;
+  });
+  return `${doc.markdown}\n\n## Hazards\n\n${lines.join('\n')}\n`;
+}
 
 function textResult(value) {
   const text = typeof value === 'string' ? value : JSON.stringify(value, null, 2);
@@ -70,76 +82,74 @@ function notFoundResult(message) {
   return { content: [{ type: 'text', text: message }], isError: true };
 }
 
-// Shared by every tool that renders a page headless, so one call can act as an
-// admin and the next as a plain member — each headless call gets its own browser
-// context, so they never share an identity.
-const userSchema = z
-  .object({})
-  .passthrough()
-  .optional()
-  .describe(
-    'Act as this caller instead of the default roleless headless user, e.g. {"roles":["user-admin"]} to render a role-gated page. Merged over the default, so include email/profile/attributes fields too if the page reads them — no auth engine runs for an injected caller, so nothing derives them. Headless only: it is never applied to a page the developer opens in their own browser, so combining it with source "tab" or load_state mode "registry-only" is an error rather than a silently dropped role.'
-  );
-
-function createDocsMcpServer({ origin, honoContext } = {}) {
+function createDocsMcpServer({ origin, honoContext, version } = {}) {
   const server = new McpServer(
-    { name: 'lowdefy-docs', version: '1.0.0' },
-    { instructions: INSTRUCTIONS }
+    { name: 'lowdefy', version },
+    { capabilities: { logging: {} }, instructions: INSTRUCTIONS }
   );
 
-  // Debug-log every tool call (name + args, never the response) so agent
-  // activity is visible in the dev terminal with --log-level=debug. Wrapping
-  // registerTool here covers all tools without touching each registration.
-  const registerTool = server.registerTool.bind(server);
-  server.registerTool = (name, definition, handler) =>
-    registerTool(name, definition, async (args, extra) => {
+  // Every tool's contract comes from devToolDefinitions, which the stdio shim
+  // also lists, so a tool registered here without a definition - or a
+  // definition left without a handler - would make the two disagree.
+  // registerDevTool looks the definition up, and the check after the last
+  // registration fails the server if any definition was missed.
+  //
+  // It also debug-logs every tool call (name + args, never the response) so
+  // agent activity is visible in the dev terminal with --log-level=debug.
+  const registered = new Set();
+  function registerDevTool(name, handler) {
+    const definition = devToolDefinitions[name];
+    if (definition === undefined) {
+      throw new Error(`Dev tool "${name}" has no entry in devToolDefinitions.`);
+    }
+    registered.add(name);
+    server.registerTool(name, definition, async (args, extra) => {
       try {
         logger.debug({ event: 'mcp_tool_call', tool: name, args }, `MCP tool call: ${name}`);
       } catch {
         // Logging must never break a tool call.
       }
-      return handler(args, extra);
+      const result = await handler(args, extra);
+      try {
+        const stale = getStaleStatus();
+        // Prepended rather than merged so it covers textResult, notFoundResult
+        // and any future result shape without parsing the tool's own payload.
+        if (stale && Array.isArray(result?.content)) {
+          result.content.unshift({
+            type: 'text',
+            text: `STALE: ${stale.staleReason} ${JSON.stringify({
+              stale: true,
+              staleSince: stale.staleSince,
+            })}`,
+          });
+        }
+      } catch {
+        // A missing or half-written artifact must never break a tool call.
+      }
+      return result;
     });
+  }
 
-  server.registerTool(
-    'lowdefy_inspect_state',
-    {
-      description:
-        "Read the LIVE state of a running page: state, request results, event log (recent actions fired), global, user, input, and urlQuery. If the developer has the page open in a browser it reads their actual tab (ask them to interact first, then inspect); otherwise it runs the page headless. Use this to see what the app's data model really looks like.",
-      inputSchema: {
-        pageId: z.string().describe('The page id to inspect.'),
-        source: z
-          .enum(['tab', 'headless'])
-          .optional()
-          .describe('Force a source. Default: live tab if connected, else headless.'),
-        user: userSchema,
-      },
-    },
-    async ({ pageId, source, user }) => {
-      const result = await inspectState({ origin, pageId, source, user });
-      if (result.error) {
-        return notFoundResult(result.error);
-      }
-      return textResult(result);
+  registerDevTool('lowdefy_inspect_state', async ({ pageId, pathParams, source, user, data }) => {
+    const result = await inspectState({ origin, pageId, pathParams, source, user, data });
+    if (result.error) {
+      return notFoundResult(result.error);
     }
-  );
+    return textResult(result);
+  });
 
-  server.registerTool(
+  registerDevTool(
     'lowdefy_eval_operator',
-    {
-      description:
-        'Evaluate a Lowdefy operator expression against the live state of a running page — a REPL for config. Pass the operator object in the "expression" argument — any JSON value, e.g. {"_state": "customer.name"} or {"_if": {...}}. Evaluates in the real browser runtime (live tab if connected, else headless).',
-      inputSchema: {
-        pageId: z.string().describe('The page id whose context to evaluate against.'),
-        expression: z
-          .any()
-          .describe('The operator expression — any JSON value, e.g. {"_state": "key"}.'),
-        source: z.enum(['tab', 'headless']).optional(),
-        user: userSchema,
-      },
-    },
-    async ({ pageId, expression, source, user }) => {
-      const result = await evalOperator({ origin, pageId, expression, source, user });
+    async ({ pageId, pathParams, expression, source, user, data }) => {
+      const result = await evalOperator({
+        origin,
+        pageId,
+        pathParams,
+        expression,
+        source,
+        user,
+        data,
+      });
       if (result.error) {
         return notFoundResult(result.error);
       }
@@ -147,46 +157,43 @@ function createDocsMcpServer({ origin, honoContext } = {}) {
     }
   );
 
-  server.registerTool(
+  registerDevTool(
     'lowdefy_run_request',
-    {
-      description:
-        'Execute a request in dev with a test payload to verify the data shape a page receives. Read-only request types always run; write requests are refused unless the app opts in (cli.agentTools.allowWriteRequests in lowdefy.yaml).',
-      inputSchema: {
-        pageId: z.string().describe('The page the request is defined on.'),
-        requestId: z.string().describe('The request id.'),
-        payload: z.record(z.any()).optional().describe('Test payload for _payload operators.'),
-      },
-    },
-    async ({ pageId, requestId, payload }) =>
-      textResult(await runRequest({ pageId, requestId, payload, honoContext }))
+    async ({ pageId, requestId, payload, user, data, saveResponse }) =>
+      textResult(
+        await runRequest({ pageId, requestId, payload, user, data, saveResponse, honoContext })
+      )
+  );
+
+  registerDevTool(
+    'lowdefy_run_endpoint',
+    async ({ endpointId, payload, user, data, system, saveResponse }) =>
+      textResult(
+        await runEndpoint({ endpointId, payload, user, data, system, saveResponse, honoContext })
+      )
   );
 
-  server.registerTool(
-    'lowdefy_app_map',
-    {
-      description:
-        'The whole-app graph in one call: every page (with its source file and, when built, block/request summaries), menus, connections, api endpoints, agents, and websockets. Call this first when working in an existing app.',
-      inputSchema: {},
-    },
-    () => textResult(getAppMap())
+  registerDevTool('lowdefy_restart', ({ reason }) =>
+    textResult({
+      ...requestRestart({ reason }),
+      note: 'The dev server is restarting. Call GET /lowdefy-docs/build-status?wait=true (lowdefy_build_status with wait: true) before your next call; it answers once the server is back.',
+    })
   );
 
-  server.registerTool(
+  registerDevTool('lowdefy_app_map', () => textResult(getAppMap()));
+
+  registerDevTool(
     'lowdefy_snapshot_state',
-    {
-      description:
-        "Capture the live state AND recorded request/api responses of a running page into a checkpoint folder (.lowdefy/state-checkpoints/<name>/, one file per part; gitignored — checkpoints contain user/session data). Snapshot the developer's open tab after they reproduce a scenario, or a headless run. Use for building test fixtures and reproducible app states.",
-      inputSchema: {
-        pageId: z.string().describe('The page to snapshot.'),
-        name: z.string().describe('Checkpoint name (letters, numbers, - and _).'),
-        notes: z.string().optional().describe('What this checkpoint captures.'),
-        source: z.enum(['tab', 'headless']).optional(),
-        overwrite: z.boolean().optional(),
-      },
-    },
-    async ({ pageId, name, notes, source, overwrite }) => {
-      const result = await snapshotState({ origin, pageId, name, notes, source, overwrite });
+    async ({ pageId, pathParams, name, notes, source, overwrite }) => {
+      const result = await snapshotState({
+        origin,
+        pageId,
+        pathParams,
+        name,
+        notes,
+        source,
+        overwrite,
+      });
       if (result.error) {
         return notFoundResult(result.error);
       }
@@ -194,338 +201,288 @@ function createDocsMcpServer({ origin, honoContext } = {}) {
     }
   );
 
-  server.registerTool(
-    'lowdefy_load_state',
-    {
-      description:
-        "Put the app back into a saved state checkpoint. mode 'headless' (default) verifies the restored state itself; mode 'registry-only' loads the recorded request data into the dev server and returns a ?_checkpoint URL the developer can open to manually test the app in that exact state.",
-      inputSchema: {
-        name: z.string().describe('The checkpoint name.'),
-        mode: z.enum(['headless', 'registry-only']).optional(),
-        user: userSchema,
-      },
-    },
-    async ({ name, mode, user }) => {
-      const result = await loadState({ origin, name, mode, user });
-      if (result.error) {
-        return notFoundResult(result.error);
-      }
-      return textResult(result);
+  registerDevTool('lowdefy_load_state', async ({ name, mode, user, data }) => {
+    const result = await loadState({ origin, name, mode, user, data });
+    if (result.error) {
+      return notFoundResult(result.error);
     }
-  );
+    return textResult(result);
+  });
 
-  server.registerTool(
-    'lowdefy_list_state_checkpoints',
-    {
-      description: 'List saved state checkpoints (name, page, captured time, notes).',
-      inputSchema: {},
-    },
-    () => textResult(listStateCheckpoints())
-  );
+  registerDevTool('lowdefy_list_state_checkpoints', () => textResult(listStateCheckpoints()));
 
-  server.registerTool(
-    'lowdefy_checkpoint_to_mocks',
-    {
-      description:
-        'Convert a state checkpoint into @lowdefy/e2e-utils mocks.yaml fixtures (requests/api entries plus rendered yaml). Use when writing e2e tests from a captured scenario.',
-      inputSchema: {
-        name: z.string().describe('The checkpoint name.'),
-      },
-    },
-    ({ name }) => {
-      const result = checkpointToMocks({ name });
-      if (result.error) {
-        return notFoundResult(result.error);
-      }
-      return textResult(result);
+  registerDevTool('lowdefy_checkpoint_to_mocks', ({ name }) => {
+    const result = checkpointToMocks({ name });
+    if (result.error) {
+      return notFoundResult(result.error);
     }
-  );
+    return textResult(result);
+  });
 
-  server.registerTool(
-    'lowdefy_checkpoint',
-    {
-      description:
-        'Snapshot all config files before risky changes. Returns a checkpoint id for lowdefy_revert_checkpoint. Use before multi-file edits so you can restore instantly.',
-      inputSchema: {
-        label: z.string().describe('Short label for the checkpoint, e.g. "before-refactor".'),
-      },
-    },
-    ({ label }) => textResult(createConfigCheckpoint({ label }))
+  registerDevTool('lowdefy_checkpoint', ({ label }) =>
+    textResult(createConfigCheckpoint({ label }))
   );
 
-  server.registerTool(
-    'lowdefy_revert_checkpoint',
-    {
-      description:
-        'Restore config files from a checkpoint made with lowdefy_checkpoint (restores changed files and removes files added since). Omit id to list available checkpoints.',
-      inputSchema: {
-        id: z.string().optional().describe('Checkpoint id. Omit to list checkpoints.'),
-      },
-    },
-    ({ id }) => {
-      if (!id) {
-        return textResult(listConfigCheckpoints());
-      }
-      return textResult(revertConfigCheckpoint({ id }));
+  registerDevTool('lowdefy_revert_checkpoint', ({ id }) => {
+    if (!id) {
+      return textResult(listConfigCheckpoints());
     }
-  );
+    return textResult(revertConfigCheckpoint({ id }));
+  });
 
-  server.registerTool(
-    'lowdefy_build_status',
-    {
-      description:
-        'Call after every config edit. Returns the current build status: errors and warnings from the last build (with source file locations), plus recent browser runtime errors. The dev server rebuilds automatically on file change — edit, then call this to see what broke.',
-      inputSchema: {},
-    },
-    () => textResult(getBuildStatus())
-  );
+  registerDevTool('lowdefy_check', async () => textResult(await runCheck()));
 
-  server.registerTool(
-    'lowdefy_get_page_config',
-    {
-      description:
-        'Get the fully built config for a page, or its structured build errors if the page fails to build. Use to verify a page after editing it.',
-      inputSchema: {
-        pageId: z.string().describe('The page id.'),
-      },
-    },
-    async ({ pageId }) => {
-      const result = await getPageConfig({ pageId });
-      if (result === null) {
-        return notFoundResult(
-          `Page "${pageId}" not found. Use lowdefy_overview or check pageRegistry for valid page ids.`
-        );
-      }
-      return textResult(result);
+  registerDevTool('lowdefy_build_status', async ({ wait }) => {
+    if (wait === true) {
+      const proxyWait = readProxyBuildWait({
+        getHeader: (name) => honoContext?.req.header(name),
+      });
+      return textResult(await getBuildStatusAfterEdits({ proxyWait }));
     }
-  );
+    return textResult(await getBuildStatus());
+  });
+
+  registerDevTool('lowdefy_get_page_config', async ({ pageId }) => {
+    const result = await getPageConfig({ pageId });
+    if (result === null) {
+      return notFoundResult(
+        `Page "${pageId}" not found. Use lowdefy_overview or check pageRegistry for valid page ids.`
+      );
+    }
+    return textResult(result);
+  });
 
-  server.registerTool(
-    'lowdefy_find_config',
-    {
-      description:
-        'Find where a config entity is defined: pass a page, block, or request id and get the source yaml file (and line where available). For block/request ids also pass the owning pageId so the page is built first.',
-      inputSchema: {
-        id: z.string().describe('The id to find, e.g. a pageId, blockId, or requestId.'),
-        pageId: z
-          .string()
-          .optional()
-          .describe(
-            'The page the id belongs to — required for block/request ids on pages not yet built.'
-          ),
-      },
-    },
-    async ({ id, pageId }) => textResult(await findConfig({ id, pageId }))
+  registerDevTool('lowdefy_find_config', async ({ id, pageId }) =>
+    textResult(await findConfig({ id, pageId }))
   );
 
-  server.registerTool(
+  registerDevTool(
     'lowdefy_screenshot_page',
-    {
-      description:
-        'Screenshot a page of the running dev server (headless Chromium) to visually verify layout and rendering. Returns a PNG image.',
-      inputSchema: {
-        pageId: z.string().describe('The page id to screenshot.'),
-        fullPage: z.boolean().optional().describe('Capture the full scrollable page.'),
-        clip: z
-          .object({
-            x: z.number(),
-            y: z.number(),
-            width: z.number(),
-            height: z.number(),
-          })
-          .optional()
-          .describe(
-            "Crop to a viewport-relative region — pass an annotation's geometry from feedback."
-          ),
-        scrollX: z.number().optional().describe('Scroll offset the clip was recorded at.'),
-        scrollY: z.number().optional().describe('Scroll offset the clip was recorded at.'),
-        user: userSchema,
-      },
-    },
-    async ({ pageId, fullPage, clip, scrollX, scrollY, user }) => {
+    async ({
+      pageId,
+      pathParams,
+      urlQuery,
+      steps,
+      fullPage,
+      clip,
+      scrollX,
+      scrollY,
+      user,
+      data,
+      width,
+      height,
+      colorScheme,
+    }) => {
       if (!origin) {
         return notFoundResult('Screenshot unavailable: server origin unknown for this transport.');
       }
       const result = await screenshotPage({
         origin,
         pageId,
+        pathParams,
+        urlQuery,
+        steps,
         fullPage,
         clip,
         scrollX,
         scrollY,
         user,
+        data,
+        width,
+        height,
+        colorScheme,
       });
       if (result.error) {
         return notFoundResult(result.error);
       }
-      return { content: [{ type: 'image', data: result.data, mimeType: result.mimeType }] };
+      const image = { type: 'image', data: result.data, mimeType: result.mimeType };
+      if (!result.failure && result.screenshots.length === 0) {
+        return { content: [image] };
+      }
+      // The final capture shows the page where the steps (or the failing step)
+      // left it; the images of `screenshot` steps follow it in step order, named
+      // in the JSON.
+      const summary = { passed: !result.failure, failure: result.failure };
+      if (result.screenshots.length > 0) {
+        summary.screenshots = result.screenshots.map(({ name }) => ({ name }));
+      }
+      return {
+        content: [
+          { type: 'text', text: JSON.stringify(summary, null, 2) },
+          image,
+          ...result.screenshots.map(({ data, mimeType }) => ({ type: 'image', data, mimeType })),
+        ],
+      };
     }
   );
 
-  server.registerTool(
-    'lowdefy_scaffold_page',
-    {
-      description:
-        'Create a new page yaml file with a canonical minimal structure. Refuses if the page already exists. Returns the created file path and the lowdefy.yaml registration step you must do next.',
-      inputSchema: {
-        pageId: z.string().describe('The new page id (letters, numbers, - and _).'),
-        title: z.string().optional().describe('Page title. Defaults to the pageId.'),
-      },
-    },
-    ({ pageId, title }) => {
-      const result = scaffoldPage({ pageId, title });
+  registerDevTool(
+    'lowdefy_run_journey',
+    async ({ pageId, pathParams, steps, user, urlQuery, state, timeout, data, exercised }) => {
+      if (!origin) {
+        return notFoundResult('Journey unavailable: server origin unknown for this transport.');
+      }
+      const { error: userError } = validateJourneyUser({ user, data });
+      if (userError) {
+        return notFoundResult(userError);
+      }
+      // One params object for both branches, so neither can drop a parameter
+      // the other passes. basePath is read as the HTTP route reads it, so
+      // expect.calls counts and app errors match under a basePath.
+      const params = {
+        origin,
+        pageId,
+        pathParams,
+        steps,
+        urlQuery,
+        state,
+        stepTimeout: timeout,
+        data,
+        basePath: lowdefyConfig.basePath ?? '',
+      };
+      if (type.isArray(user)) {
+        const { passed, runs } = await runJourneyAsUsers({ ...params, users: user });
+        // Every run's screenshots follow the JSON as images, run by run in
+        // the order of the runs, each named in its run.
+        const summary = {
+          passed,
+          runs: runs.map(({ screenshots = [], exercised: runExercised, ...run }) => ({
+            ...run,
+            ...selectExercised({ exercised: runExercised, selection: exercised }),
+            screenshots: screenshots.map(({ name }) => ({ name })),
+          })),
+        };
+        return {
+          content: [
+            { type: 'text', text: JSON.stringify(summary, null, 2) },
+            ...runs.flatMap(({ screenshots = [] }) =>
+              screenshots.map(({ data: image, mimeType }) => ({
+                type: 'image',
+                data: image,
+                mimeType,
+              }))
+            ),
+          ],
+        };
+      }
+      const result = await runJourney({
+        ...params,
+        user,
+        // Each call is its own journey run, recorded apart from the suite's.
+        recording: { source: 'journey', run: { id: createTraceId(), by: 'agent', journey: null } },
+      });
       if (result.error) {
         return notFoundResult(result.error);
       }
-      return textResult(result);
+      // The PNGs travel as image content blocks (the shape lowdefy_screenshot_page
+      // returns) so an MCP client renders them; the JSON keeps only their names.
+      const { screenshots, exercised: resultExercised, ...rest } = result;
+      const summary = {
+        ...rest,
+        ...selectExercised({ exercised: resultExercised, selection: exercised }),
+        screenshots: screenshots.map(({ name }) => ({ name })),
+      };
+      return {
+        content: [
+          { type: 'text', text: JSON.stringify(summary, null, 2) },
+          ...screenshots.map(({ data, mimeType }) => ({ type: 'image', data, mimeType })),
+        ],
+      };
     }
   );
 
-  server.registerTool(
-    'lowdefy_overview',
-    {
-      description:
-        'Start here. Overview of everything this Lowdefy project has available: counts of blocks/operators/actions/connections/requests, installed plugins, doc sections, and which tool to use next.',
-      inputSchema: {},
-    },
-    () => textResult(getOverview())
-  );
+  registerDevTool('lowdefy_scaffold_page', ({ pageId, title }) => {
+    const result = scaffoldPage({ pageId, title });
+    if (result.error) {
+      return notFoundResult(result.error);
+    }
+    return textResult(result);
+  });
 
-  server.registerTool(
-    'lowdefy_list_types',
-    {
-      description:
-        'List ALL available types of a kind — every block, operator, action, connection, or request type installed in this project (core and local plugins), whether used yet or not. Call this before writing any config to get exact type names.',
-      inputSchema: {
-        kind: z
-          .enum([
-            'blocks',
-            'operators',
-            'actions',
-            'connections',
-            'requests',
-            'agents',
-            'notifications',
-            'websockets',
-          ])
-          .describe('The kind of types to list.'),
-      },
-    },
-    ({ kind }) => textResult(listTypes({ kind }))
-  );
+  registerDevTool('lowdefy_overview', () => textResult(getOverview()));
 
-  server.registerTool(
-    'lowdefy_list_plugins',
-    {
-      description:
-        "List installed plugin packages (including this project's local custom plugins) and the type names each provides.",
-      inputSchema: {},
-    },
-    () => textResult(listPlugins())
-  );
+  registerDevTool('lowdefy_list_types', ({ kind }) => textResult(listTypes({ kind })));
 
-  server.registerTool(
-    'lowdefy_get_schema',
-    {
-      description:
-        'Get the JSON Schema for a specific type: all properties, events, and their descriptions. Use the exact type name from lowdefy_list_types.',
-      inputSchema: {
-        kind: z
-          .enum(['blocks', 'operators', 'actions', 'connections', 'requests'])
-          .describe('The kind of the type.'),
-        type: z.string().describe('The exact type name, e.g. "Button", "_get", "MongoDBFind".'),
-      },
-    },
-    ({ kind, type }) => {
-      const schema = getSchema({ kind, type });
-      if (schema === null) {
-        return notFoundResult(
-          `No schema found for ${kind} type "${type}". Use lowdefy_list_types to see available types.`
-        );
-      }
-      return textResult(schema);
-    }
-  );
+  registerDevTool('lowdefy_list_plugins', () => textResult(listPlugins()));
 
-  server.registerTool(
-    'lowdefy_get_examples',
-    {
-      description:
-        'Get real YAML usage examples for a block type (gallery and example configs shipped with the plugin).',
-      inputSchema: {
-        type: z.string().describe('The exact block type name, e.g. "Button".'),
-      },
-    },
-    ({ type }) => {
-      const examples = getExamples({ type });
-      if (examples === null) {
-        return notFoundResult(
-          `No examples shipped for block type "${type}". Use lowdefy_get_schema for its contract, or lowdefy_get_doc for its documentation page.`
-        );
-      }
-      return textResult(examples);
+  registerDevTool('lowdefy_get_schema', ({ kind, type }) => {
+    const schema = getSchema({ kind, type });
+    if (schema === null) {
+      return notFoundResult(
+        `No schema found for ${kind} type "${type}". Use lowdefy_list_types to see available types.`
+      );
     }
-  );
-
-  server.registerTool(
-    'lowdefy_get_doc',
-    {
-      description:
-        'Get a core Lowdefy documentation page as markdown. Look up by slug (e.g. "concepts/lowdefy-schema", "operators/_get") or by kind + type name. Key concept slugs: concepts/lowdefy-schema, concepts/blocks, concepts/events-and-actions, concepts/connections-and-requests, concepts/operators, concepts/page-and-app-state.',
-      inputSchema: {
-        slug: z.string().optional().describe('Doc slug, e.g. "operators/_get".'),
-        kind: z
-          .enum(['block', 'operator', 'action', 'connection'])
-          .optional()
-          .describe('Kind of the type to find the doc for.'),
-        type: z.string().optional().describe('Type name to find the doc for, e.g. "_get".'),
-      },
-    },
-    ({ slug, kind, type }) => {
-      const doc = getCoreDoc({ slug, kind, type });
-      if (doc === null) {
-        return notFoundResult(
-          `No doc found${slug ? ` for slug "${slug}"` : ''}${
-            type ? ` for type "${type}"` : ''
-          }. Use lowdefy_search_docs to find the right slug.`
-        );
-      }
-      return textResult(doc.markdown);
+    return textResult(schema);
+  });
+
+  registerDevTool('lowdefy_get_examples', ({ type }) => {
+    const examples = getExamples({ type });
+    if (examples === null) {
+      return notFoundResult(
+        `No examples shipped for block type "${type}". Use lowdefy_get_schema for its contract, or lowdefy_get_doc for its documentation page.`
+      );
     }
+    return textResult(examples);
+  });
+
+  registerDevTool('lowdefy_get_doc', ({ slug, kind, type }) => {
+    const doc = getDoc({ slug, kind, type });
+    if (doc === null) {
+      return notFoundResult(
+        `No doc found${slug ? ` for slug "${slug}"` : ''}${
+          type ? ` for type "${type}"` : ''
+        }. Use lowdefy_search_docs to find the right slug.`
+      );
+    }
+    return textResult(appendHazards(doc));
+  });
+
+  registerDevTool('lowdefy_search_docs', ({ query, source }) =>
+    textResult(searchDocs({ query, source }))
   );
 
-  server.registerTool(
-    'lowdefy_search_docs',
-    {
-      description: 'Search the core Lowdefy docs by keyword. Returns matching slugs with snippets.',
-      inputSchema: {
-        query: z.string().describe('Search keywords.'),
-      },
-    },
-    ({ query }) => textResult(searchDocs({ query }))
+  registerDevTool('lowdefy_search_icons', async ({ query, limit }) =>
+    textResult(await searchIcons({ query, limit }))
   );
 
-  server.registerTool(
-    'lowdefy_get_plugin_doc',
-    {
-      description:
-        "Get markdown documentation shipped inside an installed plugin package (README, guides). Useful for this project's local custom plugins.",
-      inputSchema: {
-        package: z.string().describe('The package name, e.g. "@lowdefy/blocks-antd".'),
-      },
-    },
-    ({ package: packageName }) => {
-      const doc = getPluginDoc({ packageName });
-      if (doc === null) {
-        return notFoundResult(
-          `Package "${packageName}" ships no markdown docs. Use lowdefy_list_types and lowdefy_get_schema for its types.`
-        );
-      }
-      return textResult(doc.markdown);
+  registerDevTool('lowdefy_get_plugin_doc', ({ package: packageName }) => {
+    const doc = getPluginDoc({ packageName });
+    if (doc === null) {
+      return notFoundResult(
+        `Package "${packageName}" ships no markdown docs. Use lowdefy_list_types and lowdefy_get_schema for its types.`
+      );
     }
-  );
+    return textResult(doc.markdown);
+  });
 
+  registerDevTool('lowdefy_journey_session', ({ id, since }) => {
+    const result = readJourneySession({ id, since });
+    if (!type.isUndefined(result.error)) {
+      return notFoundResult(result.error);
+    }
+    return textResult(result.text);
+  });
+
+  const unregistered = Object.keys(devToolDefinitions).filter((name) => !registered.has(name));
+  if (unregistered.length > 0) {
+    throw new Error(`Dev tools defined without a handler: ${unregistered.join(', ')}.`);
+  }
   return server;
 }
 
+// Forwards dev events to one connected MCP client as notifications/message
+// (the only server→client notification MCP clients surface generically; it
+// needs the logging capability declared above). Build failures go out at
+// error level so clients that filter by level still see them.
+function subscribeMcpServerToDevEvents(server) {
+  return subscribeToDevEvents((event) =>
+    server.server.sendLoggingMessage({
+      level: event.type === 'build' && event.status === 'error' ? 'error' : 'info',
+      logger: 'lowdefy',
+      data: event,
+    })
+  );
+}
+
+export { subscribeMcpServerToDevEvents };
 export default createDocsMcpServer;