A streamlined MCP (Model Context Protocol) server that provides shadcn/ui component installation and usage instructions through a simple, natural language interface.

SuperUI MCP simplifies the process of adding shadcn/ui components to your React projects. Instead of searching documentation and copying installation commands, simply ask Claude Code for the components you need, and get instant installation instructions.

This project consists of two independent services:

• MCP server that connects to Claude Code
• 2-stage discovery tools: list_components + get_component_details
• Template tool: build_landing
• Frontend cloning tool: clone_frontend
• Communicates with API server via HTTP

• Express.js backend
• Manages 70+ component library
• Provides ranked search and installation guides

User (Claude Code) → list_components → Candidates
         ↓
   Choose component
         ↓
   get_component_details → Installation Guide
         ↓
   npx install command

• 2-Stage Discovery: Search first, then get details for better accuracy
• 70+ Components: shadcn/ui + AI + Advanced Buttons + Animated Text
• Semantic Search: Ranked search with relevance scoring
• Category Filtering: Filter by form, layout, ai, advanced-button, text, etc.
• Frontend Cloning: Clone any website by iteratively comparing screenshots
• Project-Aware: Automatically detects your project structure
• Installation Commands: Ready-to-use npx commands
• Usage Examples: Import statements and code examples

Form Components (14) button, input, textarea, select, checkbox, radio-group, label, form, switch, slider, combobox, toggle, toggle-group, input-otp

Layout Components (8) card, sheet, dialog, popover, collapsible, resizable, scroll-area, aspect-ratio

Navigation Components (9) tabs, accordion, breadcrumb, navigation-menu, menubar, command, context-menu, dropdown-menu, pagination

Data Display Components (10) table, badge, avatar, progress, skeleton, calendar, date-picker, hover-card, carousel, tooltip

Feedback Components (4) alert, toast, separator, sonner

ai-actions, ai-branch, ai-code-block, ai-conversation, ai-image, ai-inline-citation, ai-loader, ai-message, ai-prompt-input, ai-reasoning, ai-response, ai-sources, ai-suggestion, ai-task, ai-tool, ai-web-preview

glow-button, shimmer-button, magnetic-button, pulse-button, gradient-button, neon-button, shine-button, copy-button, expanding-button, tilt-button

gradient-text, typing-text, shimmering-text, counting-number, sliding-number, rolling-text, rotating-text, splitting-text, highlight-text, writing-text

• Node.js 18+
• VS Code with Claude Code extension installed
• React project (Next.js, Vite, etc.)
• Tailwind CSS configured in your project

git clone <repository-url>
cd magic_to_super

cd superui-server
npm install
npx playwright install chromium
npm run build

cd ../superui-mcp
npm install
npm run build

cd superui-server
npm start

The API server will start on http://localhost:3001

Verify it's running:

curl http://localhost:3001/health

Expected response:

{
  "status": "OK",
  "timestamp": "2025-10-07T10:50:10.128Z",
  "version": "1.0.0"
}

1. Open VS Code
2. Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
3. Type "Claude Code: Edit MCP Settings"
4. Add the SuperUI MCP configuration

The .claude.json file location varies by OS:

macOS/Linux:

~/.claude.json

Windows:

%USERPROFILE%\.claude.json

Add the following configuration:

{
  "mcpServers": {
    "superui": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/magic_to_super/superui-mcp/dist/index.js"],
      "env": {
        "API_BASE_URL": "http://localhost:3001"
      }
    }
  }
}

Important: Replace /absolute/path/to/magic_to_super with your actual project path.

Example paths:

• macOS: /Users/username/projects/magic_to_super
• Linux: /home/username/projects/magic_to_super
• Windows: C:\\Users\\username\\projects\\magic_to_super

If you already have other MCP servers configured:

{
  "mcpServers": {
    "existing-server": {
      "type": "stdio",
      "command": "node",
      "args": ["..."]
    },
    "superui": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/magic_to_super/superui-mcp/dist/index.js"],
      "env": {
        "API_BASE_URL": "http://localhost:3001"
      }
    }
  }
}

1. Close VS Code completely (Cmd+Q on Mac, or close all windows)
2. Restart VS Code
3. The MCP server will load automatically

1. Open Claude Code chat in VS Code
2. Check that the MCP server is connected (look for a green indicator)
3. You're ready to use SuperUI!

