Skip to main content
Glama
Sign In
agc-analytics-mcp

agc-analytics-mcp

by D-sp-wq
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

agc-analytics-mcp

华为 AppGallery Connect 数据分析 MCP 服务器

报表趋势解析 · Crash/AppFreeze 指标 · 评论与评分聚合 · 日报周报生成

License: MIT deps: 0 node MCP

简体中文 | English

把华为 AppGallery Connect（AGC）的运营数据接进任何支持 MCP 的 AI 客户端——Claude Code、Cursor、VS Code、Codex CLI、Gemini CLI、Trae、DevEco Studio CodeGenie、Cherry Studio 等。装上之后，你可以直接问：

“我的鸿蒙应用最近 30 天新增用户趋势怎么样？有没有异常日？” “上周崩溃数比前一周涨了多少？集中在哪个版本？” “把最近一周的差评关键词聚一下类。” “出一份昨天的日报。”

服务器会自己去 AGC 拉数据、解析 CSV、做趋势与环比计算，再把结论交给模型。

本项目只读：不发布、不上传、不回复评论、不改任何 AGC 配置。

为什么用它

能力

说明

报表趋势解析

16 种 AGC 运营报表（HarmonyOS 与 Android 双平台），自动下载 CSV、解析（含 GBK）、按日聚合，给出周环比、7 日均线方向、z-score 异常日、峰值谷值与迷你趋势线

Crash 指标分析

APM 崩溃率 / 应用冻屏指标查询与汇总：总量、周环比、最严重日期、受影响版本 Top 5

评论与评分聚合

星级直方图、平均分、差评关键词聚类（中文二元组 + 英文分词，零依赖）、版本热点

日报 / 周报生成

一条调用产出 Markdown 报告，分节独立降级（某个数据源失败不会毁掉整份报告），可落盘为 .md

零依赖 · 零构建

npx 直接从 GitHub 运行，无 npm install、无编译步骤、无安装脚本

只读白名单

13 个工具全部只读；通用透传工具只放行只读路径前缀，写操作在设计上就不可达

凭据不出本机

凭据只从环境变量/文件读入内存，永不落盘、永不进日志；带鉴权请求只允许发往华为四个 AGC 站点域名

Related MCP server: Huawei Training Camp MCP

快速开始

0. 最省事：双击一个文件，把 API 粘进去

git clone https://github.com/D-sp-wq/agc-analytics-mcp.git

然后双击仓库根目录的 粘贴API.cmd，会弹出一个窗口：

┌─ 粘贴 AGC API 凭据 ─────────────────────────────────┐
│ 把你在控制台复制的内容整段粘到下面，然后点「保存并检查」。  │
│ 不需要自己创建 .json 文件。                            │
│ ┌───────────────────────────────────────────────┐ │
│ │ （在这里 Ctrl+V 粘贴）                          │ │
│ └───────────────────────────────────────────────┘ │
│ [保存并检查] [真实验证（只读）] [复制结果] [关闭]      │
└───────────────────────────────────────────────────┘

  • 粘什么都能认：控制台的 JSON、client_id: … / client_secret: … 两行、中文标签（客户端ID/密钥）、两行裸值、Service Account 的 *private.json 全文

  • 保存到 %USERPROFILE%\.agc\（仅你可读），保存后立刻清空粘贴框，窗口里不会留下密钥

  • 自动跑一次不联网的本地检查，再给你一个可选的真实只读验证按钮

  • 最后给出可直接粘贴进 AI 客户端的配置（路径已填好）

没有图形界面（Linux 服务器 / 远程终端）时，同样的能力在命令行： node scripts/setup.mjs（交互向导）或 node scripts/save-credential.mjs --from-text 粘贴内容.txt

0.5 命令行向导（等价的另一条路）

cd agc-analytics-mcp
node scripts/setup.mjs

向导会：检查 Node 版本 → 问你有哪种凭据（API 客户端 / Service Account 文件）→ 用不回显的方式录入并保存到 ~/.agc（权限仅你可读）→ 本地校验 → 问你要不要做一次真实只读验证 → 最后打印一段可直接粘贴进 AI 客户端的配置（路径已按你的机器填好），并额外给出"不用文件、直接把两个值写进配置"的替代写法。

