Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 87 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,12 @@ A Model Context Protocol (MCP) server that provides AI assistants with comprehen
## 🚀 Key Features

- **Component Source Code**: Get the latest shadcn/ui v4 component TypeScript source
- **Component Demos**: Access example implementations and usage patterns
- **Component Demos**: Access example implementations and usage patterns
- **Blocks Support**: Retrieve complete block implementations (dashboards, calendars, login forms, etc.)
- **Metadata Access**: Get component dependencies, descriptions, and configuration details
- **Directory Browsing**: Explore the shadcn/ui repository structure
- **GitHub API Integration**: Efficient caching and intelligent rate limit handling
- **Framework Support**: Switch between React (shadcn/ui) and Svelte (shadcn-svelte) implementations
- **Framework Support**: Switch between React (shadcn/ui),Vue (shadcn-vue) or Svelte (shadcn-svelte) implementations

## 📦 Quick Start

Expand Down Expand Up @@ -41,6 +41,8 @@ npx @jpisnice/shadcn-ui-mcp-server --framework svelte
# Use Svelte with GitHub token
npx @jpisnice/shadcn-ui-mcp-server --framework svelte --github-api-key ghp_your_token_here

# Switch to Vue framework with GitHub token (default is react)
npx @jpisnice/shadcn-ui-mcp-server --framework vue --github-api-key ghp_your_token_here
# Using environment variable for framework
export FRAMEWORK=svelte
npx @jpisnice/shadcn-ui-mcp-server
Expand All @@ -58,7 +60,7 @@ shadcn-ui-mcp-server [options]
Options:
--github-api-key, -g <token> GitHub Personal Access Token
--framework, -f <framework> Framework to use: 'react' or 'svelte' (default: react)
--help, -h Show help message
--help, -h Show help message
--version, -v Show version information

Environment Variables:
Expand All @@ -78,17 +80,20 @@ Examples:
## 🔑 GitHub API Token Setup

**Why do you need a token?**

- Without token: Limited to 60 API requests per hour
- With token: Up to 5,000 requests per hour
- Better reliability and faster responses

### 📝 Getting Your Token (2 minutes)

1. **Go to GitHub Settings**:

