Cloudflare MCP Server Template

Servidor MCP de Sistemas de Diseño

Un servidor de Protocolo de Contexto de Modelo (MCP) impulsado por IA que proporciona acceso inteligente al conocimiento autoritativo de sistemas de diseño. 395 entradas seleccionadas que abarcan estándares W3C, pautas WCAG, práctica de sistemas de diseño y — la parte con la que un modelo de propósito general no puede ayudarte — los protocolos de interfaz de agente 2025-2026.

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

Por qué existe esto

Un modelo de frontera ya conoce Atomic Design, BEM y los criterios de éxito de WCAG. No sabe de manera confiable que MCP Apps pasó de _meta["openai/outputTemplate"] a _meta.ui.resourceUri, o que A2UI alcanzó el candidato a v1.0 en junio de 2026. En especificaciones que cambian rápidamente, el entrenamiento de cada modelo está desactualizado de una manera que no puede detectar — responde con confianza usando los nombres de campos del año pasado.

Para eso sirve este servidor: contenido de fuentes primarias fechado, citado y extraído que supera tanto la suposición de un modelo más pequeño como la costosa investigación en vivo de un modelo de frontera.

Características

Capacidades principales

• 🎯 Búsqueda vectorial + por palabras clave - Supabase pgvector con embeddings conectables (Cloudflare Workers AI bge-m3, nativo de edge y gratuito dentro del plan Workers; OpenAI opcional), más una ruta de texto completo de Postgres que sigue funcionando cuando los embeddings no están disponibles
• 📚 395 entradas seleccionadas - Estándares W3C, WCAG 2.2, prácticas ARIA, sistemas de diseño principales y protocolos de interfaz de agente
• 🚦 Umbral de relevancia - La puntuación ponderada por IDF significa que un tema no cubierto devuelve nada en lugar de contenido adyacente y confiado
• 🚀 Optimizado para edge - Implementación en Cloudflare Workers con distribución global

Actualizaciones recientes

• 🤖 Cobertura de interfaces de agente (agosto de 2026) - A2UI v1.0, MCP Apps SEP-1865, AG-UI, Sentient Design, UI generativa/efímera, contratos de componentes
• 🧪 Arnés de evaluación - scripts/eval-mcp.ts puntúa la recuperación y la sustancia en cuatro niveles de dificultad
• 🛡️ Insignias de confiabilidad de fuentes - Cada respuesta marca fuentes Primaria / Autoritativa / Referencia / Ejemplo / Comunidad
• 📖 Soporte universal de clientes MCP - Funciona con cualquier cliente compatible con MCP (Claude Desktop, Cursor, Windsurf, Codex, etc.)
• 🏛️ Sistemas de diseño principales, en profundidad - Carbon, Polaris, Atlassian, Material 3, Fluent, Spectrum, Nord, Mantine, shadcn/ui, Radix, Untitled UI — la guía y la arquitectura de tokens, no solo tablas de props

Experiencia de desarrollador

• 🌐 Sin configuración requerida - Endpoint MCP público listo para usar
• 🤖 Interfaz de chat con IA - Preguntas y respuestas en lenguaje natural basadas en la base de conocimiento, transmitidas a través de Cloudflare Workers AI (Llama 3.3 70B) — sin OpenAI, sin créditos de API
• 🧪 Desarrollo local - Entorno de pruebas completo con recarga en caliente
• 📝 Documentación completa - Guías de configuración actualizadas para cada cliente MCP principal

Biblioteca de contenido

395 entradas seleccionadas que incluyen:

Interfaces de agente e IA (2025-2026 — el material que un modelo general se equivoca)

• Protocolo A2UI v1.0 (Google) — componentes de lista de adyacencia, negociación de catálogo, enlace A2A
• MCP Apps / SEP-1865 — recursos ui://, metadatos CSP, el espacio de nombres de método ui/, variables de tema del host
• Referencia de eventos AG-UI; mapa de migración a nivel de campo de OpenAI Apps SDK → MCP Apps
• Sentient Design (Josh Clark) — el marco, el triángulo, experiencias radicalmente adaptativas
• UI generativa y efímera — el artículo de UI generativa de Google Research, contenido vs. marco
• Contratos de componentes y componentes-como-datos (Nathan Curtis, Christine Vallaure)
• AGENTS.md / SKILL.md / DESIGN.md — la capa de sistema de diseño orientada a agentes
• Cómo Lovable, v0, Figma Make y Replit incorporan cada uno un sistema de diseño
• El debate de la fuente de verdad: tres posturas, y por qué "liderado por código vs. liderado por diseño" no es el vocabulario real
• Sistemas de diseño basados en contexto, contratos de componentes y documentación legible por máquina
• Cómo un sistema de diseño llega a Claude Code, Copilot, Cursor y Windsurf

