Servidor MCP de sistemas de diseño

Un servidor de Protocolo de Contexto de Modelos (MCP) basado en IA que proporciona acceso inteligente al conocimiento de los sistemas de diseño. Este servidor ingiere documentación de sistemas de diseño (PDF, contenido web) y permite a los asistentes de IA proporcionar orientación experta sobre sistemas de diseño, componentes, tokens y mejores prácticas.

🌐 Demostración en directo:https://design-systems-mcp.southleft.com/

Características

• 🤖 Interfaz de chat potenciada por IA: consultas en lenguaje natural con integración de OpenAI
• 📚 Ingestión de contenido: admite el análisis sintáctico de PDF y la extracción de contenido web
• 🔍 Búsqueda inteligente - Búsqueda semántica en toda la documentación de los sistemas de diseño
• 🎨 F ormato enriquecido: representación de Markdown con resaltado de sintaxis
• 🚀 Cloudflare Workers - Despliegue escalable sin servidor
• 🧪 Pruebas locales - Entorno de desarrollo local completo
• 🌐 Acceso público - Servidor MCP en vivo disponible para integraciones externas

Servidor de MCP en vivo

🚀 Puntos finales públicos

Dominio de los trabajadores:https://design-systems-mcp.southleft-llc.workers.dev

• Interfaz de chat AI:https://design-systems-mcp.southleft.com/
• Punto final MCP:https://design-systems-mcp.southleft-llc.workers.dev/mcp
• Comprobación de salud:https://design-systems-mcp.southleft-llc.workers.dev/health

pruébelo ahora

Visita la demostración en vivo y haz preguntas como:

• "¿Qué son los tokens de diseño y cómo debo utilizarlos?"
• "¿Cómo puedo crear componentes de botones accesibles?"
• "¿Cuáles son las mejores prácticas para organizar un sistema de diseño?"
• "¿Cómo funcionan los componentes en los sistemas de diseño?

Inicio rápido

Requisitos previos

• Node.js (v20.17.0+ o v22.9.0+)
• Clave API de OpenAI (para desarrollo local)

Configuración de desarrollo local

1. Clonar e instalar

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

2. Configurar entorno

   cp env.example .dev.vars # Edita .dev.vars y añade tu clave API OpenAI

3. Iniciar el servidor de desarrollo

   npm run dev

   El servidor estará disponible en: http://localhost:8787

4. Probar la Interfaz de Chat AI

   • Abre http://localhost:8787 en tu navegador
   • Prueba consultas de ejemplo como
     • "¿Qué son los tokens de diseño?"
     • "¿En qué parte del manual de sistemas de diseño se menciona a Alicia SEDLOCK?"
     • "¿Qué dice el manual de sistemas de diseño sobre Wraith, Gemini y BackstopJS?"
     • "¿Cómo implemento un sistema de diseño?"

Añadir contenido

1. Ingerir contenido (si no se ha hecho ya)

   # Añadir PDFs a local-content-library/ npm run ingest:pdf path/to/your-design-guide.pdf # O ingesta de contenido web npm run ingest:url https://example.com/design-system # O ingesta masiva desde archivo CSV npm run ingest:csv path/to/urls.csv

2. Actualizar carga de contenido en src/index.ts

   // Añadir nuevos archivos de contenido usando importaciones dinámicas const [handbookModule, buttonModule, newContentModule] = await Promise.all([ import('../content/entries/8zWJWrDK_bTOv3_KFo30V-pdf-designsystemshandbook-pdf.json'), import('../content/entries/sample-button-guidelines.json'), import('../content/entries/your-new-content.json') ]); const actualEntries = [ handbookModule.default as ContentEntry, buttonModule.default as ContentEntry, newContentModule.default as ContentEntry ]

3. Prueba local

   npm run dev # Prueba tu nuevo contenido en la interfaz de chat

Herramientas disponibles

El servidor MCP proporciona estas herramientas para los asistentes de IA:

• search_design_knowledge - Buscar contenido de sistemas de diseño
• search_chunks - Buscar información específica en fragmentos de contenido
• browse_by_category - Buscar contenido por categoría (componentes, tokens, etc.)
• get_all_tags - Obtener las etiquetas de contenido disponibles

Flujo de trabajo de pruebas locales

Prueba de nuevos contenidos

