@bifocal/mcp 0.1.5 → 0.1.7

package/dist/index.js

@@ -1,16 +1,43 @@
 #!/usr/bin/env node
 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 { 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 { writeFile } from 'fs/promises';
 import { join } from 'path';
-const server = new Server({ name: 'bifocal', version: '0.1.0' }, { capabilities: { tools: {} } });
+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: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         {
             name: 'import_prototype',
-            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.',
+            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.`,
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -36,21 +63,6 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 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.',
@@ -106,7 +118,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             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.',
+            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.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -132,7 +144,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             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. This is async — use get_solutions to check when the solution appears. 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. Blocks until the solution is ready and returns the full detail. The base prototype is resolved automatically.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -147,7 +159,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             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_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.',
+            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>',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -190,7 +202,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             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_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.',
+            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>',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -233,30 +245,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: 'get_solutions',
-            description: 'Get all solutions for a Bifocal project. Returns title, brief, barriers addressed, and prototype link (if one was generated) for each solution.',
+            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).',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    project_id: { type: 'string', description: 'The ID of the project to fetch solutions for.' },
+                    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.' },
                 },
                 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\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.',
+            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.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -269,40 +270,30 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: 'update_prototype',
-            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.',
+            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.',
             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: ['prototype_id', 'message'],
+                required: ['project_id', 'prototype_id', 'message'],
             },
         },
         {
             name: 'get_prototypes',
-            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.',
+            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.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    project_id: { type: 'string', description: 'The ID of the project to fetch prototypes for.' },
+                    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.' },
                 },
                 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.',
@@ -375,58 +366,6 @@ 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 });
@@ -462,7 +401,7 @@ Bifocal requires a Vite + React single-page app containing only the experience b
             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 get_import_instructions first to get platform-specific requirements for preparing the zip, then call import_prototype.",
+                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.",
             };
             return { content: [{ type: 'text', text: JSON.stringify(response, null, 2) }] };
         }
@@ -497,11 +436,15 @@ Bifocal requires a Vite + React single-page app containing only the experience b
             if (!basePrototype) {
                 throw new Error('No base prototype found for this project. A ready prototype with no parent is required.');
             }
-            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) }] };
+            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) }] };
         }
         if (name === 'create_solution') {
             const { project_id, title, brief, category, barriers_addressed, interventions, assumptions, open_concerns, insight_ids } = args;
@@ -517,15 +460,14 @@ Bifocal requires a Vite + React single-page app containing only the experience b
             return { content: [{ type: 'text', text: JSON.stringify({ ...result, message: 'Solution updated.' }, null, 2) }] };
         }
         if (name === 'get_solutions') {
-            const { project_id } = args;
+            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 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);
@@ -540,10 +482,18 @@ Bifocal requires a Vite + React single-page app containing only the experience b
                                 ],
                             }, null, 2) }] };
             }
-            return { content: [{ type: 'text', text: JSON.stringify(result, 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) }] };
         }
         if (name === 'update_prototype') {
-            const { prototype_id, message, coding_agent } = args;
+            const { project_id, prototype_id, message, coding_agent } = args;
             if (coding_agent === 'client') {
                 return { content: [{ type: 'text', text: JSON.stringify({
                                 prototype_id,
@@ -555,22 +505,25 @@ Bifocal requires a Vite + React single-page app containing only the experience b
                                 ],
                             }, 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) }] };
+            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) }] };
         }
         if (name === 'get_prototypes') {
-            const { project_id } = args;
+            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 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);
@@ -592,6 +545,115 @@ Bifocal requires a Vite + React single-page app containing only the experience b
         };
     }
 });
+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.5",
+  "version": "0.1.7",
   "description": "Bifocal MCP server — access projects, insights, and prototypes from Claude",
   "type": "module",
   "main": "dist/index.js",