@visualprd/mcp

VisualPRD MCP Client - Connect AI coding agents to your VisualPRD projects for autonomous application development.

What is this?

This is an MCP (Model Context Protocol) server that connects AI coding assistants (Claude Code, Cursor, Windsurf, Claude Desktop) to your VisualPRD projects. Once connected, the AI can:

• List your projects and switch between them dynamically
• Get the next build step with full context
• Access page specifications, database schemas, and API endpoints
• Receive design system tokens and tech stack details
• Generate framework-aware tests and auto-complete steps
• Report errors for AI-assisted debugging
• Detect and fix project structure issues

Quick Start

npx @visualprd/mcp@latest

IDE Configuration

Cursor IDE

Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "visualprd": {
      "command": "npx",
      "args": ["-y", "@visualprd/mcp@latest"],
      "env": {
        "VISUALPRD_USER_ID": "your-user-id"
      }
    }
  }
}

Claude Code (CLI)

Run this command in your terminal:

claude mcp add visualprd \
  -e VISUALPRD_USER_ID=your-user-id \
  -- npx @visualprd/mcp@latest

Then restart Claude Code.

Claude Desktop

Add to your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "visualprd": {
      "command": "npx",
      "args": ["-y", "@visualprd/mcp@latest"],
      "env": {
        "VISUALPRD_USER_ID": "your-user-id"
      }
    }
  }
}

Restart Claude Desktop after adding.

Windsurf IDE

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "visualprd": {
      "command": "npx",
      "args": ["-y", "@visualprd/mcp@latest"],
      "env": {
        "VISUALPRD_USER_ID": "your-user-id"
      }
    }
  }
}

Open Windsurf Settings → Cascade → Plugins, then press refresh.

Alternative: Config File

If environment variables aren't working, create ~/.visualprd.json:

{
  "userId": "your-user-id"
}

Available MCP Tools

Core Build Tools

| Tool | Description | |------|-------------| | get_next_step | Get the next build step with full context and AI guidance | | get_build_progress | View overall progress and statistics | | mark_complete | Mark a build step as complete | | report_error | Get AI-assisted debugging help with automatic remediation | | get_entity_details | Get details about pages, schemas, endpoints | | get_design_system | Get design tokens and tech stack | | check_updates | Check if the PRD has been updated |

Project Management Tools

| Tool | Description | |------|-------------| | list_projects | List all your projects with status and progress | | switch_project | Switch to a different project by name (supports fuzzy matching) |

Testing & Quality Tools

| Tool | Description | |------|-------------| | test_current_step | Generate framework-aware CLI tests; auto-completes step if all pass |

Advanced Tools

| Tool | Description | |------|-------------| | inject_dynamic_step | Inject a new build step when needed | | get_debug_suggestions | Get AI-powered debugging suggestions |

Example Prompts

Once connected, try these prompts with your AI assistant:

Getting Started (New Account-Based Flow)

• "List my projects" - Shows all your VisualPRD projects
• "Switch to MyApp" - Switches to a project by name
• "What's my build progress?" - Shows current progress
• "What should I build next?" - Gets the next step

Building Your Project

• "Help me build my VisualPRD project"
• "Get the next step and help me implement it"
• "Show me details about the Dashboard page"
• "What's the User schema look like?"

Testing & Quality

• "Test the current step" - Generates framework-aware tests

Error Handling

• "I got this error: [paste error message]"
• "I'm stuck on implementing the login flow"
• "The API endpoint is returning 404, help me debug"

Marking Progress

• "Mark the current step as complete"
• "I've finished the LoginPage, mark it done"

How Project Selection Works

1. Single Project: If you have only one project, it's auto-selected on first tool call
2. Multiple Projects: Use list_projects to see all projects, then switch_project to select one
3. Fuzzy Matching: switch_project supports partial name matching (e.g., "myapp" matches "MyApp Pro")
4. Session Persistence: Selected project persists throughout your IDE session

Example flow:

User: "What should I build next?"
AI: "No project selected. Let me list your projects..."
AI: [calls list_projects]
AI: "You have 3 projects: MyApp, TestProject, NewSite. Which one?"
User: "Switch to MyApp"
AI: [calls switch_project with projectName: "MyApp"]
AI: "Switched to MyApp. Here's your next step..."

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | VISUALPRD_USER_ID | Yes | Your VisualPRD user ID | | VISUALPRD_PROJECT_ID | No | Pre-select a specific project (optional) | | VISUALPRD_SERVER_URL | No | Override the default server URL | | VISUALPRD_MODEL | No | Override the AI model (default: anthropic/claude-sonnet-4) |

Getting Your Credentials

1. Go to VisualPRD Dashboard
2. Open any project
3. Click "Export to AI Agent"
4. Copy your User ID

test_current_step: Advanced Testing

The test_current_step tool generates comprehensive, framework-aware tests:

Supported Frameworks

• Next.js: Build, TypeScript, lint, dev server, API endpoint tests
• React: Build, lint, component tests
• Flutter: Analyze, test, build, widget tests
• Vue/Angular/Svelte: Framework-specific test generation
• Express/NestJS/Fastapi: API endpoint testing

Test Flow

1. Call test_current_step - generates CLI tests for your framework
2. Run the generated tests
3. Call test_current_step again with results:

   {
     "testResults": {
       "passed": ["build", "lint", "typecheck"],
       "failed": []
     }
   }

4. If all pass, step is auto-completed and you get the next step

Debugging Protocol

If tests fail, the tool provides the 5-attempt debugging protocol:

1. Quick fixes (syntax, imports)
2. Deeper analysis (logic, state)
3. Research (docs, similar issues)
4. Alternative approach
5. Creative solutions

Requirements

• Node.js 18 or later
• npm or npx

Troubleshooting

MCP server not connecting

• Ensure you have Node.js 18+ installed
• Try running manually: npx @visualprd/mcp@latest
• Check for error messages in terminal

"No project selected" error

• Run list_projects to see your available projects
• Run switch_project with your project name
• Or add VISUALPRD_PROJECT_ID to your config for auto-selection

Tools not appearing

• Restart your AI assistant after config changes
• Verify the config JSON is valid
• Check MCP server logs for errors

Authentication errors

• Verify your User ID is correct
• Check if the config file or environment variables are set properly
• Try the ~/.visualprd.json fallback method

Changelog

v2.0.0

• Account-based project selection: No longer requires VISUALPRD_PROJECT_ID
• New tools: list_projects, switch_project, test_current_step
• Auto-selection: Automatically selects project if user has only one
• Fuzzy matching: Switch projects by partial name match
• Framework-aware testing: Generates tests based on your tech stack

v1.0.3

• Initial release with core build tools

Support

• Documentation: visualprd.com/docs
• Support: visualprd.com/support

License

MIT