DSFR

Version Python License Tests DSFR Tests CI Security MCP

Serveur Model Context Protocol intégrant le Design System de l'État français (DSFR) dans Claude Desktop. Génération, validation et audit de composants DSFR conformes RGAA 4.1.

Optimisé pour la production : 7 dépendances essentielles, performances >1.5M ops/sec, logging simplifié.

Table des matières

• Installation
• Démarrage rapide
• Fonctionnalités
• Documentation
• Architecture
• Tests
• Contribution
• Support
• Licence

Prérequis

• Python 3.9 ou supérieur
• Claude Desktop installé
• macOS, Linux ou Windows
• 100MB d'espace disque (7 dépendances production)

Installation

Installation automatique (recommandée)

git clone https://github.com/Alexmacapple/mcp-playbook-dsfr.git
cd mcp-playbook-dsfr
./install.sh

Le script d'installation :

1. Vérifie la version Python
2. Crée l'environnement virtuel
3. Installe les dépendances de production (7 packages essentiels)
4. Teste le serveur
5. Génère la configuration Claude Desktop

Exécution des tests

# Lancer tous les tests automatiquement
./run_tests.sh

Le script run_tests.sh active l'environnement virtuel et exécute les 13 tests de validation (incluant test_non_regression.py).

Installation manuelle

# Cloner le repository
git clone https://github.com/Alexmacapple/mcp-playbook-dsfr.git
cd mcp-playbook-dsfr

# Créer l'environnement virtuel
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Installer les dépendances de production
pip install -r requirements.txt

# OU pour le développement (inclut tests et outils)
pip install -r requirements-dev.txt

# Tester l'installation
python3 -c "from mcp_local.server import app; print('Installation réussie')"

Configuration Claude Desktop

1. Localiser le fichier de configuration :

   • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows : %APPDATA%\Claude\claude_desktop_config.json
   • Linux : ~/.config/Claude/claude_desktop_config.json

2. Ajouter la configuration MCP (remplacer /chemin/absolu/vers/ par votre chemin réel) :

{
  "mcpServers": {
    "mcp-playbook-dsfr": {
      "command": "/chemin/absolu/vers/venv/bin/python3",
      "args": ["/chemin/absolu/vers/mcp_local/server.py"],
      "env": {
        "PYTHONPATH": "/chemin/absolu/vers/mcp-playbook-dsfr",
        "ENV": "production",
        "LOG_LEVEL": "INFO",
        "DEFAULT_RGAA_LEVEL": "AA",
        "ENABLE_HTML_SANITIZATION": "true"
      }
    }
  }
}

3. Redémarrer Claude Desktop
4. Vérifier la présence de l'icône de connexion MCP

Démarrage rapide

Une fois installé, utilisez ces commandes dans Claude Desktop :

# Générer un composant
"Génère un bouton DSFR primaire"

# Valider du HTML
"Valide ce code : <button class='fr-btn'>Cliquer</button>"

# Audit d'accessibilité
"Fais un audit RGAA de mon formulaire"

# Lister les composants
"Liste tous les composants DSFR disponibles"

Fonctionnalités

Outils MCP disponibles

Outil	Description	Usage
generer_composant	Génère des composants DSFR	Création de boutons, formulaires, cartes, etc.
valider_html	Valide la conformité HTML/DSFR	Vérification structure et classes CSS
audit_accessibilite	Audit RGAA 4.1	Analyse A, AA, AAA avec recommandations
analyser_cognitif	Analyse cognitive Rumsfeld	Identification des inconnues du projet
lister_composants	Liste les 48 composants	Catalogue complet avec variantes
obtenir_tokens_design	Tokens de design DSFR	Couleurs, espacements, typographie
generer_tests	Génération de tests	Jest, Cypress, Playwright
obtenir_aide_assistant	Assistant contextuel	Aide et bonnes pratiques

Resources MCP (Nouveau)

Accès direct aux 137 gabarits HTML via le protocole MCP :

Resource	Description	Exemple d'usage
gabarit://{component}/{variant}	Récupère un gabarit HTML spécifique	gabarit://button/primary
list://gabarits	Liste tous les gabarits disponibles	Retourne 137 gabarits organisés
metadata://component/{component}	Métadonnées d'un composant	metadata://component/alert

Prompts MCP (Nouveau)

5 prompts prédéfinis pour les cas d'usage courants :

Prompt	Description	Cas d'usage
formulaire_accessible	Formulaire RGAA niveau AA	Création de formulaires accessibles
tableau_responsive	Tableau adaptatif et accessible	Tables de données responsives
page_complete	Page DSFR avec tous les éléments	Structure complète de page
composant_carte	Carte (card) avec image et contenu	Cartes de présentation
navigation_complexe	Navigation multi-niveaux	Menus et navigation avancée

Composants supportés

48 composants DSFR répartis en catégories :

• Navigation : header, footer, breadcrumb, navigation, sidemenu, pagination
• Formulaires : form, input, select, checkbox, radio, toggle, upload, password
• Actions : button, button-group, link, download, share
• Contenu : accordion, alert, badge, card, table, quote, callout, summary
• Feedback : modal, notice, tag, stepper, highlight
• Layout : grid, container, tile, tabs
• Autres : logo, consent, connect, translate, follow, tooltip, transcription

Documentation

Guides principaux

• Guide Utilisateur - Comment utiliser les outils MCP dans Claude
• CLAUDE.md - Guide technique pour Claude Code
• Guide de déploiement - Déploiement production
• Roadmap - Évolutions futures

Documentation technique

