# Superdesign MCP Server

An MCP (Model Context Protocol) server that brings [Superdesign](https://github.com/superdesigndev/superdesign) - an open source AI design agent by [@jasonzhou1993](https://twitter.com/jasonzhou1993) and [@jackjack_eth](https://twitter.com/jackjack_eth) - to Claude Code as native tools. This server operates as a "design orchestrator" that provides structured specifications for your IDE's LLM to execute, enabling Superdesign's sophisticated design capabilities without requiring Anthropic API keys.

## Key Benefits

- **No API Keys Required**: Works directly with Claude Code's built-in LLM connection
- **Local Execution**: Runs entirely on your machine as an MCP server
- **IDE Integration**: Seamlessly integrates with Claude Code (and potentially Cursor, Windsurf, or other MCP-compatible IDEs - untested)
- **Based on Open Source**: Built on top of [Superdesign.dev](https://www.superdesign.dev), an open source AI design system

## Installation

1. Install dependencies:
```bash
npm install
```

2. Build the server:
```bash
npm run build
```

## Claude Code Integration

1. Add the MCP server to your Claude Code configuration:
```bash
# Create or edit your Claude Code MCP settings file
# On macOS:
mkdir -p ~/.claude-code
cp claude-mcp-config.json ~/.claude-code/mcp-settings.json

# Or add manually to your existing mcp-settings.json:
```

Example `~/.claude-code/mcp-settings.json`:
```json
{
  "mcpServers": {
    "superdesign": {
      "command": "node",
      "args": ["/path/to/superdesign/dist/index.js"],
      "env": {}
    }
  }
}
```

2. Restart Claude Code

3. The MCP server will provide these Superdesign orchestrator tools in Claude Code:
   - `superdesign_generate` - Returns specifications for Claude to generate designs
   - `superdesign_iterate` - Returns instructions for Claude to iterate on existing designs
   - `superdesign_extract_system` - Returns instructions for design system extraction
   - `superdesign_list` - Lists all created designs in the workspace

## Development

Run in development mode:
```bash
npm run dev
```

## Superdesign Tools Available

### superdesign_generate
Returns structured specifications for Claude Code to generate designs:
- **UI designs**: Complete responsive interfaces
- **Wireframes**: Minimal black and white layouts  
- **Components**: Individual UI components (HTML/React/Vue)
- **Logos**: SVG logo designs
- **Icons**: SVG icon designs

Parameters:
- `prompt`: Description of what to create
- `design_type`: Type of design (ui, wireframe, component, logo, icon)
- `variations`: Number of variations to generate (1-5, default 3)
- `framework`: Framework for components (html, react, vue)

**Output**: Detailed specifications including Superdesign system prompt, file naming patterns, and design guidelines for Claude Code to execute.

### superdesign_iterate
Returns iteration instructions for Claude Code to improve existing designs:
- Reads existing design files  
- Provides structured feedback application guidelines
- Maintains design consistency through Superdesign principles

Parameters:
- `design_file`: Path to existing design file
- `feedback`: Improvement instructions
- `variations`: Number of variations to create

**Output**: Iteration specifications including original design content, feedback to apply, and Superdesign guidelines for Claude Code to execute.

### superdesign_extract_system
Returns instructions for Claude Code to extract design systems from screenshots:
- Provides analysis framework for visual design patterns
- Guides extraction of color palettes, typography, spacing
- Specifies JSON structure for reusable design systems

**Output**: Extraction specifications and JSON schema for Claude Code to analyze images and create design system files.

### superdesign_list
List all Superdesign creations in workspace:
- Shows design iterations
- Shows extracted design systems
- Displays file organization

### superdesign_gallery
Generate an interactive HTML gallery to view all designs:
- **Browser-based gallery** - opens in your default browser
- **Visual previews** - see design thumbnails in a responsive grid
- **Interactive features** - click to view full-screen, copy paths
- **Mobile responsive** - works on desktop, tablet, and mobile
- **Auto-discovery** - finds all HTML/SVG files in design_iterations/

Parameters:
- `workspace_path`: Workspace directory (optional, defaults to current directory)

**Output**: Gallery HTML file with embedded previews and JavaScript interactions. The gallery opens automatically in your browser, providing a Superdesign-like canvas experience.

## How the Orchestrator Works

This MCP server operates as a **design orchestrator** rather than a direct generator:

1. **User Request**: "Generate a modern dashboard UI"
2. **MCP Server**: Returns detailed specifications with:
   - Complete Superdesign system prompt and guidelines
   - Exact file paths and naming conventions
   - Design type-specific instructions
   - Number of variations to create
3. **Claude Code**: Receives specifications and:
   - Generates the actual HTML/SVG/React code
   - Saves files to specified locations
   - Follows all Superdesign design principles

## Usage in Claude Code

Once configured, you can use Superdesign through Claude Code with natural language:

**Example Usage:**
- "Generate a modern dashboard UI design"
- "Create 3 variations of a login page wireframe"  
- "Design a React component for a product card"
- "Make a minimalist logo for a tech startup"
- "Iterate on the dashboard design with better spacing"
- "Show me the gallery of all my designs"

**Requirements:**
- Claude Code with MCP support
- No API keys needed (uses Claude Code's existing LLM connection)

**File Organization:**
Designs are automatically saved to `superdesign/` directory (visible folder):
- `design_iterations/` - Generated designs (HTML/SVG files)
- `design_system/` - Extracted design systems (JSON files)

**Benefits:**
- No API key configuration required
- Uses Claude Code's existing LLM capabilities
- Maintains all of Superdesign's sophisticated design methodology
- Proper file organization and naming conventions
- Full design iteration workflow support

## Known Issues & Troubleshooting

### File Permissions Error
If you encounter permission errors when running the MCP server:
```bash
# Add execute permissions to the built file
chmod +x dist/index.js
```

### MCP Tools Not Appearing
If Superdesign tools don't appear in Claude Code after installation:
1. Ensure you've completely quit Claude Code (not just closed the window)
2. Restart Claude Code from your terminal
3. Verify the server is registered: `claude mcp list`
4. Check the tools are available by asking Claude: "What tools do you have available?"

### Server Registration Issues
If the server fails to register:
```bash
# Remove and re-add the server
claude mcp remove superdesign -s user
claude mcp add --scope user superdesign /path/to/superdesign/dist/index.js
```

### Build Errors
Ensure you have Node.js 16+ installed:
```bash
node --version  # Should be v16.0.0 or higher
```

## 🤝 Relationship to Superdesign

This MCP server provides a complementary integration for [Superdesign](https://github.com/superdesigndev/superdesign) by [@jasonzhou1993](https://twitter.com/jasonzhou1993) and [@jackjack_eth](https://twitter.com/jackjack_eth).

While Superdesign offers an IDE extension that works across multiple editors, this MCP server specifically enhances Claude Code by:
- **Eliminating the need for API keys** - uses Claude Code's built-in LLM connection
- **Providing native tool integration** - no manual prompt copying required
- **Enabling direct tool calls** - seamless workflow without copy/paste

This addresses the community request for Claude Code API provider support (see [Superdesign Issue #3](https://github.com/superdesigndev/superdesign/issues)).

### How it's Different

| Aspect | Superdesign Extension | This MCP Server |
|--------|----------------------|-----------------|
| **Integration Type** | IDE Extension | Native MCP Tools |
| **Claude Code Access** | Manual prompt copying | Direct tool invocation |
| **API Requirements** | Separate API key needed | Uses Claude Code's existing connection |
| **User Experience** | Copy/paste workflow | Automated orchestration |

## License

This project follows the same license as the original Superdesign project. Please refer to the [Superdesign repository](https://www.superdesign.dev) for license details.