Estándares y especificaciones

• Especificación del Grupo Comunitario de Tokens de Diseño W3C (DTCG)
• Pautas WCAG 2.2 (niveles A, AA, AAA)
• Guía de prácticas de autoría WAI-ARIA (APG)
• Pautas de accesibilidad de contenido web W3C
• Accesibilidad móvil W3C en W3C

Recursos de sistemas de diseño

• 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

Herramientas y marcos

• Guías de sistemas de diseño de Figma
• Documentación de Style Dictionary
• Módulo de formato de tokens de diseño
• Mejores prácticas de Storybook

Metodologías y mejores prácticas

• Principios de Atomic Design
• Manual de sistemas de diseño
• Patrones de arquitectura de componentes
• Guías de implementación de accesibilidad

Inicio rápido

Uso del servidor MCP público (recomendado)

¡No se necesita instalación! Conecta cualquier cliente MCP a nuestro servidor en vivo:

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

Consulta la sección Conectar a clientes MCP a continuación para obtener instrucciones detalladas de configuración.

Desarrollo local

1. Clonar e instalar

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

2. Configurar el entorno

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

3. Iniciar el servidor de desarrollo

   npm run dev
   

   Servidor disponible en: http://localhost:8787

Conectar a clientes MCP

Elige tu herramienta de codificación con IA a continuación para obtener instrucciones de configuración:

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

Solución de problemas de conexión

¿El servidor no responde?

• Verifica que la URL sea correcta: https://design-systems-mcp.southleft.com/mcp
• Prueba con curl: curl https://design-systems-mcp.southleft.com/health
• Comprueba que tu cliente admita servidores MCP remotos

¿Las herramientas no aparecen?

• Reinicia tu cliente MCP después de los cambios de configuración
• Revisa los registros del cliente para ver errores de conexión
• Verifica que la sintaxis de la configuración JSON sea correcta

¿Necesitas ayuda?

• Abre un problema: Problemas de GitHub

Herramientas MCP disponibles

El servidor proporciona estas herramientas para asistentes de IA:

search_design_knowledge

Busca en la base de conocimiento completa con comprensión semántica.

Parámetros:

• query (cadena, obligatorio) - Consulta de búsqueda
• category (cadena, opcional) - Filtrar por categoría
• tags (matriz, opcional) - Filtrar por etiquetas
• limit (número, opcional) - Resultados máximos (predeterminado: 15)

Ejemplo:

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

search_chunks

Encuentra información específica dentro de fragmentos de contenido para respuestas detalladas.

Parámetros:

• query (cadena, obligatorio) - Consulta de búsqueda
• limit (número, opcional) - Fragmentos máximos (predeterminado: 8)

Ejemplo:

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

browse_by_category

Explora contenido organizado por categoría.

Categorías: componentes, tokens, patrones, pautas, flujos de trabajo, general

Parámetros:

• category (cadena, obligatorio) - Categoría para explorar

get_all_tags

Obtén todas las etiquetas de contenido disponibles para filtrar y explorar.

Ejemplos de API

Pruebas directas de API

Verificación de estado:

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

Lista de herramientas 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 búsqueda:

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

Interfaz de chat con IA (transmisión):

El endpoint /ai-chat devuelve una transmisión de Eventos enviados por el servidor para que el contenido aparezca progresivamente. Cada evento es 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?"}'

La interfaz web alojada en / consume esta transmisión y renderiza markdown progresivamente.

Agregar contenido

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

Incorporar contenido PDF

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

Generar embeddings vectoriales

npm run ingest:vectors

Desarrollo

Scripts disponibles

• npm run dev - Iniciar servidor de desarrollo local
• npm run deploy - Implementar en Cloudflare Workers
• npm run ingest:pdf <file> - Incorporar contenido PDF
• npm run ingest:url <url> - Incorporar contenido web
• npm run ingest:csv <file> - Incorporación masiva desde CSV
• npm run crawl:website <url> - Rastrear sitios web completos
• npm run ingest:vectors - Generar embeddings para todo el contenido
• npm run setup:supabase - Inicializar la base de datos de Supabase
• npm run check:duplicates - Verificar contenido duplicado

