@bifocal/mcp 0.1.7 → 0.1.8

package/dist/bifocalClient.js

@@ -183,3 +183,15 @@ export async function importPrototypeConfirm(projectId, prototypeId, contextId,
     }
     return response.json();
 }
+export async function screenshotPrototype(prototypeId, path, interactionSteps) {
+    const response = await fetch(`${API_URL}/api/prototypes/${prototypeId}/screenshot`, {
+        method: 'POST',
+        headers: headers(),
+        body: JSON.stringify({ path, interaction_steps: interactionSteps }),
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({}));
+        throw new Error(error.error || `Request failed: ${response.status}`);
+    }
+    return response.json();
+}

package/dist/index.js

@@ -1,43 +1,16 @@
 #!/usr/bin/env node
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { createProject, updateProject, listProjects, importPrototypeUploadUrl, importPrototypeConfirm, addFeedbackText, generateSolution, getInsights, getQuotes, getSolutions, getSolution, getPrototypes, getPrototype, exportPrototype, generatePrototype, updatePrototype, getContexts, createContext, createSolution, updateSolution } from './bifocalClient.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { createProject, updateProject, listProjects, importPrototypeUploadUrl, importPrototypeConfirm, addFeedbackText, generateSolution, getInsights, getQuotes, getSolutions, getSolution, getPrototypes, getPrototype, exportPrototype, generatePrototype, updatePrototype, getContexts, createContext, createSolution, updateSolution, screenshotPrototype } from './bifocalClient.js';
 import { writeFile } from 'fs/promises';
 import { join } from 'path';
-async function pollUntilReady(fn, isDone, intervalMs, timeoutMs) {
-    const deadline = Date.now() + timeoutMs;
-    while (true) {
-        const result = await fn();
-        if (isDone(result))
-            return { result, timedOut: false };
-        if (Date.now() + intervalMs >= deadline)
-            return { result, timedOut: true };
-        await new Promise(resolve => setTimeout(resolve, intervalMs));
-    }
-}
-const server = new Server({ name: 'bifocal', version: '0.1.0' }, { capabilities: { tools: {}, resources: {} } });
+const server = new Server({ name: 'bifocal', version: '0.1.0' }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         {
             name: 'import_prototype',
-            description: `Import a local zip file as a prototype into a Bifocal project.
-
-If prototype_id is provided, the zip is uploaded to update an existing prototype (e.g. after building or editing locally via the client coding agent). The existing prototype record is reused and re-processed — no new record is created.
-
-## Preparing the zip
-
-**Claude Code / other agents building locally:**
-- Do not modify any files in the existing codebase. Read existing files to understand the experience, but never edit them. Create all prototype files in a new separate directory.
-- Bifocal requires a Vite + React single-page app with react-router-dom so that each major section has its own URL path. Next.js is not supported.
-- Replace any API calls or environment variables with hardcoded fixture data. The prototype must work with no backend and no network requests.
-- Stub out external services — auth, feature flags, analytics, payments, real-time connections — with simple no-op replacements.
-- Run \`npm run build\` and fix any errors before zipping.
-- ZIP the project excluding node_modules, .git, dist, and any .env files or credentials.
-
-**Lovable:** open your project → top-right menu → Export → Download ZIP. Do not manually zip the files.
-
-**Figma Make:** go to Prototype Settings → GitHub, push to a GitHub repo, then download the ZIP from GitHub (Code → Download ZIP). Note: some Figma assets may not convert correctly — check asset paths if images are missing.`,
+            description: 'Import a local zip file as a prototype into a Bifocal project. Always call get_import_instructions first to ensure the zip is correctly prepared.\n\nIf prototype_id is provided, the zip is uploaded to update an existing prototype (e.g. after building or editing locally via the client coding agent). The existing prototype record is reused and re-processed — no new record is created.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -63,6 +36,21 @@ If prototype_id is provided, the zip is uploaded to update an existing prototype
                 required: ['project_id', 'prototype_id', 'source'],
             },
         },
