🎨 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