docs/
├── deployment/         # Guides de déploiement
├── tests/             # Documentation des tests
└── roadmap/           # Évolutions planifiées

Architecture

Structure du projet

mcp-playbook-dsfr/
├── mcp_local/         # Serveur MCP FastMCP
│   ├── server.py      # Point d'entrée principal
│   └── __init__.py    # Module Python
├── src/
│   ├── services/      # Services métier (SOLID)
│   ├── data/         # Registre des composants
│   ├── errors/       # Gestion des erreurs
│   └── utils/        # Utilitaires
├── gabarits/         # Templates HTML (48 composants)
├── tests/            # Suite de tests (100% de réussite)
├── docs/             # Documentation
│   ├── deployment/   # Guide de déploiement
│   └── roadmap/      # Feuille de route
├── tools/             # Outils de maintenance
│   └── check_dsfr_version.py  # Vérification des mises à jour DSFR
├── requirements.txt  # Dépendances production (7 packages)
├── requirements-dev.txt  # Dépendances développement
├── install.sh        # Script d'installation
└── run_tests.sh      # Script d'exécution des tests

Principes d'architecture

• SOLID : Chaque service a une responsabilité unique
• DRY : Pas de duplication de code
• KISS : Solutions simples et directes
• YAGNI : Uniquement les fonctionnalités nécessaires

Services principaux

• GeneratorService : Génération de composants via Factory Pattern
• ValidatorService : Validation HTML avec détection de balises croisées
• AuditService : Audit RGAA multi-niveaux
• CognitiveService : Analyse Known-Unknown de Rumsfeld
• DesignService : Gestion des tokens de design
• TestGeneratorService : Génération de tests automatiques
• AssistantService : Aide contextuelle intelligente

Tests

Suite de tests complète

100% des tests passent (13/13 tests fonctionnels)

Lancer les tests

# Script recommandé (active l'environnement virtuel automatiquement)
./run_tests.sh

# OU manuellement avec l'environnement virtuel
source venv/bin/activate
python3 tests/test-mcp-dsfr-all-components.py
# ... autres tests
deactivate

Résultats actuels

• 13 tests réussis sur 13 (100%)
• 48 composants DSFR testés
• Tous les services fonctionnels
• Génération automatique de tests (Cypress, Playwright, Jest)

Test de non-régression

# Test rapide après modifications
python3 tests/test_non_regression.py

Vérifie : imports, services, sécurité, performance (>1.5M ops/sec)

Validation manuelle

# Tester le serveur
python3 -c "
from mcp_local.server import app
from src.services import get_generator
html = get_generator().generate('button', label='Test')
print('OK' if 'fr-btn' in html else 'Erreur')
"

Développement

Configuration de l'environnement

# Environnement de développement
cp .env.example .env
# Éditer .env selon vos besoins

Variables d'environnement

Variable	Valeurs	Description
ENV	development, production	Environnement d'exécution
LOG_LEVEL	DEBUG, INFO, WARNING, ERROR	Niveau de logs
DEFAULT_RGAA_LEVEL	A, AA, AAA	Niveau RGAA par défaut
ENABLE_HTML_SANITIZATION	true, false	Sanitisation HTML

Workflow de développement

1. Créer une branche : git checkout -b feature/nouvelle-fonctionnalite
2. Développer avec tests : pytest tests/ --watch
3. Vérifier le code : black . && ruff check . && mypy .
4. Commiter : git commit -m "feat: description"
5. Push : git push origin feature/nouvelle-fonctionnalite
6. Créer une Pull Request

Conventions de commit

Format : <type>(<scope>): <description>

Types :

• feat : Nouvelle fonctionnalité
• fix : Correction de bug
• docs : Documentation
• style : Formatage
• refactor : Refactoring
• test : Ajout de tests
• chore : Maintenance

Déploiement

Docker

# Construction
docker-compose build

# Lancement
docker-compose up -d

# Logs
docker-compose logs -f

# Arrêt
docker-compose down

Production

Voir le guide de déploiement complet pour :

• Configuration systemd
• Reverse proxy nginx
• Monitoring Prometheus
• Backup et restauration

Contribution

Les contributions sont les bienvenues ! Voir CONTRIBUTING.md pour :

1. Standards de code
2. Process de review
3. Guidelines de test
4. Documentation requise

Comment contribuer

1. Fork le projet
2. Créer votre branche (git checkout -b feature/AmazingFeature)
3. Commiter vos changements (git commit -m 'feat: Add AmazingFeature')
4. Push sur la branche (git push origin feature/AmazingFeature)
5. Ouvrir une Pull Request

Support

Obtenir de l'aide

• Issues GitHub - Rapporter des bugs
• Discussions - Questions et idées
• Wiki - Documentation étendue

Dépannage courant

Problème	Solution
ModuleNotFoundError	Réinstaller : pip install -r requirements.txt
Icône MCP absente	Redémarrer Claude Desktop
Permission denied	chmod +x install.sh
Python non trouvé	Installer Python 3.9+

Auteurs

• Auteur principal - Alexandra Guiderdoni
• Co-auteur - Claude (Assistant IA d'Anthropic)

Voir la liste des contributeurs.

Licence

Ce projet est sous licence MIT - voir le fichier LICENSE pour plus de détails.

Remerciements

• Équipe DSFR pour le Design System
• Anthropic pour le Model Context Protocol
• Communauté open source française
• Contributeurs et testeurs

Ressources

• Documentation DSFR officielle
• Référentiel RGAA 4.1
• Claude Desktop
• Model Context Protocol

---

Développé pour l'accessibilité et la conformité DSFR des services publics numériques français.