- Visit [GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)](https://github.com/settings/tokens)
- Or: GitHub Profile → Settings → Developer settings → Personal access tokens

2. **Generate New Token**:

- Click "Generate new token (classic)"
- Add a note: "shadcn-ui MCP server"
- **Expiration**: Choose your preference (90 days recommended)
Expand All @@ -101,11 +106,13 @@ Examples:
### 🚀 Using Your Token

**Method 1: Command Line (Quick testing)**

```bash
npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_token_here
```

**Method 2: Environment Variable (Recommended)**

```bash
# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
Expand All @@ -120,14 +127,15 @@ The MCP server supports both **React** (shadcn/ui) and **Svelte** (shadcn-svelte

### 📋 Framework Comparison

| Framework | Repository | File Extension | Description |
|-----------|------------|----------------|-------------|
| **React** (default) | `shadcn-ui/ui` | `.tsx` | React components from shadcn/ui v4 |
| **Svelte** | `huntabyte/shadcn-svelte` | `.svelte` | Svelte components from shadcn-svelte |
| Framework | Repository | File Extension | Description |
| ------------------- | ------------------------- | -------------- | ------------------------------------ |
| **React** (default) | `shadcn-ui/ui` | `.tsx` | React components from shadcn/ui v4 |
| **Svelte** | `huntabyte/shadcn-svelte` | `.svelte` | Svelte components from shadcn-svelte |

### 🎯 How to Switch Frameworks

**Method 1: Command Line Argument (Recommended)**

```bash
# Use React (default)
npx @jpisnice/shadcn-ui-mcp-server
Expand All @@ -136,12 +144,17 @@ npx @jpisnice/shadcn-ui-mcp-server
npx @jpisnice/shadcn-ui-mcp-server --framework svelte
npx @jpisnice/shadcn-ui-mcp-server -f svelte

# Switch to Vue
npx @jpisnice/shadcn-ui-mcp-server --framework vue
npx @jpisnice/shadcn-ui-mcp-server -f vue

# Switch back to React
npx @jpisnice/shadcn-ui-mcp-server --framework react
npx @jpisnice/shadcn-ui-mcp-server -f react
```

**Method 2: Environment Variable**

```bash
# Use Svelte
export FRAMEWORK=svelte
Expand All @@ -156,6 +169,7 @@ FRAMEWORK=svelte npx @jpisnice/shadcn-ui-mcp-server
```

**Method 3: Combined with GitHub Token**

```bash
# Svelte with GitHub token
npx @jpisnice/shadcn-ui-mcp-server --framework svelte --github-api-key ghp_your_token_here
Expand All @@ -167,6 +181,7 @@ npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_token_here
### 🔍 Framework Detection

The server will log which framework is being used:

```bash
INFO: Framework set to 'svelte' via command line argument
INFO: MCP Server configured for SVELTE framework
Expand All @@ -175,6 +190,7 @@ INFO: File extension: .svelte
```

**⚠️ Important**: When using environment variables, make sure to use the correct syntax:

- ✅ Correct: `export FRAMEWORK=svelte && npx @jpisnice/shadcn-ui-mcp-server`
- ✅ Correct: `FRAMEWORK=svelte npx @jpisnice/shadcn-ui-mcp-server`
- ❌ Incorrect: `FRAMEWORK=svelte npx @jpisnice/shadcn-ui-mcp-server` (without proper spacing)
Expand All @@ -193,6 +209,7 @@ INFO: File extension: .svelte
#### Method 1: Using Continue Extension

1. **Install Continue Extension**:

- Open VS Code
- Go to Extensions (Ctrl+Shift+X)
- Search for "Continue" and install it
Expand All @@ -208,12 +225,22 @@ INFO: File extension: .svelte
"mcpServers": {
"shadcn-ui": {
"command": "npx",
"args": ["@jpisnice/shadcn-ui-mcp-server", "--github-api-key", "ghp_your_token_here"]
"args": [
"@jpisnice/shadcn-ui-mcp-server",
"--github-api-key",
"ghp_your_token_here"
]
},
// If using Svelte, do this instead:
"shadcn-ui-svelte": {
"command": "npx",
"args": ["@jpisnice/shadcn-ui-mcp-server", "--framework", "svelte", "--github-api-key", "ghp_your_token_here"]
"args": [
"@jpisnice/shadcn-ui-mcp-server",
"--framework",
"svelte",
"--github-api-key",
"ghp_your_token_here"
]
}
}
}
Expand All @@ -223,6 +250,7 @@ INFO: File extension: .svelte
#### Method 2: Using Claude Extension

1. **Install Claude Extension**:

- Search for "Claude" in VS Code extensions
- Install the official Claude extension

Expand All @@ -239,7 +267,7 @@ INFO: File extension: .svelte
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
}
},
// If using Svelte, do this instead:
// If using Svelte, do this instead:
"shadcn-ui-svelte": {
"command": "npx",
"args": ["@jpisnice/shadcn-ui-mcp-server", "--framework", "svelte"],
Expand All @@ -256,21 +284,33 @@ INFO: File extension: .svelte
#### Method 1: Global Configuration

1. **Open Cursor Settings**:

- Go to Settings (Cmd/Ctrl + ,)
- Search for "MCP" or "Model Context Protocol"

2. **Add MCP Server Configuration**:

```json
{
"mcpServers": {
"shadcn-ui": {
"command": "npx",
"args": ["@jpisnice/shadcn-ui-mcp-server", "--github-api-key", "ghp_your_token_here"]
"args": [
"@jpisnice/shadcn-ui-mcp-server",
"--github-api-key",
"ghp_your_token_here"
]
},
// If using Svelte, do this instead:
"shadcn-ui-svelte": {
"command": "npx",
"args": ["@jpisnice/shadcn-ui-mcp-server", "--framework", "svelte", "--github-api-key", "ghp_your_token_here"]
"args": [
"@jpisnice/shadcn-ui-mcp-server",
"--framework",
"svelte",
"--github-api-key",
"ghp_your_token_here"
]
}
}
}
Expand Down Expand Up @@ -311,12 +351,22 @@ Add to your Claude Desktop configuration (`~/.config/Claude/claude_desktop_confi
"mcpServers": {
"shadcn-ui": {
"command": "npx",
"args": ["@jpisnice/shadcn-ui-mcp-server", "--github-api-key", "ghp_your_token_here"]
"args": [
"@jpisnice/shadcn-ui-mcp-server",
"--github-api-key",
"ghp_your_token_here"
]
},
// If using Svelte, do this instead:
"shadcn-ui-svelte": {
"command": "npx",
"args": ["@jpisnice/shadcn-ui-mcp-server", "--framework", "svelte", "--github-api-key", "ghp_your_token_here"]
"args": [
"@jpisnice/shadcn-ui-mcp-server",
"--framework",
"svelte",
"--github-api-key",
"ghp_your_token_here"
]
}
}
}
Expand Down Expand Up @@ -349,6 +399,7 @@ Or with environment variable:
### Continue.dev Integration

