MCP WDS Renderer

An MCP server that renders WDS (Wix Design System) components using JSX syntax and returns screenshots to LLMs via a Vercel-deployed rendering site.

Features

• screenshot: Renders JSX/React components with full WDS component library and captures screenshots
• JSX Syntax Support: Use <Button>Hello</Button> instead of React.createElement
• Wix UI Icons: Full Icons.Add, Icons.Search, etc. support (1400+ icons)
• All WDS components pre-imported (no import statements needed)
• Automatic WixDesignSystemProvider wrapping
• Vercel Deployment: Scalable, fast rendering via deployed Vite site
• Playwright Screenshots: Reliable browser automation with Chromium

How It Works

The renderer uses a Vercel-deployed site + Playwright architecture:

1. MCP Server Receives Request

• Client sends JSX code via MCP protocol to the server
• Server encodes JSX as base64 for URL transport
• Constructs URL to Vercel-deployed renderer site

2. Vercel Renderer Site

• Standalone Vite + React application hosted on Vercel
• Receives JSX via URL query parameter
• All WDS components and icons pre-imported and available
• Dynamically evaluates JSX using new Function() with React in scope
• Renders component with proper error boundaries

3. Playwright Screenshot

• MCP server controls headless Chromium browser via Playwright
• Navigates to the Vercel URL with encoded JSX
• Waits for React to render the component
• Captures PNG screenshot of the rendered output
• Returns base64-encoded image to MCP client

4. Browser Management

• Reuses browser instances for performance
• Automatic health checks and recycling every 10 minutes
• Idle browsers closed after 5 minutes of inactivity
• Connection retry logic for reliability

Key Technical Details

• Separation of Concerns: MCP server is lightweight, rendering happens remotely
• URL Transport: JSX passed as base64-encoded query parameter (handles large components)
• Dynamic Evaluation: Renderer site evaluates JSX with WDS and Icons in scope
• Error Boundaries: Visual error feedback in rendered output
• Scalability: Can point to any deployed instance via RENDERER_URL env var
• Browser Management: Playwright provides reliable, modern browser automation

Architecture Benefits

✅ Scalability: Rendering happens on Vercel, not local machine ✅ Fast Performance: Pre-built Vite site, instant loads ✅ Reliability: Playwright provides modern, stable browser automation ✅ Separation: MCP server is lightweight, easy to deploy ✅ Flexibility: Can switch renderer URLs for dev/staging/prod ✅ No Build Step: No temp files or compilation in MCP server

Usage

Tools

screenshot

Renders JSX components and returns a PNG screenshot.

Parameters:

• jsx (string, required): JSX code to render

Example:

{
  "jsx": "<Button priority='primary' prefixIcon={<Icons.Add />}>Add Item</Button>"
}

Response:

• Returns base64-encoded PNG image
• Includes success message and rendered screenshot
• Error details if compilation/rendering fails

Test Prompts

Simple Button Test:

Use the screenshot tool to render: <Button priority="primary">Hello World</Button>

With Icons:

Use the screenshot tool to render:
<Button priority="primary" prefixIcon={<Icons.Add />}>Add Item</Button>

Complex Layout:

Use the screenshot tool to render:
<Box direction="vertical" gap="20px" padding="24px">
  <Heading size="H2">WDS Components</Heading>
  <Box gap="12px">
    <Button priority="primary" prefixIcon={<Icons.Add />}>Add</Button>
    <IconButton><Icons.Search /></IconButton>
  </Box>
  <Card>
    <Card.Header title="Form Example" />
    <Card.Content>
      <Box direction="vertical" gap="12px">
        <Input placeholder="Enter name" />
        <Checkbox>Enable notifications</Checkbox>
        <Badge skin="success">Active</Badge>
      </Box>
    </Card.Content>
  </Card>
</Box>

Inline Styles Test:

Use the screenshot tool to render:
<div style={{padding: '20px', backgroundColor: '#f0f0f0', borderRadius: '8px', textAlign: 'center'}}>
  <h1 style={{color: '#333', marginBottom: '16px'}}>Hello WDS Renderer!</h1>
  <p style={{color: '#666', fontSize: '16px'}}>This component uses inline styles.</p>
