Cloudflare MCP Server Template

Servidor MCP de Design Systems

Um servidor de Model Context Protocol (MCP) com tecnologia de IA, fornecendo acesso inteligente a conhecimento autoritativo de design systems. 395 entradas selecionadas abrangendo padrões W3C, diretrizes WCAG, prática de design systems e — a parte que um modelo de propósito geral não pode ajudar — os protocolos de interface de agente de 2025-2026.

🌐 Demonstração ao Vivo: https://design-systems-mcp.southleft.com/

Por que isso existe

Um modelo de fronteira já conhece Atomic Design, BEM e os critérios de sucesso da WCAG. Ele não sabe de forma confiável que os MCP Apps mudaram de _meta["openai/outputTemplate"] para _meta.ui.resourceUri, ou que o A2UI alcançou o candidato a v1.0 em junho de 2026. Em especificações em rápida evolução, o treinamento de todo modelo está desatualizado de uma forma que ele não consegue detectar — ele responde com confiança usando nomes de campos do ano passado.

É para isso que este servidor serve: conteúdo de fonte primária datado, citado e extraído que supera tanto o palpite de um modelo menor quanto a cara pesquisa ao vivo de um modelo de fronteira.

Recursos

Capacidades Principais

• 🎯 Busca Vetorial + por Palavras-chave - Supabase pgvector com embeddings plugáveis (Cloudflare Workers AI bge-m3, nativo de borda e gratuito dentro do plano Workers; OpenAI opcional), além de um caminho de texto completo Postgres que continua funcionando quando embeddings não estão disponíveis
• 📚 395 Entradas Selecionadas - Padrões W3C, WCAG 2.2, práticas ARIA, principais design systems e protocolos de interface de agente
• 🚦 Piso de Relevância - Pontuação ponderada por IDF significa que um tópico não coberto retorna nada em vez de conteúdo confiante e adjacente
• 🚀 Otimizado para Borda - Implantação em Cloudflare Workers com distribuição global

Atualizações Recentes

• 🤖 Cobertura de Interface de Agente (Ago 2026) - A2UI v1.0, MCP Apps SEP-1865, AG-UI, Sentient Design, UI generativa/efêmera, contratos de componentes
• 🧪 Harness de Avaliação - scripts/eval-mcp.ts pontua recuperação e substância em quatro níveis de dificuldade
• 🛡️ Selos de Confiabilidade de Fonte - Cada resposta sinaliza fontes Primária / Autoritativa / Referência / Exemplo / Comunidade
• 📖 Suporte Universal a Clientes MCP - Funciona com qualquer cliente compatível com MCP (Claude Desktop, Cursor, Windsurf, Codex, etc.)
• 🏛️ Principais Design Systems, em Profundidade - Carbon, Polaris, Atlassian, Material 3, Fluent, Spectrum, Nord, Mantine, shadcn/ui, Radix, Untitled UI — a orientação e a arquitetura de tokens, não apenas tabelas de props

Experiência do Desenvolvedor

• 🌐 Zero Configuração Necessária - Endpoint MCP público pronto para uso
• 🤖 Interface de Chat com IA - Perguntas e respostas em linguagem natural fundamentadas na base de conhecimento, transmitidas via Cloudflare Workers AI (Llama 3.3 70B) — sem OpenAI, sem créditos de API
• 🧪 Desenvolvimento Local - Ambiente de teste completo com recarga automática
• 📝 Documentação Abrangente - Guias de configuração atualizados para cada cliente MCP principal

Biblioteca de Conteúdo

395 Entradas Selecionadas Incluindo:

Interfaces de Agente e IA (2025-2026 — o material que um modelo geral erra)

• Protocolo A2UI v1.0 (Google) — componentes de lista de adjacência, negociação de catálogo, vinculação A2A
• MCP Apps / SEP-1865 — recursos ui://, metadados CSP, o namespace de método ui/, variáveis de tema do host
• Referência de eventos AG-UI; mapa de migração campo a campo do OpenAI Apps SDK → MCP Apps
• Sentient Design (Josh Clark) — o framework, o triângulo, experiências radicalmente adaptativas
• UI generativa e efêmera — artigo de UI generativa do Google Research, conteúdo versus chrome
• Contratos de componentes e componentes-como-dados (Nathan Curtis, Christine Vallaure)
• AGENTS.md / SKILL.md / DESIGN.md — a camada de design system voltada para agentes
• Como Lovable, v0, Figma Make e Replit cada um ingere um design system
• O debate da fonte da verdade: três campos, e por que "liderado por código vs liderado por design" não é o vocabulário real
• Design Systems Baseados em Contexto, contratos de componentes e documentação legível por máquina
• Como um design system chega ao Claude Code, Copilot, Cursor e Windsurf

