Laravel Boost MCP Integration

Ce skill explique comment utiliser le MCP server officiel Laravel Boost déclaré dans plugins/atum-stack-backend/.mcp.json. Il complète les skills statiques laravel-patterns, laravel-security, laravel-tdd et laravel-verification en permettant à Claude Code d'introspecter une vraie application Laravel au lieu de générer du code à l'aveugle.

Prérequis : un projet Laravel 11+ avec laravel/boost installé via Composer.

Pourquoi Boost ?

Sans Boost, Claude Code génère du code Laravel à partir de patterns statiques (skills laravel-*). C'est utile mais limité : il ne sait pas quels modèles existent, quelles relations sont définies, quelles routes sont enregistrées, ni quel middleware est appliqué.

Avec Boost, Claude Code peut :

• Lister les routes (GET /api/users → UserController@index middleware auth:sanctum)
• Inspecter un modèle Eloquent (attributes fillable, casts, relations, scopes, accessors)
• Voir les jobs en queue + leurs handlers
• Voir les events et leurs listeners
• Lire la config publiée (sans .env si correctement gitignored)
• Inspecter les migrations appliquées
• Connaître la version PHP / Laravel / packages installés

Cela permet de générer du code qui s'intègre réellement au projet, pas du code générique qui sera à corriger.

Installation Boost dans le projet Laravel

composer require laravel/boost
php artisan boost:install  # Si command de scaffolding fournie

Vérifier que le command MCP est disponible :

php artisan list | grep boost
# Devrait afficher : boost:mcp

Tester :

php artisan boost:mcp
# Devrait démarrer un serveur stdio JSON-RPC

Configuration MCP côté Claude Code

Le plugin atum-stack-backend déclare déjà :

// plugins/atum-stack-backend/.mcp.json
{
  "mcpServers": {
    "laravel-boost": {
      "command": "php",
      "args": ["artisan", "boost:mcp"]
    }
  }
}

Important : ce command est lancé dans le CWD du shell de Claude Code. Donc Claude Code doit être lancé depuis la racine du projet Laravel (où se trouve le fichier artisan), sinon php artisan échouera.

Si tu travailles dans un monorepo avec le projet Laravel dans un sous-dossier, modifier le command :

{
  "mcpServers": {
    "laravel-boost": {
      "command": "php",
      "args": ["artisan", "boost:mcp"],
      "cwd": "./apps/api"
    }
  }
}

Modèle de sécurité

Boost expose :

• ✅ La structure de l'app (routes, models, jobs, events)
• ✅ Le code source (lecture)
• ✅ La config publiée (cf. config/)
• ❌ Les secrets .env (sauf si tu mets explicitement les variables dans config/*.php en dur — ce qui est une mauvaise pratique de toute façon)
• ❌ Les données utilisateur en DB (Boost n'expose pas la DB par défaut)

Recommandation : ne jamais lancer Boost en production. C'est un outil dev/staging. Pour un audit sur prod, utiliser un dump anonymisé en local.

Patterns d'invocation

1. Scaffolding qui respecte les modèles existants

Demande à Claude Code : "Crée un endpoint pour lister les commandes d'un user avec pagination et filtre par statut."

Sans Boost : Claude Code suppose un modèle Order avec des champs génériques.

Avec Boost : Claude Code interroge le serveur MCP pour :

1. Lister les modèles existants → trouve App\Models\Order
2. Inspecter Order → relations (user, items, payment), casts (status enum), scopes
3. Trouver le contrôleur existant OrderController ou en créer un nouveau cohérent
4. Regarder les routes existantes pour matcher la convention Route::resource ou Route::apiResource
5. Générer le code qui respecte exactement ces conventions

2. Debug d'une route mystérieuse

Demande : "Pourquoi /api/users/me retourne 401 ?"

Avec Boost : Claude Code peut :

1. Lister les routes correspondant à /api/users/me
2. Voir le middleware appliqué (auth:sanctum)
3. Inspecter la config Sanctum (stateful domains, guard)
4. Suggérer le fix sans deviner

3. Exploration de l'event system

Demande : "Quels listeners s'exécutent quand un user est créé ?"

Avec Boost : query l'EventServiceProvider → liste UserCreated event + ses listeners + leur queue.

4. Génération de Form Requests cohérentes

Demande : "Crée une Form Request pour valider la création d'un Product."

Avec Boost :

1. Inspecter le modèle Product → attributes, casts, relations
2. Inspecter la migration récente → contraintes DB (NOT NULL, max length, unique)
3. Générer une Form Request avec rules cohérentes avec le schéma DB

Workflow recommandé

1. Démarrer Claude Code dans la racine du projet Laravel (cd /path/to/laravel-app && claude)
2. Vérifier que le MCP est connecté : Claude Code doit lister laravel-boost dans les MCP servers actifs
3. Demander d'introspecter avant de générer : "Inspecte le modèle Order avant de créer le contrôleur"
4. Si Boost ne répond pas, vérifier :
   • php artisan boost:mcp fonctionne en standalone
   • Le projet est bien à la racine
   • Pas de conflit de version PHP

Combinaison avec les skills statiques Laravel

Skill	Rôle
laravel-patterns	Patterns canoniques Laravel (Eloquent, queues, events, broadcasting) — pour les nouveaux projets
laravel-security	Sécurité (mass assignment, auth, CSRF, rate limiting)
laravel-tdd	Pest / PHPUnit, factories, faking, HTTP tests
laravel-verification	Checklist QA pré-merge
laravel-boost-integration (ce skill)	Live introspection via MCP — pour les projets existants

Workflow type sur un projet existant :

1. laravel-boost-integration → comprendre l'état actuel via MCP
2. laravel-patterns → générer du code idiomatique cohérent
3. laravel-tdd → écrire les tests
4. laravel-security → audit sécurité
5. laravel-verification → checklist finale

Anti-patterns

1. Lancer Boost en prod — risque d'exposer du code, pas une attaque directe mais surface inutile
2. Faire confiance aveugle aux retours Boost — toujours valider en lisant le code source réel
3. Utiliser uniquement Boost sans skills statiques — manque de patterns canoniques pour les choix architecturaux
4. Oublier de relancer Claude Code après une migration — le MCP boost re-introspecte à chaque appel mais Claude Code peut cacher le résultat

Limites connues

• Boost ne montre PAS les données réelles (juste la structure)
• Boost ne montre PAS les variables .env non publiées dans config/
• Boost peut être lent sur de très gros projets (1000+ routes)
• Le MCP server tourne en stdio → un seul client Claude Code à la fois

Quand déléguer

• Patterns Laravel canoniques → skill laravel-patterns
• Sécurité Laravel → skill laravel-security
• Tests Laravel → skill laravel-tdd
• Verification finale → skill laravel-verification
• Choix entre Laravel et autre framework PHP → décision indépendante hors scope MCP
• Déploiement Laravel → skills deploy-* (atum-workflows)

Ressources

• https://laravel.com (Laravel core docs)
• https://github.com/laravel/boost (upstream Boost repo)
• https://modelcontextprotocol.io (spec MCP)
• License Laravel Boost : MIT (cf. THIRD-PARTY-LICENSES.md de ce plugin)