À propos du projet

GA4 Dashboard & MCP est un tableau de bord Google Analytics 4 auto-hébergé en temps réel et un serveur optionnel Model Context Protocol (MCP) pour assistants IA. ## Fonctionnalités du tableau de bord - **Analytique en temps réel** : Suivi des utilisateurs actifs, comparaison de propriétés, recettes de trafic et suivi des quotas API. - **Globe interactif 3D** : Visualise l'activité site web mondiale via Three.js, accessible à l'adresse `/globe`. - **Détection pics de trafic** : Détecte automatiquement les pics et classe les sources (référent, direct ou campagne). - **Insights visiteurs** : Cartes personas pour nouveaux/retour visiteurs, répartition par appareil et géographie principale. - **Bouclier de confidentialité** : Masque les paramètres URL complets pour éviter les fuites de données. - **Cache intelligent** : Couches de cache disque/mémoire avec mise à jour automatique des métadonnées pour préserver le quota GA4 API. - **Page configuration première utilisation** : Redirige vers un flux de configuration dans le navigateur si aucune credential n'est trouvée. ## Serveur MCP Un package autonome `mcp-server/` expose les outils GA4 Admin et Data API aux clients MCP compatibles (Claude Desktop, Antigravity, Cursor). Fonctionne indépendamment du tableau de bord avec ses propres dépendances et credentials. ## Prérequis - Node.js v18.0.0+ - Gestionnaire de paquets pnpm - Compte Google Cloud Platform avec Service Account autorisé sur Google Analytics Data API et Admin API ## Procédure d'installation 1. Cloner le dépôt et exécuter `pnpm install`. 2. Créer un Service Account Google Cloud, activer les API requises et générer un fichier clé JSON. 3. Accorder au Service Account un accès Viewer sur la propriété GA4 et placer le fichier JSON à la racine du projet (ou définir `GA4_CREDENTIALS_PATH` dans `.env`). 4. Démarrer l'appli via `pnpm dev` (développement) ou `pnpm start` (production). 5. Optionnel : configurer le serveur MCP en copiant `.env.example`, pointant `GOOGLE_APPLICATION_CREDENTIALS` vers un fichier clé, et ajoutant le serveur dans la config de votre client MCP. ## URLs - Tableau de bord principal : `http://localhost:3000` - Globe 3D : `http://localhost:3000/globe` - Vue analytique : `http://localhost:3000/analytics` ## Tests & Compilation Exécuter `pnpm test` pour la suite de tests unitaires Mocha et `pnpm build` pour les vérifications de compilation TypeScript. Licence MIT.