Design Systems MCP Server

An AI-powered Model Context Protocol (MCP) server providing intelligent access to authoritative design systems knowledge. Powered by Supabase vector search with 188+ curated entries including W3C standards, WCAG guidelines, and design system best practices.

🌐 Live Demo: https://design-systems-mcp.southleft.com/

Features

Core Capabilities

🎯 Production Vector Search - Supabase pgvector with OpenAI embeddings for semantic understanding
📚 188+ Curated Entries - W3C standards, WCAG 2.2, ARIA practices, and 10+ major design systems
🔍 Hybrid Search Architecture - Combines vector similarity with keyword matching (0.15 threshold)
🚀 Edge-Optimized - Cloudflare Workers deployment with global distribution

Latest Updates

✨ 36 New Authoritative Sources - Fresh content from Style Dictionary, Figma docs, CSS specs, and more
🔧 Production Vector Search - Now fully operational with proper Supabase integration
📖 Universal MCP Client Support - Pre-configured setups for 7+ popular AI coding tools
🎨 Rich Content Formatting - Enhanced markdown rendering with syntax highlighting

Developer Experience

🌐 Zero Setup Required - Public MCP endpoint ready to use
🤖 AI Chat Interface - Natural language queries with GPT-4o integration
🧪 Local Development - Complete testing environment with hot reload
📝 Comprehensive Docs - Updated setup guides for every major MCP client

Content Library

188+ Curated Entries Including:

Standards & Specifications

W3C Design Tokens Community Group (DTCG) Specification
WCAG 2.2 Guidelines (A, AA, AAA levels)
WAI-ARIA Authoring Practices Guide (APG)
W3C Web Content Accessibility Guidelines
W3C Mobile Accessibility at W3C

Design System Resources

Material Design 3 (Google)
Fluent Design System (Microsoft)
Ant Design (Alibaba)
Carbon Design System (IBM)
Polaris (Shopify)
Lightning Design System (Salesforce)
Atlassian Design System
Adobe Spectrum
GitHub Primer
Shopify Polaris

Tools & Frameworks

Figma Design System Guides
Style Dictionary Documentation
Design Tokens Format Module
Storybook Best Practices

Methodologies & Best Practices

Atomic Design principles
Design Systems Handbook
Component architecture patterns
Accessibility implementation guides

Quick Start

Using the Public MCP Server (Recommended)

No installation needed! Connect any MCP client to our live server:

https://design-systems-mcp.southleft.com/mcp

See Connect to MCP Clients section below for detailed setup instructions.

Local Development

Clone and Install

git clone https://github.com/southleft/design-systems-mcp.git
cd design-systems-mcp
npm install

Configure Environment

cp .dev.vars.example .dev.vars
# Edit .dev.vars and add your credentials

Start Development Server
```
npm run dev
```
Server available at: http://localhost:8787

Connect to MCP Clients

Choose your AI coding tool below for setup instructions:

Claude Desktop - Click to expand configuration

Add via Custom Connector UI (Recommended - No JSON editing!)

Open Claude Desktop and navigate to Settings → Connectors
Click "Add custom connector" at the bottom of the connectors list
Fill in the connector details:
- Name: Design Systems Assistant (or any name you prefer)
- URL: https://design-systems-mcp.southleft.com/mcp
Click "Add" to save the connector
Start using it! The connector will appear in your connectors list with 4 available tools:
- search_design_knowledge
- search_chunks
- browse_by_category
- get_all_tags

That's it! You can now use the Design Systems Assistant in your Claude Desktop conversations.

Note: Custom connectors are available for Claude Pro, Team, and Enterprise plans.

Claude Code (CLI) - Click to expand configuration

Quick Setup via CLI:

claude mcp add --transport http design-systems https://design-systems-mcp.southleft.com/mcp

Or manually edit .mcp.json:

{
  "mcpServers": {
    "design-systems": {
      "type": "http",
      "url": "https://design-systems-mcp.southleft.com/mcp"
    }
  }
}

Verify connection:

claude mcp list

Cursor IDE - Click to expand configuration

Location: ~/.cursor/mcp_config.json or ~/.config/cursor/mcp_config.json

{
  "mcpServers": {
    "design-systems": {
      "url": "https://design-systems-mcp.southleft.com/mcp"
    }
  }
}

Restart Cursor after updating the configuration.

Cline (VSCode Extension) - Click to expand configuration

Location: VSCode Settings → Extensions → Cline → MCP Settings

Add to MCP servers configuration:

{
  "design-systems": {
    "url": "https://design-systems-mcp.southleft.com/mcp",
    "description": "Design systems knowledge and best practices"
  }
}

