@bifocal/mcp 0.1.0

package/dist/bifocalClient.js

@@ -0,0 +1,72 @@
+const API_KEY = process.env.BIFOCAL_API_KEY;
+const API_URL = process.env.BIFOCAL_API_URL || 'https://api.bifocal.ai';
+if (!API_KEY) {
+    throw new Error('BIFOCAL_API_KEY environment variable is required');
+}
+function headers() {
+    return {
+        'Authorization': `Bearer ${API_KEY}`,
+        'Content-Type': 'application/json',
+    };
+}
+async function get(path) {
+    const response = await fetch(`${API_URL}${path}`, { headers: headers() });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({}));
+        throw new Error(error.error || `Request failed: ${response.status}`);
+    }
+    return response.json();
+}
+export async function updateProject(projectId, updates) {
+    const response = await fetch(`${API_URL}/api/projects/${projectId}`, {
+        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 createProject(name, description) {
+    const response = await fetch(`${API_URL}/api/projects`, {
+        method: 'POST',
+        headers: headers(),
+        body: JSON.stringify({ name, 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 listProjects() {
+    const data = await get('/api/projects');
+    return data.projects;
+}
+export async function getInsights(projectId) {
+    const data = await get(`/api/projects/${projectId}/insights`);
+    return data.insights;
+}
+export async function getQuotes(projectId, insightId) {
+    const data = await get(`/api/projects/${projectId}/insights/${insightId}/quotes`);
+    return data.quotes;
+}
+export async function getSolutions(projectId) {
+    const data = await get(`/api/projects/${projectId}/solutions`);
+    return data.solutions;
+}
+export async function getSolution(projectId, solutionId) {
+    return get(`/api/projects/${projectId}/solutions/${solutionId}`);
+}
+export async function getPrototypes(projectId) {
+    const data = await get(`/api/projects/${projectId}/prototypes`);
+    return data.prototypes;
+}
+export async function getPrototype(projectId, prototypeId) {
+    return get(`/api/projects/${projectId}/prototypes/${prototypeId}`);
+}
+export async function exportPrototype(projectId, prototypeId) {
+    return get(`/api/projects/${projectId}/prototypes/${prototypeId}/download-zip`);
+}

package/dist/index.js

@@ -0,0 +1,225 @@
+#!/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, getInsights, getQuotes, getSolutions, getSolution, getPrototypes, getPrototype, exportPrototype } from './bifocalClient.js';
+import { writeFile } from 'fs/promises';
+import { join } from 'path';
+const server = new Server({ name: 'bifocal', version: '0.1.0' }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            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.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'The name of the project.' },
+                    description: { type: 'string', description: 'Optional PRD or context for the project.' },
+                },
+                required: ['name'],
+            },
+        },
+        {
+            name: 'update_project',
+            description: 'Update a Bifocal project\'s name or description/context.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_id: { type: 'string', description: 'The ID of the project to update.' },
+                    name: { type: 'string', description: 'New name for the project.' },
+                    description: { type: 'string', description: 'Updated PRD or context for the project.' },
+                },
+                required: ['project_id'],
+            },
+        },
+        {
+            name: 'list_projects',
+            description: 'List all Bifocal projects for the authenticated user.',
+            inputSchema: { type: 'object', properties: {}, required: [] },
+        },
+        {
+            name: 'get_insights',
+            description: 'Get all insights for a Bifocal project. Returns structured data including the user goal, problem, specific barriers, and mention count for each insight. Results are ordered by mention count descending.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_id: { type: 'string', description: 'The ID of the project to fetch insights for.' },
+                },
+                required: ['project_id'],
+            },
+        },
+        {
+            name: 'get_quotes',
+            description: 'Get supporting user quotes for a specific insight. Call this when the user wants to see evidence or examples behind a particular insight.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_id: { type: 'string', description: 'The ID of the project the insight belongs to.' },
+                    insight_id: { type: 'string', description: 'The ID of the insight to fetch quotes for.' },
+                },
+                required: ['project_id', 'insight_id'],
+            },
+        },
+        {
+            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.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_id: { type: 'string', description: 'The ID of the project to fetch solutions for.' },
+                },
+                required: ['project_id'],
+            },
+        },
+        {
+            name: 'get_solution',
+            description: 'Get full detail for a specific solution including all proposed interventions and page changes. Call this when the user wants to understand what a solution proposes to change.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_id: { type: 'string', description: 'The ID of the project the solution belongs to.' },
+                    solution_id: { type: 'string', description: 'The ID of the solution to fetch.' },
+                },
+                required: ['project_id', 'solution_id'],
+            },
+        },
+        {
+            name: '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.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_id: { type: 'string', description: 'The ID of the project to fetch prototypes for.' },
+                },
+                required: ['project_id'],
+            },
+        },
+        {
+            name: 'get_prototype',
+            description: 'Get full detail for a specific prototype including its sitemap and key capabilities. Use this when you need to understand what pages exist in a prototype.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_id: { type: 'string', description: 'The ID of the project the prototype belongs to.' },
+                    prototype_id: { type: 'string', description: 'The ID of the prototype to fetch.' },
+                },
+                required: ['project_id', 'prototype_id'],
+            },
+        },
+        {
+            name: 'export_prototype',
+            description: 'Download a prototype\'s source code as a ZIP file and save it to the local filesystem. Returns the path where the file was saved.',
+            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 export.' },
+                    output_dir: { type: 'string', description: 'Directory to save the ZIP file. Defaults to the current working directory.' },
+                },
+                required: ['project_id', 'prototype_id'],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        if (name === 'update_project') {
+            const { project_id, name: projectName, description } = args;
+            const project = await updateProject(project_id, { name: projectName, description });
+            return { content: [{ type: 'text', text: JSON.stringify(project, null, 2) }] };
+        }
+        if (name === 'create_project') {
+            const { name: projectName } = args;
+            let description = args.description;
+            // Ask for PRD/context via elicitation if not already provided
+            if (!description) {
+                try {
+                    const result = await server.elicitInput({
+                        message: `Do you have a PRD or any context to add for "${projectName}"?`,
+                        requestedSchema: {
+                            type: 'object',
+                            properties: {
+                                description: {
+                                    type: 'string',
+                                    title: 'PRD / Context',
+                                    description: 'Paste a PRD, user research summary, or any relevant context for this project.',
+                                },
+                            },
+                        },
+                    });
+                    if (result.action === 'accept' && result.content?.description) {
+                        description = result.content.description;
+                    }
+                }
+                catch {
+                    // Client doesn't support elicitation — proceed without context
+                }
+            }
+            const project = await createProject(projectName, description);
+            return { content: [{ type: 'text', text: JSON.stringify(project, null, 2) }] };
+        }
+        if (name === 'list_projects') {
+            const projects = await listProjects();
+            return { content: [{ type: 'text', text: JSON.stringify(projects, null, 2) }] };
+        }
+        if (name === 'get_insights') {
+            const { project_id } = args;
+            const insights = await getInsights(project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(insights, null, 2) }] };
+        }
+        if (name === 'get_quotes') {
+            const { project_id, insight_id } = args;
+            const quotes = await getQuotes(project_id, insight_id);
+            return { content: [{ type: 'text', text: JSON.stringify(quotes, null, 2) }] };
+        }
+        if (name === 'get_solutions') {
+            const { project_id } = args;
+            const solutions = await getSolutions(project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(solutions, null, 2) }] };
+        }
+        if (name === 'get_solution') {
+            const { project_id, solution_id } = args;
+            const solution = await getSolution(project_id, solution_id);
+            return { content: [{ type: 'text', text: JSON.stringify(solution, null, 2) }] };
+        }
+        if (name === 'get_prototypes') {
+            const { project_id } = args;
+            const prototypes = await getPrototypes(project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(prototypes, null, 2) }] };
+        }
+        if (name === 'get_prototype') {
+            const { project_id, prototype_id } = args;
+            const prototype = await getPrototype(project_id, prototype_id);
+            return { content: [{ type: 'text', text: JSON.stringify(prototype, null, 2) }] };
+        }
+        if (name === 'export_prototype') {
+            const { project_id, prototype_id, output_dir } = args;
+            const { downloadUrl, fileName } = await exportPrototype(project_id, prototype_id);
+            const response = await fetch(downloadUrl);
+            if (!response.ok)
+                throw new Error(`Failed to download zip: ${response.status}`);
+            const buffer = Buffer.from(await response.arrayBuffer());
+            const dir = output_dir || process.cwd();
+            const filePath = join(dir, fileName);
+            await writeFile(filePath, buffer);
+            return { content: [{ type: 'text', text: `Saved to ${filePath}` }] };
+        }
+        return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+    }
+    catch (error) {
+        return {
+            content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}` }],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error('MCP server error:', error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@bifocal/mcp",
+  "version": "0.1.0",
+  "description": "Bifocal MCP server — access projects, insights, and prototypes from Claude",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "bifocal-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "tsc"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.2"
+  }
+}