Buggregator : serveur de debug PHP local

📚 Introduction

Quand on travaille sur une application PHP moderne, on finit toujours par accumuler une dizaine d’outils annexes pour déboguer : MailHog pour les emails, un Sentry local pour les exceptions, Ray pour les dumps, XHProf pour le profiling, un viewer de logs pour Monolog, un proxy HTTP pour inspecter les requêtes sortantes. Chacun est utile, mais l’addition fait beaucoup à installer, configurer et maintenir.

Buggregator propose une approche radicalement simple : un seul conteneur Docker, une seule interface web, et tous ces outils intégrés et corrélés. Tout reste en local, il n’y a rien à modifier dans le composer.json de l’application, et l’outil est gratuit et open source sous licence MIT.

🚀 Démarrage en 30 secondes

L’installation tient en une commande Docker :

docker run -p 127.0.0.1:8000:8000 ghcr.io/buggregator/server:latest

L’interface est disponible sur http://127.0.0.1:8000. À partir de là, on configure les variables d’environnement de son application pour pointer les flux de debug vers Buggregator. Quelques exemples côté Laravel ou Symfony :

# Sentry vers Buggregator
SENTRY_LARAVEL_DSN=http://sentry@127.0.0.1:8000/1
 
# Mailer SMTP vers Buggregator
MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
 
# Monolog HTTP handler vers Buggregator
LOG_CHANNEL=stack

Pas de SDK propriétaire, pas de wrapper à installer : Buggregator parle nativement les protocoles déjà supportés par votre application.

🧰 Tout dans une seule interface

Buggregator agrège une dizaine de fonctions, toutes accessibles depuis la même UI :

Exceptions captées via le SDK Sentry, avec stack trace complète et tagging.
Emails SMTP : remplacement direct de MailHog ou Mailtrap pour le local.
Dumps de variables : compatible VarDumper de Symfony et avec Ray (le client desktop).
Profiling XHProf : flame graphs lisibles directement dans l’UI.
Logs Monolog : agrégation des flux de log applicatif.
HTTP Dumps : inspection des requêtes sortantes via le mode proxy.
SMS et autres événements pour les outils internes ou les services tiers.

L’avantage de tout corréler dans la même interface est concret : quand une requête échoue, on retrouve sur la même timeline l’exception Sentry, le dump de variables émis pendant le traitement, le log Monolog, et les éventuels emails envoyés. Plus besoin de jongler entre cinq onglets.

🧱 Architecture et intégration

L’outil est livré comme un binaire Docker indépendant. Il ne touche pas à votre application :

Compatible avec Laravel, Symfony, Spiral, WordPress, Drupal, Yii3, et globalement toute application PHP.
Compatible avec les runtimes modernes : Laravel Octane, FrankenPHP, Swoole, RoadRunner.
Aucune modification du composer.json : on peut l’activer ou le couper sans toucher au code applicatif.
Package Composer optionnel buggregator/trap qui fournit des helpers ergonomiques (trap(), tr(), td()) si l’on veut dumper depuis le code, mais ce n’est pas obligatoire.
Plugin PhpStorm disponible pour ouvrir directement le fichier/ligne d’un dump ou d’une stack trace dans l’IDE.

🎯 Quand utiliser Buggregator

Mon arbitrage actuel :

Développement local : installation automatique sur tous mes projets PHP. Le gain est immédiat dès le premier debug.
Staging interne ou ateliers d’équipe : un Buggregator partagé permet à plusieurs développeurs d’observer ensemble les flux d’une application.
Tests E2E en CI : on peut le démarrer comme service GitHub Actions et vérifier après coup les emails et exceptions capturés pendant les tests.
Production : ce n’est pas son rôle. En production, on garde une vraie stack d’observabilité (SigNoz avec OpenTelemetry est mon défaut).

🔒 Côté confidentialité

C’est un argument particulièrement appréciable pour les projets sensibles (santé, finance, secteur public) :

Toutes les données restent sur la machine locale ou le serveur self-hosted.
Aucun compte SaaS à créer.
Aucun trafic sortant vers un tiers.

Pour les développeurs habitués à voir leurs payloads applicatifs partir chez un éditeur cloud, c’est un soulagement non négligeable.

🤖 Serveur MCP intégré : déboguer avec un agent IA

