@just-every/design 0.1.31 → 0.1.33

package/dist/server.js

@@ -4,11 +4,17 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { statSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { fileURLToPath } from 'node:url';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { DesignAppClient } from './design-client.js';
+import { INSTRUCTIONS_MD } from './instructions.js';
+import { runScreenshotCommand } from './screenshot.js';
 import { buildCreateRunRequest, NOT_AUTHENTICATED_HELP, watchRun } from './tool-logic.js';
-import { wrapToolResponse } from './response-guidance.js';
+import { formatToolResponseMarkdown, wrapToolResponse } from './response-guidance.js';
+import { createSyncProgressTracker, getProgressPct } from './progress.js';
 export async function startMcpServer(options) {
     const config = options.config;
     const sessionToken = config.sessionToken ?? '';
@@ -34,155 +40,51 @@ export async function startMcpServer(options) {
         tools: [
             {
                 name: 'design.create',
-                description: 'Create a design run in Every Design (async). Use this to generate things like: ' +
-                    'web/landing page designs (HTML/CSS + assets), logos, icons, marketing graphics/illustrations, ' +
-                    'photorealistic images, backgrounds/patterns, and even 3D assets (GLB). ' +
-                    'Attach 1+ source images via `sourceImages` (local path, URL, or base64) or pass web URLs via `referenceUrls`/`references`. ' +
-                    'Note: when using this MCP server/CLI, HTML output is opt-in (use output.designKind=interface and enable progression.autoGenerateHtml/autoExtractAssets or call `design.generateHtml`). If output.designKind is omitted, this server defaults to output.designKind=interface to avoid expensive code builds while still producing a UI design. For interface runs, asset extraction and HTML generation are deferred by default; use `design.extractAssets` and `design.generateHtml` when you explicitly want those outputs. To allow backend inference, explicitly set output.designKind=auto. ' +
-                    'Returns a run id; follow up with `design.watch`, `design.get`, and `design.artifacts.*`.',
+                description: 'Create a new design. Returns run id. You must use design.create -> design.sync -> design.check in that order for interface creation or visual tasks (UI, Web, Mobile, Logos, Icons, 3D, Photos).',
                 inputSchema: {
                     type: 'object',
                     properties: {
                         prompt: { type: 'string', description: 'Prompt for the design run.' },
                         parentRunId: {
                             type: 'string',
-                            description: 'Optional parent run id to associate this run with an existing run/thread (useful when a CLI is working inside a run and wants related requests grouped).',
-                        },
-                        output: {
-                            type: 'object',
-                            description: 'Optional output controls. If omitted, the system tries to infer the best kind from the prompt.',
-                            properties: {
-                                designKind: {
-                                    type: 'string',
-                                    description: 'What to generate. Use interface for UI designs (image target by default; HTML/code is opt-in via progression flags); use 3dasset for GLB output.',
-                                    enum: ['auto', 'logo', 'icon', 'interface', 'graphic', 'photo', 'background', '3dasset'],
-                                },
-                                format: {
-                                    type: 'string',
-                                    description: 'Optional format hint for image outputs.',
-                                    enum: ['png', 'webp'],
-                                },
-                                assetFormats: {
-                                    type: 'array',
-                                    description: 'Optional formats for 3d assets (glb is always produced).',
-                                    items: { type: 'string', enum: ['glb', 'fbx'] },
-                                },
-                            },
-                            additionalProperties: true,
-                        },
-                        style: {
-                            type: 'string',
-                            description: 'Optional style string appended to the prompt (e.g. “minimal, Swiss, high-contrast”).',
+                            description: 'Optional request changes to a target design or new designs based on a previous run.',
                         },
                         referenceUrls: {
                             type: 'array',
-                            description: 'Optional web-accessible URLs to use as visual reference/inspiration.',
+                            description: 'Optional public web-accessible URLs to use as visual reference/inspiration.',
                             items: { type: 'string' },
                             maxItems: 8,
                         },
-                        references: {
-                            type: 'array',
-                            description: 'Optional structured references (advanced). Most users should prefer `sourceImages` or `referenceUrls`.',
-                            items: {
-                                type: 'object',
-                                properties: {
-                                    type: { type: 'string', enum: ['url', 'path'] },
-                                    url: { type: 'string' },
-                                    path: { type: 'string' },
-                                    filename: { type: 'string' },
-                                    userProvided: { type: 'boolean' },
-                                },
-                                required: ['type'],
-                                additionalProperties: true,
-                            },
-                            maxItems: 8,
-                        },
                         sourceImages: {
                             type: 'array',
-                            description: 'Optional images to upload to Every Design and use as references. Supports local file paths, URLs, and base64.',
+                            description: 'Optional local images to upload to Every Design and use as references. Supports local file paths and URLs.',
                             items: {
                                 type: 'object',
                                 properties: {
-                                    type: { type: 'string', enum: ['path', 'url', 'base64'] },
-                                    path: { type: 'string', description: 'Local file path (png/jpg).', },
-                                    url: { type: 'string', description: 'Public URL of an image.', },
-                                    data: { type: 'string', description: 'Base64 payload (optionally a data: URL).', },
-                                    mime: { type: 'string', description: 'MIME type for base64 data (e.g. image/png).', },
-                                    filename: { type: 'string', description: 'Optional filename override.', },
+                                    type: { type: 'string', enum: ['path', 'url'] },
+                                    path: { type: 'string', description: 'Local file path (png/jpg).' },
+                                    url: { type: 'string', description: 'Public URL of an image.' },
                                 },
                                 required: ['type'],
                                 additionalProperties: false,
                             },
                             maxItems: 8,
                         },
-                        config: {
-                            type: 'object',
-                            description: 'Advanced pass-through config merged with the convenience fields above. Useful keys include: ' +
-                                '`output` (designKind/format/assetFormats), `references` (url/path refs), `imageLoop`, `codeLoop`, and `refinementLoop`.',
-                            additionalProperties: true,
-                        },
                     },
                     required: ['prompt'],
                     additionalProperties: false,
                 },
             },
             {
-                name: 'design.list',
-                description: 'List recent design runs for the currently selected organization (chosen during auth login).',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        page: { type: 'number', description: 'Page number (default 1).' },
-                        limit: { type: 'number', description: 'Page size (default 20, max 50).' },
-                    },
-                    additionalProperties: false,
-                },
-            },
-            {
-                name: 'design.get',
-                description: 'Fetch a single design run by id (status, prompt, timestamps, etc).',
+                name: 'design.sync',
+                description: 'Wait for a design to complete, extracts assets and sync to a folder. Takes up to 30 mins for a fresh design. MCP clients should call with a long timeout (>=30 minutes).',
                 inputSchema: {
                     type: 'object',
                     properties: {
                         runId: { type: 'string' },
-                    },
-                    required: ['runId'],
-                    additionalProperties: false,
-                },
-            },
-            {
-                name: 'design.watch',
-                description: 'Watch a run until it finishes by polling status. Optionally sync useful artifacts to a local folder (downloads missing files and can trigger asset extraction when needed).',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        runId: { type: 'string' },
-                        timeoutSeconds: { type: 'number', description: 'Max wait time (default 3600).' },
-                        intervalSeconds: { type: 'number', description: 'Polling interval (default 5).' },
-                        syncDir: { type: 'string', description: 'Optional local directory to sync artifacts into.' },
-                        ensureAssets: { type: 'boolean', description: 'Whether to trigger extract-assets if assets are missing when syncDir is set (default true).' },
-                        targetArtifactId: { type: 'string', description: 'Optional: select this artifact as the run target before extracting/syncing.' },
-                    },
-                    required: ['runId'],
-                    additionalProperties: false,
-                },
-            },
-            {
-                name: 'design.extractAssets',
-                description: 'Trigger the asset extraction phase for an existing interface run (useful when runs are configured to stop after the target image by default). ' +
-                    'If you pass targetArtifactId, this tool will first set the run\'s explicit target selection to that artifact (so subsequent progress actions use the same target unless cleared).',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        runId: { type: 'string' },
-                        targetArtifactId: {
-                            type: 'string',
-                            description: 'Optional artifact id to explicitly set as the run\'s target image before extracting assets (must be an image draft artifact from the same run).',
-                        },
-                        designKind: {
+                        syncDir: {
                             type: 'string',
-                            description: 'Optional explicit kind to persist for the run when progressing (interface).',
-                            enum: ['interface'],
+                            description: 'Optional local directory to sync artifacts into (default: ./every-design/<run-id>).',
                         },
                     },
                     required: ['runId'],
@@ -190,187 +92,25 @@ export async function startMcpServer(options) {
                 },
             },
             {
-                name: 'design.generateHtml',
-                description: 'Trigger HTML generation (assets + code) for an existing interface run. This is separate from design.create so HTML builds are not automatic by default. ' +
-                    'If you pass targetArtifactId, this tool will first set the run\'s explicit target selection to that artifact.',
+                name: 'design.check',
+                description: 'Returns a screenshot and guidance on how close we are to matching a design run. Accepts either URL or path to html file. MCP clients should call with a long timeout (>=15 minutes).',
                 inputSchema: {
                     type: 'object',
                     properties: {
                         runId: { type: 'string' },
-                        targetArtifactId: {
-                            type: 'string',
-                            description: 'Optional artifact id to explicitly set as the run\'s target image before generating HTML (must be an image draft artifact from the same run).',
-                        },
+                        url: { type: 'string', description: 'HTTP(S) URL to screenshot (local URL is allowed).' },
+                        path: { type: 'string', description: 'Absolute or relative path to a local HTML file.' },
                     },
                     required: ['runId'],
                     additionalProperties: false,
                 },
             },
             {
-                name: 'design.iterate',
-                description: 'Iterate on an existing run using screenshot feedback. This creates an iterate operation under the run, waits for completion, and returns the iterate report JSON. ' +
-                    'Provide 1+ render screenshots via `render`. Optionally include a `target` image; if omitted, the backend will use the run\'s latest target image.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        runId: { type: 'string' },
-                        concerns: { type: 'string', description: 'Optional: what to focus on (spacing, hierarchy, etc).' },
-                        viewport: {
-                            type: 'object',
-                            description: 'Optional viewport hint used for iteration context.',
-                            properties: {
-                                width: { type: 'number' },
-                                height: { type: 'number' },
-                            },
-                            additionalProperties: false,
-                        },
-                        target: {
-                            type: 'array',
-                            description: 'Optional target/reference images (path/url/base64). If omitted, the run\'s latest target-image is used.',
-                            items: {
-                                type: 'object',
-                                properties: {
-                                    type: { type: 'string', enum: ['path', 'url', 'base64'] },
-                                    path: { type: 'string' },
-                                    url: { type: 'string' },
-                                    data: { type: 'string' },
-                                    mime: { type: 'string' },
-                                    filename: { type: 'string' },
-                                },
-                                required: ['type'],
-                                additionalProperties: false,
-                            },
-                            maxItems: 4,
-                        },
-                        render: {
-                            type: 'array',
-                            description: 'Render/current screenshots to iterate on (path/url/base64).',
-                            items: {
-                                type: 'object',
-                                properties: {
-                                    type: { type: 'string', enum: ['path', 'url', 'base64'] },
-                                    path: { type: 'string' },
-                                    url: { type: 'string' },
-                                    data: { type: 'string' },
-                                    mime: { type: 'string' },
-                                    filename: { type: 'string' },
-                                },
-                                required: ['type'],
-                                additionalProperties: false,
-                            },
-                            maxItems: 4,
-                        },
-                        timeoutSeconds: { type: 'number', description: 'Max wait time for the iterate operation (default 900).' },
-                        intervalSeconds: { type: 'number', description: 'Polling interval (default 5).' },
-                    },
-                    required: ['runId', 'render'],
-                    additionalProperties: false,
-                },
-            },
-            {
-                name: 'design.refineDraft',
-                description: 'Refine a specific draft image within the same run by generating a new refined draft (non-fork). ' +
-                    'Use this for quick, single-pass iteration without forking the run thread.',
+                name: 'design.instructions',
+                description: 'Return the Every Design MCP workflow instructions for gudiance on how to use these tools.',
                 inputSchema: {
                     type: 'object',
-                    properties: {
-                        runId: { type: 'string' },
-                        artifactId: { type: 'string', description: 'Draft/refined draft (or target) artifact id to refine.' },
-                        prompt: { type: 'string', description: 'Refinement instructions (what to change).', minLength: 1 },
-                    },
-                    required: ['runId', 'artifactId', 'prompt'],
-                    additionalProperties: false,
-                },
-            },
-            {
-                name: 'design.uploadTarget',
-                description: 'Upload an image and set it as the run\'s explicit target selection (used by extract-assets and generate-html).',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        runId: { type: 'string' },
-                        sourceImage: {
-                            type: 'object',
-                            description: 'Image to upload (path/url/base64).',
-                            properties: {
-                                type: { type: 'string', enum: ['path', 'url', 'base64'] },
-                                path: { type: 'string' },
-                                url: { type: 'string' },
-                                data: { type: 'string' },
-                                mime: { type: 'string' },
-                                filename: { type: 'string' },
-                            },
-                            required: ['type'],
-                            additionalProperties: false,
-                        },
-                    },
-                    required: ['runId', 'sourceImage'],
-                    additionalProperties: false,
-                },
-            },
-            {
-                name: 'design.setTarget',
-                description: 'Select which draft image should be treated as the canonical target for this run (used by extract-assets and generate-html). ' +
-                    'This persists in the run config until changed or cleared.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        runId: { type: 'string' },
-                        artifactId: {
-                            type: 'string',
-                            description: 'Artifact id of a draft/refined draft image in this run.',
-                        },
-                    },
-                    required: ['runId', 'artifactId'],
-                    additionalProperties: false,
-                },
-            },
-            {
-                name: 'design.clearTarget',
-                description: 'Clear any explicit target selection for this run (reverts to default target selection behavior on subsequent progress actions).',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        runId: { type: 'string' },
-                    },
-                    required: ['runId'],
-                    additionalProperties: false,
-                },
-            },
-            {
-                name: 'design.events',
-                description: 'Fetch structured events/logs for a run (useful for debugging failures).',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        runId: { type: 'string' },
-                    },
-                    required: ['runId'],
-                    additionalProperties: false,
-                },
-            },
-            {
-                name: 'design.artifacts.list',
-                description: 'List artifacts for a run (e.g. png/webp/html/css/glb, previews, logs).',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        runId: { type: 'string' },
-                    },
-                    required: ['runId'],
-                    additionalProperties: false,
-                },
-            },
-            {
-                name: 'design.artifacts.download',
-                description: 'Download an artifact to a local cache directory and return the file path (for opening/viewing locally).',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        runId: { type: 'string' },
-                        artifactId: { type: 'string' },
-                    },
-                    required: ['runId', 'artifactId'],
+                    properties: {},
                     additionalProperties: false,
                 },
             },