1. **Install Continue.dev**:

- Download from [continue.dev](https://continue.dev)
- Install the application

Expand All @@ -361,7 +412,11 @@ Or with environment variable:
{
"name": "shadcn-ui",
"command": "npx",
"args": ["@jpisnice/shadcn-ui-mcp-server", "--github-api-key", "ghp_your_token_here"]
"args": [
"@jpisnice/shadcn-ui-mcp-server",
"--github-api-key",
"ghp_your_token_here"
]
}
```

Expand All @@ -371,7 +426,13 @@ Or for Svelte:
{
"name": "shadcn-ui-svelte",
"command": "npx",
"args": ["@jpisnice/shadcn-ui-mcp-server", "--framework", "svelte", "--github-api-key", "ghp_your_token_here"]
"args": [
"@jpisnice/shadcn-ui-mcp-server",
"--framework",
"svelte",
"--github-api-key",
"ghp_your_token_here"
]
}
```

Expand All @@ -380,6 +441,7 @@ Or for Svelte:
### Getting Component Source Code

Ask your AI assistant:

```
"Show me the source code for the shadcn/ui button component"
```
Expand All @@ -389,6 +451,7 @@ The AI can now access the complete TypeScript source code for the button compone
### Creating a Dashboard

Ask your AI assistant:

```
"Create a dashboard using shadcn/ui components. Use the dashboard-01 block as a starting point"
```
Expand All @@ -398,6 +461,7 @@ The AI can retrieve the complete dashboard block implementation and customize it
### Building a Login Form

Ask your AI assistant:

```
"Help me build a login form using shadcn/ui components. Show me the available form components"
```
Expand Down Expand Up @@ -443,7 +507,7 @@ The MCP server provides these tools for AI assistants:

// Get dashboard block
{
"tool": "get_block",
"tool": "get_block",
"arguments": { "blockName": "dashboard-01" }
}
```
Expand All @@ -453,26 +517,30 @@ The MCP server provides these tools for AI assistants:
### Common Issues

**"Rate limit exceeded" errors:**

```bash
# Solution: Add GitHub API token
npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_token_here
```

**"Command not found" errors:**

```bash
# Solution: Install Node.js 18+ and ensure npx is available
node --version # Should be 18+
npx --version # Should work
```

**Component not found:**

```bash
# Check available components first
npx @jpisnice/shadcn-ui-mcp-server
# Then call list_components tool via your MCP client
```

**Network/proxy issues:**

```bash
# Set proxy if needed
export HTTP_PROXY=http://your-proxy:8080
Expand All @@ -481,6 +549,7 @@ npx @jpisnice/shadcn-ui-mcp-server
```

**Editor not recognizing MCP server:**

```bash
# Verify the server is running
npx @jpisnice/shadcn-ui-mcp-server --help
Expand Down Expand Up @@ -534,4 +603,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file

**Made with ❤️ by [Janardhan Polle](https://github.com/Jpisnice)**

**Star ⭐ this repo if you find it helpful!**
**Star ⭐ this repo if you find it helpful!**
Loading
Loading