UXSmith MCP Server

An intelligent MCP (Model Context Protocol) server for automated UX auditing and fixing. UXSmith renders pages, audits them against brand guidelines + accessibility + layout rules, and returns code diffs (JS codemods + CSS/Tailwind fixes) that can be applied in one go.

Features

• 🎨 Brand Compliance: Enforce design tokens (colors, spacing, typography, motion)
• ♿ Accessibility Auditing: Full WCAG 2.1 AA compliance checking with axe-core
• 🔧 Automated Fixes: Generate codemods to fix issues automatically
• 📸 Visual Alignment: Compare implementation against mockups (Figma/images)
• 🚀 Component Upgrades: Upgrade components to follow design system standards
• 🎯 Tailwind Optimization: Sort classes, remove duplicates, enforce best practices

Quick Start

Installation

Recommended: Global Installation

# Install globally for best compatibility
npm install -g uxsmith-mcp-server

# Verify installation
uxsmith-mcp-server --version

Alternative: Use with npx

# Note: npx may have issues with some versions
# If npx fails, use global installation instead
npx uxsmith-mcp-server@latest

Setup in Claude Code

# Navigate to your project
cd /path/to/your/project

# If installed globally (recommended):
claude mcp add uxsmith "uxsmith-mcp-server"

# Or if using npx:
claude mcp add uxsmith "npx uxsmith-mcp-server@latest"

# Restart Claude Code to activate

Setup in Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "uxsmith": {
      "command": "uxsmith-mcp-server",
      "args": []
    }
  }
}

Note: If not installed globally, use:

{
  "mcpServers": {
    "uxsmith": {
      "command": "npx",
      "args": ["uxsmith-mcp-server@latest"]
    }
  }
}

Setup in Cursor IDE

Add to your .cursor/mcp.json in your project:

{
  "mcpServers": {
    "uxsmith": {
      "command": "uxsmith-mcp-server",
      "args": []
    }
  }
}

Available Tools

🎨 ux_set_brand_guide

Load brand tokens and rules to enforce consistency.

{
  "tokens_url": "file://tokens.json",  // Path to design tokens
  "rules_url": "file://BRAND.md"       // Path to brand rules markdown
}

Or provide directly:

{
  "tokens_json": { /* token object */ },
  "rules_md": "## Brand Rules\n..."
}

🔍 ux_audit_page

Render and audit a page for UX conformance issues.

{
  "page_url": "http://localhost:3000/dashboard",
  "breakpoints": [320, 768, 1280]  // Viewport widths to test
}

Returns:

• Accessibility violations
• Token compliance issues
• Layout problems
• Performance metrics
• Screenshots at each breakpoint

🔧 ux_propose_fixes

Generate code diffs to fix identified issues.

{
  "page_url": "http://localhost:3000/dashboard",
  "fixes": [
    "color_tokens",    // Replace raw colors with tokens
    "a11y",           // Fix accessibility issues
    "tailwind_sort",  // Sort and dedupe Tailwind classes
    "inline_styles",  // Convert inline styles to classes
    "grid",          // Standardize grid spacing
    "motion",        // Add motion tokens
    "copy"           // Fix copy tone
  ]
}

Returns unified patch diffs that can be applied directly.

🎯 ux_align_to_mockup

Analyze visual differences and generate fixes to match mockup.

{
  "page_url": "http://localhost:3000",
  "mockup_image": "file://design.png",  // Or...
  "figma_frame": "frame-id"            // Figma frame reference
}

Returns:

• Visual difference analysis
• Suggested code changes
• Similarity score (0-1)

🚀 ux_component_upgrade

Upgrade a component to design system standards.

{
  "component_path": "src/components/Button.tsx",
  "target_api": "Button(variant|size|disabled)",
  "enforce_tokens": true
}

Transforms:

• Raw <button> → <Button variant="primary" size="md" />
• Enforces design tokens
• Adds accessibility attributes
• Standardizes prop APIs

✅ ux_apply_fixes

Apply generated fixes to the codebase.

{
  "fixes": [
    { "file": "src/App.tsx", "patch": "..." }
  ],
  "dry_run": false  // Set true to preview without applying
}

Brand Token Format

Define your design system tokens in JSON:

{
  "color": {
    "text": {
      "primary": "#0f172a",
      "muted": "#475569",
      "inverse": "#ffffff"
    },
    "bg": {
      "surface": "#f8fafc",
      "card": "#ffffff"
    },
    "brand": {
      "primary": "#2563eb",
      "accent": "#22c55e"
    }
  },
  "space": {
    "0": 0,
    "1": 4,
    "2": 8,
    "3": 12,
    "4": 16,
    "5": 20,
    "6": 24,
    "8": 32
  },
  "radius": {
    "sm": 6,
    "md": 12,
    "lg": 16,
    "xl": 24
  },
  "motion": {
    "duration": {
      "fast": 150,
      "base": 250
    },
    "easing": {
      "standard": "cubic-bezier(0.2,0,0,1)"
    }
  },
  "typography": {
    "display": {
      "font": "Inter",
      "size": 48,
      "line": 56,
      "weight": 700
    },
    "body": {
      "font": "Inter",
      "size": 14,
      "line": 20,
      "weight": 400
    }
  }
}

