@bifocal/mcp 0.1.3 → 0.1.5

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,11 +111,47 @@ export async function getPrototype(projectId, prototypeId) {
 export async function exportPrototype(projectId, prototypeId) {
     return get(`/api/projects/${projectId}/prototypes/${prototypeId}/download-zip`);
 }
-export async function importPrototypeUploadUrl(projectId, prototypeName, filename) {
+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(() => ({}));
+        throw new Error(error.error || `Request failed: ${response.status}`);
+    }
+    return response.json();
+}
+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

@@ -2,7 +2,7 @@
 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 } from './bifocalClient.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: {} } });
@@ -10,15 +10,16 @@ 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'],
             },
         },
         {
@@ -141,6 +254,32 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 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.',
+            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.',
@@ -183,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);
@@ -341,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);
@@ -359,6 +526,41 @@ Bifocal requires a Vite + React single-page app containing only the experience b
             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);
+            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);

package/package.json

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