🎨 UI/UX Pro MCP Server

AI-powered UI/UX design intelligence — Instantly access 1,920+ curated design resources through natural language search.

✨ Features

| Feature | Details | |---------|---------| | 📚 1,920+ Documents | Curated design knowledge across 11 domains + 2 platforms | | 🔧 6 Tools | Consolidated search tools optimized for LLM performance | | ⚡ BM25 Ranking | Fast, relevant search results using industry-standard text ranking | | 🔗 Universal | Works with VS Code, Claude Desktop, Cursor, and any MCP-compatible client | | 🎯 12 Frameworks | Stack-specific guidelines for React, Vue, Next.js, Flutter, SwiftUI, Jetpack Compose, and more | | 📱 Platform Guidelines | iOS Human Interface Guidelines (110) + Android Material 3 (112) with cross-platform equivalents |

Platform-Specific Design

• iOS Human Interface Guidelines (110 patterns) — Colors, typography, navigation, gestures, accessibility with SwiftUI, Flutter, React Native code
• Android Material 3 Design (112 patterns) — Dynamic color, typography, components, elevation, motion with Compose, Flutter, React Native code
• Cross-platform code equivalents — Every pattern includes Flutter_Equiv and RN_Equiv for building native-feeling apps without native code
• Auto-detection from keywords — Queries containing iOS/Android keywords automatically boost platform-specific results

🚀 Quick Start

Option 1: NPX (Recommended)

npx ui-ux-pro-mcp

Option 2: Global Install

npm install -g ui-ux-pro-mcp
ui-ux-pro-mcp

Option 3: From Source

# Clone the repository
git clone https://github.com/redf0x1/ui-ux-pro-mcp.git
cd ui-ux-pro-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
npm start

⚙️ MCP Configuration

VS Code / Cursor

Add to your MCP settings (settings.json or mcp.json):

Option A: Using NPX (Recommended - No Installation Required)

{
  "mcpServers": {
    "ui-ux-pro": {
      "command": "npx",
      "args": ["ui-ux-pro-mcp", "--stdio"]
    }
  }
}

Option B: Using Global Install

{
  "mcpServers": {
    "ui-ux-pro": {
      "command": "ui-ux-pro-mcp",
      "args": ["--stdio"]
    }
  }
}

Option C: From Source

{
  "mcpServers": {
    "ui-ux-pro": {
      "command": "node",
      "args": [
        "/path/to/ui-ux-pro-mcp/dist/index.js",
        "--stdio"
      ]
    }
  }
}

Configuration file locations:

| Platform | Path | |----------|------| | macOS | ~/Library/Application Support/Code/User/mcp.json | | Windows | %APPDATA%\Code\User\mcp.json | | Linux | ~/.config/Code/User/mcp.json |

Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Option A: Using NPX (Recommended - No Installation Required)

{
  "mcpServers": {
    "ui-ux-pro": {
      "command": "npx",
      "args": ["ui-ux-pro-mcp", "--stdio"]
    }
  }
}

Option B: Using Global Install

{
  "mcpServers": {
    "ui-ux-pro": {
      "command": "ui-ux-pro-mcp",
      "args": ["--stdio"]
    }
  }
}

Option C: From Source

{
  "mcpServers": {
    "ui-ux-pro": {
      "command": "node",
      "args": [
        "/path/to/ui-ux-pro-mcp/dist/index.js",
        "--stdio"
      ]
    }
  }
}

🔧 Available Tools

| Tool | Documents | Description | |------|-----------|-------------| | search_ui_styles | 85 | UI design styles (Glassmorphism, Minimalism, Brutalism, etc.) with colors, effects, and use cases | | search_colors | 121 | Color palettes for industries (SaaS, Healthcare, Fintech) with hex codes | | search_typography | 74 | Font pairings with Google Fonts imports and Tailwind configs | | search_charts | 37 | Chart types with implementation recommendations for dashboards | | search_ux_guidelines | 115 | UX best practices, do's and don'ts, accessibility (WCAG) | | search_icons | 176 | Curated Lucide icons with import codes and use cases | | search_landing | 49 | Landing patterns, Bento Grids (Config & Maps), Responsive Strategy | | search_products | 114 | Product type design recommendations per industry | | search_prompts | 39 | AI prompt templates with CSS snippets and implementation checklists | | search_stack | 696 | Framework-specific guidelines (React, Vue, Next.js, Flutter, etc.) | | search_all | All | Unified search across all design domains | | get_design_system | — | Generate complete design system with colors, typography, UI style, and layout in one call |