随时可非交互使用：

node scripts/setup.mjs --client-id <id> --client-secret <secret>
node scripts/setup.mjs --sa "C:\Users\你\Downloads\xxx-private.json"
node scripts/setup.mjs --print-config-only    # 只看配置，不写任何文件

1. 拿到 AGC 凭据

找不到「API 密钥」入口？ 大概率是打开成了 HarmonyOS 开发者中心（hdc-console）—— Connect API 凭据只在 AppGallery Connect（service/josp/agc/index.html）里。对照表与逐条排查见 docs/WHERE-IS-API-KEY.md。

没有凭据、或不确定该建哪一种？照着 docs/GETTING-CREDENTIALS.md 做一遍即可（含控制台路径、两个 JSON 文件长什么样、权限与常见错误对照表）。

打开 AppGallery Connect →「用户与访问 → API 密钥 → Connect API」，创建凭据。两种凭据可以同时配置：

凭据

创建方式

环境变量

适用

API 客户端

「API 密钥」页签 → 创建 API 客户端（项目选 N/A），然后 node scripts/save-credential.mjs 录入（密钥不回显）

AGC_CLIENT_FILE（含 client_id/client_secret 的 JSON 路径）或 AGC_CLIENT_ID + AGC_CLIENT_SECRET

全部工具，评论/评分接口必须用它

Service Account

「Service Account」页签 → 创建，类型选开发者级，会下载 *private.json

AGC_SERVICE_ACCOUNT_FILE（该 JSON 的路径）

除评论/评分外的全部工具

站点用 AGC_SITE 选择：cn（默认）/ de / sg / ru。

其它可选环境变量：

变量

默认

说明

AGC_TIMEOUT_MS

30000

单次请求超时（毫秒）

AGC_BASE_URL

按站点推导

自定义 API 入口，用于企业网关或本地 mock 联调。必须 https；只有回环地址（127.0.0.1 / localhost）允许 http，配置不当会回退到官方站点并在 agc_auth_status 中提示

凭据文件请放在仓库之外，不要提交进 Git。.gitignore 已忽略 .env* 与 *.local.json。

2. 安装方式（三选一）

方式

命令

适用

A. 克隆即用（最稳，推荐）

git clone https://github.com/D-sp-wq/agc-analytics-mcp.git 然后用 node <路径>/index.js 启动

任何环境。零依赖、零安装，只需要 Node ≥ 20

B. npx 直连 GitHub

npx --allow-git=all -y github:D-sp-wq/agc-analytics-mcp

允许 npm 拉取 git 依赖的环境（见下方提示）

C. npm 包

由你自行 npm publish 后 npx -y agc-analytics-mcp

想给团队内分发时

⚠️ npm 12 起默认禁用 git 依赖：直接 npx -y github:... 会报 EALLOWGIT: Fetching packages of type "git" have been disabled。 两种解法：加 --allow-git=all（如上），或者改用方式 A —— 克隆后用 node 启动，完全不经过 npm。 npm 11 及更早版本没有该限制。

3. 配置客户端（同一套「命令 + 环境变量」）

方式 A（克隆）的配置 —— command 指向克隆下来的 index.js：

{
  "mcpServers": {
    "agc": {
      "command": "node",
      "args": ["C:/tools/agc-analytics-mcp/index.js"],
      "env": {
        "AGC_CLIENT_FILE": "/absolute/path/to/api-client.json",
        "AGC_SERVICE_ACCOUNT_FILE": "/absolute/path/to/service-account.json",
        "AGC_SITE": "cn"
      }
    }
  }
}

方式 B（npx）的配置 —— 把 command/args 换成：

      "command": "npx",
      "args": ["--allow-git=all", "-y", "github:D-sp-wq/agc-analytics-mcp"],

各客户端的配置文件位置：

客户端

位置

Claude Code