Padrões e Especificações

• Especificação do W3C Design Tokens Community Group (DTCG)
• Diretrizes WCAG 2.2 (níveis A, AA, AAA)
• Guia de Práticas de Autoria WAI-ARIA (APG)
• Diretrizes de Acessibilidade de Conteúdo Web W3C
• Acessibilidade Móvel W3C no W3C

Recursos de Design Systems

• 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

Ferramentas e Frameworks

• Guias de Design Systems do Figma
• Documentação do Style Dictionary
• Módulo de Formato de Design Tokens
• Melhores Práticas do Storybook

Metodologias e Melhores Práticas

• Princípios do Atomic Design
• Manual de Design Systems
• Padrões de arquitetura de componentes
• Guias de implementação de acessibilidade

Início Rápido

Usando o Servidor MCP Público (Recomendado)

Sem necessidade de instalação! Conecte qualquer cliente MCP ao nosso servidor ao vivo:

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

Veja a seção Conectar a Clientes MCP abaixo para instruções detalhadas de configuração.

Desenvolvimento Local

1. Clonar e Instalar

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

2. Configurar Ambiente

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

3. Iniciar Servidor de Desenvolvimento

   npm run dev
   

   Servidor disponível em: http://localhost:8787

Conectar a Clientes MCP

Escolha sua ferramenta de codificação com IA abaixo para instruções de configuração:

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

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

claude mcp list

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

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

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

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

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

Solução de Problemas de Conexão

Servidor não está respondendo?

• Verifique se a URL está correta: https://design-systems-mcp.southleft.com/mcp
• Teste com curl: curl https://design-systems-mcp.southleft.com/health
• Verifique se seu cliente suporta servidores MCP remotos

Ferramentas não aparecendo?

• Reinicie seu cliente MCP após alterações de configuração
• Verifique os logs do cliente para erros de conexão
• Verifique se a sintaxe da configuração JSON está correta

Precisa de ajuda?

• Abra uma issue: Issues do GitHub

Ferramentas MCP Disponíveis

O servidor fornece estas ferramentas para assistentes de IA:

search_design_knowledge

Pesquise a base de conhecimento completa com compreensão semântica.

Parâmetros:

• query (string, obrigatório) - Consulta de pesquisa
• category (string, opcional) - Filtrar por categoria
• tags (array, opcional) - Filtrar por tags
• limit (número, opcional) - Máximo de resultados (padrão: 15)

Exemplo:

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

search_chunks

Encontre informações específicas dentro de blocos de conteúdo para respostas detalhadas.

Parâmetros:

• query (string, obrigatório) - Consulta de pesquisa
• limit (número, opcional) - Máximo de blocos (padrão: 8)

Exemplo:

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

browse_by_category

Navegue pelo conteúdo organizado por categoria.

Categorias: components, tokens, patterns, guidelines, workflows, general

Parâmetros:

• category (string, obrigatório) - Categoria para navegar

get_all_tags

Obtenha todas as tags de conteúdo disponíveis para filtragem e exploração.

Exemplos de API

Teste Direto da API

Verificação de Saúde:

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

Lista de Ferramentas MCP:

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

Consulta de Pesquisa:

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

Interface de Chat com IA (streaming):

O endpoint /ai-chat retorna um stream de Server-Sent Events para que o conteúdo apareça progressivamente. Cada evento é data: {"t": "<chunk>"}\n\n, terminado por 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?"}'

A interface web hospedada em / consome este stream e renderiza markdown progressivamente.

Adicionando Conteúdo

Ingerir Conteúdo Web

# 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

Ingerir Conteúdo PDF

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

Gerar Embeddings Vetoriais

npm run ingest:vectors

Desenvolvimento

Scripts Disponíveis