Or add via Command Palette: Cline: Add MCP Server

Reload VSCode after configuration.

Continue (VSCode Extension) - Click to expand configuration

Location: VSCode Settings → Extensions → Continue → config.json

{
  "mcpServers": [
    {
      "name": "design-systems",
      "url": "https://design-systems-mcp.southleft.com/mcp",
      "description": "Design systems knowledge base"
    }
  ]
}

Zed Editor - Click to expand configuration

Location: ~/.config/zed/settings.json

{
  "mcp": {
    "servers": {
      "design-systems": {
        "url": "https://design-systems-mcp.southleft.com/mcp"
      }
    }
  }
}

Generic MCP Client - Click to expand configuration

For any MCP client supporting remote servers:

Endpoint: https://design-systems-mcp.southleft.com/mcp

Protocol: JSON-RPC 2.0 over HTTP/HTTPS

Transport: Standard MCP transport (stdio, SSE, or HTTP)

Local Development Setup - Click to expand configuration

To connect to your local development server instead of the public endpoint:

{
  "mcpServers": {
    "design-systems": {
      "url": "http://localhost:8787/mcp"
    }
  }
}

Note: Local server requires running npm run dev first.

Connection Troubleshooting

Server not responding?

Verify the URL is correct: https://design-systems-mcp.southleft.com/mcp
Test with curl: curl https://design-systems-mcp.southleft.com/health
Check your client supports remote MCP servers

Tools not appearing?

Restart your MCP client after configuration changes
Check client logs for connection errors
Verify JSON configuration syntax is correct

Need help?

Open an issue: GitHub Issues
Check documentation: Connection Guide

Available MCP Tools

The server provides these tools for AI assistants:

search_design_knowledge

Search the complete knowledge base with semantic understanding.

Parameters:

query (string, required) - Search query
category (string, optional) - Filter by category
tags (array, optional) - Filter by tags
limit (number, optional) - Max results (default: 15)

Example:

{
  "name": "search_design_knowledge",
  "arguments": {
    "query": "WCAG 2.2 color contrast requirements",
    "category": "guidelines",
    "limit": 5
  }
}

search_chunks

Find specific information within content chunks for detailed answers.

Parameters:

query (string, required) - Search query
limit (number, optional) - Max chunks (default: 8)

Example:

{
  "name": "search_chunks",
  "arguments": {
    "query": "W3C DTCG design tokens specification",
    "limit": 3
  }
}

browse_by_category

Browse content organized by category.

Categories: components, tokens, patterns, guidelines, tools, general

Parameters:

category (string, required) - Category to browse

get_all_tags

Get all available content tags for filtering and exploration.

API Examples

Direct API Testing

Health Check:

curl https://design-systems-mcp.southleft.com/health

MCP Tools List:

curl -X POST https://design-systems-mcp.southleft.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Search Query:

curl -X POST https://design-systems-mcp.southleft.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search_chunks",
      "arguments": {"query": "design tokens", "limit": 3}
    }
  }'

AI Chat Interface:

curl -X POST https://design-systems-mcp.southleft.com/ai-chat \
  -H "Content-Type: application/json" \
  -d '{"message":"What are the WCAG 2.2 contrast requirements?"}'

Adding Content

Ingest Web Content

# Single URL
npm run ingest:url https://material.io/components/buttons

# Bulk from CSV
npm run ingest:csv urls.csv

# Crawl entire website
npm run crawl:website https://polaris.shopify.com --max-depth 3

Ingest PDF Content

npm run ingest:pdf path/to/design-guide.pdf

Generate Vector Embeddings

npm run ingest:vectors

See Content Ingestion Guide for detailed instructions.

Development

Available Scripts

npm run dev - Start local development server
npm run deploy - Deploy to Cloudflare Workers
npm run ingest:pdf <file> - Ingest PDF content
npm run ingest:url <url> - Ingest web content
npm run ingest:csv <file> - Bulk ingest from CSV
npm run crawl:website <url> - Crawl entire websites
npm run ingest:vectors - Generate embeddings for all content
npm run setup:database - Initialize Supabase database
npm run check:duplicates - Check for duplicate content

Project Structure

design-systems-mcp/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── lib/
│   │   ├── content-manager.ts     # Content management
│   │   ├── search-handler.ts      # Vector search
│   │   └── vector-search.ts       # Supabase integration
│   └── tools/                # MCP tool definitions
├── content/
│   ├── entries/              # Ingested content (JSON)
│   └── raw/                  # Raw source files
├── scripts/
│   ├── ingestion/            # Content ingestion tools
│   └── setup/                # Database setup scripts
├── types/
│   └── content.ts           # TypeScript definitions
├── docs/                    # Additional documentation
├── wrangler.jsonc          # Cloudflare Workers config
└── .dev.vars              # Local environment variables

