@bifocal/mcp 0.1.6 → 0.1.8

package/dist/bifocalClient.js

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

package/dist/index.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { createProject, updateProject, listProjects, importPrototypeUploadUrl, importPrototypeConfirm, addFeedbackText, generateSolution, getInsights, getQuotes, getSolutions, getSolution, getPrototypes, getPrototype, exportPrototype, generatePrototype, updatePrototype, getContexts, createContext, createSolution, updateSolution } from './bifocalClient.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { createProject, updateProject, listProjects, importPrototypeUploadUrl, importPrototypeConfirm, addFeedbackText, generateSolution, getInsights, getQuotes, getSolutions, getSolution, getPrototypes, getPrototype, exportPrototype, generatePrototype, updatePrototype, getContexts, createContext, createSolution, updateSolution, screenshotPrototype } from './bifocalClient.js';
 import { writeFile } from 'fs/promises';
 import { join } from 'path';
-const server = new Server({ name: 'bifocal', version: '0.1.0' }, { capabilities: { tools: {}, resources: {} } });
+const server = new Server({ name: 'bifocal', version: '0.1.0' }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         {
@@ -316,6 +316,34 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ['project_id', 'prototype_id'],
             },
         },
+        {
+            name: 'screenshot_prototype',
+            description: 'Capture a screenshot of a specific page or UI state in a prototype and render it inline.\n\nBefore calling, make sure you know what path to capture — get valid paths from the prototype\'s sitemap by calling get_prototypes with the prototype_id if you haven\'t already.\n\n**Choosing whether to pass interaction_steps:**\nPass interaction steps when the screen you want to capture requires user interaction to reach — this includes: a specific step in a multi-page flow that can\'t be reached by URL alone, a UI state triggered by a selection or toggle (e.g. a plan option selected, a modal open, a tab active), or any meaningful variation of a screen that differs from its default loaded state. If navigating directly to the path shows the right screen, no steps are needed.\n\nIf you need interaction steps but aren\'t sure what selectors to use, read the relevant page or component source — export the prototype first via export_prototype if you don\'t have the source locally.\n\n**IMPORTANT**: Only call this when you actually need to see something — after an edit, to evaluate a specific screen, or to compare before and after. Don\'t call it speculatively.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_id: { type: 'string', description: 'The ID of the project the prototype belongs to.' },
+                    prototype_id: { type: 'string', description: 'The ID of the prototype to screenshot.' },
+                    path: { type: 'string', description: 'The URL path to capture (e.g. "/onboarding/step-13"). Must be a real path from the prototype sitemap.' },
+                    interaction_steps: {
+                        type: 'array',
+                        description: 'Optional steps to execute before screenshotting, to reach a specific UI state.',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                action: { type: 'string', enum: ['click', 'hover', 'waitForSelector', 'waitForTimeout', 'select', 'type'] },
+                                selector: { type: 'string', description: 'CSS selector for the target element. Required for all actions except waitForTimeout.' },
+                                ms: { type: 'number', description: 'Milliseconds to wait. Required for waitForTimeout.' },
+                                value: { type: 'string', description: 'Value to select. Required for select.' },
+                                text: { type: 'string', description: 'Text to type. Required for type.' },
+                            },
+                            required: ['action'],
+                        },
+                    },
+                },
+                required: ['project_id', 'prototype_id', 'path'],
+            },
+        },
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -583,6 +611,11 @@ Bifocal requires a Vite + React single-page app containing only the experience b
             await writeFile(filePath, buffer);
             return { content: [{ type: 'text', text: `Saved to ${filePath}` }] };
         }
+        if (name === 'screenshot_prototype') {
+            const { prototype_id, path, interaction_steps } = args;
+            const { screenshot, mime_type } = await screenshotPrototype(prototype_id, path, interaction_steps);
+            return { content: [{ type: 'image', data: screenshot, mimeType: mime_type }] };
+        }
         return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
     }
     catch (error) {
@@ -592,117 +625,6 @@ 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.6",
+  "version": "0.1.8",
   "description": "Bifocal MCP server — access projects, insights, and prototypes from Claude",
   "type": "module",
   "main": "dist/index.js",