@@ -385,117 +125,122 @@ export async function startMcpServer(options) {
                     const { prompt, config, parentRunId } = await buildCreateRunRequest(client, input ?? {});
                     const created = await client.createRun({ prompt, config, ...(parentRunId ? { parentRunId } : {}) });
                     const wrapped = wrap('design.create', created);
-                    return { content: [{ type: 'text', text: pretty(wrapped) }] };
-                }
-                case 'design.list': {
-                    const page = typeof input?.page === 'number' ? input.page : undefined;
-                    const limit = typeof input?.limit === 'number' ? input.limit : undefined;
-                    const runs = await client.listRuns({ page, limit });
-                    const wrapped = wrap('design.list', runs);
-                    return { content: [{ type: 'text', text: pretty(wrapped) }] };
-                }
-                case 'design.get': {
-                    const runId = String(input?.runId ?? '').trim();
-                    if (!runId)
-                        throw new Error('Missing required argument: runId');
-                    const run = await client.getRun(runId);
-                    const wrapped = wrap('design.get', run, { runId });
-                    return { content: [{ type: 'text', text: pretty(wrapped) }] };
+                    return { content: [{ type: 'text', text: formatToolResponseMarkdown(wrapped) }] };
                 }
-                case 'design.watch': {
+                case 'design.sync': {
                     const runId = String(input?.runId ?? '').trim();
                     if (!runId)
                         throw new Error('Missing required argument: runId');
-                    const timeoutSeconds = typeof input?.timeoutSeconds === 'number' ? input.timeoutSeconds : 3600;
-                    const intervalSeconds = typeof input?.intervalSeconds === 'number' ? input.intervalSeconds : 5;
-                    const syncDir = typeof input?.syncDir === 'string' ? input.syncDir.trim() : '';
-                    const ensureAssets = typeof input?.ensureAssets === 'boolean' ? input.ensureAssets : undefined;
-                    const targetArtifactId = typeof input?.targetArtifactId === 'string' ? input.targetArtifactId.trim() : '';
+                    const syncDirInput = typeof input?.syncDir === 'string' ? input.syncDir.trim() : '';
+                    const syncDir = syncDirInput || `./every-design/${runId}`;
+                    const progressToken = request.params?.progressToken;
+                    const hasProgressToken = progressToken !== null && progressToken !== undefined;
+                    const progressLines = [];
+                    const tracker = createSyncProgressTracker();
+                    const emitProgress = (pct) => {
+                        progressLines.push(`Progress: ${pct}%`);
+                        if (!hasProgressToken)
+                            return;
+                        void server.notification({
+                            method: 'notifications/progress',
+                            params: {
+                                progressToken,
+                                progress: pct,
+                                total: 100,
+                                message: `Sync ${pct}%`,
+                            },
+                        });
+                    };
+                    const initialPct = tracker.next(0);
+                    if (initialPct !== null) {
+                        emitProgress(initialPct);
+                    }
                     const run = await watchRun(client, runId, {
-                        timeoutSeconds,
-                        intervalSeconds,
-                        log: (line) => console.error(line),
-                        ...(syncDir ? { syncDir } : {}),
-                        ...(ensureAssets !== undefined ? { ensureAssets } : {}),
-                        ...(targetArtifactId ? { targetArtifactId } : {}),
+                        timeoutSeconds: 1800,
+                        intervalSeconds: 5,
+                        onUpdate: (snapshot) => {
+                            const pct = getProgressPct(snapshot.run);
+                            const mapped = tracker.next(pct);
+                            if (mapped !== null) {
+                                emitProgress(mapped);
+                            }
+                        },
+                        onExtractStart: () => {
+                            const mapped = tracker.markExtractStart();
+                            if (mapped !== null) {
+                                emitProgress(mapped);
+                            }
+                        },
+                        syncDir,
+                        ensureAssets: true,
                     });
-                    const wrapped = wrap('design.watch', run, { runId, ...(syncDir ? { syncDir } : {}) });
-                    return { content: [{ type: 'text', text: pretty(wrapped) }] };
-                }
-                case 'design.extractAssets': {
-                    const runId = String(input?.runId ?? '').trim();
-                    if (!runId)
-                        throw new Error('Missing required argument: runId');
-                    const targetArtifactId = typeof input?.targetArtifactId === 'string' ? input.targetArtifactId.trim() : '';
-                    const designKind = typeof input?.designKind === 'string' ? input.designKind.trim().toLowerCase() : '';
-                    const normalizedKind = designKind === 'html' ? 'interface' : designKind;
-                    if (targetArtifactId) {
-                        await client.setRunTarget(runId, targetArtifactId);
+                    const finalPct = getProgressPct(run);
+                    const mappedFinal = tracker.finalize(finalPct);
+                    if (mappedFinal !== null) {
+                        emitProgress(mappedFinal);
                     }
-                    const res = await client.progressRun(runId, {
-                        action: 'extract_assets',
-                        ...(normalizedKind === 'interface' ? { designKind: 'interface' } : {}),
-                    });
-                    const wrapped = wrap('design.extractAssets', res, {
-                        runId,
-                        ...(targetArtifactId ? { artifactId: targetArtifactId } : {}),
-                    });
-                    return { content: [{ type: 'text', text: pretty(wrapped) }] };
+                    const payload = typeof run === 'object' && run ? { ...run, progress: progressLines } : { run, progress: progressLines };
+                    const wrapped = wrap('design.sync', payload, { runId, syncDir });
+                    return { content: [{ type: 'text', text: formatToolResponseMarkdown(wrapped) }] };
                 }
-                case 'design.generateHtml': {
+                case 'design.check': {
                     const runId = String(input?.runId ?? '').trim();
                     if (!runId)
                         throw new Error('Missing required argument: runId');
-                    const targetArtifactId = typeof input?.targetArtifactId === 'string' ? input.targetArtifactId.trim() : '';
-                    if (targetArtifactId) {
-                        await client.setRunTarget(runId, targetArtifactId);
+                    const urlInput = typeof input?.url === 'string' ? input.url.trim() : '';
+                    const pathInput = typeof input?.path === 'string' ? input.path.trim() : '';
+                    if (!urlInput && !pathInput)
+                        throw new Error('Missing required argument: url or path');
+                    if (urlInput && pathInput)
+                        throw new Error('Provide only one of url or path');
+                    let targetUrl = urlInput;
+                    if (pathInput) {
+                        const resolved = path.resolve(pathInput);
+                        let stat;
+                        try {
+                            stat = statSync(resolved);
+                        }
+                        catch {
+                            throw new Error(`File not found: ${resolved}`);
+                        }
+                        if (!stat.isFile()) {
+                            throw new Error(`Path must be a file: ${resolved}`);
+                        }
+                        targetUrl = pathToFileURL(resolved).toString();
                     }
-                    const res = await client.progressRun(runId, { action: 'generate_html', designKind: 'interface' });
-                    const wrapped = wrap('design.generateHtml', res, {
-                        runId,
-                        ...(targetArtifactId ? { artifactId: targetArtifactId } : {}),
+                    const screenshotOut = path.join(os.tmpdir(), `every-design-check-${runId}-${Date.now()}.png`);
+                    const screenshot = await runScreenshotCommand({
+                        url: targetUrl,
+                        outPath: screenshotOut,
+                        width: 1696,
+                        height: 2528,
+                        waitMs: 4000,
                     });
-                    return { content: [{ type: 'text', text: pretty(wrapped) }] };
-                }
-                case 'design.iterate': {
-                    const runId = String(input?.runId ?? '').trim();
-                    if (!runId)
-                        throw new Error('Missing required argument: runId');
-                    const concerns = typeof input?.concerns === 'string' ? input.concerns.trim() : '';
-                    const viewportInput = input?.viewport && typeof input.viewport === 'object' ? input.viewport : null;
-                    const viewport = {
-                        width: Number(viewportInput?.width) || 1696,
-                        height: Number(viewportInput?.height) || 2528,
-                    };
-                    const render = Array.isArray(input?.render) ? input?.render : [];
-                    if (render.length === 0)
-                        throw new Error('Missing required argument: render (array of images)');
-                    const target = Array.isArray(input?.target) ? input?.target : [];
-                    const renderRefs = await client.uploadSourceImages(render);
-                    const targetRefs = target.length > 0 ? await client.uploadSourceImages(target) : [];
+                    const renderRefs = await client.uploadSourceImages([{ type: 'path', path: screenshot.screenshotPath }]);
                     const created = await client.createRunOperation(runId, {
                         type: 'iterate',
-                        ...(concerns ? { concerns } : {}),
-                        viewport,
+                        viewport: { width: screenshot.width, height: screenshot.height },
                         render: renderRefs,
-                        ...(targetRefs.length > 0 ? { target: targetRefs } : {}),
                     });
                     const operationId = String(created?.operation?.id ?? '').trim();
                     if (!operationId)
                         throw new Error('Iterate operation created but missing operation id');
-                    const timeoutSeconds = typeof input?.timeoutSeconds === 'number' ? input.timeoutSeconds : 900;
-                    const intervalSeconds = typeof input?.intervalSeconds === 'number' ? input.intervalSeconds : 5;
-                    const deadlineMs = Date.now() + Math.max(1, timeoutSeconds) * 1000;
+                    const deadlineMs = Date.now() + 900 * 1000;
+                    let terminalStatus = '';
                     while (true) {
                         const op = await client.getOperation(operationId);
                         const status = String(op?.operation?.status ?? '').trim().toLowerCase();
                         if (status === 'completed' || status === 'failed' || status === 'cancelled') {
+                            terminalStatus = status;
                             break;
                         }
                         if (Date.now() > deadlineMs) {
                             throw new Error(`Timed out waiting for iterate operation (${operationId})`);
                         }
-                        await new Promise((r) => setTimeout(r, Math.max(1, intervalSeconds) * 1000));
+                        await new Promise((r) => setTimeout(r, 5_000));
+                    }
+                    if (terminalStatus !== 'completed') {
+                        throw new Error(`Iterate operation ${operationId} ended with status ${terminalStatus || 'unknown'}`);
                     }
                     const detail = await client.getRun(runId);
                     const outputs = Array.isArray(detail?.run?.outputs) ? detail.run.outputs : [];
@@ -518,12 +263,17 @@ export async function startMcpServer(options) {
                             runId,
                             operationId,
                             status: 'completed',
+                            screenshot: {
+                                filePath: screenshot.screenshotPath,
+                                width: screenshot.width,
+                                height: screenshot.height,
+                            },
                             iterate: null,
                             generatedAssets,
                             error: 'Missing critique artifact for iterate operation',
                         };
-                        const wrapped = wrap('design.iterate', payload, { runId });
-                        return { content: [{ type: 'text', text: pretty(wrapped) }] };
+                        const wrapped = wrap('design.check', payload, { runId });
+                        return { content: [{ type: 'text', text: formatToolResponseMarkdown(wrapped) }] };
                     }
                     const url = typeof critiqueArtifact?.url === 'string' ? String(critiqueArtifact.url) : '';
                     if (!url)
@@ -539,103 +289,21 @@ export async function startMcpServer(options) {
                     }
                     const payload = {
                         runId,
-                        operationId,
+                        screenshot: {
+                            filePath: screenshot.screenshotPath,
+                            width: screenshot.width,
+                            height: screenshot.height,
+                        },
                         iterate: parsed,
                         artifact: { id: critiqueArtifact.id, filePath: downloaded.filePath },
                         generatedAssets,
                     };
-                    const wrapped = wrap('design.iterate', payload, { runId });
-                    return { content: [{ type: 'text', text: pretty(wrapped) }] };
-                }
-                case 'design.uploadTarget': {
-                    const runId = String(input?.runId ?? '').trim();
-                    if (!runId)
-                        throw new Error('Missing required argument: runId');
-                    const sourceImage = input?.sourceImage;
-                    if (!sourceImage || typeof sourceImage !== 'object') {
-                        throw new Error('Missing required argument: sourceImage');
-                    }
-                    const res = await client.uploadRunTarget(runId, sourceImage);
-                    const wrapped = wrap('design.uploadTarget', res, { runId });
-                    return { content: [{ type: 'text', text: pretty(wrapped) }] };
-                }
-                case 'design.refineDraft': {
-                    const runId = String(input?.runId ?? '').trim();
-                    const artifactId = String(input?.artifactId ?? '').trim();
-                    const prompt = String(input?.prompt ?? '').trim();
-                    if (!runId)
-                        throw new Error('Missing required argument: runId');
-                    if (!artifactId)
-                        throw new Error('Missing required argument: artifactId');
-                    if (!prompt)
-                        throw new Error('Missing required argument: prompt');
-                    const res = await client.refineDraft(runId, artifactId, prompt);
-                    const wrapped = wrap('design.refineDraft', res, { runId, artifactId });
-                    return { content: [{ type: 'text', text: pretty(wrapped) }] };
-                }
-                case 'design.setTarget': {
-                    const runId = String(input?.runId ?? '').trim();
-                    const artifactId = String(input?.artifactId ?? '').trim();
-                    if (!runId)
-                        throw new Error('Missing required argument: runId');
-                    if (!artifactId)
-                        throw new Error('Missing required argument: artifactId');
-                    const res = await client.setRunTarget(runId, artifactId);
-                    const wrapped = wrap('design.setTarget', res, { runId, artifactId });
-                    return { content: [{ type: 'text', text: pretty(wrapped) }] };
-                }
-                case 'design.clearTarget': {
-                    const runId = String(input?.runId ?? '').trim();
-                    if (!runId)
-                        throw new Error('Missing required argument: runId');
-                    const res = await client.clearRunTarget(runId);
-                    const wrapped = wrap('design.clearTarget', res, { runId });
-                    return { content: [{ type: 'text', text: pretty(wrapped) }] };
-                }
-                case 'design.events': {
-                    const runId = String(input?.runId ?? '').trim();
-                    if (!runId)
-                        throw new Error('Missing required argument: runId');
-                    const events = await client.getRunEvents(runId);
-                    const wrapped = wrap('design.events', events, { runId });
-                    return { content: [{ type: 'text', text: pretty(wrapped) }] };
-                }
-                case 'design.artifacts.list': {
-                    const runId = String(input?.runId ?? '').trim();
-                    if (!runId)
-                        throw new Error('Missing required argument: runId');
-                    const detail = await client.getRun(runId);
-                    const outputs = Array.isArray(detail?.run?.outputs) ? detail.run.outputs : [];
-                    const wrapped = wrap('design.artifacts.list', { artifacts: outputs }, { runId });
-                    return { content: [{ type: 'text', text: pretty(wrapped) }] };
+                    const wrapped = wrap('design.check', payload, { runId });
+                    return { content: [{ type: 'text', text: formatToolResponseMarkdown(wrapped) }] };
                 }
-                case 'design.artifacts.download': {
-                    const runId = String(input?.runId ?? '').trim();
-                    const artifactId = String(input?.artifactId ?? '').trim();
-                    if (!runId)
-                        throw new Error('Missing required argument: runId');
-                    if (!artifactId)
-                        throw new Error('Missing required argument: artifactId');
-                    const detail = await client.getRun(runId);
-                    const outputs = Array.isArray(detail?.run?.outputs) ? detail.run.outputs : [];
-                    const found = outputs.find((entry) => String(entry?.id ?? '') === artifactId) || null;
-                    const url = typeof found?.url === 'string' ? found.url : '';
-                    if (!url)
-                        throw new Error(`Artifact not found in standard outputs: ${artifactId}`);
-                    const hint = (() => {
-                        try {
-                            const u = url.startsWith('http://') || url.startsWith('https://')
-                                ? new URL(url)
-                                : new URL(url, 'https://example.invalid');
-                            return u.pathname.split('/').filter(Boolean).pop() || undefined;
-                        }
-                        catch {
-                            return url.split('/').filter(Boolean).pop() || undefined;
-                        }
-                    })();
-                    const artifact = await client.downloadUrlToCache(runId, artifactId, url, { fileNameHint: hint });
-                    const wrapped = wrap('design.artifacts.download', artifact, { runId, artifactId });
-                    return { content: [{ type: 'text', text: pretty(wrapped) }] };
+                case 'design.instructions': {
+                    const wrapped = wrap('design.instructions', { instructions: INSTRUCTIONS_MD });
+                    return { content: [{ type: 'text', text: formatToolResponseMarkdown(wrapped) }] };
                 }
                 default:
                     throw new Error(`Unknown tool: ${tool}`);
@@ -649,9 +317,6 @@ export async function startMcpServer(options) {
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
-function pretty(value) {
-    return JSON.stringify(value, null, 2);
-}
 async function resolvePackageVersion() {
     try {
         const pkgPath = fileURLToPath(new URL('../package.json', import.meta.url));