@bifocal/mcp 0.1.4 → 0.1.6

package/dist/bifocalClient.js

@@ -17,11 +17,39 @@ async function get(path) {
     }
     return response.json();
 }
-export async function generateSolution(projectId, insightIds, prototypeId, goal, constraints) {
+export async function getContexts(projectId) {
+    const data = await get(`/api/projects/${projectId}/contexts`);
+    return data.contexts;
+}
+export async function createSolution(projectId, title, brief, category, barriers_addressed, interventions, assumptions, open_concerns, insight_ids) {
+    const response = await fetch(`${API_URL}/api/projects/${projectId}/solutions`, {
+        method: 'POST',
+        headers: headers(),
+        body: JSON.stringify({ title, brief, category, barriers_addressed, interventions, assumptions, open_concerns, insight_ids }),
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({}));
+        throw new Error(error.error || `Request failed: ${response.status}`);
+    }
+    return response.json();
+}
+export async function createContext(projectId, name, type, content, description) {
+    const response = await fetch(`${API_URL}/api/projects/${projectId}/contexts`, {
+        method: 'POST',
+        headers: headers(),
+        body: JSON.stringify({ name, type, content, description }),
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({}));
+        throw new Error(error.error || `Request failed: ${response.status}`);
+    }
+    return response.json();
+}
+export async function generateSolution(projectId, insightIds, prototypeId, goal, constraints, contextIds) {
     const response = await fetch(`${API_URL}/api/projects/${projectId}/solutions/generate`, {
         method: 'POST',
         headers: headers(),
-        body: JSON.stringify({ insightIds, prototypeId, goal, constraints }),
+        body: JSON.stringify({ insightIds, prototypeId, goal, constraints, contextIds }),
     });
     if (!response.ok) {
         const error = await response.json().catch(() => ({}));
@@ -83,10 +111,35 @@ export async function getPrototype(projectId, prototypeId) {
 export async function exportPrototype(projectId, prototypeId) {
     return get(`/api/projects/${projectId}/prototypes/${prototypeId}/download-zip`);
 }
-export async function generatePrototype(projectId, solutionId) {
+export async function updateSolution(projectId, solutionId, updates) {
+    const response = await fetch(`${API_URL}/api/projects/${projectId}/solutions/${solutionId}`, {
+        method: 'PATCH',
+        headers: headers(),
+        body: JSON.stringify(updates),
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({}));
+        throw new Error(error.error || `Request failed: ${response.status}`);
+    }
+    return response.json();
+}
+export async function updatePrototype(prototypeId, message) {
+    const response = await fetch(`${API_URL}/api/prototypes/chat`, {
+        method: 'POST',
+        headers: headers(),
+        body: JSON.stringify({ prototypeId, message }),
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({}));
+        throw new Error(error.error || `Request failed: ${response.status}`);
+    }
+    return response.json();
+}
+export async function generatePrototype(projectId, solutionId, codingAgent) {
     const response = await fetch(`${API_URL}/api/projects/${projectId}/solutions/${solutionId}/generate-prototype`, {
         method: 'POST',
         headers: headers(),
+        body: codingAgent ? JSON.stringify({ coding_agent: codingAgent }) : undefined,
     });
     if (!response.ok) {
         const error = await response.json().catch(() => ({}));
@@ -94,11 +147,11 @@ export async function generatePrototype(projectId, solutionId) {
     }
     return response.json();
 }
-export async function importPrototypeUploadUrl(projectId, prototypeName, filename) {
+export async function importPrototypeUploadUrl(projectId, filename, prototypeName, prototypeId) {
     const response = await fetch(`${API_URL}/api/projects/${projectId}/prototypes/import/upload-url`, {
         method: 'POST',
         headers: headers(),
-        body: JSON.stringify({ prototype_name: prototypeName, filename }),
+        body: JSON.stringify({ prototype_name: prototypeName, filename, prototype_id: prototypeId }),
     });
     if (!response.ok) {
         const error = await response.json().catch(() => ({}));

package/dist/index.js

@@ -1,24 +1,25 @@
 #!/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 { createProject, updateProject, listProjects, importPrototypeUploadUrl, importPrototypeConfirm, addFeedbackText, generateSolution, getInsights, getQuotes, getSolutions, getSolution, getPrototypes, getPrototype, exportPrototype, generatePrototype } from './bifocalClient.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: {} } });
+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.',
+            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: {
                     project_id: { type: 'string', description: 'The ID of the project to import into.' },
-                    prototype_name: { type: 'string', description: 'A name for the prototype.' },
+                    prototype_name: { type: 'string', description: 'A name for the prototype. Required when creating a new prototype (no prototype_id).' },
                     zip_path: { type: 'string', description: 'Absolute path to the zip file on the local filesystem.' },
+                    prototype_id: { type: 'string', description: 'If provided, updates this existing prototype instead of creating a new one. Use this after building or editing a prototype locally.' },
                 },
-                required: ['project_id', 'prototype_name', 'zip_path'],
+                required: ['project_id', 'zip_path'],
             },
         },
         {
@@ -103,19 +104,131 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ['project_id', 'insight_id'],
             },
         },
+        {
+            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.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_id: { type: 'string', description: 'The ID of the project.' },
+                    name: { type: 'string', description: 'A short name for the context (e.g. "Brand Guidelines", "Design System").' },
+                    type: { type: 'string', description: 'The type of context (e.g. "product", "design", "brand", "research", "other").' },
+                    content: { type: 'string', description: 'The full text content of the context.' },
+                    description: { type: 'string', description: 'Optional short description of what this context contains.' },
+                },
+                required: ['project_id', 'name', 'type', 'content'],
+            },
+        },
+        {
+            name: 'get_contexts',
+            description: 'Get all contexts for a Bifocal project. Contexts contain product, design, or other reference material that can be attached to a solution to guide generation. Call this before generate_solution if you want to include context.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_id: { type: 'string', description: 'The ID of the project.' },
+                },
+                required: ['project_id'],
+            },
+        },
         {
             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. Only call this tool once you have that input. This is async — use get_solutions to check when the solution appears.',
+            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: {
                     project_id: { type: 'string', description: 'The ID of the project.' },
                     insight_ids: { type: 'array', items: { type: 'string' }, description: 'IDs of insights to base the solution on. Use get_insights to find them.' },
-                    prototype_id: { type: 'string', description: 'The ID of the prototype to use as context for the solution.' },
                     goal: { type: 'string', description: 'Optional goal or focus for the solution.' },
                     constraints: { type: 'string', description: 'Optional constraints to consider.' },
+                    context_ids: { type: 'array', items: { type: 'string' }, description: 'Optional IDs of contexts to attach. Use get_contexts to find them.' },
+                },
+                required: ['project_id', 'insight_ids'],
+            },
+        },
+        {
+            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.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_id: { type: 'string', description: 'The ID of the project.' },
+                    title: { type: 'string', description: 'Concise name for the solution (e.g. "Condensed Flow with Unified Plan Builder").' },
+                    brief: { type: 'string', description: '1-2 sentence summary of what the solution does and why.' },
+                    category: { type: 'string', enum: ['feature', 'design', 'copy', 'content', 'flow', 'pricing', 'simplification', 'other'], description: 'Category that best describes the type of change.' },
+                    barriers_addressed: { type: 'array', items: { type: 'string' }, description: 'List of user barriers or pain points this solution directly addresses.' },
+                    interventions: {
+                        type: 'array',
+                        description: 'One or more interventions, each addressing a specific barrier. Each intervention contains a set of concrete UI/UX changes to implement.',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                barrier: { type: 'string', description: 'The specific barrier or problem this intervention targets.' },
+                                changes: {
+                                    type: 'array',
+                                    description: 'Concrete changes to implement for this barrier.',
+                                    items: {
+                                        type: 'object',
+                                        properties: {
+                                            approach: { type: 'string', description: 'Short name/headline for this change (e.g. "Add frequency price cards to step 13").' },
+                                            description: { type: 'string', description: 'Detailed description of what to build or change, including layout, copy, interactions, and any edge cases. Be specific enough for a coding agent to implement it.' },
+                                            pages_to_modify: { type: 'array', items: { type: 'string' }, description: 'Existing page route paths to modify (e.g. ["/onboarding/step-13"]). Empty array if none.' },
+                                            pages_to_create: { type: 'array', items: { type: 'string' }, description: 'New page route paths to create (e.g. ["/menu-preview"]). Empty array if none.' },
+                                        },
+                                        required: ['approach', 'description', 'pages_to_modify', 'pages_to_create'],
+                                    },
+                                },
+                            },
+                            required: ['barrier', 'changes'],
+                        },
+                    },
+                    assumptions: { type: 'array', items: { type: 'string' }, description: 'Assumptions this solution makes about the product, users, or implementation. Use an empty array if none.' },
+                    open_concerns: { type: 'array', items: { type: 'string' }, description: 'Open questions, risks, or things to validate. Use an empty array if none.' },
+                    insight_ids: { type: 'array', items: { type: 'string' }, description: 'IDs of insights this solution addresses. Use get_insights to find them.' },
                 },