C’est la fonctionnalité que je n’avais pas vue venir, et probablement la plus différenciante de Buggregator côté 2026 : un serveur MCP intégré qui permet aux assistants IA (Claude Code, Cursor, etc.) d’interroger directement les événements de debug, sans quitter l’éditeur.

Activation

mcp:
  enabled: true

Ou via variable d’environnement :

MCP_ENABLED=true

Deux modes de transport, selon votre setup :

# Socket Unix (recommandé en local)
mcp:
  enabled: true
  transport: socket
  socket_path: /tmp/buggregator-mcp.sock

# HTTP / SSE (Docker, accès distant)
mcp:
  enabled: true
  transport: http
  addr: ':8001'
  auth_token: my-secret-token

Outils MCP exposés

Le serveur expose une dizaine d’outils, organisés par catégorie :

Événements : events_list (liste filtrable par type/projet, jusqu’à 100), event_get (récupère un événement complet via UUID), event_delete.
Sentry : sentry_event retourne les détails structurés d’une exception (stack trace, contexte, environnement).
VarDumper : vardump_get rend les dumps de variables en texte brut, lisible directement par un agent.
Profiler : profiler_summary (CPU, mémoire, fonctions lentes), profiler_top (top par métrique), profiler_call_graph (graphe d’appels filtrable).

Configuration Claude Code

Dans le .mcp.json du projet, pour un socket local :

{
	"mcpServers": {
		"buggregator": {
			"command": "./buggregator",
			"args": ["mcp"]
		}
	}
}

Pour une instance Buggregator déjà lancée en Docker, on bascule en HTTP :

{
	"mcpServers": {
		"buggregator": {
			"type": "url",
			"url": "http://localhost:8001/mcp"
		}
	}
}

Côté docker-compose.yml, l’exposition de l’endpoint MCP tient en quelques lignes :

services:
  buggregator:
    image: ghcr.io/buggregator/server:latest
    ports:
      - 127.0.0.1:8000:8000
      - 127.0.0.1:8001:8001
    environment:
      MCP_ENABLED: 'true'
      MCP_TRANSPORT: http
      MCP_ADDR: ':8001'

Ce que ça change concrètement

Sur une session de debug, on peut désormais demander à l’agent :

“Affiche les 5 dernières exceptions Sentry du projet, et regroupe-les par cause.”
“Quelle est la stack trace de l’événement abc-123 ?”
“Analyse les données de profiling et identifie les fonctions les plus coûteuses.”
“Compare les dumps de la requête A avec ceux de la requête B.”

L’agent ne se contente plus de proposer du code à l’aveugle : il lit les vrais événements générés par votre application, et propose des correctifs basés sur des faits. Couplé à Laravel Boost qui expose l’application elle-même, le résultat est saisissant : l’agent peut lire le code, exécuter Tinker, déclencher des requêtes, et inspecter ce qui s’est passé dans Buggregator, le tout dans la même conversation.

⚠️ Sécurité du MCP

En socket Unix local, l’accès est restreint à l’utilisateur de la machine. Bon réflexe pour le dev.
En HTTP, toujours définir un auth_token. Et garder le port mappé sur 127.0.0.1 sauf besoin explicite.
Le MCP donne accès aux événements bruts : ne pas l’activer en production sans contrôle d’accès strict.

⚠️ Quelques précautions

Ne pas exposer l’instance publiquement. Le mapping par défaut sur 127.0.0.1 est le bon réflexe : tout ce qui est exposé sur Internet doit être derrière une authentification.
Mémoire : la rétention peut grimper rapidement sur une session intensive. Penser à purger régulièrement ou à monter un volume dédié.
Compléter, pas remplacer : pour la production et la rétention longue durée, Buggregator n’est pas conçu pour ça. C’est un outil de développement.

🎉 Conclusion

Buggregator coche les bonnes cases : installation triviale (un docker run), couverture fonctionnelle large, compatibilité avec les SDK déjà utilisés, et un vrai respect de la confidentialité. C’est le genre d’outil qu’on regrette de ne pas avoir installé plus tôt, parce qu’il remplace toute une étagère d’outils annexes par une seule interface cohérente.

Si vous travaillez sur PHP et que vous avez encore plusieurs conteneurs séparés pour MailHog, un mock Sentry, un serveur de dumps, c’est le bon moment pour faire le grand ménage.

🐞 Buggregator : le serveur de débogage tout-en-un pour PHP