Cloudflare MCP Server Template

★ 176

from southleft

A template for deploying a remote, authentication-free MCP server on Cloudflare Workers. Tools are defined directly in the source code.

🔥🔥🔥✓ VerifiedFreeAdvanced setup

#automation #crm #e-commerce #scraping #database #documents #cloud #devops

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

Connect to MCP Clients

Choose your AI coding tool below for setup instructions:

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

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.

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

Quick Setup via CLI:

Copy & paste — that's it

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

Or manually edit .mcp.json:

Copy & paste — that's it

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

Verify connection:

Copy & paste — that's it

claude mcp list

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

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

Copy & paste — that's it

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

Restart Cursor after updating the configuration.

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

Location: VSCode Settings → Extensions → Cline → MCP Settings

Add to MCP servers configuration:

Copy & paste — that's it

{
  "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>Continue (VSCode Extension) - Click to expand configuration</summary>

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

Copy & paste — that's it

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

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

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

Copy & paste — that's it

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

</details> <details> <summary>Generic MCP Client - 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>Local Development Setup - Click to expand configuration</summary>

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

Copy & paste — that's it

{
  "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:

Copy & paste — that's it

{
  "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:

Copy & paste — that's it

{
  "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:

Copy & paste — that's it

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

MCP Tools List:

Copy & paste — that's it

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:

Copy & paste — that's it

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.

Copy & paste — that's it

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

Copy & paste — that's it

# 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

Copy & paste — that's it

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

Generate Vector Embeddings

Copy & paste — that's it

npm run ingest:vectors

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:supabase - Initialize Supabase database
npm run check:duplicates - Check for duplicate content

Project Structure

Copy & paste — that's it

design-systems-mcp/
├── src/
│   ├── index.ts                    # Main MCP server, transports, tool dispatch, embedded chat UI
│   ├── sse-session.ts              # SSE transport (Durable Object)
│   ├── streamable-http-handler.ts  # Streamable HTTP transport (/mcp)
│   ├── oauth-handler.ts            # OAuth flow
│   └── lib/
│       ├── content-manager.ts      # Content management
│       ├── search-handler.ts       # Vector + keyword search dispatch
│       ├── source-authority.ts     # Reliability tiers & APG disclaimers
│       └── ... (chunker, formatters, ingestion helpers)
├── content/
│   └── entries/              # Ingested content (JSON)
├── supabase/
│   └── migrations/           # SQL schema + RPC functions
├── scripts/
│   ├── ingestion/            # Content ingestion pipeline (URL, PDF, HTML, CSV, crawler)
│   └── build/                # Build helpers (manifest generation)
├── types/
│   └── content.ts           # TypeScript definitions
├── wrangler.jsonc          # Cloudflare Workers config
└── .dev.vars              # Local environment variables

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:

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

Documentation

DEPLOYMENT.md - Production deployment
CONTRIBUTING.md - How to contribute and add content
CREDITS.md - Content sources and attribution

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

Copy & paste — that's it

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

Quick Start

Using the Public MCP Server (Recommended)

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

Copy & paste — that's it

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

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

Local Development

Clone and Install

Copy & paste — that's it

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

Configure Environment

Copy & paste — that's it

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

Start Development Server
Copy & paste — that's it
```
npm run dev
```
Server available at: http://localhost:8787

Deployment

Deploy to Cloudflare Workers

Login to Cloudflare
Copy & paste — that's it
```
npx wrangler login
```

Set Secrets

Copy & paste — that's it

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
Copy & paste — that's it
```
npm run deploy
```

See DEPLOYMENT.md for detailed instructions.

Design Systems MCP Server

Features

Core Capabilities

Latest Updates

Developer Experience

Content Library

200+ Curated Entries Including:

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

Vector Search Architecture

Documentation

License & Attribution

Security & Privacy

Contributing

Support

Acknowledgments

Quick Start

Using the Public MCP Server (Recommended)

Local Development

Deployment

Deploy to Cloudflare Workers

Troubleshooting

Common Issues