• npm run dev - Iniciar servidor de desenvolvimento local
• npm run deploy - Implantar no Cloudflare Workers
• npm run ingest:pdf <file> - Ingerir conteúdo PDF
• npm run ingest:url <url> - Ingerir conteúdo web
• npm run ingest:csv <file> - Ingestão em massa a partir de CSV
• npm run crawl:website <url> - Rastrear sites inteiros
• npm run ingest:vectors - Gerar embeddings para todo o conteúdo
• npm run setup:supabase - Inicializar banco de dados Supabase
• npm run check:duplicates - Verificar conteúdo duplicado

Estrutura do Projeto

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

Implantação

Implantar no Cloudflare Workers

1. Fazer login no Cloudflare

   npx wrangler login
   

2. Definir Segredos

   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
   

3. Implantar

   npm run deploy
   

Veja DEPLOYMENT.md para instruções detalhadas.

Arquitetura de Busca Vetorial

Este servidor usa Supabase para busca vetorial de nível de produção:

• Banco de dados: PostgreSQL com extensão pgvector
• Embeddings: Cloudflare Workers AI @cf/baai/bge-m3 (1024-dim, nativo de borda, sem chave de API) via VECTOR_SEARCH_PROVIDER=cloudflare; OpenAI text-embedding-3-small (1536-dim) também suportado
• Limite: 0,15 para recall ideal
• Busca Híbrida: Combina vetores semânticos com correspondência de texto
• Desempenho: Consultas abaixo de 100ms com indexação adequada

Estatísticas:

• 395 entradas no banco de dados de produção
• Mais de 4.800 blocos de conteúdo; busca vetorial em nível de entrada via Cloudflare Workers AI
• Padrões W3C, diretrizes WCAG, documentação de design systems
• Atualizações regulares com novas fontes autoritativas

Solução de Problemas

Problemas Comuns

Busca vetorial não está funcionando:

• Verifique as credenciais do Supabase nas variáveis de ambiente
• Verifique se as tabelas do banco de dados existem: npm run setup:supabase
• Verifique os logs: npx wrangler tail Conteúdo não encontrado:
• Verifique se o conteúdo existe: npm run check:duplicates
• Verifique se os embeddings foram gerados: Procure pelo campo embedding nas entradas de conteúdo
• Teste a busca localmente: npm run dev e use comandos curl

Falha na conexão MCP:

• Verifique se a URL está correta e acessível
• Confirme se o cliente suporta servidores MCP remotos
• Teste com curl: curl https://design-systems-mcp.southleft.com/health
• Reinicie o cliente MCP após alterações de configuração

Documentação

• DEPLOYMENT.md - Implantação em produção
• CONTRIBUTING.md - Como contribuir e adicionar conteúdo
• CREDITS.md - Fontes de conteúdo e atribuição

Licença e Atribuição

Licença: Licença MIT - Gratuita para uso pessoal e comercial

Atribuição de Conteúdo: Este projeto compila conhecimento sobre sistemas de design de muitos criadores brilhantes. Todo o conteúdo original permanece como propriedade intelectual de seus respectivos autores.

• Consulte CREDITS.md para atribuição completa
• Sempre faça link para as fontes originais ao compartilhar insights
• Apoie os criadores originais visitando seus sites

Segurança e Privacidade

• Nenhum dado sensível armazenado - Apenas conhecimento público sobre sistemas de design
• Variáveis de ambiente usam segredos do Cloudflare
• Código aberto e auditável
• Foco em privacidade - Nenhuma coleta de dados do usuário
• Atualizações regulares de segurança

Reporte problemas de segurança para: Segurança do GitHub

Contribuindo

Aceitamos contribuições! Se você deseja:

• Reportar bugs ou problemas
• Sugerir novos recursos
• Adicionar mais conteúdo sobre sistemas de design
• Melhorar o código
• Aprimorar a documentação

Por favor:

1. Verifique as issues existentes
2. Abra uma nova issue para discutir
3. Envie um pull request
4. Siga as diretrizes de contribuição

Suporte

• Issues: Issues do GitHub
• Discussões: Discussões do GitHub
• Demonstração ao vivo: https://design-systems-mcp.southleft.com/

Agradecimentos

Agradecemos à comunidade de sistemas de design por compartilhar conhecimento:

• Brad Frost pela metodologia Atomic Design
• W3C Design Tokens Community Group
• Web Accessibility Initiative (WAI)
• Todas as equipes de design que compartilham abertamente seu trabalho
• Toda a comunidade de sistemas de design

Consulte CREDITS.md para a lista completa.

Construído com ❤️ usando Cloudflare Workers e o Model Context Protocol