</div>

Available Components

All WDS components are pre-imported and available:

Core Components:

• Button, TextButton, IconButton, CloseButton
• Text, Heading
• Box, Layout, Cell, Divider
• Input, InputArea, NumberInput
• Card, Modal, Popover, Tooltip

Form Components:

• Checkbox, RadioGroup, ToggleSwitch
• Dropdown, AutoComplete, MultiSelect
• Search, DatePicker, ColorPicker
• Slider, Stepper, SegmentedToggle
• FormField, FieldSet, FileUpload

Display Components:

• Badge, Tag, TagList, Avatar
• Table, Tabs, Accordion, VerticalTabs
• Loader, LinearProgressBar, CircularProgressBar
• StatusIndicator, Notification, FloatingNotification
• Image, Carousel, MediaOverlay, Thumbnail

Layout & Navigation:

• Page, PageHeader, SidePanel
• Breadcrumbs, Pagination
• EmptyState, AddItem

Advanced:

• RichTextInputArea, SocialButton
• HorizontalTimeline, MarketingLayout
• AnnouncementModalLayout, MessageModalLayout, CustomModalLayout

Icons:

• Icons.Add, Icons.Search, Icons.Delete, Icons.Close
• Icons.ArrowLeft, Icons.ArrowRight, Icons.ChevronDown
• All 1500+ icons from @wix/wix-ui-icons-common

Development

MCP Server

Install dependencies:

yarn install

Build the package:

yarn build

Run the MCP server locally for testing:

node dist/index.js

Renderer Site

The renderer site is deployed to Vercel. For local development:

cd renderer-site
yarn install
yarn dev

Set RENDERER_URL=http://localhost:3000 when running the MCP server to use local renderer.

Deploy to Vercel:

# From project root
vercel deploy

The vercel.json config handles building the renderer-site automatically.

Configuration

Setting RENDERER_URL

The RENDERER_URL environment variable tells the MCP server where to find the renderer site. You can use either:

• Production (default): https://renderer-site-coral.vercel.app (used if not specified)
• Local development: http://localhost:3000 (requires running cd renderer-site && yarn dev)
• Custom deployment: Your own deployed Vercel URL

Note: The server defaults to the production Vercel URL (https://renderer-site-coral.vercel.app), so you only need to set RENDERER_URL if you want to use a local or custom deployment.

MCP Configuration

Configure in .cursor/mcp.json (or your MCP config file):

For local development:

{
  "mcpServers": {
    "wds-renderer-dev": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "RENDERER_URL": "http://localhost:3000"
      }
    }
  }
}

For production (using deployed Vercel renderer):

{
  "mcpServers": {
    "wds-renderer-prod": {
      "command": "npx",
      "args": ["@vltansky/wds-renderer-mcp@latest"],
      "env": {
        "RENDERER_URL": "https://renderer-site-coral.vercel.app"
      }
    }
  }
}

Environment Variables:

• RENDERER_URL (optional): URL of the renderer site
  • Default: https://renderer-site-coral.vercel.app (if not set)
  • Local dev: http://localhost:3000 (must run cd renderer-site && yarn dev)
  • Production: https://renderer-site-coral.vercel.app (or your custom deployed URL)

How It Works

1. The MCP server reads RENDERER_URL from the env section in your MCP config
2. Playwright navigates to ${RENDERER_URL}/?jsx=<base64-encoded-jsx>
3. The renderer site receives the JSX, renders it, and Playwright captures a screenshot
4. The screenshot is returned to the MCP client as base64-encoded PNG

Note: After changing RENDERER_URL in your MCP config, restart Claude Code/Cursor for the changes to take effect.

Getting Started

Standard Config

The standard config works in most MCP clients:

{
  "mcpServers": {
    "wds-renderer": {
      "command": "npx",
      "args": ["@vltansky/wds-renderer-mcp@latest"]
    }
  }
}