claude mcp add agc -s user -- node /绝对路径/agc-analytics-mcp/index.js（加 -e AGC_CLIENT_FILE=...）

Claude Desktop

Windows %APPDATA%\Claude\claude_desktop_config.json；macOS ~/Library/Application Support/Claude/claude_desktop_config.json

Cursor

全局 ~/.cursor/mcp.json 或项目内 .cursor/mcp.json

VS Code (Copilot Agent)

.vscode/mcp.json，键名为 servers，需加 "type": "stdio"

Codex CLI

~/.codex/config.toml 的 [mcp_servers.agc]

Gemini CLI

~/.gemini/settings.json

Trae / DevEco Studio / Cherry Studio

各自的 MCP 设置面板粘贴上面的 JSON

Windows 提示：少数客户端无法直接启动 npx，把 "command" 改成 "cmd"，"args" 改为 ["/c","npx", ...]；路径用正斜杠 C:/tools/... 最省事。

4. 从源码跑测试

git clone https://github.com/D-sp-wq/agc-analytics-mcp.git
cd agc-analytics-mcp
npm test   # 55 项测试，无需网络与凭据
node index.js                     # 直接以 stdio 方式启动

工具一览

全部 13 个工具均为只读（readOnlyHint: true）。

工具

作用

agc_auth_status

检查凭据与站点配置（不联网），返回已加载的凭据类型与修复建议

agc_list_apps

列出项目与项目下的应用（appId / 包名 / 设备类型）

agc_get_app_id

包名 → appId（逗号分隔，最多 50 个）

agc_report_export

导出 16 种报表之一，下载并解析为结构化行（默认返回前 500 行，可 outPath 落盘全量 CSV）

agc_report_trend

对指定指标做趋势分析：周环比、7 日均线方向、异常日、峰值谷值、28 天趋势线；metric:"" 得到所有数值列的总览

agc_crash_metric

Crash / AppFreeze 指标原始查询，归一化为 {day, version, count, users, rate}

agc_crash_summary

Crash 汇总：总量、周环比、最严重日期、受影响版本 Top 5（beta：该接口为社区实测，字段以官方文档为准）

agc_ratings_summary

评分查询（时间跨度 ≤ 6 个月，需 API 客户端凭据）

agc_reviews_list

评论列表，支持评分/版本/答复状态/关键词/排序过滤与分页

agc_review_insights

评论洞察：星级直方图、平均分、关键词聚类（带例句）、版本热点

agc_daily_report

单日 Markdown 日报（默认昨天）：下载安装、Crash、评分快照

agc_weekly_report

周报 + 上周自动对比，可落盘

agc_request

只读白名单透传，覆盖没有专用工具的只读接口

可用报表（report 参数）

HarmonyOS 5+

Android / HarmonyOS 4-

harmony-download 下载安装

download 下载安装

harmony-install-failed 安装失败

install-failed 安装失败

harmony-user-analysis 用户分析

new-and-retention 新增与留存

harmony-atomic-distribute 元服务分发

iap 应用内付费

harmony-voc 应用源声

paid-download / paid-download-detail 付费下载及明细

game-reservation 预约、activity-award 发奖、coupon 优惠券

atomic-distribute / atomic-user / atomic-widget 元服务（旧版）

报表时间跨度上限 180 天；评论接口上限 6 个月——两个限制都会在调用前本地校验并给出可执行的修正建议。

使用示例

# 先确认凭据
agc_auth_status

# 找到 appId
agc_list_apps

# 最近 30 天新增用户趋势 + 异常日
agc_report_trend { appId, report: "harmony-user-analysis", metric: "" }

# 下载安装量周环比
agc_report_trend { appId, report: "harmony-download", metric: "下载量" }

# 上周崩溃总量与版本分布
agc_crash_summary { appId, startDate: "2026-06-01", endDate: "2026-06-07" }

# 差评关键词
agc_review_insights { appId, platform: "harmonyos", onlyNegative: true, pages: 3 }

# 一份周报
agc_weekly_report { appId, endDate: "2026-06-07", outPath: "D:/reports/agc-week.md" }

