منصوبے کے بارے میں

GA4 Dashboard & MCP 是一个自托管的实时 Google Analytics 4 仪表盘，可选配 Model Context Protocol (MCP) 服务器供 AI 助手使用。 ## 仪表盘功能 - **实时分析**：监控活跃用户、属性对比、流量来源配方及 API 配额。 - **3D 互动地球**：使用 Three.js 可视化全球网站活动，访问路径为 `/globe`。 - **流量激增检测**：自动识别突发流量并分类来源（引荐、直接或广告活动）。 - **访客洞察**：新/回访者画像卡、设备分布与热门地区。 - **隐私保护**：隐藏完整 URL 参数和查询字符串，防止仪表盘数据泄露。 - **智能缓存**：磁盘与内存双层缓存，后台自动更新属性元数据以节省 GA4 API 配额。 - **首次运行设置页**：无凭证时引导用户完成浏览器内配置流程。 ## MCP 服务器 独立 `mcp-server/` 包向 Claude Desktop、Antigravity 和 Cursor 等 MCP 兼容客户端暴露 GA4 管理与数据 API 工具。其独立于仪表盘，拥有专属依赖与凭证。 ## 前提条件 - Node.js v18.0.0+ - pnpm 包管理器 - 拥有服务账号权限的 Google Cloud Platform 账户，已启用 Google Analytics Data API 与 Admin API ## 设置概览 1. 克隆仓库并运行 `pnpm install`。 2. 创建 GCP 服务账号，启用所需 API 并生成 JSON 密钥文件。 3. 授予服务账号对 GA4 属性的查看者权限，将密钥文件置于项目根目录（或在 `.env` 中设置 `GA4_CREDENTIALS_PATH`）。 4. 使用 `pnpm dev`（开发）或 `pnpm start`（生产）启动应用。 5. 可选：复制 `.env.example` 配置 MCP 服务器，设置 `GOOGLE_APPLICATION_CREDENTIALS` 指向密钥文件，并添加服务器至 MCP 客户端配置。 ## 访问地址 - 主仪表盘：`http://localhost:3000` - 3D 地球：`http://localhost:3000/globe` - 分析视图：`http://localhost:3000/analytics` ## 测试与构建 运行 `pnpm test` 执行 Mocha 单元测试套件，`pnpm build` 进行 TypeScript 编译检查。 遵循 MIT 许可证。