Svelte Shadcn Mcp

shadcn-svelte MCP Server

A specialized Model Context Protocol (MCP) server for shadcn-svelte development, providing curated knowledge, code examples, and intelligent assistance for building modern UI components with design systems, theming, and accessibility best practices in Svelte and SvelteKit applications.

Features

🔍 Searchable Resources

Knowledge Base: Curated Q&A covering shadcn-svelte concepts, patterns, and best practices
Code Examples: Searchable collection of shadcn-svelte implementation patterns

🛠️ Intelligent Tools

search_knowledge - Find explanations and concepts
search_examples - Discover code patterns and implementations
search_components - Search UI components with props and variants
generate_component - Generate components with themes and accessibility
audit_with_rules - Review code against shadcn-svelte best practices
explain_concept - Get detailed explanations with examples

📝 Smart Prompts

generate-component - Generate modern shadcn-svelte components
audit-shadcn-code - Audit code for accessibility and design system compliance
explain-concept - Detailed concept explanations with examples
find-component - Find specific components with usage patterns

Installation

Option 1: Direct usage with bunx (Recommended)

Simply add to your Claude Desktop configuration - no installation required:

{
  "mcpServers": {
    "shadcn-svelte": {
      "command": "bunx",
      "args": ["@binsarjr/shadcn-svelte-mcp"],
      "env": {}
    }
  }
}

Option 2: Manual installation

# Clone and setup
git clone https://github.com/binsarjr/shadcn-svelte-mcp
cd shadcn-svelte-mcp

# Install dependencies with Bun
bun install

# Start the server
bun start

Project Structure

shadcn-svelte-mcp/
├── src/
│   ├── index.ts                    # Main MCP server implementation
│   ├── ShadcnSvelteSearchDB.ts   # SQLite database with FTS5 search
│   └── data/
│       ├── knowledge/             # Curated Q&A knowledge base (JSONL)
│       ├── examples/              # Code examples and patterns (JSONL)
│       └── components/            # Component catalog with props and variants (JSONL)
├── package.json
├── tsconfig.json
└── README.md

Usage with Claude Desktop

Recommended: Using bunx (no installation required)

{
  "mcpServers": {
    "shadcn-svelte": {
      "command": "bunx",
      "args": ["@binsarjr/shadcn-svelte-mcp"],
      "env": {}
    }
  }
}

Alternative: Local installation

{
  "mcpServers": {
    "shadcn-svelte": {
      "command": "bun",
      "args": ["/path/to/shadcn-svelte-mcp/src/index.ts"],
      "env": {}
    }
  }
}

Usage Examples

🔍 Search Knowledge

Tool: search_knowledge
Query: "button variants themes"

Returns detailed explanations about implementing button variants with different themes in shadcn-svelte.

📚 Find Code Examples

Tool: search_examples
Query: "card component accessibility"

Returns working shadcn-svelte card component implementations with accessibility features.

🧩 Search Components

Tool: search_components
Query: "dialog modal"

Returns component details for dialog/modal components with props, variants, and installation instructions.

🏗️ Generate Components

Tool: generate_component
Description: "User profile card with avatar, name, and action buttons"
Component Type: "card"
Theme: "auto"

Generates a complete shadcn-svelte component using modern patterns with relevant examples from the knowledge base.

🔍 Audit Code

Tool: audit_with_rules
Code: "<script>\n  let { variant = 'default', ...props } = $props();\n</script>\n<button class={buttonVariants({ variant })} {...props}><slot /></button>"
Focus: "accessibility"

Analyzes code and suggests shadcn-svelte improvements for accessibility compliance and design system consistency.

Key shadcn-svelte Concepts Covered

🎯 Core shadcn-svelte Features

Components - Pre-built, accessible UI components
Themes - Light/dark mode support with CSS variables
Variants - Component styling variations using class-variance-authority
Design System - Consistent color, spacing, and typography tokens
Accessibility - WCAG-compliant components with proper ARIA attributes

🧩 Svelte Integration

Component Composition - Using slots and component patterns
Reactive Patterns - Svelte's reactivity with shadcn-svelte components
TypeScript Integration - Proper type definitions and prop typing
SvelteKit Usage - Server-side rendering and routing integration
Style Management - Tailwind CSS integration and customization

📈 Advanced Patterns

Custom Theming - Creating custom theme configurations
Component Variants - Advanced styling patterns with cva
Responsive Design - Mobile-first component implementations
Form Handling - Form components with validation and accessibility
Animation - Motion and transition patterns with shadcn-svelte

Data Format

Knowledge Base (JSONL files in `data/knowledge/`)

{
  "question": "How do I customize shadcn-svelte button variants?",
  "answer": "To customize button variants in shadcn-svelte, you can modify the variants object in your button component using class-variance-authority (cva)...",
  "category": "components",
  "tags": ["button", "variants", "customization"]
}

Examples (JSONL files in `data/examples/`)

{
  "title": "Accessible Button with Custom Variants",
  "description": "Button component with custom variants and full accessibility support",
  "component": "Button",
  "code": "<script lang=\"ts\">\n  import { cn } from '$lib/utils';\n  import { buttonVariants } from './variants';\n  \n  type Variant = 'default' | 'destructive' | 'outline';\n  \n  interface Props {\n    variant?: Variant;\n    class?: string;\n  }\n  \n  let { variant = 'default', class: className, ...restProps }: Props = $props();\n</script>\n\n<button \n  class={cn(buttonVariants({ variant }), className)}\n  {...restProps}\n>\n  <slot />\n</button>",
  "category": "buttons",
  "tags": ["button", "variants", "accessibility", "typescript"],
  "complexity": "intermediate",
  "dependencies": ["class-variance-authority", "clsx"]
}

Component Entries (JSONL files in `data/components/`)

{
  "name": "Button",
  "description": "Displays a button or a component that looks like a button with various styling variants",
  "category": "form",
  "props": "{\"variant\": {\"type\": \"'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link'\", \"default\": \"'default'\"}, \"size\": {\"type\": \"'default' | 'sm' | 'lg' | 'icon'\", \"default\": \"'default'\"}}",
  "usage": "<Button variant=\"outline\" size=\"sm\">Click me</Button>",
  "installation": "npx shadcn-svelte@latest add button",
  "variants": ["default", "destructive", "outline", "secondary", "ghost", "link"],
  "dependencies": ["class-variance-authority", "clsx"]
}

Configuration

Database Location

The server stores its SQLite database following the XDG Base Directory specification:

All platforms: ~/.config/binsarjr/shadcn-svelte-mcp/database.db

This provides a consistent, organized location across all operating systems.

Environment Variables

You can customize the database location using environment variables:

{
  "mcpServers": {
    "shadcn-svelte": {
      "command": "bunx",
      "args": ["@binsarjr/shadcn-svelte-mcp"],
      "env": {
        "SHADCN_SVELTE_MCP_CONFIG_DIR": "/custom/config/path",
        "SHADCN_SVELTE_MCP_DB_PATH": "/custom/database.db"
      }
    }
  }
}

Search Features

The server uses SQLite with FTS5 for advanced search capabilities:

Full-Text Search: Utilizes SQLite's FTS5 extension for powerful and efficient searching across the knowledge base, examples, and components.
Tokenization: Employs the unicode61 tokenizer with a comprehensive set of separators for robust indexing of terms.
Synonym Expansion: Enhances search recall by automatically expanding query terms with predefined shadcn-svelte-specific synonyms.
Result Highlighting: Search results include highlighted matches within relevant fields using FTS5's highlight() function.
Relevance Ranking: Results are ordered by relevance based on FTS5's internal ranking algorithm.
Advanced Boosting: Offers capabilities for custom scoring and boosting to fine-tune search results.

Development

Testing

The server provides comprehensive logging and error handling:

# Test the server
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | bun start

# Test via bunx
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | bunx @binsarjr/shadcn-svelte-mcp

# Enable development mode with watch
bun run dev

# Inspect the server (for debugging)
bun run inspect

Building and Publishing

# Build for production
bun run build

# Publish to npm
npm publish

Contributing

Adding Knowledge

Add entries to JSONL files in src/data/knowledge/
Format: {"question": "...", "answer": "...", "category": "...", "tags": [...]}
Focus on shadcn-svelte specific features and best practices

Adding Examples

Add entries to JSONL files in src/data/examples/
Format: {"title": "...", "description": "...", "component": "...", "code": "...", "category": "...", "tags": [...], "complexity": "...", "dependencies": [...]}
Include complete, working shadcn-svelte code examples

Adding Components

Add entries to JSONL files in src/data/components/
Format: {"name": "...", "description": "...", "category": "...", "props": "...", "usage": "...", "installation": "...", "variants": [...], "dependencies": [...]}
Document component API, variants, and usage patterns

Search Optimization

Use descriptive, searchable keywords in questions, titles, and descriptions
Include alternative phrasings for common concepts
Tag examples with relevant feature names (button, theme, variant, etc.)

Advanced Usage

Custom Search Queries

The search tools support sophisticated queries:

// Search for component patterns
search_examples("button variants accessibility")

// Find theming guidance
search_knowledge("dark mode theme customization")

// Discover specific components
search_components("dialog modal overlay")

Prompt Chaining

Use prompts in sequence for complex workflows:

find-component - Find relevant components
generate-component - Create based on patterns
audit-shadcn-code - Review and optimize

Integration Tips

Claude Desktop: Best for interactive development
API Integration: Use programmatically for code generation
CI/CD: Audit code in automated workflows
Documentation: Generate examples for design system documentation

Troubleshooting

Common Issues

"No results found"

Check search terms are relevant to shadcn-svelte
Try broader queries first, then narrow down
Ensure data files are properly formatted JSONL

"Tool not found"

Check MCP client configuration
Review server logs for startup errors

"Invalid data format"

Validate JSONL files (one JSON object per line)
Check for syntax errors in JSON objects

Database/Config Issues

Check if config directory is writable
Verify database permissions in the config folder
Use SHADCN_SVELTE_MCP_DB_PATH environment variable for custom locations
Check logs for database initialization messages

Debugging

# Enable debug logging
DEBUG=* bun start

# Test database location
bunx @binsarjr/shadcn-svelte-mcp  # Watch for config path logs

# Check config directory (all platforms)
ls -la ~/.config/binsarjr/shadcn-svelte-mcp/

License

MIT License - see LICENSE file for details.

Acknowledgments

Built with MCP TypeScript SDK
Validation with Zod
Curated shadcn-svelte knowledge from official documentation and community best practices
Powered by shadcn-svelte, Svelte, and SvelteKit

Top categories

tailwind daisyui admin template popup mdsvex portfolio blog form ecommerce ui carousel auth dark seo image routing