+        {
+            name: 'get_import_instructions',
+            description: 'Get platform-specific instructions for preparing a prototype zip file before importing it into Bifocal. Always call this before import_prototype.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    platform: {
+                        type: 'string',
+                        enum: ['claudecode', 'lovable', 'figmamake', 'other'],
+                        description: 'The platform the prototype was built with.',
+                    },
+                },
+                required: ['platform'],
+            },
+        },
         {
             name: 'create_project',
             description: 'Create a new Bifocal project. Before calling this tool, always ask the user if they have a PRD or any context to add for the project.',
@@ -118,7 +106,7 @@ If prototype_id is provided, the zip is uploaded to update an existing prototype
         },
         {
             name: 'create_context',
-            description: 'Create or update a context for a Bifocal project. Contexts are attached to a solution to provide additional reference material (e.g. product docs, design system, brand guidelines) during generation. If a context with the same name and type already exists for the project\'s organization, it will be updated.\n\nIf you\'re not sure whether a context with this name already exists, call get_contexts first — an existing match will be silently overwritten.',
+            description: 'Create or update a context for a Bifocal project. Contexts are attached to a solution to provide additional reference material (e.g. product docs, design system, brand guidelines) during generation. If a context with the same name and type already exists for the project\'s organization, it will be updated.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -144,7 +132,7 @@ If prototype_id is provided, the zip is uploaded to update an existing prototype
         },
         {
             name: 'generate_solution',
-            description: 'Generate a new solution for a project based on selected insights. Before calling this tool, always: (1) call get_insights to show the user the available insights, (2) ask the user which insights they want to prioritize, (3) ask if they have a specific goal or any constraints for the solution, (4) optionally call get_contexts and ask the user if they want to attach any context. Only call this tool once you have that input. Blocks until the solution is ready and returns the full detail. The base prototype is resolved automatically.',
+            description: 'Generate a new solution for a project based on selected insights. Before calling this tool, always: (1) call get_insights to show the user the available insights, (2) ask the user which insights they want to prioritize, (3) ask if they have a specific goal or any constraints for the solution, (4) optionally call get_contexts and ask the user if they want to attach any context. Only call this tool once you have that input. This is async — use get_solutions to check when the solution appears. The base prototype is resolved automatically.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -159,7 +147,7 @@ If prototype_id is provided, the zip is uploaded to update an existing prototype
         },
         {
             name: 'create_solution',
-            description: 'Directly insert a fully-specified solution into a Bifocal project. Use this when you already know exactly what the solution should be, rather than having it generated. The solution must follow the same schema as generated solutions. The base prototype is resolved automatically.\n\nBefore calling this tool you MUST:\n1. Call get_insights — insight_ids must be real IDs from that response. Never fabricate or guess insight IDs.\n2. Call get_prototypes with the base prototype_id — pages_to_modify must be real page paths that exist in the prototype sitemap. pages_to_create must be genuinely new paths not already in the sitemap. Never fabricate page paths.\n\nAll fields are required. barriers_addressed must reflect actual barriers from the selected insights. interventions must each map to a real barrier. Do not submit this tool call until every field has been populated with valid, verified data.\n\n**IMPORTANT**: Never fabricate or guess insight_ids or page paths in interventions — they must come from a real tool response. A made-up insight ID will silently link to nothing. A made-up page path will send the coding agent to a page that doesn\'t exist.\n\n<example description="A solution with one intervention and two changes">\n{\n  "project_id": "proj_abc123",\n  "title": "Condensed Flow with Inline Price Transparency",\n  "brief": "Surfaces pricing and meal frequency options earlier in onboarding so users can evaluate value before committing. Reduces drop-off at the plan selection step.",\n  "category": "flow",\n  "barriers_addressed": [\n    "Users don\'t understand what\'s included in the price before they reach checkout",\n    "Frequency options feel buried and hard to compare"\n  ],\n  "interventions": [\n    {\n      "barrier": "Users don\'t understand what\'s included in the price before they reach checkout",\n      "changes": [\n        {\n          "approach": "Add frequency price cards to step 13",\n          "description": "Replace the single plan summary with 3 side-by-side cards showing weekly, biweekly, and monthly frequency. Each card shows: price per delivery, total weekly cost, and a \'most popular\' badge on the biweekly option. Tapping a card selects it and updates the CTA label to reflect the chosen frequency.",\n          "pages_to_modify": ["/onboarding/step-13"],\n          "pages_to_create": []\n        },\n        {\n          "approach": "Add a \'What\'s included\' expandable section to step 13",\n          "description": "Below the frequency cards, add a collapsed accordion labeled \'What\'s included in every box\'. Expanding it shows: number of recipes, serving sizes, packaging info, and a skip-anytime note. Default state is collapsed.",\n          "pages_to_modify": ["/onboarding/step-13"],\n          "pages_to_create": []\n        }\n      ]\n    }\n  ],\n  "assumptions": [\n    "Users can see and compare all three frequency options without scrolling on mobile"\n  ],\n  "open_concerns": [\n    "Does surfacing price earlier increase or decrease conversion? Should be A/B tested."\n  ],\n  "insight_ids": ["ins_111", "ins_222"]\n}\n</example>',
+            description: 'Directly insert a fully-specified solution into a Bifocal project. Use this when you already know exactly what the solution should be, rather than having it generated. The solution must follow the same schema as generated solutions. The base prototype is resolved automatically.\n\nBefore calling this tool you MUST:\n1. Call get_insights — insight_ids must be real IDs from that response. Never fabricate or guess insight IDs.\n2. Call get_prototype on the base prototype — pages_to_modify must be real page paths that exist in the prototype sitemap. pages_to_create must be genuinely new paths not already in the sitemap. Never fabricate page paths.\n\nAll fields are required. barriers_addressed must reflect actual barriers from the selected insights. interventions must each map to a real barrier. Do not submit this tool call until every field has been populated with valid, verified data.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -202,7 +190,7 @@ If prototype_id is provided, the zip is uploaded to update an existing prototype
         },
         {
             name: 'update_solution',
-            description: 'Update an existing solution in a Bifocal project. All fields are optional — only send what needs to change. The solution schema must remain valid after the update.\n\nBefore calling this tool you MUST:\n1. Call get_solutions with solution_id to read the current state. Verify solution_generation_status is "completed" — do not call this tool if the solution is still generating.\n2. If updating insight_ids: call get_insights first and use only real IDs from that response. Never fabricate or guess insight IDs.\n3. If updating interventions (and therefore page paths): call get_prototypes with the base prototype_id to confirm pages_to_modify exist in the sitemap and pages_to_create are genuinely new.\n\nDo not submit partial or invalid data. Every field you include must be fully valid and complete.\n\n**IMPORTANT**: interventions is a full replacement — include every intervention, not just the ones that changed. Omitting an existing intervention will delete it. interventions is a full replacement — include all interventions, not just the ones that changed.\n\n<example description="Updating only the interventions on an existing solution">\n{\n  "project_id": "proj_abc123",\n  "solution_id": "sol_xyz789",\n  "interventions": [\n    {\n      "barrier": "Users don\'t understand what\'s included in the price before they reach checkout",\n      "changes": [\n        {\n          "approach": "Add frequency price cards to step 13",\n          "description": "Replace the single plan summary with 3 side-by-side cards showing weekly, biweekly, and monthly frequency. Each card shows price per delivery and total weekly cost.",\n          "pages_to_modify": ["/onboarding/step-13"],\n          "pages_to_create": []\n        }\n      ]\n    }\n  ]\n}\n</example>',
+            description: 'Update an existing solution in a Bifocal project. All fields are optional — only send what needs to change. The solution schema must remain valid after the update.\n\nBefore calling this tool you MUST:\n1. Call get_solution to read the current state. Verify solution_generation_status is "completed" — do not call this tool if the solution is still generating.\n2. If updating insight_ids: call get_insights first and use only real IDs from that response. Never fabricate or guess insight IDs.\n3. If updating interventions (and therefore page paths): call get_prototype on the base prototype to confirm pages_to_modify exist in the sitemap and pages_to_create are genuinely new.\n\nDo not submit partial or invalid data. Every field you include must be fully valid and complete.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -245,19 +233,30 @@ If prototype_id is provided, the zip is uploaded to update an existing prototype
         },
         {
             name: 'get_solutions',
-            description: 'Get solutions for a Bifocal project. If solution_id is provided, returns full detail for that solution including all interventions and page changes. If omitted, returns a summary list of all solutions (title, brief, barriers addressed, prototype link).',
+            description: 'Get all solutions for a Bifocal project. Returns title, brief, barriers addressed, and prototype link (if one was generated) for each solution.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    project_id: { type: 'string', description: 'The ID of the project.' },
-                    solution_id: { type: 'string', description: 'Optional. If provided, returns full detail for this specific solution.' },
+                    project_id: { type: 'string', description: 'The ID of the project to fetch solutions for.' },
                 },
                 required: ['project_id'],
             },
         },