-                required: ['project_id', 'insight_ids', 'prototype_id'],
+                required: ['project_id', 'title', 'brief', 'category', 'barriers_addressed', 'interventions', 'assumptions', 'open_concerns', 'insight_ids'],
+            },
+        },
+        {
+            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.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_id: { type: 'string', description: 'The ID of the project.' },
+                    solution_id: { type: 'string', description: 'The ID of the solution to update.' },
+                    title: { type: 'string', description: 'Updated title for the solution.' },
+                    brief: { type: 'string', description: 'Updated 1-2 sentence summary.' },
+                    category: { type: 'string', enum: ['feature', 'design', 'copy', 'content', 'flow', 'pricing', 'simplification', 'other'], description: 'Updated category.' },
+                    barriers_addressed: { type: 'array', items: { type: 'string' }, description: 'Full replacement list of barriers addressed.' },
+                    interventions: {
+                        type: 'array',
+                        description: 'Full replacement list of interventions. If provided, selected_changes will be re-derived automatically.',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                barrier: { type: 'string', description: 'The specific barrier this intervention targets.' },
+                                changes: {
+                                    type: 'array',
+                                    items: {
+                                        type: 'object',
+                                        properties: {
+                                            approach: { type: 'string' },
+                                            description: { type: 'string' },
+                                            pages_to_modify: { type: 'array', items: { type: 'string' } },
+                                            pages_to_create: { type: 'array', items: { type: 'string' } },
+                                        },
+                                        required: ['approach', 'description', 'pages_to_modify', 'pages_to_create'],
+                                    },
+                                },
+                            },
+                            required: ['barrier', 'changes'],
+                        },
+                    },
+                    assumptions: { type: 'array', items: { type: 'string' }, description: 'Full replacement list of assumptions.' },
+                    open_concerns: { type: 'array', items: { type: 'string' }, description: 'Full replacement list of open concerns.' },
+                    insight_ids: { type: 'array', items: { type: 'string' }, description: 'Full replacement list of insight IDs. Replaces all existing links.' },
+                },
+                required: ['project_id', 'solution_id'],
             },
         },
         {
@@ -143,16 +256,30 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: 'generate_prototype',
-            description: 'Generate a prototype from a solution. This queues an async build — call get_prototype with the returned prototype_id to check when status changes to "ready". If a prototype already exists for the solution, returns it immediately.',
+            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: {
                     project_id: { type: 'string', description: 'The ID of the project.' },
                     solution_id: { type: 'string', description: 'The ID of the solution to generate a prototype from.' },
+                    coding_agent: { type: 'string', enum: ['bifocal', 'client'], description: 'Who will build the prototype. "bifocal" (default) queues it to Bifocal\'s agent. "client" returns the spec for the calling agent to build locally.' },
                 },
                 required: ['project_id', 'solution_id'],
             },
         },
