这个项目能做什么

GA4 Dashboard & MCP 是一个自托管的实时 Google Analytics 4 仪表板，以及一个可选的用于 AI 助手的 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. 授予该服务账号对 GA4 资源的查看者 (Viewer) 权限，并将 JSON 密钥放置在项目根目录（或在 `.env` 中设置 `GA4_CREDENTIALS_PATH`）。 4. 使用 `pnpm dev`（开发环境）或 `pnpm start`（生产环境）启动应用。 5. 可选：通过复制 `.env.example` 配置 MCP 服务器，将 `GOOGLE_APPLICATION_CREDENTIALS` 指向密钥文件，并将服务器添加到您的 MCP 客户端配置中。 ## URL 地址 - 主仪表板：`http://localhost:3000` - 3D 地球：`http://localhost:3000/globe` - 分析视图：`http://localhost:3000/analytics` ## 测试与构建 运行 `pnpm test` 执行 Mocha 单元测试套件，运行 `pnpm build` 进行 TypeScript 编译检查。 基于 MIT 许可证授权。