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)

npm install -g @visualprd/mcp-server

Option 2: From Source

cd mcp-server
npm install
npm run build
npm link

Configuration

For Cursor

Add to your Cursor MCP settings (Settings → Extensions → MCP Servers):

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

npm run build

Running in Dev Mode

npm run dev

Testing

npm test

License

MIT