Design Systems Mcp

An AI-powered Model Context Protocol (MCP) server providing intelligent access to authoritative design systems knowledge. Powered by Supabase vector search with 200+ 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 - 📚 200+ 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

- ⚡ Streaming Responses - Chat answers stream token-by-token via SSE; first content appears in seconds - 🏠 Refreshed Landing Page - Hero, MCP endpoint with one-click copy, and a "What's inside" overview - 🛡️ Source Reliability Badges - Every answer flags Primary / Authoritative / Reference / Example / Community sources - ✨ 200+ Curated Entries - W3C, WCAG 2.2, ARIA APG, and 10+ major design systems - 🔧 Production Vector Search - Supabase pgvector with OpenAI embeddings, keyword fallback - 📖 Universal MCP Client Support - Works with any MCP-capable client (Claude Desktop, Cursor, Windsurf, etc.)

Developer Experience

- 🌐 Zero Setup Required - Public MCP endpoint ready to use - 🤖 AI Chat Interface - Natural language queries with GPT-4o + streaming responses (SSE) for fast time-to-first-token - 🧪 Local Development - Complete testing environment with hot reload - 📝 Comprehensive Docs - Updated setup guides for every major MCP client

Content Library

200+ 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

1. Clone and Install

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

   cd design-systems-mcp

   npm install

   

2. Configure Environment

   cp .dev.vars.example .dev.vars

   # Edit .dev.vars and add your credentials

   

3. 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:

<details>
<summary><b>Claude Desktop</b> - Click to expand configuration</summary>

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

1. Open Claude Desktop and navigate to Settings → Connectors

2. Click "Add custom connector" at the bottom of the connectors list

3. Fill in the connector details:
- Name: Design Systems Assistant (or any name you prefer)
- URL: https://design-systems-mcp.southleft.com/mcp

4. Click "Add" to save the connector

5. 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.

</details>

<details>
<summary><b>Claude Code (CLI)</b> - Click to expand configuration</summary>

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

</details>

<details>
<summary><b>Cursor IDE</b> - Click to expand configuration</summary>

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.

</details>

<details>
<summary><b>Cline (VSCode Extension)</b> - Click to expand configuration</summary>

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.

</details>

<details>
<summary><b>Continue (VSCode Extension)</b> - Click to expand configuration</summary>

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

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

</details>

<details>
<summary><b>Zed Editor</b> - Click to expand configuration</summary>

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

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

</details>

<details>
<summary><b>Generic MCP Client</b> - Click to expand configuration</summary>

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)

</details>

<details>
<summary><b>Local Development Setup</b> - Click to expand configuration</summary>

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.

</details>

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

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, workflows, 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 (streaming):

The /ai-chat endpoint returns a Server-Sent Events stream so content appears progressively. Each event is data: {"t": "<chunk>"}\n\n, terminated by event: done\ndata: {}\n\n.

curl -N -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?"}'

The hosted web UI at / consumes this stream and renders markdown progressively.

Adding Content

Ingest Web Content

```bash