+        {
+            name: 'get_solution',
+            description: 'Get full detail for a specific solution including all proposed interventions and page changes. Call this when the user wants to understand what a solution proposes to change.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_id: { type: 'string', description: 'The ID of the project the solution belongs to.' },
+                    solution_id: { type: 'string', description: 'The ID of the solution to fetch.' },
+                },
+                required: ['project_id', 'solution_id'],
+            },
+        },
         {
             name: 'generate_prototype',
-            description: 'Generate a prototype from a solution.\n\nBefore calling, make sure you understand what the solution does — its interventions, the pages it targets, and the barriers it addresses. This helps you evaluate the result and write useful edits if needed. If you haven\'t read the full detail yet, call get_solutions with the solution_id first.\n\n**IMPORTANT**: Don\'t call this while the solution is still generating — check that solution_generation_status is completed first.\n\nIf coding_agent is "bifocal" (default): queues a build and blocks until the prototype is ready, then returns the full prototype detail.\n\nIf coding_agent is "client": returns the full solution spec, base prototype ID, and org contexts so the client can build the prototype locally. After building, call import_prototype with the returned prototype_id to upload and link. If a prototype already exists for the solution, returns it immediately regardless of coding_agent.',
+            description: 'Generate a prototype from a solution.\n\nIf coding_agent is "bifocal" (default): queues an async build — poll get_prototype until status is "ready".\n\nIf coding_agent is "client": returns the full solution spec, base prototype ID, and org contexts so the client can build the prototype locally. After building, call import_prototype with the returned prototype_id to upload and link. If a prototype already exists for the solution, returns it immediately regardless of coding_agent.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -270,30 +269,40 @@ If prototype_id is provided, the zip is uploaded to update an existing prototype
         },
         {
             name: 'update_prototype',
-            description: 'Edit an existing prototype.\n\nYour edit instruction should reference real pages that exist in the prototype. Make sure you know the sitemap before writing it — if you\'re not sure what pages exist, call get_prototypes with the prototype_id first.\n\nIf coding_agent is "bifocal" (default): sends the edit instruction to Bifocal\'s coding agent and blocks until the prototype is ready, then returns the full prototype detail.\n\nIf coding_agent is "client": returns the edit instruction and prototype_id so the client can make the changes locally. Export the prototype first via export_prototype, apply the changes, then call import_prototype with prototype_id to upload the updated zip.',
+            description: 'Edit an existing prototype.\n\nIf coding_agent is "bifocal" (default): sends the edit instruction to Bifocal\'s coding agent — async, poll get_prototype until status returns to "ready".\n\nIf coding_agent is "client": returns the edit instruction and prototype_id so the client can make the changes locally. Export the prototype first via export_prototype, apply the changes, then call import_prototype with prototype_id to upload the updated zip.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    project_id: { type: 'string', description: 'The ID of the project the prototype belongs to.' },
                     prototype_id: { type: 'string', description: 'The ID of the prototype to update.' },
                     message: { type: 'string', description: 'The edit instruction.' },
                     coding_agent: { type: 'string', enum: ['bifocal', 'client'], description: 'Who will apply the edit. "bifocal" (default) sends to Bifocal\'s agent. "client" returns the instruction for the calling agent to apply locally.' },
                 },