+        {
+            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.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    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'],
+            },
+        },
         {
             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.',
@@ -195,10 +322,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
         if (name === 'import_prototype') {
-            const { project_id, prototype_name, zip_path } = args;
+            const { project_id, prototype_name, zip_path, prototype_id: existingPrototypeId } = args;
             const filename = zip_path.split('/').pop() || 'prototype.zip';
             // Step 1: get presigned upload URL
-            const uploadResult = await importPrototypeUploadUrl(project_id, prototype_name, filename);
+            const uploadResult = await importPrototypeUploadUrl(project_id, filename, prototype_name, existingPrototypeId);
             if (uploadResult.warning) {
                 // Surface warning but continue
                 console.warn('[import_prototype]', uploadResult.warning);
@@ -353,14 +480,42 @@ Bifocal requires a Vite + React single-page app containing only the experience b
             const quotes = await getQuotes(project_id, insight_id);
             return { content: [{ type: 'text', text: JSON.stringify(quotes, null, 2) }] };
         }
+        if (name === 'create_context') {
+            const { project_id, name: contextName, type, content, description } = args;
+            const result = await createContext(project_id, contextName, type, content, description);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        if (name === 'get_contexts') {
+            const { project_id } = args;
+            const contexts = await getContexts(project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(contexts, null, 2) }] };
+        }
         if (name === 'generate_solution') {
-            const { project_id, insight_ids, prototype_id, goal, constraints } = args;
-            const result = await generateSolution(project_id, insight_ids, prototype_id, goal, constraints);
+            const { project_id, insight_ids, goal, constraints, context_ids } = args;
+            const prototypes = await getPrototypes(project_id);
+            const basePrototype = prototypes.find(p => p.parent_prototype_id === null && p.status === 'ready');
+            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) }] };
         }
