প্রকল্প সম্পর্কে

GA4 Dashboard & MCP 是一个自托管的实时 Google Analytics 4 仪表板，以及一个可选的 Model Context Protocol (MCP) 服务器，用于 AI 助手。 ## 仪表板功能 - **实时分析**：实时监控活跃用户、属性对比、流量来源配方及 API 配额追踪。 - **3D 互动地球仪**：使用 Three.js 可视化全球各国网站活动，访问路径为 `/globe`。 - **流量激增检测**：自动识别突发流量并分类来源（引荐、直接或广告活动）。 - **访客洞察**：提供新访客与回访者画像卡、设备分布及热门地理区域。 - **隐私保护**：屏蔽完整 URL 参数与查询字符串，防止仪表板数据泄露。 - **智能缓存**：磁盘与内存双层缓存，后台自动更新属性元数据以节省 GA4 API 配额。 - **首次运行设置页**：若无凭证，用户将被重定向至浏览器内设置流程。 ## MCP 服务器 独立的 `mcp-server/` 包向兼容 MCP 的客户端（如 Claude Desktop、Antigravity 和 Cursor）暴露 GA4 管理与数据 API 工具。它独立于仪表板运行，拥有自己的依赖项与凭证。 ## 前提条件 - 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 属性的查看者权限，并将 JSON 密钥置于项目根目录（或在 `.env` 中设置 `GA4_CREDENTIALS_PATH`）。 4. 使用 `pnpm dev`（开发模式）或 与数据 API 工具。它独立于仪表板运行，拥有自己的依赖项与凭证。 ## 前提条件 - 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 属性的查看者权限，并将 JSON 密钥置于项目根目录（或在 `.env` 中设置 `GA4_CREDENTIALS_PATH`）。 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 许可证。