Brand Rules Format

Document your brand guidelines in Markdown:

## Buttons
- Primary buttons should use brand.primary color
- Secondary buttons should have outline style
- All buttons must have focus-visible states
- Icon-only buttons require aria-label

## Spacing
- Use consistent spacing scale (0, 1, 2, 3, 4, 5, 6, 8)
- Grid gaps should align to spacing tokens
- Maintain 8px baseline grid

## Colors
- Never use raw hex values
- Text must meet WCAG AA contrast ratios
- Use semantic color names (primary, muted, inverse)

## Accessibility
- All interactive elements need focus indicators
- Images require alt text
- Form inputs need associated labels
- Support prefers-reduced-motion

Workflow Example

// 1. Load brand guidelines
await ux_set_brand_guide({
  tokens_url: "file://design-tokens.json",
  rules_url: "file://BRAND.md"
});

// 2. Audit the page
const audit = await ux_audit_page({
  page_url: "http://localhost:3000",
  breakpoints: [320, 768, 1280]
});

// 3. Generate fixes
const fixes = await ux_propose_fixes({
  page_url: "http://localhost:3000",
  fixes: ["color_tokens", "a11y", "tailwind_sort"]
});

// 4. Apply fixes
await ux_apply_fixes({
  fixes: fixes.fixes,
  dry_run: false
});

// 5. (Optional) Align to mockup
const alignment = await ux_align_to_mockup({
  page_url: "http://localhost:3000",
  mockup_image: "file://design.png"
});

Architecture

┌──────────────────┐     ┌──────────────────┐
│  Claude/AI Agent │────▶│   MCP Protocol   │
└──────────────────┘     └──────────────────┘
                                │
                                ▼
                         ┌──────────────────┐
                         │  UXSmith Server  │
                         └──────────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        ▼                       ▼                       ▼
┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   Playwright │      │   axe-core   │      │  jscodeshift │
│   (Render)   │      │   (Audit)    │      │  (Transform) │
└──────────────┘      └──────────────┘      └──────────────┘
        │                       │                       │
        └───────────────────────┼───────────────────────┘
                                ▼
                        ┌──────────────────┐
                        │   Your App       │
                        └──────────────────┘

Development

Setup

# Clone the repository
git clone https://github.com/uxsmith/mcp-server
cd uxsmith-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run watch

Testing

# Run unit tests
npm run test:unit

# Run integration tests (requires Playwright browsers)
npm run test:integration

# Test with MCP Inspector
npx @modelcontextprotocol/inspector npm start

Fix Categories

Color Tokens

• Replace hex values with design tokens
• Map raw RGB to semantic colors
• Enforce color consistency

Accessibility (a11y)

• Add missing ARIA attributes
• Fix color contrast issues
• Ensure keyboard navigation
• Add focus indicators
• Support screen readers

Tailwind Sorting

• Order classes consistently
• Remove duplicate classes
• Group responsive variants
• Fix conflicting utilities

Inline Styles

• Convert to Tailwind classes
• Move to external CSS
• Use design tokens

Grid Alignment

• Snap to spacing grid
• Standardize gaps
• Align to baseline

Motion

• Add transition classes
• Support prefers-reduced-motion
• Use duration/easing tokens

Troubleshooting

MCP Connection Issues

If you see ✗ Failed to connect when running claude mcp list:

1. Use global installation instead of npx:

   # Uninstall any cached versions
   npm uninstall -g uxsmith-mcp-server
      
   # Clear npm cache
   npm cache clean --force
   rm -rf ~/.npm/_npx
      
   # Install globally
   npm install -g uxsmith-mcp-server
      
   # Update MCP config
   claude mcp remove uxsmith
   claude mcp add uxsmith "uxsmith-mcp-server"

2. Clear npx cache if using npx:

   npx clear-npx-cache
   rm -rf ~/.npm/_cacache ~/.npm/_npx

3. Verify installation:

   # Test the server directly
   echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | uxsmith-mcp-server

   You should see a JSON response with available tools.

Common Issues

• "command not found": Install globally with npm install -g uxsmith-mcp-server
• npx fails to execute: Use global installation instead of npx
• Old version cached: Clear npm/npx cache and reinstall

Requirements

• Node.js 18+
• TypeScript 5+
• Playwright browsers (auto-installed)

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions