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

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

Adding Examples

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

Adding Components

1. Add entries to JSONL files in src/data/components/
2. Format: {"name": "...", "description": "...", "category": "...", "props": "...", "usage": "...", "installation": "...", "variants": [...], "dependencies": [...]}
3. 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:

1. find-component - Find relevant components
2. generate-component - Create based on patterns
3. 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