AI-Optimized Query Processing

The get_design_system tool uses intelligent query processing optimized for AI model consumers:

Position-Weighted Intent Classification

Queries are processed left-to-right with multi-word phrase priority:

1. Multi-word phrases first: "landing page", "admin panel", "hero section" have higher priority
2. Then single words: "dashboard", "landing", "analytics"
3. Position matters: Earlier keywords get higher confidence (5% penalty per word position)

Examples: | Query | Detected Intent | Reason | |-------|-----------------|--------| | "SaaS landing page dashboard" | landing | "landing page" phrase found | | "dashboard for SaaS landing" | dashboard | "dashboard" is first | | "admin panel with hero section" | dashboard | "admin panel" phrase beats "hero" | | "website for fintech startup" | landing | "website" maps to landing |

AI-Optimized Output Structure

The _meta field provides transparency for AI models:

{
  "_meta": {
    "query_interpretation": "SaaS landing page with glassmorphism (dark mode)",
    "detected_intent": "landing",
    "intent_confidence": 0.85,
    "matched_keyword": "landing page",
    "keyword_position": 1,
    "warnings": []
  }
}

Dark Mode Color Parsing

When mode: "dark", the tool:

1. Searches for dark-mode compatible palettes
2. Parses Dark_Mode_Colors JSON from the database
3. Replaces palette colors with dark mode equivalents
4. Includes both light and dark mode palettes in response

Code-Ready Snippets

Colors include ready-to-paste code:

{
  "colors": {
    "css_variables": "--primary: #0066FF; --background: #0A0E14; --text: #E5E5E5;",
    "tailwind_config": "colors: { primary: '#0066FF', ... }"
  }
}

Layout Source Indicator

The layout.source field tells AI models where the layout recommendation came from:

• "landing" - From landing page patterns database
• "dashboard" - From product's dashboard style recommendation

💬 Example Prompts

Use these with Claude, Cursor, or any MCP-compatible AI:

🎨 Design Systems
"What UI style works best for a fintech dashboard?"
"Give me a color palette for a healthcare app"
"Find modern font pairings for a SaaS landing page"

📊 Data Visualization
"What chart type should I use for time-series data?"
"How do I make charts accessible?"

🖥️ Landing Pages
"Show me landing page patterns for SaaS conversion"
"What sections should a pricing page have?"

📱 UX Guidelines
"What are mobile touch target best practices?"
"Show me accessibility guidelines for forms"

⚛️ Framework-Specific
"React hooks best practices"
"Vue 3 composition API patterns"
"Next.js App Router guidelines"
"Flutter state management recommendations"

📱 Platform Guidelines (NEW)
"iOS navigation patterns"
"Android Material 3 color system"
"SwiftUI style without Swift" → Flutter/RN equivalents
"iOS typography guidelines with Flutter equivalent"
"Android dynamic color implementation"

Platform Keyword Triggers

The search engine automatically detects platform intent from these keywords:

| Platform | Trigger Keywords | |----------|------------------| | iOS | ios, swiftui, cupertino, iphone, ipad, apple design, hig, sf symbols | | Android | android, material 3, material design, jetpack compose, kotlin ui, dynamic color, m3 |

Cross-Platform Query Examples

🍎 iOS Design Without Swift
Query: "SwiftUI style flutter e-commerce"
Returns: iOS HIG patterns with Flutter_Equiv code (CupertinoWidgets)

🤖 Android Material 3
Query: "material design android dashboard"
Returns: Material 3 patterns with Compose, Flutter, RN equivalents

🔄 Cross-Platform Patterns
Query: "iOS navigation patterns react native"
Returns: iOS navigation guidelines with RN_Equiv implementations

📂 Data Sources

This server aggregates curated design intelligence from multiple domains:

| Domain | File | Count | Content | |--------|------|-------|---------| | Styles | styles.csv | 85 | UI design trends, effects, animations | | Colors | colors.csv | 121 | Industry-specific color palettes | | Typography | typography.csv | 74 | Font pairings and configurations | | Charts | charts.csv | 37 | Data visualization recommendations | | UX Guidelines | ux-guidelines.csv | 115 | Usability and accessibility best practices | | Icons | icons.csv | 176 | Lucide icon recommendations | | Landing | landing.csv | 49 | Patterns, Bento Layout Maps, Responsive Strategy | | Products | products.csv | 114 | Industry design recommendations | | Prompts | prompts.csv | 39 | AI prompt templates | | Stacks | stacks/*.csv | 766 | Framework-specific guidelines (12 stacks) | | iOS | platforms/ios.csv | 110 | iOS Human Interface Guidelines with cross-platform equivalents | | Android | platforms/android.csv | 112 | Android Material 3 Design with cross-platform equivalents |

Available Framework Stacks: flutter · html-tailwind · jetpack-compose · nextjs · nuxt-ui · nuxtjs · react-native · react · shadcn · svelte · swiftui · vue

Platform-Specific Guidelines: ios (110 entries) · android (112 entries)

Platform data includes:

• Flutter_Equiv: CupertinoWidgets/Material widget equivalents
• RN_Equiv: React Native implementation patterns
• Categories: Colors, Typography, Spacing, Components, Navigation, Gestures/Shapes, Animation/Motion, Icons, Layout, Accessibility

📖 API Reference

Common Input Parameters

All search tools accept:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | query | string | required | Natural language search query | | max_results | number | 3 | Maximum results to return (1-50) |

search_stack Additional Parameter

| Parameter | Type | Description | |-----------|------|-------------| | stack_name | string | Framework name: react, vue, nextjs, flutter, swiftui, etc. |

Response Format

All tools return results in this structure:

{
  results: Array<{
    id: string;           // Document identifier
    score: number;        // BM25 relevance score
    type: string;         // Document type (style, color, etc.)
    data: object;         // Full document data
  }>;
  total: number;          // Total results returned
  query: string;          // Original search query
}

Error Response

{
  error: string;          // Error description
}

🛠️ Development

Build Commands

# Build TypeScript to JavaScript
npm run build

# Development mode with hot reload
npm run dev

# Start production server (stdio mode)
npm start

# Start HTTP server for testing
npm run start:http

Testing

# Run test suite
npm test

HTTP Mode for Testing

The server can run in HTTP mode for testing without MCP clients:

# Start HTTP server on port 3456
PORT=3456 npm run start:http

Then test with curl:

curl -X POST http://localhost:3456/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"search_colors","arguments":{"query":"fintech"}},"id":1}'

Project Structure

ui-ux-pro-mcp/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── data/
│   │   └── loader.ts     # CSV data loading utilities
│   ├── search/
│   │   └── bm25.ts       # BM25 search implementation
│   └── tools/
│       ├── index.ts      # Tool exports
│       └── handlers.ts   # Search handlers
├── data/
│   ├── *.csv             # Design domain data files
│   ├── stacks/           # Framework-specific guidelines (12 stacks)
│   └── platforms/        # Platform guidelines (iOS HIG, Android M3)
└── dist/                 # Compiled JavaScript output

🌐 Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | MCP_LOG_LEVEL | info | Log level (debug, info, warn, error) | | PORT | 3000 | HTTP server port (when using HTTP transport) | | MCP_HTTP_HOST | localhost | HTTP server host |

🔌 HTTP Transport Mode

For development and testing, you can run the server in HTTP mode:

# Start HTTP server
npm run start:http

# Server runs at http://localhost:3000
# SSE endpoint: GET /sse
# Message endpoint: POST /message

Test with curl:

curl -X POST http://localhost:3000/message \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_colors","arguments":{"query":"fintech"}}}'

❓ Troubleshooting

MCP Connection Issues

"Cannot find MCP server"

• Ensure npm run build completed successfully
• Check the path in your MCP config points to dist/index.js
• Verify Node.js is in your PATH

"No results returned"

• Try broader search terms
• Use search_all for cross-domain queries
• Check if the domain matches your query type

"Server not responding"

• Restart VS Code/Claude Desktop
• Check terminal for error messages
• Verify the server process is running

Common Queries

| Need | Best Tool | |------|----------| | Color palettes | search_styles with domain: "color" | | UI components | search_styles with domain: "style" | | Best practices | search_patterns with type: "ux" | | Icons | search_components with type: "icon" | | Framework tips | search_stack | | Everything | search_all |

� Contact

• Telegram: @redf0x1
• GitHub: @redf0x1

�📄 License

MIT License — see LICENSE for details.

🙏 Acknowledgments

• Original Data: Based on nextlevelbuilder/ui-ux-pro-max-skill
• MCP SDK: Built with @modelcontextprotocol/sdk
• Search: BM25 ranking algorithm for relevance scoring

⭐ Star this repo if you find it useful!

Made with ❤️ by redf0x1