-                required: ['project_id', 'prototype_id', 'message'],
+                required: ['prototype_id', 'message'],
             },
         },
         {
             name: 'get_prototypes',
-            description: 'Get prototypes for a Bifocal project. If prototype_id is provided, returns full detail for that prototype including its sitemap and key capabilities. If omitted, returns a summary list of all prototypes (name, status, published URL, parent prototype, linked solution). Use the full detail form when you need to understand what pages exist or poll for build status.',
+            description: 'List all prototypes for a Bifocal project. Returns name, status, published URL, parent prototype (for iteration chains), and linked solution if any. Ordered oldest to newest.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    project_id: { type: 'string', description: 'The ID of the project.' },
-                    prototype_id: { type: 'string', description: 'Optional. If provided, returns full detail for this specific prototype.' },
+                    project_id: { type: 'string', description: 'The ID of the project to fetch prototypes for.' },
                 },
                 required: ['project_id'],
             },
         },
+        {
+            name: 'get_prototype',
+            description: 'Get full detail for a specific prototype including its sitemap and key capabilities. Use this when you need to understand what pages exist in a prototype.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_id: { type: 'string', description: 'The ID of the project the prototype belongs to.' },
+                    prototype_id: { type: 'string', description: 'The ID of the prototype to fetch.' },
+                },
+                required: ['project_id', 'prototype_id'],
+            },
+        },
         {
             name: 'export_prototype',
             description: 'Download a prototype\'s source code as a ZIP file and save it to the local filesystem. Returns the path where the file was saved.',
@@ -307,6 +316,34 @@ If prototype_id is provided, the zip is uploaded to update an existing prototype
                 required: ['project_id', 'prototype_id'],
             },
         },