agc_report_export 的 outPath 默认不覆盖已存在文件，需要覆盖时显式传 overwrite: true。

真实输出长什么样

仓库里带了一份可复现的样例输出（node scripts/generate-examples.mjs 用本地 mock 上游重新生成，不需要凭据）：

文件

内容

docs/examples/report-trend.json

30 天报表：各指标周环比、趋势方向、峰值/谷值、异常日（发布日激增 z=46.55）

docs/examples/daily-report.md

日报：7 日下载趋势 + 崩馈日均/最差日/版本分布 + 评分与差评关键词

docs/examples/weekly-report.md

周报：下载量 ↑+6.4%、崩溃数 ↑+134.6%（自动对比上一周）

docs/examples/review-insights.json

评论洞察：星级直方图、平均分、「闪退」等关键词簇带例句

日报片段（节选自 docs/examples/daily-report.md）：

## Download & install trend (harmony-download, 7 days to 20260530)

- 下载量: 2332 over the last 7 days (daily average 333.1)
- range 2026-05-24 → 2026-05-30 (7 day(s)); latest 310
- direction down (-3.8%/day); peak 360 on 2026-05-25, trough 264 on 2026-05-29
- trend: ███▇▆▁▄

## Crash metrics (crash, 7 days to 20260530)

- crash events: 448 over 7 day(s) (64.0/day)
- worst day: 2026-05-27 with 146
- top versions: 2.3.0 (406), 2.2.1 (42)

安全与隐私

完整威胁模型见 SECURITY.md。核心保证：

  1. 出网白名单：所有带鉴权的请求只能发往 connect-api.cloud.huawei.com / -dre / -dra / -drru 四个主机且必须 HTTPS；其它主机在连接前即被拒绝。报表下载地址会剥离鉴权头并限制大小。

  2. 凭据只进内存：从环境变量或凭据文件读取，不写盘、不缓存到文件、不进入任何日志或错误消息（统一脱敏 client_secret / access_token / Bearer / private_key）。

  3. 只读设计：没有发布、上传、删除、回复评论的能力；agc_request 只放行只读路径前缀，且评论与 app-info 路径强制 GET。

  4. 零依赖：package.json 无 dependencies / devDependencies，没有供应链风险、没有安装脚本、没有 postinstall。

  5. 本地数据：分析全部在本机完成，不上传任何数据到第三方；唯一的外部访问是华为 AGC 官方接口。

限制与已知问题

  • Crash 接口标记 beta：/api/apm/api/v1/hap/query/{crash|app-freeze}/metric 的请求体字段来自社区实测。若上游拒绝，工具会原样返回响应并提示改用 agc_request 调整字段。

  • 评论接口只支持 API 客户端凭据：只用 Service Account 时评论类工具会失败并提示原因，其余工具不受影响。

  • 报表下载地址有效期约 5 分钟：工具在同一次调用内立即下载，无需人工干预。

  • CSV 编码：优先按严格 UTF-8 解析，失败时回退 GBK；两者都不可用时按 UTF-8 宽松解析。

  • GBK 需要 Node 的完整 ICU：官方发行版默认包含；若运行时不支持，中文报表可能出现替换字符。

  • 本项目为社区项目，与华为公司无关，未获其背书。AppGallery Connect、HarmonyOS 为华为技术有限公司的商标。

开发

npm test    # 单元 + 协议 e2e + mock 全链路，55 项
node scripts/check-secrets.mjs      # 提交前密钥扫描
node scripts/handshake-check.mjs    # 真机 stdio 握手自检（CI 同款）
node scripts/live-smoke.mjs         # 真实凭据冒烟（需 AGC_* 环境变量，不属于 CI）

第一次用真实凭据验证（推荐顺序）

# 1) 离线预检：不联网，只检查凭据文件是否存在、格式对不对、有没有把
#    Service Account 的 JSON 错填给 AGC_CLIENT_FILE（反之亦然）
AGC_CLIENT_FILE=/绝对路径/api-client.json node scripts/live-smoke.mjs --check-only

