Об этом проекте

GA4 Dashboard & MCP — это самохостинговый реал-тайм дашборд Google Analytics 4 и опциональный сервер Model Context Protocol (MCP) для ИИ-ассистентов. ## Возможности дашборда - **Аналитика в реальном времени**: мониторинг активных пользователей, сравнение свойств, рецепты трафика и отслеживание квот API. - **Интерактивный 3D-глобус**: визуализация активности сайта по странам с использованием Three.js, доступен по адресу `/globe`. - **Обнаружение всплесков трафика**: автоматическое выявление резких скачков и классификация источников как реферальный, прямой или кампания. - **Инсайты о посетителях**: карточки персонажей для новых и повторяющихся посетителей, разбивка по устройствам и топ-география. - **Защита конфиденциальности**: маскировка полных URL-параметров и строк запросов для предотвращения утечки данных на дашбордах. - **Умное кэширование**: дисковые и оперативные кэш-слои с автоматическим фоновым обновлением метаданных свойств для сохранения квоты GA4 API. - **Настройка при первом запуске**: если учетные данные не найдены, пользователи перенаправляются на встроенный браузерный процесс настройки. ## MCP-сервер Отдельный пакет `mcp-server/` предоставляет инструменты GA4 Admin и Data API клиентам, совместимым с MCP, таким как Claude Desktop, Antigravity и Cursor. Работает независимо от дашборда и имеет собственные зависимости и учетные данные. ## Предварительные требования - Node.js v18.0.0+ - менеджер пакетов pnpm - аккаунт Google Cloud Platform с сервисной учетной записью, имеющей доступ к Google Analytics Data API и Admin API ## Обзор настройки 1. Клонируйте репозиторий и выполните `pnpm install`. 2. Создайте сервисную учетную запись Google Cloud, включите необходимые API и сгенерируйте JSON-ключ. 3. Предоставьте сервисной учетной записи доступ Viewer к свойству GA4 и поместите JSON-ключ в корень проекта (или установите `GA4_CREDENTIALS_PATH` в `.env`). 4. Запустите приложение с помощью `pnpm dev` (разработка) или `pnpm start` (продакшн). 5. Опционально: настройте MCP-сервер, скопировав `.env.example`, указав `GOOGLE_APPLICATION_CREDENTIALS` на файл ключа и добавив сервер в конфигурацию клиента MCP. ## URL-адреса - Основной дашборд: `http://localhost:3000` - 3D-глобус: `http://localhost:3000/globe` - Анализ: `http://localhost:3000/analytics` ## Тестирование и сборка Запустите `pnpm test` для набора модульных тестов Mocha и `pnpm build` для проверки компиляции TypeScript. Лицензировано под MIT License.