1. Añadir archivos de contenido a content/entries/
2. Actualizar src/index.ts para cargar el nuevo contenido
3. Reiniciar el servidor de desarrollo: npm run dev
4. Pruebe las consultas en la interfaz de chat en http://localhost:8787
5. Compruebe que las respuestas de la IA son precisas y completas

Prueba directa de las herramientas MCP

Pruebas locales:

# Probar la búsqueda MCP directamente curl -X POST http://localhost:8787/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc": "2.0", "id":1, "method": "tools/call", "params":{"name": "search_chunks", "arguments":{"query": "design tokens"}}' # Probar la integración AI curl -X POST http://localhost:8787/ai-chat \ -H "Content-Type: application/json" \ -d '{"message": "What are design tokens?"}'

Pruebas de producción:

# Test live MCP endpoint curl -X POST https://design-systems-mcp.southleft-llc.workers.dev/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc": "2.0", "id":1, "method": "tools/call", "params":{"name": "search_chunks", "arguments":{"query": "design tokens"}} # Probar la integración AI en vivo curl -X POST https://design-systems-mcp.southleft-llc.workers.dev/ai-chat \ -H "Content-Type: application/json" \ -d '{"message": "What are design tokens?"}'

Despliegue

Despliegue en Cloudflare Workers

1. Iniciar sesión en Cloudflare

   npx wrangler login

2. Establecer variables de entorno

   npx wrangler secret put OPENAI_API_KEY # Introduzca su clave de API de OpenAI cuando se le solicite # Opcional: Establecer modelo personalizado (por defecto: gpt-4o) npx wrangler secret put OPENAI_MODEL # Introduzca el nombre del modelo (por defecto: gpt-4o)

3. Despliegue

   npm run deploy

4. Acceda a su servidor desplegado

   • Su servidor estará disponible en: design-systems-mcp.<su-cuenta>.workers.dev
   • Interfaz de chat: https://design-systems-mcp.<su-cuenta>.workers.dev
   • Punto final MCP: https://design-systems-mcp.<su-cuenta>.workers.dev/mcp

Configuración de dominios personalizados

Para configurar un dominio personalizado como design-systems-mcp.southleft.com:

1. Despliega tu worker (consulta los pasos anteriores)
2. En el panel de control de Cloudflare
   • Ve a Trabajadores y páginas → Dominios personalizados
   • Añade tu dominio personalizado
   • Apúntalo a tu worker desplegado: design-systems-mcp
3. Configura las DNS en los ajustes de tu dominio
4. Pruebe los endpoints una vez propagados

Variables de entorno

Variables de entorno necesarias:

• OPENAI_API_KEY - Su clave de la API OpenAI
• OPENAI_MODEL - Modelo a utilizar (por defecto: "gpt-4o")
• AI_SYSTEM_PROMPT - Aviso de sistema personalizado (opcional)

Conectar con Clientes MCP

Claude Desktop / Cursor

Añadir a su archivo de configuración MCP(~/.cursor/mcp.json para Cursor, o claude_desktop_config.json para Claude):

Opción 1: Usar Servidor Remoto Público (Recomendado para la mayoría de los usuarios)