# 2) 真实冒烟：默认取最近 7 天，逐段报告成功/失败（只读调用）
AGC_CLIENT_FILE=/绝对路径/api-client.json node scripts/live-smoke.mjs
AGC_SERVICE_ACCOUNT_FILE=/绝对路径/private.json node scripts/live-smoke.mjs 110012345 --days=14

退出码：0 核心链路可用 / 1 核心步骤失败 / 2 凭据缺失或不可用 / 3 命令行参数有误。 输出里 ! 是警告（该凭据或站点不支持的段落，核心链路仍然可用），✘ 才是失败。 --json 可输出机器可读结果，便于接入你自己的巡检。

目录结构：

index.js              # bin 入口（仅作为进程入口时启动）
src/mcp-server.js     # stdio JSON-RPC 循环（手写 MCP 协议子集，零依赖）
src/client.js         # HTTP 客户端：域名守卫、业务码、401 重试、下载
src/auth.js           # client_credentials 令牌 + Service Account PS256 JWT
src/tools/*.js        # 13 个工具
src/analytics/*.js    # 趋势 / 文本聚类 / Crash 归一化 / 报告组装（纯函数）
test/*.test.js        # 55 项测试

提交 PR 前请确保 node --test、node scripts/check-secrets.mjs 与 node scripts/handshake-check.mjs 均通过；CI 会在 Windows 与 Linux、Node 20 与 22 上跑同一套测试。

许可

MIT

Available Tools

13 tools
agc_auth_statusCheck AGC credential configurationA
Read-only

Report the AGC credential configuration: which credential kinds are loaded (API client / Service Account), the active site, timeout, and any configuration problems. No network request is made. Call this first when requests start failing with auth errors. Secrets are never included.

Inputs: no named parameters.

agc_crash_metricQuery crash / app-freeze metricsA
Read-only

Query AGC APM crash or app-freeze metrics (POST /api/apm/api/v1/hap/query/{kind}/metric) and return normalised rows {day, version, count, users, rate}. If the gateway rejects the body shape, the raw response is returned with a note; use agc_request to adjust fields. This endpoint is community-verified; schema drift is possible.

Inputs: appId (required), kind, site, endDate, +3 more.

agc_crash_summarySummarise crash / app-freeze metricsA
Read-only

Query crash or app-freeze metrics and summarise: total, last-7 vs previous-7 (WoW), worst days, top affected versions, daily series.

Inputs: appId (required), kind, site, endDate, +3 more.

agc_daily_reportBuild a one-day AGC report (Markdown)A
Read-only

Build a daily operations digest for one day (default: yesterday): the 7-day download/install trend ending that day, crash/app-freeze totals, and a review snapshot. Each section degrades independently into a marked paragraph; the Markdown is returned and optionally written to outPath.

Inputs: appId (required), date, site, report, +5 more.

agc_get_app_idResolve package name to appIdB
Read-only

Resolve AGC appId(s) from package name(s), comma-separated, up to 50.

Inputs: packageNames (required), site.

agc_list_appsList AGC projects and appsA
Read-only

List all AGC projects visible to the credential and the apps inside each (appId, name, package name, device types). Use this to discover the appId every other tool requires.

Inputs: site.

agc_ratings_summarySummarise app ratingsA
Read-only

Fetch ratings for an app (average, star histogram) over a time window (max 6 months). Requires the API-client credential.

Inputs: appId (required), platform (required), end, site, +2 more.

agc_report_exportExport an AGC report as parsed rowsA
Read-only

Export an AGC operations report and return parsed rows. Reports: harmony-download (harmonyos: HarmonyOS app downloads & installs); harmony-install-failed (harmonyos: HarmonyOS install failures); harmony-user-analysis (harmonyos: HarmonyOS user analysis (new/active/retention)); harmony-atomic-distribute (harmonyos: HarmonyOS atomic service distribution); download (android: Downloads & installs (Android)); install-failed (android: Install failures (Android)); new-and-retention (android: New users & retention (Android)); iap (android: In-app purchases (Android)); paid-download (android: Paid downloads (Android)); paid-download-detail (android: Paid download details (Android)); game-reservation (android: Game reservations (Android)); activity-award (android: User-group award campaigns (Android)); coupon (android: Coupon campaigns (Android)); atomic-distribute (android: Atomic service distribution (legacy, Android)); atomic-user (android: Atomic service users (legacy, Android)); atomic-widget (android: Atomic service widgets (legacy, Android)). Window at most 180 days ending today. Rows are capped in the response (allRows=false); set outPath to also save the raw CSV on disk.

Inputs: appId (required), report (required), site, allRows, +8 more.

agc_report_trendTrend analysis over an AGC reportB
Read-only

Export a report and analyse the trend of one metric: week-over-week change, 7-day moving-average direction, z-score anomaly days, peak/trough and a 28-day sparkline. Use metric="" to get a compact overview of all numeric columns.

Inputs: appId (required), report (required), site, metric, +5 more.

agc_requestCall a whitelisted read-only AGC endpointA
Read-only

Generic GET/POST passthrough for AGC Connect API read endpoints without a dedicated tool. Allowed path prefixes: /api/report/, /api/apm/, /api/project-service/v1/projects, /api/publish/v2/appid-list, /api/publish/v2/app-info, /api/marketing-api/v2/reviews/manage/dev/ratings, /api/marketing-api/v2/reviews/manage/dev/reviews, /api/reviews/v1/manage/dev/ratings, /api/reviews/v1/manage/dev/reviews. Review/app-info paths accept GET only. Write operations (publish, upload, reply, delete) are not callable through this tool by design.

Inputs: path (required), body, site, query, +1 more.

agc_review_insightsCluster review keywords & star distributionA
Read-only

Fetch reviews (up to 10 pages of 100) and analyse them: star histogram, average rating, top complaint/praise keywords (CJK bigrams + Latin words), per-version negative hotspots. Set onlyNegative=true to focus on stars ≤ minRating (default 3). Requires the API-client credential.

Inputs: appId (required), platform (required), end, site, +6 more.

agc_reviews_listList app reviewsA
Read-only

Fetch the review list with filters (rating, version, reply state, keyword, sort) — window max 6 months, page size max 100. Requires the API-client credential.

Inputs: appId (required), platform (required), end, page, +9 more.

agc_weekly_reportBuild a weekly AGC report with WoW comparison (Markdown)A
Read-only

Build a weekly digest for the 7 days ending on endDate (default: yesterday): download/install totals with week-over-week comparison, crash totals with week-over-week, and the week's review keywords. The previous week is fetched automatically. Markdown is returned and optionally written to outPath.

Inputs: appId (required), site, report, endDate, +5 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.8/5.0

    Scored across 13 tools

    Disambiguation4/5

    Each tool targets a reasonably distinct output, and descriptions explicitly steer choices (e.g. raw vs summary crash, list vs insights for reviews). However, there is genuine layering overlap: agc_crash_metric/agc_crash_summary query the same endpoint, agc_reviews_list/agc_review_insights/agc_ratings_summary fetch overlapping review data, and the digest tools re-aggregate the same sources, so an agent could occasionally misselect.

    Naming Consistency4/5

    Every tool shares the agc_ prefix and snake_case, which is highly predictable. The internal verb/noun ordering is slightly loose (agc_list_apps vs agc_report_export vs agc_crash_metric), but the convention is clear and readable throughout.

    Tool Count5/5

    13 tools sit squarely in the well-scoped 3-15 band, and each occupies a distinct role (auth, discovery, export, trend, crash, reviews, digests, passthrough). No tool feels redundant or bloated for the analytics scope.

    Completeness4/5

    Coverage of the read-only AGC analytics domain is strong: apps, downloads, installs, failures, users/retention, IAP/coupons, crashes, ratings and reviews, plus daily/weekly rollups and a generic passthrough fallback. Write operations (reply, publish, upload) are deliberately excluded, which is a defensible but real boundary.

    Resources

    Related MCP Connectors

    Related MCP Servers