इस प्रोजेक्ट के बारे में

GA4 Dashboard & MCP एक सेल्फ-होस्टेड रियल-टाइम Google Analytics 4 डैशबोर्ड और AI सहायकों के लिए एक वैकल्पिक Model Context Protocol (MCP) सर्वर है। ## डैशबोर्ड की विशेषताएं - **रियल-टाइम एनालिटिक्स**: लाइव एक्टिव यूजर मॉनिटरिंग, प्रॉपर्टी तुलना, ट्रैफिक रेसिपी और API कोटा ट्रैकिंग। - **3D इंटरैक्टिव ग्लोब**: Three.js का उपयोग करके दुनिया भर के देशों में लाइव वेबसाइट गतिविधि को विज़ुअलाइज़ करता है, जो `/globe` पर उपलब्ध है। - **ट्रैफिक स्पाइक डिटेक्शन**: अचानक आने वाली वृद्धि का स्वचालित रूप से पता लगाता है और स्रोतों को रेफरल, डायरेक्ट या कैंपेन के रूप में वर्गीकृत करता है। - **विज़िटर इनसाइट्स**: नए बनाम लौटने वाले विज़िटर्स के लिए पर्सोना कार्ड, डिवाइस ब्रेकडाउन और टॉप ज्योग्राफी। - **प्राइवेसी शील्ड**: डैशबोर्ड पर डेटा लीक को रोकने के लिए फुल URL पैरामीटर्स और क्वेरी स्ट्रिंग्स को रेडैक्ट करता है। - **स्मार्ट कैशिंग**: GA4 API कोटा को सुरक्षित रखने के लिए स्वचालित बैकग्राउंड प्रॉपर्टी मेटाडेटा अपडेट के साथ डिस्क और इन-मेमोरी कैशिंग लेयर्स। - **फर्स्ट-रन सेटअप पेज**: यदि कोई क्रेडेंशियल्स नहीं मिलते हैं, तो उपयोगकर्ताओं को इन-ब्राउज़र सेटअप फ्लो पर रीडायरेक्ट किया जाता है। ## MCP सर्वर एक स्टैंडअलोन `mcp-server/` पैकेज Claude Desktop, Antigravity और Cursor जैसे MCP-संगत क्लाइंट्स को GA4 Admin और Data API टूल्स उपलब्ध कराता है। यह डैशबोर्ड से स्वतंत्र रूप से संचालित होता है और इसकी अपनी डिपेंडेंसी और क्रेडेंशियल्स होते हैं। ## पूर्व-आवश्यकताएं (Prerequisites) - Node.js v18.0.0+ - pnpm पैकेज मैनेजर - Google Cloud Platform अकाउंट, जिसमें सर्विस अकाउंट को Google Analytics Data API और Admin API का एक्सेस दिया गया हो ## सेटअप अवलोकन 1. रिपॉजिटरी को क्लोन करें और `pnpm install` चलाएं। 2. एक Google Cloud सर्विस अकाउंट बनाएं, आवश्यक APIs सक्षम करें और एक JSON की (key) फाइल जेनरेट करें। 3. सर्विस अकाउंट को GA4 प्रॉपर्टी का Viewer एक्सेस दें और JSON की को प्रोजेक्ट रूट में रखें (या `.env` में `GA4_CREDENTIALS_PATH` सेट करें)। 4. ऐप को `pnpm dev` (डेवलपमेंट) या `pnpm start` (प्रोडक्शन) के साथ शुरू करें। 5. वैकल्पिक: `.env.example` को कॉपी करके, `GOOGLE_APPLICATION_CREDENTIALS` को की फाइल की ओर पॉइंट करके और अपने MCP क्लाइंट कॉन्फ़िगरेशन में सर्वर को जोड़कर MCP सर्वर को कॉन्फ़िगर करें। ## URLs - मुख्य डैशबोर्ड: `http://localhost:3000` - 3D ग्लोब: `http://localhost:3000/globe` - एनालिटिक्स व्यू: `http://localhost:3000/analytics` ## टेस्टिंग और बिल्डिंग Mocha यूनिट टेस्ट सूट के लिए `pnpm test` और TypeScript कंपाइलेशन चेक के लिए `pnpm build` चलाएं। MIT लाइसेंस के तहत लाइसेंस प्राप्त।