+        {
+            name: 'screenshot_prototype',
+            description: 'Capture a screenshot of a specific page or UI state in a prototype and render it inline.\n\nBefore calling, make sure you know what path to capture — get valid paths from the prototype\'s sitemap by calling get_prototypes with the prototype_id if you haven\'t already.\n\n**Choosing whether to pass interaction_steps:**\nPass interaction steps when the screen you want to capture requires user interaction to reach — this includes: a specific step in a multi-page flow that can\'t be reached by URL alone, a UI state triggered by a selection or toggle (e.g. a plan option selected, a modal open, a tab active), or any meaningful variation of a screen that differs from its default loaded state. If navigating directly to the path shows the right screen, no steps are needed.\n\nIf you need interaction steps but aren\'t sure what selectors to use, read the relevant page or component source — export the prototype first via export_prototype if you don\'t have the source locally.\n\n**IMPORTANT**: Only call this when you actually need to see something — after an edit, to evaluate a specific screen, or to compare before and after. Don\'t call it speculatively.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_id: { type: 'string', description: 'The ID of the project the prototype belongs to.' },
+                    prototype_id: { type: 'string', description: 'The ID of the prototype to screenshot.' },
+                    path: { type: 'string', description: 'The URL path to capture (e.g. "/onboarding/step-13"). Must be a real path from the prototype sitemap.' },
+                    interaction_steps: {
+                        type: 'array',
+                        description: 'Optional steps to execute before screenshotting, to reach a specific UI state.',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                action: { type: 'string', enum: ['click', 'hover', 'waitForSelector', 'waitForTimeout', 'select', 'type'] },
+                                selector: { type: 'string', description: 'CSS selector for the target element. Required for all actions except waitForTimeout.' },
+                                ms: { type: 'number', description: 'Milliseconds to wait. Required for waitForTimeout.' },
+                                value: { type: 'string', description: 'Value to select. Required for select.' },
+                                text: { type: 'string', description: 'Text to type. Required for type.' },
+                            },
+                            required: ['action'],
+                        },
+                    },
+                },
+                required: ['project_id', 'prototype_id', 'path'],
+            },
+        },
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -366,6 +403,58 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
             }
         }
+        if (name === 'get_import_instructions') {
+            const { platform } = args;
+            const instructions = {
+                claudecode: `⚠️ Do not modify any files in the existing codebase. Read existing files to understand the experience, but never edit them. Create all prototype files in a new separate directory.
+
+Bifocal requires a Vite + React single-page app containing only the experience being tested. Follow these steps:
+
+1. Ask the user: "What specific page or flow do you want to test in Bifocal?" Only include what is needed to render that experience. Remove unrelated pages, routes, and components.
+
+2. Ask: "Is this project built with Next.js or Vite?"
+
+If Next.js:
+- Convert to a Vite + React single-page app with react-router-dom. Remove all SSR, API routes, getServerSideProps, and getStaticProps.
+- Verify: run npm run build and fix any errors before continuing.
+- Create a ZIP excluding node_modules, .git, dist, and any .env files or credentials.
+
+If Vite:
+- Ask: "Does this project use react-router-dom so that each major section has its own URL path?"
+- If no: add react-router-dom with each major section as its own route.
+- Verify: run npm run build and fix any errors before continuing.
+- Create a ZIP excluding node_modules, .git, dist, and any .env files or credentials.
+
+3. Replace any API calls or environment variables with hardcoded fixture data. The prototype must work with no backend and no network requests.
+
+4. Stub out external services — auth, feature flags, analytics, payments, real-time connections — with simple no-op replacements.`,
+                lovable: `To export from Lovable: open your project → top-right menu → Export → Download ZIP.
+
+Do not manually zip the project files — the Export button handles cleanup automatically.`,
+                figmamake: `To export from Figma Make:
+1. In Figma Make, go to Prototype Settings → GitHub and push your project to a GitHub repo.
+2. Go to your GitHub repo → click the green Code button → Download ZIP.
+
+Note: Some Figma assets may not convert correctly after export. If your build fails or images are missing, check that all asset paths are correct.`,
+                other: `⚠️ Do not modify any files in the existing codebase. Read existing files to understand the experience, but never edit them. Create all prototype files in a new separate directory.
+
+Bifocal requires a Vite + React single-page app containing only the experience being tested.
+
+1. Ask the user: "What specific page or flow do you want to test in Bifocal?" Only include what is needed to render that experience. Remove unrelated pages, routes, and components.
+
+2. Your project should have package.json, index.html, and src/ at the root. Next.js is not supported — use Vite. npm run build should output to a dist/ or build/ folder.
+
+3. Replace any API calls or environment variables with hardcoded fixture data. The prototype must work with no backend and no network requests.
+
+4. Stub out external services — auth, feature flags, analytics, payments, real-time connections — with simple no-op replacements.
+
+5. Verify: run npm run build and fix any errors before continuing.
+
+6. Create a ZIP excluding node_modules, .git, dist, and any .env files or credentials.`,
+            };
+            const text = instructions[platform] ?? instructions.other;
+            return { content: [{ type: 'text', text }] };
+        }
         if (name === 'update_project') {
             const { project_id, name: projectName, description } = args;
             const project = await updateProject(project_id, { name: projectName, description });
@@ -401,7 +490,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const project = await createProject(projectName, description);
             const response = {
                 ...project,
-                next_step: "Ask the user if they have a prototype they'd like to import — projects require one to be useful. If yes, call import_prototype — the description contains platform-specific instructions for preparing the zip.",
+                next_step: "Ask the user if they have a prototype they'd like to import — projects require one to be useful. If yes, call get_import_instructions first to get platform-specific requirements for preparing the zip, then call import_prototype.",
             };
             return { content: [{ type: 'text', text: JSON.stringify(response, null, 2) }] };
         }