SuperUI uses a 2-stage discovery process for better accuracy:

When you ask for a component, Claude automatically calls list_components to find matching options:

User: "I need an animated button with glow effect"

Claude:
  → list_components(query="animated button glow effect")
  ← Returns: [glow-button, neon-button, shimmer-button, pulse-button, ...]

Claude reviews the candidates and calls get_component_details for the best match:

Claude:
  → get_component_details(componentName="glow-button")
  ← Returns: Full installation guide with commands, imports, and examples

I need a button component for my React app

What happens behind the scenes:

1. Claude calls list_components(query="button")
2. Finds: button, glow-button, shimmer-button, etc.
3. Claude calls get_component_details(componentName="button")
4. Provides installation guide

I want an AI chat interface with streaming support

What happens:

1. list_components(query="ai chat streaming")
2. Finds: ai-conversation, ai-message, ai-loader, ai-prompt-input
3. Claude reviews and selects appropriate components
4. Gets details for each selected component

Show me all animated text components

What happens:

1. list_components(query="animated text", category="text")
2. Finds: gradient-text, typing-text, shimmering-text, etc.
3. Claude presents the list and can get details for any of them

When Claude gets component details, you'll see:

# Glow Button

Button with animated glow effect and neon styling

## 📦 Installation

cd /path/to/your/project
npx shadcn@latest add glow-button

## 📁 Installation Path

The component will be installed to:
`src/components/ui`

## 🔧 Import Statement

import { GlowButton } from "@/components/button/glow-button"

## 💡 Basic Usage

<GlowButton>Click me</GlowButton>

## 🏷️ Component Details

- **Name**: Glow Button
- **Package**: shadcn-button
- **Category**: Advanced-button
- **Library**: shadcn-button
- **Tags**: button, glow, neon, animated, effect

## 📚 Additional Resources