+        if (name === 'create_solution') {
+            const { project_id, title, brief, category, barriers_addressed, interventions, assumptions, open_concerns, insight_ids } = args;
+            const result = await createSolution(project_id, title, brief, category, barriers_addressed, interventions, assumptions, open_concerns, insight_ids);
+            return { content: [{ type: 'text', text: JSON.stringify({
+                            ...result,
+                            message: 'Solution created. Call generate_prototype to build a prototype from it.',
+                        }, null, 2) }] };
+        }
+        if (name === 'update_solution') {
+            const { project_id, solution_id, title, brief, category, barriers_addressed, interventions, assumptions, open_concerns, insight_ids } = args;
+            const result = await updateSolution(project_id, solution_id, { title, brief, category, barriers_addressed, interventions, assumptions, open_concerns, insight_ids });
+            return { content: [{ type: 'text', text: JSON.stringify({ ...result, message: 'Solution updated.' }, null, 2) }] };
+        }
         if (name === 'get_solutions') {
             const { project_id } = args;
             const solutions = await getSolutions(project_id);
@@ -372,10 +527,40 @@ Bifocal requires a Vite + React single-page app containing only the experience b
             return { content: [{ type: 'text', text: JSON.stringify(solution, null, 2) }] };
         }
         if (name === 'generate_prototype') {
-            const { project_id, solution_id } = args;
-            const result = await generatePrototype(project_id, solution_id);
+            const { project_id, solution_id, coding_agent } = args;
+            const result = await generatePrototype(project_id, solution_id, coding_agent);
+            if (coding_agent === 'client') {
+                const clientResult = result;
+                return { content: [{ type: 'text', text: JSON.stringify({
+                                ...clientResult,
+                                instructions: [
+                                    `1. Call export_prototype with project_id and base_prototype_id to download the base code.`,
+                                    `2. Unzip and implement the changes described in solution.interventions. Apply org contexts (design system, brand guidelines) if provided.`,
+                                    `3. Zip the result and call import_prototype with project_id, zip_path, and prototype_id (${clientResult.prototype_id}).`,
+                                ],
+                            }, null, 2) }] };
+            }
             return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
         }
+        if (name === 'update_prototype') {
+            const { prototype_id, message, coding_agent } = args;
+            if (coding_agent === 'client') {
+                return { content: [{ type: 'text', text: JSON.stringify({
+                                prototype_id,
+                                edit_instruction: message,
+                                instructions: [
+                                    `1. Call export_prototype to download the current prototype code.`,
+                                    `2. Unzip and apply the edit instruction above.`,
+                                    `3. Zip the result and call import_prototype with project_id, zip_path, and prototype_id (${prototype_id}).`,
+                                ],
+                            }, 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 } = args;
             const prototypes = await getPrototypes(project_id);
@@ -407,6 +592,117 @@ 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. This is async — the solution appears in \`get_solutions\` within 1–2 minutes. Always call \`get_solution\` after to read the full intervention detail.
+
+4. **Build a prototype** — call \`generate_prototype\` with the solution ID. Bifocal's coding agent builds a working app. This is async — poll \`get_prototype\` until status is \`ready\` (typically 3–5 minutes). The \`published_url\` is the live prototype.
+
+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; use to check if generation is complete
+- \`get_solution\` — full detail including interventions and page changes; always call after generation
+- \`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_prototype\` — full detail including sitemap; use to poll for ready status
+- \`get_prototypes\` — list all prototypes for a project
+- \`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; always call \`get_import_instructions\` first
+
+**Feedback**
+- \`add_feedback\` — add text or PDF research to a project, linked to a prototype
+
+## Key Behaviors to Know
+
+- **Async operations**: \`generate_solution\`, \`generate_prototype\`, and \`update_prototype\` are all async. After calling them, poll the corresponding getter (\`get_solutions\`/\`get_prototype\`) until the result appears. Do not assume they complete immediately.
+
+- **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.4",
+  "version": "0.1.6",
   "description": "Bifocal MCP server — access projects, insights, and prototypes from Claude",
   "type": "module",
   "main": "dist/index.js",