@@ -436,15 +525,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             if (!basePrototype) {
                 throw new Error('No base prototype found for this project. A ready prototype with no parent is required.');
             }
-            const generated = await generateSolution(project_id, insight_ids, basePrototype.id, goal, constraints, context_ids);
-            const { result, timedOut } = await pollUntilReady(() => getSolution(project_id, generated.solution_id), s => s.solution_generation_status === 'completed', 10_000, 3 * 60_000);
-            if (timedOut) {
-                return { content: [{ type: 'text', text: JSON.stringify({
-                                solution_id: generated.solution_id,
-                                message: 'Solution is still generating after 3 minutes. Call get_solutions with solution_id to check when it\'s ready.',
-                            }, null, 2) }] };
-            }
-            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            const result = await generateSolution(project_id, insight_ids, basePrototype.id, goal, constraints, context_ids);
+            return { content: [{ type: 'text', text: JSON.stringify({
+                            ...result,
+                            message: 'Solution is being generated. Use get_solutions to check when it appears — typically takes 1-2 minutes.',
+                        }, null, 2) }] };
         }
         if (name === 'create_solution') {
             const { project_id, title, brief, category, barriers_addressed, interventions, assumptions, open_concerns, insight_ids } = args;
@@ -460,14 +545,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             return { content: [{ type: 'text', text: JSON.stringify({ ...result, message: 'Solution updated.' }, null, 2) }] };
         }
         if (name === 'get_solutions') {
-            const { project_id, solution_id } = args;
-            if (solution_id) {
-                const solution = await getSolution(project_id, solution_id);
-                return { content: [{ type: 'text', text: JSON.stringify(solution, null, 2) }] };
-            }
+            const { project_id } = args;
             const solutions = await getSolutions(project_id);
             return { content: [{ type: 'text', text: JSON.stringify(solutions, null, 2) }] };
         }
+        if (name === 'get_solution') {
+            const { project_id, solution_id } = args;
+            const solution = await getSolution(project_id, solution_id);
+            return { content: [{ type: 'text', text: JSON.stringify(solution, null, 2) }] };
+        }
         if (name === 'generate_prototype') {
             const { project_id, solution_id, coding_agent } = args;
             const result = await generatePrototype(project_id, solution_id, coding_agent);
@@ -482,18 +568,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 ],
                             }, null, 2) }] };
             }
-            const bifocalResult = result;
-            const { result: prototype, timedOut } = await pollUntilReady(() => getPrototype(project_id, bifocalResult.prototype_id), p => p.status === 'ready', 15_000, 10 * 60_000);
-            if (timedOut) {
-                return { content: [{ type: 'text', text: JSON.stringify({
-                                prototype_id: bifocalResult.prototype_id,
-                                message: 'Prototype is still building after 10 minutes. Call get_prototypes with prototype_id to check when it\'s ready.',
-                            }, null, 2) }] };
-            }
-            return { content: [{ type: 'text', text: JSON.stringify(prototype, null, 2) }] };
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
         }
         if (name === 'update_prototype') {
-            const { project_id, prototype_id, message, coding_agent } = args;
+            const { prototype_id, message, coding_agent } = args;
             if (coding_agent === 'client') {
                 return { content: [{ type: 'text', text: JSON.stringify({
                                 prototype_id,
@@ -505,25 +583,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 ],
                             }, null, 2) }] };
             }