- [Documentation](https://www.shadcn.io/button/glow-button)
- [Button Components Collection](https://www.shadcn.io/button)

## 💡 Pro Tips

- These buttons include advanced animations and effects
- Test performance on lower-end devices
- Consider using reduced-motion queries for accessibility

The ranking algorithm prioritizes:

1. Exact matches (highest priority)
2. Name prefix matches
3. Name contains query
4. Tag matches
5. Description matches
6. Multi-word bonuses

Examples:

• "button" → Finds button first, then glow-button, shimmer-button
• "glow" → Finds glow-button first, then neon-button (similar tags)
• "chat interface" → Finds ai-conversation, ai-message, ai-prompt-input

SuperUI includes a powerful frontend cloning tool that helps you recreate any website's UI by iteratively comparing screenshots.

• 🌐 Playwright-Powered: Server automatically captures screenshots using headless browser
• 👁️ Vision-Based Comparison: LLM uses multimodal capabilities to compare screenshots
• 🔄 Iterative Refinement: Continuous improvement through multiple iterations
• 🎯 Pattern Matching: Automatically suggests relevant shadcn/ui components
• 📦 Stateless Design: No session management, LLM controls entire workflow
• 🚀 Zero Manual Work: All screenshot capture handled by server

Clone this website: https://example.com

What happens:

1. Server captures screenshot of target website
2. LLM analyzes structure, colors, components
3. Server suggests matching shadcn/ui components
4. LLM implements initial version
5. Server captures both target and current screenshots
6. LLM compares screenshots and identifies differences
7. LLM iteratively improves until satisfied

Clone this design (uploads screenshot)

What happens:

1. User provides screenshot instead of URL
2. Same workflow as above
3. No need for target URL

The tool supports 4 request types:

Captures target screenshot and provides analysis prompt.

Parameters:

• targetUrl (optional): Website URL to clone
• targetScreenshotBase64 (optional): Or provide screenshot directly
• screenshotOptions (optional): Viewport size, fullPage, delay, etc.

Returns:

• Analysis prompt with checklist
• Target screenshot as image

Matches components based on your analysis.

Parameters:

• targetDescription: Your vision analysis of the target

Returns:

• Recommended components
• Installation commands
• Usage examples

Captures both target and current implementation for comparison.

Parameters:

• targetUrl or targetScreenshotBase64: Target to compare against
• localUrl: Your development server (e.g., http://localhost:3000)
• iteration (optional): Current iteration number

Returns:

• Comparison checklist prompt
• Target screenshot
• Current implementation screenshot

Provides specific improvement suggestions based on differences.

Parameters:

• differences: Array of differences found during comparison
• iteration (optional): Current iteration number

Returns:

• Priority-based improvement guide
• Specific suggestions for each difference
• Next steps

Create a .env file in superui-server/:

PORT=3001
NODE_ENV=development
CORS_ORIGINS=http://localhost:3000,http://localhost:3001

Set in .claude.json:

{
  "env": {
    "API_BASE_URL": "http://localhost:3001",
    "TIMEOUT": "30000"
  }
}

If you need to use a different port:

1. Update PORT in API server .env
2. Update API_BASE_URL in .claude.json
3. Restart both servers

Symptoms:

• Claude Code doesn't respond to component requests
• "Tool not available" errors

Solutions:

1. Check VS Code Output:

   • View → Output (Cmd+Shift+U)
   • Select "Claude Code" from dropdown
   • Look for error messages

2. Verify .claude.json:

   # Check JSON syntax
   cat ~/.claude.json | jq

3. Check MCP server path:

   # Verify file exists
   ls /path/to/magic_to_super/superui-mcp/dist/index.js

4. Rebuild MCP server:

   cd superui-mcp
   npm run build

5. Restart VS Code completely

Symptoms:

• "API Server Unavailable" messages
• Fallback installation instructions

Solutions:

1. Check API server status:

   curl http://localhost:3001/health

2. Restart API server:

   cd superui-server
   npm start

3. Check if port 3001 is in use:

   # macOS/Linux
   lsof -i :3001
   
   # Windows
   netstat -ano | findstr :3001

4. Check API server logs for errors

Symptoms:

• "Component not found" messages

Solutions:

1. Check available components:

   curl http://localhost:3001/api/component/list

2. Search for component:

   curl "http://localhost:3001/api/component/search?q=button"

3. Try using exact component name from the supported list

Solutions:

1. Make sure you're in the correct project directory
2. Claude Code automatically detects your VS Code workspace path
3. Check the installation guide for the correct path

GET http://localhost:3001/health

POST http://localhost:3001/api/component/list
Content-Type: application/json

{
  "query": "animated button glow",
  "category": "advanced-button",  // optional
  "limit": 10                     // optional, default: 10
}

Response:

{
  "results": [
    {
      "name": "glow-button",
      "displayName": "Glow Button",
      "description": "Button with animated glow effect",
      "category": "advanced-button",
      "library": "shadcn-button"
    }
  ],
  "metadata": {
    "query": "animated button glow",
    "category": "all",
    "count": 5,
    "timestamp": "2025-10-08T...",
    "version": "1.0.0"
  }
}

POST http://localhost:3001/api/component/details
Content-Type: application/json

{
  "componentName": "glow-button",
  "absolutePathToCurrentFile": "/path/to/file.tsx",
  "absolutePathToProjectDirectory": "/path/to/project"
}

Response:

{
  "result": "# Glow Button\n\nButton with animated glow effect...",
  "metadata": {
    "componentName": "glow-button",
    "timestamp": "2025-10-08T...",
    "version": "1.0.0"
  }
}

POST http://localhost:3001/api/component
Content-Type: application/json

{
  "searchQuery": "button",
  "message": "I need a button",
  "absolutePathToCurrentFile": "/path/to/file.tsx",
  "absolutePathToProjectDirectory": "/path/to/project",
  "standaloneRequestQuery": "I need a button component"
}

GET http://localhost:3001/api/component/search?q=button

GET http://localhost:3001/api/component/list?category=form

GET http://localhost:3001/api/component/button

POST http://localhost:3001/api/clone
Content-Type: application/json

{
  "requestType": "initial_analysis",
  "targetUrl": "https://example.com",
  "screenshotOptions": {
    "fullPage": true,
    "width": 1920,
    "height": 1080,
    "delay": 2000
  }
}

Request Types:

• initial_analysis - Capture and analyze target screenshot
• component_suggestion - Get component recommendations
• compare_screenshots - Compare target vs current
• iteration_guide - Get improvement suggestions

Response:

{
  "text": "Analysis prompt and instructions...",
  "screenshots": {
    "target": {
      "data": "base64-encoded-image",
      "mimeType": "image/png",
      "metadata": { "width": 1920, "height": 1080, "url": "...", "timestamp": "..." }
    },
    "current": {
      "data": "base64-encoded-image",
      "mimeType": "image/png",
      "metadata": { ... }
    }
  },
  "components": [ ... ],
  "installations": [ "npx shadcn@latest add button", ... ],
  "metadata": {
    "requestType": "initial_analysis",
    "timestamp": "2025-10-12T...",
    "version": "1.0.0"
  }
}

POST http://localhost:3001/api/clone/screenshot
Content-Type: application/json

{
  "url": "https://example.com",
  "options": {
    "fullPage": true,
    "width": 1920,
    "height": 1080
  }
}

magic_to_super/
├── superui-mcp/              # MCP Server (v2.0.0)
│   ├── src/
│   │   ├── index.ts          # Main server
│   │   ├── tools/
│   │   │   ├── list-components.ts       # Stage 1: Component discovery
│   │   │   ├── get-components.ts        # DEPRECATED
│   │   │   ├── get-component-details.ts # Stage 2: Component details
│   │   │   ├── build-landing.ts         # Template builder
│   │   │   └── clone-frontend.ts        # NEW: Frontend cloning
│   │   └── utils/
│   │       ├── base-tool.ts
│   │       ├── config.ts
│   │       └── http-client.ts
│   ├── dist/                 # Built files
│   ├── package.json
│   └── tsconfig.json
│
└── superui-server/           # API Server
    ├── src/
    │   ├── index.ts          # Express server
    │   ├── routes/
    │   │   ├── component.ts  # Component endpoints
    │   │   ├── landing.ts    # Template endpoints
    │   │   └── clone.ts      # Clone endpoints
    │   ├── services/
    │   │   ├── component-service.ts       # Component logic
    │   │   ├── landing-service.ts         # Template logic
    │   │   ├── clone-service.ts           # Clone logic
    │   │   └── screenshot-service.ts      # Playwright screenshots
    │   └── utils/
    │       ├── component-finder.ts        # 70+ components database
    │       ├── component-matcher.ts       # Pattern matching
    │       ├── clone-prompts.ts           # Analysis prompts
    │       └── landing-conversation.ts    # Template conversation
    ├── dist/                 # Built files
    ├── package.json
    └── tsconfig.json

cd superui-server
npm run dev

cd superui-mcp
npm run dev

1. Edit superui-server/src/utils/component-finder.ts
2. Add component to COMPONENT_LIBRARY object:

   "new-component": {
     componentName: "new-component",
     displayName: "New Component",
     packageName: "@radix-ui/react-new-component",
     importStatement: `import { NewComponent } from "@/components/ui/new-component"`,
     usage: `<NewComponent />`,
     description: "Description of the component",
     category: "form",
     tags: ["tag1", "tag2", "tag3"]
   }

3. Rebuild and restart API server

# Test API server health
curl http://localhost:3001/health

# Test component search
curl "http://localhost:3001/api/component/search?q=button"

# Test component retrieval
curl -X POST http://localhost:3001/api/component \
  -H "Content-Type: application/json" \
  -d '{"searchQuery": "button", "message": "I need a button"}'

cd superui-server
npm run build
NODE_ENV=production npm start

# Install PM2
npm install -g pm2

# Start API server
cd superui-server
pm2 start dist/index.js --name superui-api

# Start on boot
pm2 startup
pm2 save

Create Dockerfile in superui-server/:

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist ./dist
EXPOSE 3001
CMD ["npm", "start"]

Build and run:

docker build -t superui-api .
docker run -p 3001:3001 superui-api

• shadcn/ui Documentation
• Radix UI Documentation
• Tailwind CSS Documentation
• MCP (Model Context Protocol)
• Claude Code Extension

MIT License

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

For issues and questions:

1. Check the API server logs
2. Check VS Code Output panel (Claude Code)
3. Verify MCP server build status
4. Check .claude.json syntax
5. Open an issue on GitHub

• Node.js 18+ installed
• Claude Code extension installed in VS Code
• Repository cloned
• API server installed and built
• Playwright chromium installed (npx playwright install chromium)
• MCP server installed and built
• API server running on port 3001
• .claude.json configured with correct absolute path
• VS Code restarted
• Tested with "I need a button component"
• Received installation instructions

Ready to go!

• Ask Claude Code for UI components and get instant installation instructions! 🚀
• Clone any website with "Clone https://example.com" 🎨
• Build landing pages with conversational templates! 📄