Serveur MCP pour les systèmes de conception

Serveur MCP (Model Context Protocol) alimenté par l'IA qui fournit un accès intelligent à la connaissance des systèmes de conception. Ce serveur ingère la documentation des systèmes de conception (PDF, contenu web) et permet aux assistants IA de fournir des conseils d'experts sur les systèmes de conception, les composants, les jetons et les meilleures pratiques.

🌐 Démonstration en direct: https://design-systems-mcp.southleft.com/

Fonctionnalités

• 🤖 Interface de chat alimentée par l'IA - Requêtes en langage naturel avec intégration d'OpenAI
• 📚 Ingestion de contenu - Prise en charge de l'analyse des PDF et de l'extraction de contenu Web
• 🔍 Recherche intelligente - Recherche sémantique dans la documentation des systèmes de conception
• 🎨 F ormatage riche - Rendu Markdown avec mise en évidence de la syntaxe
• 🚀 Cloudflare Workers - Déploiement évolutif sans serveur
• 🧪 Test local - Environnement de développement local complet
• 🌐 Accès public - Serveur Live MCP disponible pour des intégrations externes

Serveur Live MCP

🚀 Points d'extrémité publics

Domaine des travailleurs: https://design-systems-mcp.southleft-llc.workers.dev

• Interface de chat AI: https://design-systems-mcp.southleft.com/
• Point final MCP: https://design-systems-mcp.southleft-llc.workers.dev/mcp
• Bilan de santé: https://design-systems-mcp.southleft-llc.workers.dev/health

✨ Essayez-le maintenant

Visitez la démo en direct et posez des questions telles que :

• "Que sont les jetons de conception et comment dois-je les utiliser ?"
• "Comment créer des boutons accessibles ?
• "Quelles sont les meilleures pratiques pour organiser un système de conception ?"
• "Comment les composants fonctionnent-ils dans les systèmes de conception ?

Démarrage rapide

Conditions préalables

• Node.js (v20.17.0+ ou v22.9.0+)
• Clé API OpenAI (pour le développement local)

Configuration du développement local

1. Cloner et installer

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

2. Configuration de l'environnement

   cp env.example .dev.vars # Editer .dev.vars et ajouter votre clé API OpenAI

3. Démarrer le serveur de développement

   npm run dev

   Le serveur sera disponible à l'adresse suivante : http://localhost:8787

4. Tester l'interface de chat de l'IA

   • Ouvrez http://localhost:8787 dans votre navigateur
   • Essayez des exemples de requêtes comme
     • "Qu'est-ce qu'un jeton de conception ?
     • "Où Alicia SEDLOCK est-elle mentionnée dans le manuel des systèmes de conception ?
     • "Que dit le manuel des systèmes de conception à propos de Wraith, Gemini et BackstopJS ?
     • "Comment mettre en œuvre un système de conception ?

Ajout de contenu