-            await updatePrototype(prototype_id, message);
-            const { result: prototype, timedOut } = await pollUntilReady(() => getPrototype(project_id, prototype_id), p => p.status === 'ready', 15_000, 10 * 60_000);
-            if (timedOut) {
-                return { content: [{ type: 'text', text: JSON.stringify({
-                                prototype_id,
-                                message: 'Prototype is still building after 10 minutes. Call get_prototypes with prototype_id to check when it\'s ready.',
-                            }, null, 2) }] };
-            }
-            return { content: [{ type: 'text', text: JSON.stringify(prototype, null, 2) }] };
+            const result = await updatePrototype(prototype_id, message);
+            return { content: [{ type: 'text', text: JSON.stringify({
+                            ...result,
+                            message: 'Edit queued. Call get_prototype to poll until status returns to "ready".',
+                        }, null, 2) }] };
         }
         if (name === 'get_prototypes') {
-            const { project_id, prototype_id } = args;
-            if (prototype_id) {
-                const prototype = await getPrototype(project_id, prototype_id);
-                return { content: [{ type: 'text', text: JSON.stringify(prototype, null, 2) }] };
-            }
+            const { project_id } = args;
             const prototypes = await getPrototypes(project_id);
             return { content: [{ type: 'text', text: JSON.stringify(prototypes, null, 2) }] };
         }
+        if (name === 'get_prototype') {
+            const { project_id, prototype_id } = args;
+            const prototype = await getPrototype(project_id, prototype_id);
+            return { content: [{ type: 'text', text: JSON.stringify(prototype, null, 2) }] };
+        }
         if (name === 'export_prototype') {
             const { project_id, prototype_id, output_dir } = args;
             const { downloadUrl, fileName } = await exportPrototype(project_id, prototype_id);
@@ -536,6 +611,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             await writeFile(filePath, buffer);
             return { content: [{ type: 'text', text: `Saved to ${filePath}` }] };
         }
+        if (name === 'screenshot_prototype') {
+            const { prototype_id, path, interaction_steps } = args;
+            const { screenshot, mime_type } = await screenshotPrototype(prototype_id, path, interaction_steps);
+            return { content: [{ type: 'image', data: screenshot, mimeType: mime_type }] };
+        }
         return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
     }
     catch (error) {
@@ -545,115 +625,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
     }
 });
