MCP DSFR

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/yourusername/mcp-playbook-dsfr.git
cd mcp-playbook-dsfr
./install.sh

Le script d'installation :

Vérifie la version Python
Crée l'environnement virtuel
Installe les dépendances de production (7 packages essentiels)
Teste le serveur
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/yourusername/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

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

Redémarrer Claude Desktop
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 |

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

Créer une branche : git checkout -b feature/nouvelle-fonctionnalite
Développer avec tests : pytest tests/ --watch
Vérifier le code : black . && ruff check . && mypy .
Commiter : git commit -m "feat: description"
Push : git push origin feature/nouvelle-fonctionnalite
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 :

Standards de code
Process de review
Guidelines de test
Documentation requise

Comment contribuer

Fork le projet
Créer votre branche (git checkout -b feature/AmazingFeature)
Commiter vos changements (git commit -m 'feat: Add AmazingFeature')
Push sur la branche (git push origin feature/AmazingFeature)
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

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