Note: This uses the default production renderer URL (https://renderer-site-coral.vercel.app). For local development, add "env": {"RENDERER_URL": "http://localhost:3000"} and run cd renderer-site && yarn dev.

Platform-Specific Setup

Click the button to install:

Or install manually:

1. Open Cursor Settings (⌘, or Ctrl+,)
2. Search for "MCP" or navigate to MCP settings
3. Click "Edit Config" or open .cursor/mcp.json directly
4. Add the WDS Renderer configuration:

{
  "mcpServers": {
    "wds-renderer": {
      "command": "npx",
      "args": ["@vltansky/wds-renderer-mcp@latest"]
    }
  }
}

5. Restart Cursor
6. Verify the MCP server is connected in the MCP settings panel

Note: The env section with RENDERER_URL is optional. The server uses the production Vercel URL by default.

For local development:

{
  "mcpServers": {
    "wds-renderer-dev": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "RENDERER_URL": "http://localhost:3000"
      }
    }
  }
}

Make sure to run cd renderer-site && yarn dev before using the local configuration.

Use the Claude Code CLI to add the WDS Renderer MCP server:

claude mcp add wds-renderer npx '@vltansky/wds-renderer-mcp@latest'

Then edit your config file (.mcp.json for project scope, or Claude Desktop config for user scope) to add the env section with RENDERER_URL.

Alternative: Using Claude CLI with user scope

For user/global scope (stored in Claude Desktop config):

claude mcp add -s user wds-renderer npx '@vltansky/wds-renderer-mcp@latest'

Then manually edit the Claude Desktop config file to add the env section:

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

Note: The -s flag specifies the scope:

• Default (no flag): Project-level install, stored in .mcp.json in your project
• -s user (or --scope user): Global/user-level install, stored in Claude Desktop config
• -s project (or --scope project): Project-level install, stored in .mcp.json in your project

If your version of Claude CLI supports the --env flag, you can add environment variables directly:

claude mcp add wds-renderer npx '@vltansky/wds-renderer-mcp@latest' --env RENDERER_URL=https://renderer-site-coral.vercel.app

Follow the MCP install guide, use the standard config above with RENDERER_URL in the env section.

1. Open Cline Settings
2. Navigate to MCP Configuration
3. Add the WDS Renderer server using the standard config above with RENDERER_URL in the env section
4. Restart Cline
5. The screenshot tool should now be available in your chat

Verifying Installation

After setup, test the installation by asking your AI assistant:

Use the screenshot tool to render: <Button priority="primary">Hello World</Button>

If configured correctly, you should see a rendered screenshot of a WDS button component.

Testing the MCP Server

Manual Testing with Test Script

Run the included test script:

node test-mcp.js

This will:

1. Start the MCP server
2. Send a tools/list request to verify tools are exposed
3. Send a screenshot request with sample JSX
4. Display the responses and shut down

Troubleshooting

Common Issues

Connection errors:

• The server uses the production Vercel URL by default (https://renderer-site-coral.vercel.app)
• If using local renderer, set RENDERER_URL=http://localhost:3000 in your MCP config and verify it's running: cd renderer-site && yarn dev
• If using a custom deployed renderer, set RENDERER_URL in your MCP config
• Check that Playwright browsers are installed: npx playwright install chromium
• Restart Claude Code/Cursor after changing RENDERER_URL

"Could not navigate to URL":

• Verify the renderer site is accessible
• Check network connectivity to Vercel (if using deployed renderer)
• Try accessing the URL manually in a browser

Browser/Playwright errors:

• Install Playwright browsers: npx playwright install chromium
• The browser instance is managed automatically with health checks
• On macOS, ensure no aggressive antivirus software is blocking browser launches

Render errors visible in screenshot:

• The renderer site shows visual error messages
• Check JSX syntax is valid
• Verify WDS component names are correct
• Look at the screenshot for error details

Environment Variables:

• RENDERER_URL is optional - defaults to https://renderer-site-coral.vercel.app
• For local testing: Set "RENDERER_URL": "http://localhost:3000" in your MCP config's env section
• For custom deployment: Set "RENDERER_URL": "https://your-deployed-renderer.vercel.app"
• Remember to restart Claude Code/Cursor after changing the config

Performance

• Browser instances are reused and recycled every 10 minutes
• Idle browsers are closed after 5 minutes of inactivity
• Vercel provides CDN-cached assets for fast loads
• No build step in MCP server = instant response