{ "mcpServidores": { "design-systems": { "url": "https://design-systems-mcp.southleft-llc.workers.dev/mcp" } }

Opción 2: Usar Servidor de Desarrollo Local (Para colaboradores/personalización)

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

Notas importantes:

• ✅ Tanto el servidor local como el remoto son totalmente funcionales
• 🌐 Servidor remoto: Siempre disponible, no requiere configuración
• 🔧 Servidor local: Requiere ejecutar primero npm run dev
• 📝 Después de actualizar la configuración, reinicia tu cliente MCP (Cursor/Claude)

Cloudflare AI Playground

1. Vaya a https://playground.ai.cloudflare.com/
2. Introduce la URL de tu servidor MCP: design-systems-mcp.southleft-llc.workers.dev/mcp
3. ¡Empieza a utilizar las herramientas de sistemas de diseño en el patio de recreo!

Aplicaciones externas

Cualquier aplicación que soporte MCP puede conectarse al servidor en vivo:

Punto final:https://design-systems-mcp.southleft-llc.workers.dev/mcp

Ejemplo de llamada a la API:

# Inicializar conexión curl -X POST https://design-systems-mcp.southleft-llc.workers.dev/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {"roots": {"listChanged": true}}, "clientInfo": {"name": "test", "version": "1.0.0"} } }' # Buscar conocimiento de sistemas de diseño curl -X POST https://design-systems-mcp.southleft-llc.workers.dev/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "search_design_knowledge", "arguments": {"query": "design tokens"} }'

Estructura del proyecto

design-systems-mcp/ ├── src/ │ ├── index.ts # Servidor principal con integración de IA │ ├── lib/ │ │ └── content-manager.ts # Gestión de contenidos y búsqueda │ └── herramientas/ # Definiciones de herramientas MCP ├── contenido/ │ ├── entradas/ # Contenido ingestado (JSON) ││─   └── raw/ # Archivos fuente en bruto ├── scripts/ │ └── ingestion/ # Scripts de ingestión de contenidos ├── types/ │ └── content.ts # Definiciones TypeScript ├── local-content-library/ # PDFs y archivos fuente ├── wrangler.jsonc # Cloudflare Workers config └── .dev.vars # Variables de entorno local

Gestión de contenidos

Tipos de contenido admitidos

• PDFs - Manuales de diseño del sistema, directrices
• Contenido web - Diseño de sitios de documentación del sistema
• CSV URLs - Ingesta masiva desde archivos CSV que contienen múltiples URLs
• JSON - Datos del sistema de diseño preprocesados

Ingesta masiva de CSV

Para la ingestión masiva de contenidos, puede utilizar archivos CSV que contengan varias URL:

1. Crear un archivo CSV

# Generar una plantilla CSV de ejemplo npm run ingest:csv --sample

2. Formato CSV

Su archivo CSV debe incluir estas columnas (se recomienda la fila de encabezado):

3. Ejemplo CSV

url,title,category,tags,description,confidence,system,author,version https://material.io/components/buttons,Material Design Buttons,components, "button,interaction,material",Material Design button guidelines,high,Material Design,Google,3.0 https://polaris.shopify.com/components/button,Shopify Polaris Button,components, "button,shopify,polaris",Shopify's button component,high,Polaris,Shopify, https://primer.style/components/button,GitHub Primer Button,components, "button,github,primer",GitHub's button guidelines,high,Primer,GitHub,

4. Ingesta de contenido

# Ingesta básica npm run ingest:csv my-urls.csv # Con opciones personalizadas npm run ingest:csv my-urls.csv --max-concurrent 5 --timeout 60000 # Dry run (validar sin buscar) npm run ingest:csv my-urls.csv --dry-run # Ver todas las opciones npm run ingest:csv --help

5. Opciones avanzadas

• --max-concurrent <n> - Procesar N URLs simultáneamente (por defecto: 3)
• --timeout <ms> - Tiempo de espera en milisegundos (por defecto: 30000)
• --retry-attempts <n> - Número de reintentos para URLs fallidas (por defecto: 2)
• --output-dir <dir> - Directorio de salida personalizado (por defecto: content/entries)
• --delimiter <char> - Delimitador CSV (por defecto: ',')
• --no-header - El archivo CSV no tiene encabezado

Procesamiento del contenido

El contenido se procesa automáticamente:

• Troceado para optimizar el rendimiento de la búsqueda
• Etiquetado y categorizado
• Indexado para la búsqueda semántica
• Puesta a disposición de la IA para respuestas inteligentes

Desarrollo

Scripts disponibles

• npm run dev - Iniciar servidor de desarrollo local
• npm run deploy - Desplegar en Cloudflare Workers
• npm run ingest:pdf <file> - Ingesta de contenido PDF
• npm run ingest:url <url> - Ingesta de contenido web
• npm run ingest:csv <file> - Ingesta masiva desde un archivo CSV que contiene URLs
• npm run check:duplicates - Comprueba si hay URL duplicadas en las entradas de contenido

Control de calidad del contenido

Comprobar si hay URL duplicadas

npm run check:duplicates

Este comando escanea todas las entradas de contenido e identifica cualquier URL duplicada para mantener la calidad del contenido. Ejecútelo

• Antes de desplegar nuevos contenidos
• Después de ingestar nuevos artículos
• Periódicamente para garantizar la integridad de los datos

El comprobador mostrará:

• Total de entradas escaneadas
• Número de URL únicas encontradas
• Cualquier duplicado con nombres de archivo y títulos
• Comandos de limpieza sugeridos

Añadir nuevas herramientas MCP

1. Defina las herramientas en src/index.ts:

   server.tool("tu_nombre_de_herramienta", schema, async (params) => { // Implementación de la herramienta })

2. Añadir a las definiciones de función OpenAI:

   const MCP_TOOLS = [ // ... herramientas existentes { type: "function", function: { nombre: "tu_nombre_de_la_herramienta", descripción: "Descripción de la herramienta", parámetros: { /* esquema JSON */ } } } ]

Solución de problemas

Problemas comunes

El contenido no se carga:

• Compruebe que existen archivos JSON en content/entries/
• Compruebe las rutas de importación dinámicas en src/index.ts
• Compruebe si hay errores de carga en los registros del servidor
• Asegúrese de que los archivos de contenido tienen un formato JSON válido

Problemas de puerto:

• Asegúrese de que wrangler.jsonc tiene el puerto de desarrollo correcto (8787)
• Matar los procesos existentes: pkill -f "wrangler dev"

Variables de entorno:

• Local: Utilice el archivo .dev.vars
• Producción: Establecer mediante npx wrangler secret put

Registros y depuración

# Ver logs del servidor npx wrangler tail # Logs de desarrollo local npm run dev # Comprobar la salida de la consola para ver el estado de carga del contenido

📄 Licencia y uso

Este proyecto es gratuito y de código abierto bajo la Licencia MIT. Usted es bienvenido a:

• ✅ Usarlo para proyectos personales y comerciales
• ✅ Modificarlo y distribuirlo
• ✅ Construir sobre él para tus propios proyectos
• ✅ Compartirlo con su equipo y su comunidad

Atribución del contenido

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

• 📚 Consulta CREDITS.md para ver la atribución completa
• 🔗 Siempre enlaza a las fuentes originales cuando compartas ideas
• 🙏 Apoya a los creadores originales visitando sus sitios web y plataformas

🔒 Seguridad y privacidad

• No se almacenan datos sensibles - Sólo conocimiento público del sistema de diseño
• Las variables de entorno son seguras - Las claves API utilizan secretos de Cloudflare
• Código abierto y auditable - Todo el código está a disposición del público
• Centrado en la privacidad - No se recopilan datos de usuarios más allá de la analítica básica de uso

Consulte SECURITY.md para obtener información detallada sobre seguridad y buenas prácticas.

🤝 Contribuir

Aceptamos contribuciones Tanto si quieres:

• 🐛 Informar de errores o problemas
• 💡 Sugerir nuevas funciones o mejoras
• 📚 Añadir más contenido al sistema de diseño
• 🔧 Mejorar el código base
• 📖 Mejorar la documentación

Por favor:

1. Revisa primero las incidencias existentes
2. Abre una nueva incidencia para comentar tu idea
3. Envía un pull request con tus cambios
4. Siga nuestras directrices de seguridad

Añadir contenido

Para aportar nuevos contenidos al sistema de diseño

1. Asegúrese de que tiene permiso para compartir el contenido
2. Siga el proceso de ingestión documentado anteriormente
3. Añada la atribución adecuada en CREDITS.md
4. Envía un pull request con el nuevo contenido

agradecimientos

Este proyecto existe gracias al generoso intercambio de conocimientos de la comunidad de sistemas de diseño. Un agradecimiento especial a:

• Brad Frost por la metodología fundacional Atomic Design
• El equipo deDesign System Guide por los completos recursos prácticos
• Figma por su excelente documentación oficial
• A todos los equipos de diseño que comparten abiertamente sus experiencias y metodologías
• A toda la comunidad de sistemas de diseño por fomentar el intercambio de conocimientos

Consulte CREDITS.md para ver la lista completa de colaboradores y fuentes.

📞 Soporte y comunidad

• 🐛 Problemas:Problemas en GitHub
• 📧 Seguridad: Reporta problemas de seguridad de forma privada a los mantenedores
• 🌐 S itio web:Demo en vivo

Información sobre la plantilla heredada de Cloudflare

Este proyecto se construyó a partir de la plantilla de servidor remoto MCP de Cloudflare. Para obtener información adicional sobre los trabajadores de Cloudflare:

Despliegue de la plantilla original

Plantilla de línea de comandos

npm create cloudflare@latest -- mi-servidor-mcp --template=cloudflare/ai/demos/remote-mcp-authless