-const PRIMER = `# Bifocal — What It Is and How to Use It
-
-## What is Bifocal?
-Bifocal is a product discovery platform. It takes raw user research (interview transcripts, usability session notes, feedback documents) and turns it into structured insights, then uses those insights to generate and iterate on interactive prototypes — all without writing code manually.
-
-The typical use case: a product team has run user research sessions. They upload the raw feedback into Bifocal, which analyzes it and extracts structured insights (barriers, goals, mention counts). They then use those insights to generate solution hypotheses and working prototypes to test with users.
-
-## Core Concepts
-
-**Project**
-The top-level container. Represents a product area or research initiative (e.g. "Onboarding Flow Redesign"). Holds all the feedback, insights, solutions, and prototypes for that initiative.
-
-**Feedback**
-Raw user research uploaded to a project — interview transcripts, session notes, usability findings. Bifocal processes this into structured insights.
-
-**Insight**
-A structured finding extracted from feedback. Each insight has a title, description, category, user goal, specific barriers, affected pages, and a mention count (how many feedback sessions surfaced this issue). Insights are ordered by mention count — higher count = more critical.
-
-**Solution**
-A hypothesis for how to address one or more insights. Contains a set of interventions — each intervention targets a specific barrier and describes exact UI/UX changes to make (which pages to modify, what to change, why). Solutions are generated from insights but can also be created manually.
-
-**Prototype**
-A working, deployed web app (Vite + React) built from a solution. Accessible at a public URL. Prototypes are either generated by Bifocal's coding agent from a solution spec, or built locally and imported. Each prototype forks from a base prototype and only applies the changes described in its solution.
-
-**Context**
-Reusable reference material attached to a project — design tokens, component specs, brand guidelines, page layouts. Contexts are injected into solution and prototype generation to ensure consistency.
-
-## Data Model
-\`\`\`
-Project
-  └── Feedback (raw research)
-  └── Insights (structured findings, ordered by mention_count)
-  └── Contexts (design system, brand guidelines)
-  └── Solutions (hypotheses built from insights)
-        └── Prototype (deployed web app)
-\`\`\`
-
-## Standard Workflow
-
-1. **Orient** — call \`list_projects\` to find the project, then \`get_insights\` to understand what the research says. Insights with high mention counts are the most critical to address.
-
-2. **Plan** — select 1–3 insights to address. Consider the user's goal and any constraints. Optionally call \`get_contexts\` to understand design constraints.
-
-3. **Generate a solution** — call \`generate_solution\` with the selected insight IDs, a goal, and any constraints. Blocks until ready and returns the full solution detail — typically 1–2 minutes.
-
-4. **Build a prototype** — call \`generate_prototype\` with the solution ID. Blocks until the prototype is ready and returns the full detail including \`published_url\` — typically 3–5 minutes.
-
-5. **Iterate** — use \`update_prototype\` to refine a prototype with specific edit instructions, or generate a new solution from different insights. Use \`add_feedback\` to log what you learn from testing.
-
-## Tool Reference by Category
-
-**Finding your project**
-- \`list_projects\` — start here, always
-
-**Understanding the research**
-- \`get_insights\` — structured findings ordered by mention count; read these before generating anything
-- \`get_quotes\` — raw supporting quotes for a specific insight; use when you need more evidence
-
-**Design system / constraints**
-- \`get_contexts\` — read design tokens, component specs, brand guidelines for the project
-- \`create_context\` — add new context (design system, brand guidelines, etc.)
-
-**Solutions**
-- \`generate_solution\` — async; requires insight IDs, optional goal + constraints; always elicit these from the user first
-- \`get_solutions\` — list all solutions, or pass solution_id for full detail including interventions and page changes
-- \`create_solution\` — manually specify a solution without using the generator
-- \`update_solution\` — modify an existing solution
-
-**Prototypes**
-- \`generate_prototype\` — async; builds from a solution; use \`coding_agent: "bifocal"\` (default) or \`"client"\` (to build locally)
-- \`get_prototypes\` — list all prototypes, or pass prototype_id for full detail including sitemap; use to poll for ready status
-- \`update_prototype\` — async edit instruction to an existing prototype; use for targeted refinements
-- \`export_prototype\` — download source as ZIP for local editing
-- \`import_prototype\` — upload a locally built or edited ZIP; includes platform-specific instructions
-
-**Feedback**
-- \`add_feedback\` — add text or PDF research to a project, linked to a prototype
-
-## Key Behaviors to Know
-
-- **Blocking operations**: \`generate_solution\`, \`generate_prototype\`, and \`update_prototype\` block until the result is ready and return the full detail directly — no polling needed. If they time out, they return a message with the ID so you can check status manually via \`get_solutions\` or \`get_prototypes\`.
-
-- **Base prototype**: Every project has a base prototype that all solution prototypes fork from. The base prototype ID is resolved automatically by \`generate_prototype\` — you do not need to specify it.
-
-- **Client vs Bifocal coding agent**: \`generate_prototype\` and \`update_prototype\` both support \`coding_agent: "client"\`. Use this when you want to build or edit the prototype locally (exports the spec + base code, you implement and import back). Use \`"bifocal"\` (default) when you want Bifocal to build it automatically.
-
-- **Solution elicitation**: Before calling \`generate_solution\`, always show the user the available insights and ask which to prioritize, what the goal is, and whether there are constraints. The tool description spells this out explicitly.
-
-- **Prototype forking**: Prototypes are built from a base, so each one only contains the changes from its solution — not the entire app. When comparing prototypes, they share the same baseline.
-`;
-server.setRequestHandler(ListResourcesRequestSchema, async () => ({
-    resources: [
-        {
-            uri: 'bifocal://primer',
-            name: 'Bifocal Primer',
-            description: 'Start here — overview of what Bifocal is, core concepts, data model, standard workflow, and tool reference. Read this before using any tools.',
-            mimeType: 'text/markdown',
-        },
-    ],
-}));
-server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-    const { uri } = request.params;
-    if (uri === 'bifocal://primer') {
-        return {
-            contents: [{ uri, mimeType: 'text/markdown', text: PRIMER }],
-        };
-    }
-    throw new Error(`Unknown resource: ${uri}`);
-});
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bifocal/mcp",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Bifocal MCP server — access projects, insights, and prototypes from Claude",
   "type": "module",
   "main": "dist/index.js",