Deployment

Deploy to Cloudflare Workers

Login to Cloudflare
```
npx wrangler login
```

Set Secrets

npx wrangler secret put OPENAI_API_KEY
npx wrangler secret put SUPABASE_URL
npx wrangler secret put SUPABASE_SERVICE_KEY
npx wrangler secret put SUPABASE_ANON_KEY

Deploy
```
npm run deploy
```

See Deployment Guide for detailed instructions.

Vector Search Architecture

This server uses Supabase for production-grade vector search:

Database: PostgreSQL with pgvector extension
Embeddings: OpenAI text-embedding-3-small (1536 dimensions)
Threshold: 0.15 for optimal recall
Hybrid Search: Combines semantic vectors with text matching
Performance: Sub-100ms queries with proper indexing

Statistics:

188+ entries in production database
761+ content chunks with embeddings
W3C standards, WCAG guidelines, design system documentation
Regular updates with new authoritative sources

See Vector Search Setup for architecture details.

Troubleshooting

Common Issues

Vector search not working:

Check Supabase credentials in environment variables
Verify database tables exist: npm run setup:database
Check logs: npx wrangler tail

Content not found:

Verify content exists: npm run check:duplicates
Check if embeddings generated: Look for embedding field in content entries
Test search locally: npm run dev and use curl commands

MCP connection fails:

Verify URL is correct and accessible
Check client supports remote MCP servers
Test with curl: curl https://design-systems-mcp.southleft.com/health
Restart MCP client after configuration changes

See Troubleshooting Guide for detailed solutions.

Documentation

Connection Guide - Detailed MCP client setup
Content Ingestion - Adding new content
Vector Search Setup - Database configuration
Deployment Guide - Production deployment
Contributing - How to contribute
Security - Security best practices

License & Attribution

License: MIT License - Free for personal and commercial use

Content Attribution: This project compiles design systems knowledge from many brilliant creators. All original content remains the intellectual property of their respective authors.

See CREDITS.md for complete attribution
Always link back to original sources when sharing insights
Support original creators by visiting their websites

Security & Privacy

No sensitive data stored - Only public design system knowledge
Environment variables use Cloudflare secrets
Open source and auditable
Privacy-focused - No user data collection
Regular security updates

Report security issues to: GitHub Security

Contributing

We welcome contributions! Whether you want to:

Report bugs or issues
Suggest new features
Add more design system content
Improve the codebase
Enhance documentation

Please:

Check existing issues
Open a new issue to discuss
Submit a pull request
Follow contribution guidelines

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Live Demo: https://design-systems-mcp.southleft.com/

Acknowledgments

Thanks to the design systems community for sharing knowledge:

Brad Frost for Atomic Design methodology
W3C Design Tokens Community Group
Web Accessibility Initiative (WAI)
All design teams who openly share their work
The entire design systems community

See CREDITS.md for the complete list.

Built with ❤️ using Cloudflare Workers and the Model Context Protocol

Name		Name	Last commit message	Last commit date
Latest commit History 64 Commits
config		config
content		content
docs		docs
local-content-library		local-content-library
public		public
scripts		scripts
src		src
supabase		supabase
types		types
.dev.vars.example		.dev.vars.example
.env.example		.env.example
.gitignore		.gitignore
CREDITS.md		CREDITS.md
DEPLOYMENT.md		DEPLOYMENT.md
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
env.example		env.example
icon.png		icon.png
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
worker-configuration.d.ts		worker-configuration.d.ts
wrangler.jsonc		wrangler.jsonc

License

southleft/design-systems-mcp

Folders and files

Latest commit

History

Repository files navigation

Design Systems MCP Server

Features

Core Capabilities

Latest Updates

Developer Experience

Content Library

188+ Curated Entries Including:

Quick Start

Using the Public MCP Server (Recommended)

Local Development

Connect to MCP Clients

Connection Troubleshooting

Available MCP Tools

search_design_knowledge

search_chunks

browse_by_category

get_all_tags

API Examples

Direct API Testing

Adding Content

Ingest Web Content

Ingest PDF Content

Generate Vector Embeddings

Development

Available Scripts

Project Structure

Deployment

Deploy to Cloudflare Workers

Vector Search Architecture

Troubleshooting

Common Issues

Documentation

License & Attribution

Security & Privacy

Contributing

Support

Acknowledgments

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 3

Languages

Packages