1. Ingérer le contenu (si ce n'est pas déjà fait)

   # Ajouter des PDF à local-content-library/ npm run ingest:pdf path/to/your-design-guide.pdf # Ou ingérer du contenu web npm run ingest:url https://example.com/design-system # Ou ingérer en masse à partir d'un fichier CSV npm run ingest:csv path/to/urls.csv

2. Mise à jour du chargement du contenu dans src/index.ts

   // Ajouter de nouveaux fichiers de contenu en utilisant des importations dynamiques 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. Test local

   npm run dev # Testez votre nouveau contenu dans l'interface de chat

Outils disponibles

Le serveur MCP fournit ces outils pour les assistants d'intelligence artificielle :

• search_design_knowledge - Recherche dans le contenu des systèmes de conception
• search_chunks - Recherche d'informations spécifiques dans des morceaux de contenu
• browse_by_category - Permet de parcourir le contenu par catégorie (composants, jetons, etc.)
• get_all_tags - Obtenir les balises de contenu disponibles

Flux de travail des tests locaux

Test d'un nouveau contenu

1. Ajouter les fichiers de contenu à content/entries/
2. Mettre à jour src/index.ts pour charger le nouveau contenu
3. Redémarrer le serveur de développement : npm run dev
4. Tester les requêtes dans l'interface de discussion à l'adresse http://localhost:8787
5. Vérifier que les réponses de l'IA sont exactes et complètes

Test direct des outils MCP

Test local :

# Tester la recherche MCP directement curl -X POST http://localhost:8787/mcp \N -H "Content-Type : application/json" \N -d '{"jsonrpc" : "2.0", "id":1, "method" : "tools/call", "params":{"name" : "search_chunks", "arguments":{"query" : "design tokens"}}}' # Test de l'intégration AI curl -X POST http://localhost:8787/ai-chat \N -H "Content-Type : application/json" \N -d '{"message" : "What are design tokens ?"}'

Test de production :

# Tester le point de terminaison MCP en direct curl -X POST https://design-systems-mcp.southleft-llc.workers.dev/mcp \N -H "Content-Type : application/json" \N -d '{"jsonrpc" : "2.0", "id":1, "method" : "tools/call", "params":{"name" : "search_chunks", "arguments":{"query" : "design tokens"}}}' # Test de l'intégration AI en direct curl -X POST https://design-systems-mcp.southleft-llc.workers.dev/ai-chat \N -H "Content-Type : application/json" \N -d '{"message" : "What are design tokens ?"}'

Déploiement

Déploiement vers les travailleurs de Cloudflare

1. Se connecter à Cloudflare

   connexion à npx wrangler

2. Définir les variables d'environnement

   npx wrangler secret put OPENAI_API_KEY # Entrez votre clé d'API OpenAI quand on vous le demande # Optionnel : Définir un modèle personnalisé (défaut actuel : gpt-4o) npx wrangler secret put OPENAI_MODEL # Saisir le nom du modèle (défaut : gpt-4o)

3. Déployer

   npm run deploy

4. Accéder à votre serveur déployé

   • Votre serveur sera disponible à l'adresse : design-systems-mcp.<votre-compte>.workers.dev
   • Interface de chat : https://design-systems-mcp.<votre-compte>.workers.dev
   • Point de terminaison MCP : https://design-systems-mcp.<votre-compte>.workers.dev/mcp

Configuration d'un domaine personnalisé

Pour configurer un domaine personnalisé comme design-systems-mcp.southleft.com:

1. Déployez votre travailleur (voir les étapes ci-dessus)
2. Dans le tableau de bord Cloudflare
   • Allez dans Workers & Pages → Custom Domains (Domaines personnalisés)
   • Ajoutez votre domaine personnalisé
   • Pointez-le vers votre serveur déployé : design-systems-mcp
3. Configurez le DNS dans vos paramètres de domaine
4. Testez les points d'extrémité une fois propagés

Variables d'environnement

Variables d'environnement requises :

• OPENAI_API_KEY - Votre clé d'API OpenAI
• OPENAI_MODEL - Modèle à utiliser (par défaut : "gpt-4o")
• AI_SYSTEM_PROMPT - Invite système personnalisée (facultatif)

Connexion aux clients MCP

Bureau de Claude / Curseur

Ajouter à votre fichier de configuration MCP(~/.cursor/mcp.json pour Cursor, ou claude_desktop_config.json pour Claude) :

Option 1 : Utiliser un serveur distant public (recommandé pour la plupart des utilisateurs)

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

Option 2 : Utiliser le serveur de développement local (pour les contributeurs/personnalisation)

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

Notes importantes :

• ✅ Les serveurs locaux et distants sont entièrement fonctionnels
• serveur distant : Toujours disponible, aucune configuration n'est requise
• 🔧 Serveur local : Nécessite l'exécution de npm run dev en premier lieu
• 📝 Après la mise à jour de la configuration, redémarrez votre client MCP (Cursor/Claude)

Terrain de jeu Cloudflare AI

1. Allez sur https://playground.ai.cloudflare.com/
2. Saisissez l'URL de votre serveur MCP : design-systems-mcp.southleft-llc.workers.dev/mcp
3. Commencez à utiliser les outils des systèmes de conception dans l'aire de jeu !

Applications externes

Toute application prenant en charge MCP peut se connecter au serveur live :

Point de terminaison: https://design-systems-mcp.southleft-llc.workers.dev/mcp

Exemple d'appel API :

# Initialiser la connexion curl -X POST https://design-systems-mcp.southleft-llc.workers.dev/mcp \N -H "Content-Type : application/json" \N -d '{ "jsonrpc" : "2.0", "id" : 1, "method" : "initialize", "params" : { "protocolVersion" : "2024-11-05", "capabilities" : {"roots" : {"listChanged" : true}}, "clientInfo" : {"name" : "test", "version" : "1.0.0"} }' # Search design systems knowledge curl -X POST https://design-systems-mcp.southleft-llc.workers.dev/mcp \N -H "Content-Type : application/json" \N -d '{ "jsonrpc" : "2.0", "id" : 2, "method" : "tools/call", "params" : { "name" : "search_design_knowledge", "arguments" : {"query" : "design tokens"} }' }'

Structure du projet

design-systems-mcp/ ├── src/ │ ├── index.ts # Serveur principal avec intégration AI │ ├── lib/ │ └─── content-manager.ts # Gestion de contenu et recherche │ └─── tools/ # Définitions des outils MCP ├── content/ │ ├── entries/ # Contenu ingéré (JSON) │   └── raw/ # Fichiers sources bruts ├─── scripts/ │ └── ingestion/ # Scripts d'ingestion de contenu ├─── types/ │ └── content.ts # Définitions TypeScript ├── local-content-library/ # PDF et fichiers sources ├── wrangler.jsonc # Cloudflare Workers config └── .dev.vars # Variables d'environnement local

Gestion du contenu

Types de contenu pris en charge

• PDF - Concevoir des manuels et des directives pour le système
• Contenu Web - Conception de sites de documentation du système
• CSV URLs - ingestion en masse à partir de fichiers CSV contenant plusieurs URLs
• JSON - Données prétraitées du système de conception

Ingestion en masse de fichiers CSV

Pour l'ingestion de contenu en masse, vous pouvez utiliser des fichiers CSV contenant plusieurs URL :

1. Créer un fichier CSV

# Générer un modèle CSV type npm run ingest:csv --sample

2. Format CSV

Votre fichier CSV doit inclure les colonnes suivantes (ligne d'en-tête recommandée) :

3. Exemple 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. Contenu de l'ingestion

# Ingestion de base npm run ingest:csv my-urls.csv # Avec des options personnalisées npm run ingest:csv my-urls.csv --max-concurrent 5 --timeout 60000 # Exécution à sec (validation sans récupération) npm run ingest:csv my-urls.csv --dry-run # Voir toutes les options npm run ingest:csv --help

5. Options avancées

• --max-concurrent <n> - Traite N URLs simultanément (par défaut : 3)
• --timeout <ms> - Délai d'attente de la requête en millisecondes (par défaut : 30000)
• --retry-attempts <n> - Nombre de tentatives de réessai pour les URL qui ont échoué (par défaut : 2)
• --output-dir <dir> - Répertoire de sortie personnalisé (par défaut : content/entries)
• --delimiter <char> - Délimiteur CSV (par défaut : ',')
• --no-header - Le fichier CSV n'a pas de ligne d'en-tête

Traitement du contenu

Le contenu est automatiquement

• Chunked pour des performances de recherche optimales
• Étiqueté et catégorisé
• Indexé pour la recherche sémantique
• Mis à la disposition de l'IA pour des réponses intelligentes

Développement

Scripts disponibles

• npm run dev - Démarrer le serveur de développement local
• npm run deploy - Déploiement sur Cloudflare Workers
• npm run ing est:pdf <file> - Ingérer du contenu PDF
• npm run ingest:url <url> - Ingérer du contenu web
• npm run ingest:csv <file> - Ingestion en bloc à partir d'un fichier CSV contenant des URLs
• npmrun check:duplicates - Vérifie la présence d'URL en double dans les entrées de contenu

Assurance qualité du contenu

Vérifier les URL en double :

npm run check:duplicates

Cette commande analyse toutes les entrées de contenu et identifie les URL en double afin de maintenir la qualité du contenu. Exécutez cette commande :

• Avant de déployer un nouveau contenu
• Après l'ingestion de nouveaux articles
• Périodiquement pour assurer l'intégrité des données

Le vérificateur affichera :

• Nombre total d'entrées analysées
• Nombre d'URL uniques trouvés
• Tous les doublons avec les noms de fichiers et les titres
• Suggestions de commandes de nettoyage

Ajout de nouveaux outils MCP

1. Définissez les outils dans src/index.ts:

   server.tool("nom_de_votre_outil", schema, async (params) => { // Implémentation de l'outil })

2. Ajouter aux définitions des fonctions OpenAI :

   const MCP_TOOLS = [ // ... outils existants { type : "function", function : { name : "your_tool_name", description : "Description de l'outil", parameters : { /* schéma JSON */ } } } ]

Résolution des problèmes

Problèmes courants

Le contenu ne se charge pas :

• Vérifiez que les fichiers JSON existent dans content/entries/
• Vérifier les chemins d'importation dynamique dans src/index.ts
• Vérifier les erreurs de chargement dans les journaux du serveur
• S'assurer que les fichiers de contenu sont au format JSON valide

Problèmes de port :

• S'assurer que wrangler.jsonc a le bon port dev (8787)
• Tuer les processus existants : pkill -f "wrangler dev"

Variables d'environnement :

• Local : Utiliser le fichier .dev.vars
• Production : Définies via npx wrangler secret put

Journaux et débogage

# Voir les logs du serveur npx wrangler tail # Logs de développement local npm run dev # Vérifier la sortie de la console pour l'état de chargement du contenu

licence et utilisation

Ce projet est libre et open source sous la licence MIT. Vous êtes invités à :

• ✅ l'utiliser pour des projets personnels et commerciaux
• ✅ le modifier et le distribuer
• ✅ le développer pour vos propres projets
• ✅ le partager avec votre équipe et votre communauté

Attribution du contenu

Ce projet compile les connaissances sur les systèmes de conception de nombreux créateurs brillants. Tous les contenus originaux restent la propriété intellectuelle de leurs auteurs respectifs.

• 📚 Voir CREDITS.md pour une attribution complète
• 🔗 Toujours faire un lien vers les sources originales lorsque vous partagez des idées
• 🙏 Soutenir les créateurs originaux en visitant leurs sites web et leurs plateformes

🔒 Sécurité et confidentialité

• Aucune donnée sensible n'est stockée - Seules les connaissances publiques du système de conception sontstockées
• Lesvariables d'environnement sont sécurisées - Les clés API utilisent les secrets Cloudflare
• Open source et auditable - Tout le code est accessible au public
• Axé sur la protection de la vie privée - Aucune collecte de données d'utilisateur au-delà de l'analyse de l'utilisation de base

Voir SECURITY.md pour des informations détaillées sur la sécurité et les meilleures pratiques.

🤝 Contribuer

Les contributions sont les bienvenues ! Que vous souhaitiez :

• 🐛 Signaler des bogues ou des problèmes
• 💡 Proposer de nouvelles fonctionnalités ou améliorations
• 📚 Ajouter du contenu au système de conception
• 🔧 Améliorer la base de code
• 📖 Améliorer la documentation

S'il vous plaît :

1. Vérifiez d'abord les problèmes existants
2. Ouvrez un nouveau problème pour discuter de votre idée
3. Soumettez une demande d'extraction avec vos changements
4. Suivez nos directives de sécurité

Ajouter du contenu

Pour ajouter du contenu au système de conception :

1. Assurez-vous que vous avez la permission de partager le contenu
2. Suivez le processus d'ingestion documenté ci-dessus
3. Ajoutez l'attribution appropriée dans CREDITS.md
4. Soumettre une demande d'extraction avec le nouveau contenu

🙏 Remerciements

Ce projet existe grâce au partage généreux des connaissances de la communauté des systèmes de conception. Remerciements particuliers à :

• Brad Frost pour la méthodologie fondamentale de conception atomique
• L'équipe duGuide des systèmes de conception pour ses ressources pratiques complètes
• Figma pour son excellente documentation officielle
• Toutes les équipes de conception qui partagent ouvertement leurs expériences et leurs méthodologies
• L'ensemble de la communauté des systèmes de conception pour avoir favorisé le partage des connaissances

Voir CREDITS.md pour la liste complète des contributeurs et des sources.

📞 Support et communauté

• 🐛 Problèmes :GitHub Issues
• 📧 Sécurité : Rapporter les problèmes de sécurité en privé aux mainteneurs
• 🌐 S ite web :Live Demo

Informations sur le modèle Cloudflare hérité

Ce projet a été construit à partir du modèle de serveur MCP distant de Cloudflare. Pour plus d'informations sur les travailleurs de Cloudflare :

Déploiement du modèle original

Modèle en ligne de commande

npm create cloudflare@latest -- my-mcp-server --template=cloudflare/ai/demos/remote-mcp-authless