@visualprd/mcp-server 1.1.0

package/README.md

@@ -0,0 +1,396 @@
+# VisualPRD MCP Server
+
+**Intelligent Model Context Protocol server for autonomous build orchestration between VisualPRD and AI coding agents.**
+
+This MCP server acts as an intelligent middleman between your VisualPRD project and AI coding assistants like Cursor, Claude, and Windsurf. It doesn't just fetch data — it **thinks, orchestrates, adapts, and guides** the entire build process.
+
+## Features
+
+### Autonomous Decision Making
+- Tracks build prompt dependencies automatically
+- Fetches relevant context for each step
+- Validates completion before moving forward
+
+### Intelligent Context Optimization
+- Only fetches entities relevant to the current task
+- Reduces token usage by 60-80% compared to dumping all project data
+- Automatically includes design system for UI tasks
+- Includes schema relationships for database tasks
+
+### Error Detection & Recovery
+- Pattern-based error analysis for common issues
+- Suggests multiple fix approaches with confidence scores
+- Can inject new build steps when migrations are needed
+- Provides code examples for fixes
+
+### Gap Filling Intelligence
+- Detects missing authentication flows (password reset, email verification)
+- Identifies incomplete CRUD operations
+- Suggests schema field additions
+- Warns about missing error handling pages
+
+### Contextual Guidance
+- Technical considerations based on tech stack
+- Potential issues to watch out for
+- Testing criteria for each step
+- Related patterns from completed steps
+
+## Installation
+
+### Option 1: NPM (Recommended)
+
+```bash
+npm install -g @visualprd/mcp-server
+```
+
+### Option 2: From Source
+
+```bash
+cd mcp-server
+npm install
+npm run build
+npm link
+```
+
+## Configuration
+
+### For Cursor
+
+Add to your Cursor MCP settings (Settings → Extensions → MCP Servers):
+
+```json
+{
+  "mcpServers": {
+    "visualprd": {
+      "command": "visualprd-mcp",
+      "args": ["--project", "YOUR_PROJECT_ID"],
+      "env": {
+        "FIREBASE_PROJECT_ID": "visualprd-app",
+        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
+      }
+    }
+  }
+}
+```
+
+### For Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "visualprd": {
+      "command": "visualprd-mcp",
+      "args": ["--project", "YOUR_PROJECT_ID"],
+      "env": {
+        "VISUALPRD_PROJECT_ID": "YOUR_PROJECT_ID",
+        "FIREBASE_PROJECT_ID": "visualprd-app"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `VISUALPRD_PROJECT_ID` | Your VisualPRD project ID | Yes |
+| `VISUALPRD_API_KEY` | API key (if using hosted API) | No |
+| `VISUALPRD_API_URL` | API base URL | No |
+| `FIREBASE_PROJECT_ID` | Firebase project ID | For direct Firestore |
+| `GOOGLE_APPLICATION_CREDENTIALS` | Path to service account JSON | For direct Firestore |
+
+## Available Tools
+
+### `get_next_build_step`
+
+Get the next build step with full intelligent context.
+
+**Example Response:**
+```json
+{
+  "step": {
+    "promptId": "prompt-003",
+    "title": "Implement User Authentication Flow",
+    "category": "pages",
+    "instruction": "Create the LoginPage component...",
+    "estimatedMinutes": 45
+  },
+  "relatedEntities": {
+    "pages": [{ "pageName": "LoginPage", "route": "/login", ... }],
+    "schemas": [{ "collectionName": "users", "fields": [...] }],
+    "endpoints": [{ "name": "authenticateUser", "method": "POST", ... }],
+    "designSystem": { "colorPalette": {...}, "typography": {...} }
+  },
+  "contextualGuidance": {
+    "technicalConsiderations": [
+      "Use Firebase Auth SDK for authentication",
+      "Store auth state in context for app-wide access"
+    ],
+    "potentialIssues": [
+      "Remember to handle auth state persistence",
+      "Password reset flow may not be defined"
+    ],
+    "testingCriteria": [
+      "User can log in with valid credentials",
+      "Invalid credentials show error message"
+    ]
+  },
+  "buildProgress": {
+    "totalSteps": 25,
+    "completedSteps": 2,
+    "currentStep": 3,
+    "percentComplete": 8
+  }
+}
+```
+
+### `mark_step_complete`
+
+Mark a step as complete and automatically fetch the next one.
+
+**Parameters:**
+- `promptId` (required): ID of the step to mark complete
+- `completionNotes`: Description of what was done
+- `filesCreated`: Array of file paths created
+- `testResults`: Object with `passed` and `failed` counts
+
+**Example:**
+```json
+{
+  "promptId": "prompt-003",
+  "completionNotes": "LoginPage implemented with Zod validation",
+  "filesCreated": ["src/pages/LoginPage.tsx", "src/services/auth.ts"],
+  "testResults": { "passed": 8, "failed": 0 }
+}
+```
+
+### `report_error`
+
+Report an error and get intelligent diagnosis with fixes.
+
+**Parameters:**
+- `promptId` (required): Where the error occurred
+- `errorType` (required): `compile_error`, `runtime_error`, `test_failure`, `missing_dependency`, `other`
+- `errorMessage` (required): The error message
+- `stackTrace`: Stack trace if available
+- `context`: What you were doing when it occurred
+
+**Example Response:**
+```json
+{
+  "diagnosis": {
+    "rootCause": "Field 'emailVerified' is defined in schema but not in database",
+    "explanation": "The schema definition is ahead of the actual database state",
+    "severity": "high"
+  },
+  "suggestedFixes": [
+    {
+      "approach": "Database Migration",
+      "steps": [
+        "Create migration script for users collection",
+        "Add default value for emailVerified",
+        "Run migration before continuing"
+      ],
+      "code": {
+        "filename": "migrations/add-email-verified.ts",
+        "content": "// Migration script..."
+      },
+      "confidence": 0.9
+    }
+  ],
+  "shouldInjectNewStep": true,
+  "newStep": {
+    "title": "Database Migration: Add emailVerified to users",
+    "category": "database"
+  }
+}
+```
+
+### `get_entity_details`
+
+Get detailed information about a specific entity.
+
+**Parameters:**
+- `entityType` (required): `page`, `schema`, `endpoint`, `tech`
+- `entityId` (required): ID or name of the entity
+- `includeRelationships`: Include relationship info (for schemas)
+- `includeUsageExamples`: Include code examples
+
+### `get_debug_suggestions`
+
+Get AI-powered debugging suggestions when stuck.
+
+**Parameters:**
+- `currentTask` (required): What you're trying to do
+- `issue` (required): The problem you're facing
+- `context`: Additional context
+- `attemptedSolutions`: What you've already tried
+
+### `inject_dynamic_step`
+
+Add a new build step when you identify missing functionality.
+
+**Parameters:**
+- `insertAfter` (required): Prompt ID to insert after
+- `title` (required): Title of the new step
+- `category` (required): Step category
+- `reason` (required): Why this step is needed
+- `instruction` (required): Detailed instructions
+
+### `get_build_progress`
+
+Get current build progress statistics.
+
+### `get_design_system`
+
+Get the project's design system specifications.
+
+**Parameters:**
+- `section`: `all`, `colors`, `typography`, `spacing`, `components`
+
+## How It Works
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  AI Agent (Cursor/Claude/Windsurf)                          │
+│  "Help me build the next feature"                           │
+└─────────────────────┬───────────────────────────────────────┘
+                      │ MCP Protocol
+                      ↓
+┌─────────────────────────────────────────────────────────────┐
+│  VisualPRD MCP Server                                       │
+│                                                             │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  Intelligence Layer                                  │   │
+│  │  • Context Optimizer - Fetches relevant data only    │   │
+│  │  • Error Analyzer - Diagnoses issues, suggests fixes │   │
+│  │  • Gap Filler - Detects missing flows                │   │
+│  │  • Guidance Generator - Provides contextual help     │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                             │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  VisualPRD Client                                    │   │
+│  │  • Firestore connection                              │   │
+│  │  • Caching layer                                     │   │
+│  │  • Entity resolution                                 │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────┬───────────────────────────────────────┘
+                      │
+                      ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Firestore Database                                         │
+│  • projects/{projectId}/                                    │
+│    • pages/                                                 │
+│    • databaseSchemas/                                       │
+│    • apiEndpoints/                                          │
+│    • techStack/                                             │
+│    • buildPrompts/                                          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Intelligence Decision Making
+
+The server uses a tiered intelligence approach to minimize costs:
+
+1. **Rule-Based (Free)**: Simple lookups, status changes, dependency checks
+2. **Pattern Matching (Free)**: Known error patterns, common gaps
+3. **Lightweight AI (Cheap)**: Complex debugging suggestions
+4. **Full AI (Expensive)**: Only when truly needed
+
+### Context Optimization
+
+The server intelligently decides what context to include:
+
+| Prompt Type | Included Context |
+|-------------|------------------|
+| UI/Pages | Design system, related components, state specs |
+| Database | Full schema with relationships, indexes |
+| Integration | Endpoints with auth, tech stack configs |
+| Setup | Full tech stack, environment requirements |
+
+## Example Usage Flow
+
+```
+User: "Help me build my VisualPRD project"
+
+MCP Server:
+  ✓ Loads project abc123
+  ✓ Finds next available step (Step 3: User Authentication)
+  ✓ Fetches LoginPage spec, user schema, auth endpoint
+  ✓ Generates contextual guidance
+
+Response: "Ready to work on Step 3 of 25: Implement User Authentication Flow
+
+           I've fetched:
+           - LoginPage spec with component structure
+           - User schema with 14 fields
+           - authenticateUser endpoint (POST /api/auth/login)
+           - Design system for consistent styling
+
+           Technical considerations:
+           - Use Firebase Auth SDK
+           - Store session in context
+
+           Watch out for:
+           - Password reset flow isn't defined yet
+           - Remember auth state persistence"
+
+User: [Implements LoginPage]
+User: "Done, mark it complete"
+
+MCP Server:
+  ✓ Validates: files created ✓, tests passing ✓
+  ✓ Updates Firestore
+  ✓ Fetches next step automatically
+
+Response: "✅ Step 3 complete!
+           Next up: Step 4 - Implement User Dashboard"
+```
+
+## Troubleshooting
+
+### "Project not found"
+- Verify the project ID is correct
+- Ensure Firebase credentials have access to the project
+
+### "Permission denied"
+- Check Firebase security rules allow read access
+- Verify service account has correct permissions
+
+### "Module not found" errors
+- Run `npm install` in the mcp-server directory
+- Ensure you're using Node.js 18+
+
+### Tools not appearing in Cursor
+- Restart Cursor after adding MCP config
+- Check the MCP server logs for errors
+- Verify the server starts correctly: `visualprd-mcp --help`
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Running in Dev Mode
+
+```bash
+npm run dev
+```
+
+### Testing
+
+```bash
+npm test
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * VisualPRD MCP Server CLI
+ *
+ * Command-line interface for the MCP server
+ */
+export * from './index.js';
+import './index.js';
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;GAIG;AAGH,cAAc,YAAY,CAAC;AAG3B,OAAO,YAAY,CAAC"}

package/dist/cli.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * VisualPRD MCP Server CLI
+ *
+ * Command-line interface for the MCP server
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Re-export the main entry point
+__exportStar(require("./index.js"), exports);
+// The main logic is in index.ts
+require("./index.js");
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;AACA;;;;GAIG;;;;;;;;;;;;;;;;AAEH,iCAAiC;AACjC,6CAA2B;AAE3B,gCAAgC;AAChC,sBAAoB"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * VisualPRD MCP Server
+ *
+ * Intelligent Model Context Protocol server for autonomous build orchestration
+ * between VisualPRD and AI coding agents (Cursor, Claude, etc.)
+ */
+import { ProjectConfig } from './types/index.js';
+declare class VisualPRDMCPServer {
+    private server;
+    private client;
+    private intelligence;
+    private toolHandlers;
+    private config;
+    constructor(config: ProjectConfig);
+    private setupHandlers;
+    start(): Promise<void>;
+}
+export { VisualPRDMCPServer };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AAcH,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,cAAM,kBAAkB;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,MAAM,CAAgB;gBAElB,MAAM,EAAE,aAAa;IAyBjC,OAAO,CAAC,aAAa;IAyHf,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAS7B;AA2FD,OAAO,EAAE,kBAAkB,EAAE,CAAC"}