Estructura del proyecto

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

Implementación

Implementar en Cloudflare Workers

1. Iniciar sesión en Cloudflare

   npx wrangler login
   

2. Establecer secretos

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

   npm run deploy
   

Consulta DEPLOYMENT.md para obtener instrucciones detalladas.

Arquitectura de búsqueda vectorial

Este servidor utiliza Supabase para búsqueda vectorial de nivel de producción:

• Base de datos: PostgreSQL con extensión pgvector
• Embeddings: Cloudflare Workers AI @cf/baai/bge-m3 (1024-dim, nativo de edge, sin clave de API) mediante VECTOR_SEARCH_PROVIDER=cloudflare; OpenAI text-embedding-3-small (1536-dim) también compatible
• Umbral: 0.15 para una recuperación óptima
• Búsqueda híbrida: Combina vectores semánticos con coincidencia de texto
• Rendimiento: Consultas de menos de 100 ms con indexación adecuada

Estadísticas:

• 395 entradas en la base de datos de producción
• Más de 4,800 fragmentos de contenido; búsqueda vectorial a nivel de entrada mediante Cloudflare Workers AI
• Estándares W3C, pautas WCAG, documentación de sistemas de diseño
• Actualizaciones regulares con nuevas fuentes autoritativas

Solución de problemas

Problemas comunes

La búsqueda vectorial no funciona:

• Verifica las credenciales de Supabase en las variables de entorno
• Confirma que las tablas de la base de datos existan: npm run setup:supabase
• Revisa los registros: npx wrangler tail Contenido no encontrado:
• Verificar que el contenido existe: npm run check:duplicates
• Comprobar si se generaron los embeddings: Buscar el campo embedding en las entradas de contenido
• Probar la búsqueda localmente: npm run dev y usar comandos curl

La conexión MCP falla:

• Verificar que la URL sea correcta y accesible
• Comprobar que el cliente soporte servidores MCP remotos
• Probar con curl: curl https://design-systems-mcp.southleft.com/health
• Reiniciar el cliente MCP después de cambios de configuración

Documentación

• DEPLOYMENT.md - Despliegue en producción
• CONTRIBUTING.md - Cómo contribuir y añadir contenido
• CREDITS.md - Fuentes de contenido y atribución

Licencia y Atribución

Licencia: Licencia MIT - Gratuita para uso personal y comercial

Atribución de contenido: Este proyecto recopila conocimiento sobre sistemas de diseño de muchos creadores brillantes. Todo el contenido original sigue siendo propiedad intelectual de sus respectivos autores.

• Ver CREDITS.md para la atribución completa
• Siempre enlaza a las fuentes originales al compartir ideas
• Apoya a los creadores originales visitando sus sitios web

Seguridad y Privacidad

• No se almacenan datos sensibles - Solo conocimiento público de sistemas de diseño
• Las variables de entorno usan secretos de Cloudflare
• Código abierto y auditable
• Enfocado en la privacidad - No se recopilan datos de usuarios
• Actualizaciones de seguridad periódicas

Reporta problemas de seguridad a: Seguridad de GitHub

Contribuciones

¡Aceptamos contribuciones! Ya sea que quieras:

• Reportar errores o problemas
• Sugerir nuevas funciones
• Añadir más contenido de sistemas de diseño
• Mejorar el código base
• Mejorar la documentación

Por favor:

1. Revisa los problemas existentes
2. Abre un nuevo problema para discutir
3. Envía una solicitud de extracción (pull request)
4. Sigue las guías de contribución

Soporte

• Problemas: Problemas de GitHub
• Discusiones: Discusiones de GitHub
• Demo en vivo: https://design-systems-mcp.southleft.com/

Agradecimientos

Gracias a la comunidad de sistemas de diseño por compartir conocimiento:

• Brad Frost por la metodología de Diseño Atómico
• Grupo Comunitario de Design Tokens del W3C
• Iniciativa de Accesibilidad Web (WAI)
• Todos los equipos de diseño que comparten abiertamente su trabajo
• Toda la comunidad de sistemas de diseño

Ver CREDITS.md para la lista completa.

Construido con ❤️ usando Cloudflare Workers y el Protocolo de Contexto de Modelo (MCP)