apphud-mcp 0.2.1 → 0.2.4

package/README.md

@@ -1,104 +1,93 @@
 # apphud-mcp <img src="./assets/apphud-mcp-logo.svg" alt="apphud + mcp" height="28" />
 
-Zero-config MCP server for Apphud Dashboard Analytics with local SQLite storage.
+MCP server for Apphud analytics with storage-based ETL ingestion (GCS/S3) and local SQLite query cache.
 
 ## Quick Start
 
-1. Optional config file (`apphud-mcp.config.json`):
-
-```json
-{
-  "storage": {
-    "backend": "sqlite",
-    "sqlite_path": ".apphud-mcp/apphud.db"
-  },
-  "etl": {
-    "enabled": true,
-    "tenant_id": "default",
-    "poll_interval_minutes": 60,
-    "storage_dir": ".apphud-etl",
-    "incoming_dir": ".apphud-etl/incoming",
-    "alerts_stale_hours": 30,
-    "remote_fetch_enabled": false
-  }
-}
-```
-
-2. Cursor MCP config:
+1. Add MCP server:
 
 ```json
 {
   "mcpServers": {
     "apphud-mcp": {
-      "command": "node",
-      "args": [
-        "/Users/you/apphud-mcp/dist/src/cli.js",
-        "start",
-        "--config",
-        "/Users/you/apphud-mcp/apphud-mcp.config.json"
-      ],
+      "command": "npx",
+      "args": ["-y", "apphud-mcp@0.2.2", "start"],
       "env": {
         "login": "your@apphud.email",
-        "password": "your_apphud_password"
+        "password": "your_apphud_password",
+        "ETL_SOURCE": "gcs",
+        "ETL_GCS_BUCKET": "your-bucket",
+        "ETL_GCS_PREFIX": "apphud/exports"
       }
     }
   }
 }
 ```
 
-3. Restart MCP server in Cursor.
-
-## What Changed
+2. Restart MCP server.
+3. Check ingestion:
+   - `apphud_etl_local_status`
+   - `apphud_apps_list_local`
+   - `apphud_dashboard_local`
+
+## ETL Setup
+
+<details>
+<summary>Google Cloud Storage (GCS) setup</summary>
+
+1. In Apphud:
+   - Open `Integrations` -> `GCS ETL` -> `Add connection`.
+   - Enter project/service account/bucket and enable export for apps.
+2. In Google Cloud Console:
+   - Create/select a bucket in [Cloud Storage](https://console.cloud.google.com/storage/browser).
+   - Create a Service Account in [IAM](https://console.cloud.google.com/iam-admin/serviceaccounts).
+   - Create JSON key for that service account.
+   - Grant access to the bucket (read for MCP side, write for Apphud side as needed by your policy).
+3. MCP env vars:
+   - `ETL_SOURCE=gcs`
+   - `ETL_GCS_BUCKET=<bucket-name>`
+   - `ETL_GCS_PREFIX=<optional-prefix>`
+   - `GOOGLE_APPLICATION_CREDENTIALS=<path-to-service-account-json>`
+4. Ensure `gsutil` is installed and authenticated in runtime environment.
+
+</details>
+
+<details>
+<summary>Amazon S3 setup</summary>
+
+1. In Apphud:
+   - Open `Integrations` -> `S3 ETL` -> `Add connection`.
+   - Fill bucket/credentials/region and enable export for apps.
+2. In AWS Console:
+   - Create/select bucket in [S3](https://s3.console.aws.amazon.com/s3/home).
+   - Create IAM user/role with bucket access.
+   - Generate access key (if using user credentials).
+3. MCP env vars:
+   - `ETL_SOURCE=s3`
+   - `ETL_S3_BUCKET=<bucket-name>`
+   - `ETL_S3_PREFIX=<optional-prefix>`
+   - `AWS_ACCESS_KEY_ID=<key-id>`
+   - `AWS_SECRET_ACCESS_KEY=<secret>`
+   - `AWS_REGION=<region>`
+4. Ensure AWS CLI (`aws`) is installed and usable in runtime environment.
+
+</details>
+
+## Defaults
+
+- SQLite DB: `.apphud-mcp/apphud.db`
+- Incoming ETL files: `.apphud-etl/incoming`
+- Poll interval: 60 minutes
+- ETL enabled: `true`
+- ETL source default: `none` (set `ETL_SOURCE=gcs` or `ETL_SOURCE=s3`)
+
+## Useful Tools
 
-- Default mode is analytics-only.
-- No Postgres required (SQLite is default).
-- No webhook/event-store setup required.
-- Apps are fetched directly from Apphud Dashboard API.
-- ETL worker can run hourly and auto-sync app API keys from Dashboard (`settings/general` fallback).
-
-## Basic Checks
-
-Ask MCP to call:
-
-1. `apphud_apps_list`
-2. `apphud_analytics_capabilities_get` (with `app_id` from step 1)
-3. `apphud_analytics_revenue_summary` (for a date range)
-
-## Available Tools
-
-Local-first tools (higher priority):
 - `apphud_etl_local_status`
-- `apphud_apps_list_local`
 - `apphud_dashboard_local`
-- `apphud_analytics_events_list_local`
-- `apphud_analytics_active_subscriptions_local`
-- `apphud_analytics_capabilities_get_local`
-- `apphud_analytics_metrics_list_local`
-- `apphud_analytics_metric_value_local`
-- `apphud_analytics_metric_timeseries_local`
-- `apphud_analytics_metric_breakdown_local`
-- `apphud_analytics_revenue_summary_local`
-- `apphud_analytics_subscriptions_summary_local`
-- `apphud_analytics_conversion_trial_to_paid_local`
-- `apphud_analytics_cohorts_retention_local`
-- `apphud_analytics_cohorts_ltv_local`
-- `apphud_analytics_query_raw_local`
-
-Remote tools (still available):
-- `apphud_apps_list`
-- `apphud_analytics_events_list`
-- `apphud_analytics_active_subscriptions`
-- `apphud_analytics_capabilities_get`
-- `apphud_analytics_metrics_list`
-- `apphud_analytics_metric_value`
-- `apphud_analytics_metric_timeseries`
-- `apphud_analytics_metric_breakdown`
-- `apphud_analytics_revenue_summary`
-- `apphud_analytics_subscriptions_summary`
-- `apphud_analytics_conversion_trial_to_paid`
-- `apphud_analytics_cohorts_retention`
-- `apphud_analytics_cohorts_ltv`
-- `apphud_analytics_query_raw`
+- `apphud_apps_list_local`
+- `apphud_analytics_*_local`
+- `apphud_analytics_*` (remote analytics endpoints)
 
 ## Development
 

package/dist/src/cli.js

@@ -33,6 +33,33 @@ function printHelp() {
 Usage:
   apphud-mcp start [--config <path>] [--config-json '<json>']
   apphud-mcp init-config [--out <path>] [--force]
+
+Zero-config quick start:
+  1) Add MCP server using:
+     npx -y apphud-mcp@0.2.2 start
+  2) Set env vars:
+     login=<your apphud email>
+     password=<your apphud password>
+  3) Use local-first tools:
+     apphud_etl_local_status
+     apphud_dashboard_local
+     apphud_apps_list_local
+
+Defaults:
+  - SQLite DB: .apphud-mcp/apphud.db
+  - ETL storage: .apphud-etl
+  - Poll interval: 60 minutes
+  - ETL worker enabled; source is none until you set GCS/S3
+
+Storage source setup:
+  GCS:
+    ETL_SOURCE=gcs
+    ETL_GCS_BUCKET=<bucket>
+    ETL_GCS_PREFIX=<prefix optional>
+  S3:
+    ETL_SOURCE=s3
+    ETL_S3_BUCKET=<bucket>
+    ETL_S3_PREFIX=<prefix optional>
 `);
 }
 async function ensureWritable(filePath, force = false) {

package/dist/src/config/env.js

@@ -190,18 +190,16 @@ export function loadEnvConfig(options = {}) {
         : `${etlStorageDir}/incoming`;
     const etlTenantIdRaw = simpleConfig.etl?.tenant_id ?? process.env.ETL_TENANT_ID;
     const etlTenantId = typeof etlTenantIdRaw === "string" && etlTenantIdRaw.trim().length > 0 ? etlTenantIdRaw.trim() : "default";
-    const etlExportsApiBaseUrlRaw = simpleConfig.apphud?.etl_exports_api_base_url ?? process.env.APPHUD_ETL_EXPORTS_API_BASE_URL;
-    const apphudEtlExportsApiBaseUrl = typeof etlExportsApiBaseUrlRaw === "string" && etlExportsApiBaseUrlRaw.trim().length > 0
-        ? etlExportsApiBaseUrlRaw.trim()
-        : "https://api.apphud.com/v1";
-    const apphudEtlExportsListPathRaw = simpleConfig.apphud?.etl_exports_list_path ?? process.env.APPHUD_ETL_EXPORTS_LIST_PATH;
-    const apphudEtlExportsListPath = typeof apphudEtlExportsListPathRaw === "string" && apphudEtlExportsListPathRaw.trim().length > 0
-        ? apphudEtlExportsListPathRaw.trim()
-        : "/apps/{app_id}/etl-exports";
-    const apphudEtlExportsDownloadPathRaw = simpleConfig.apphud?.etl_exports_download_path ?? process.env.APPHUD_ETL_EXPORTS_DOWNLOAD_PATH;
-    const apphudEtlExportsDownloadPath = typeof apphudEtlExportsDownloadPathRaw === "string" && apphudEtlExportsDownloadPathRaw.trim().length > 0
-        ? apphudEtlExportsDownloadPathRaw.trim()
-        : "/apps/{app_id}/etl-exports/{export_id}";
+    const etlSourceRaw = simpleConfig.etl?.source ?? process.env.ETL_SOURCE;
+    const etlSource = etlSourceRaw === "gcs" || etlSourceRaw === "s3" || etlSourceRaw === "none" ? etlSourceRaw : "none";
+    const etlGcsBucketRaw = simpleConfig.etl?.gcs_bucket ?? process.env.ETL_GCS_BUCKET;
+    const etlGcsBucket = typeof etlGcsBucketRaw === "string" && etlGcsBucketRaw.trim().length > 0 ? etlGcsBucketRaw.trim() : undefined;
+    const etlGcsPrefixRaw = simpleConfig.etl?.gcs_prefix ?? process.env.ETL_GCS_PREFIX;
+    const etlGcsPrefix = typeof etlGcsPrefixRaw === "string" && etlGcsPrefixRaw.trim().length > 0 ? etlGcsPrefixRaw.trim() : undefined;
+    const etlS3BucketRaw = simpleConfig.etl?.s3_bucket ?? process.env.ETL_S3_BUCKET;
+    const etlS3Bucket = typeof etlS3BucketRaw === "string" && etlS3BucketRaw.trim().length > 0 ? etlS3BucketRaw.trim() : undefined;
+    const etlS3PrefixRaw = simpleConfig.etl?.s3_prefix ?? process.env.ETL_S3_PREFIX;
+    const etlS3Prefix = typeof etlS3PrefixRaw === "string" && etlS3PrefixRaw.trim().length > 0 ? etlS3PrefixRaw.trim() : undefined;
     return {
         nodeEnv: simpleConfig.node_env ?? process.env.NODE_ENV ?? "development",
         port: parseNumber(simpleConfig.transport?.port ?? process.env.PORT, 8080),
@@ -234,17 +232,18 @@ export function loadEnvConfig(options = {}) {
             "/sessions",
         apphudAnalyticsLoginEmailSecretRef: analyticsLoginEmailSecretRef,
         apphudAnalyticsLoginPasswordSecretRef: analyticsLoginPasswordSecretRef,
-        apphudEtlExportsApiBaseUrl,
-        apphudEtlExportsListPath,
-        apphudEtlExportsDownloadPath,
         apphudWebhookTokenHeader: simpleConfig.security?.webhook_token_header ?? process.env.APPHUD_WEBHOOK_TOKEN_HEADER ?? "x-apphud-token",
-        etlEnabled: parseBoolean(simpleConfig.etl?.enabled ?? process.env.ETL_ENABLED, false),
+        etlEnabled: parseBoolean(simpleConfig.etl?.enabled ?? process.env.ETL_ENABLED, true),
         etlTenantId,
         etlPollIntervalMinutes: parseNumber(simpleConfig.etl?.poll_interval_minutes ?? process.env.ETL_POLL_INTERVAL_MINUTES, 60),
         etlStorageDir,
         etlIncomingDir,
         etlAlertsStaleHours: parseNumber(simpleConfig.etl?.alerts_stale_hours ?? process.env.ETL_ALERTS_STALE_HOURS, 30),
-        etlRemoteFetchEnabled: parseBoolean(simpleConfig.etl?.remote_fetch_enabled ?? process.env.ETL_REMOTE_FETCH_ENABLED, false),
+        etlSource,
+        etlGcsBucket,
+        etlGcsPrefix,
+        etlS3Bucket,
+        etlS3Prefix,
         httpEnabled: parseBoolean(simpleConfig.transport?.http_enabled ?? process.env.HTTP_ENABLED, false),
         mcpStdioEnabled: parseBoolean(simpleConfig.transport?.mcp_stdio_enabled ?? process.env.MCP_STDIO_ENABLED, true),
     };
@@ -256,13 +255,17 @@ export function buildExampleSimpleConfig() {
             sqlite_path: ".apphud-mcp/apphud.db",
         },
         etl: {
-            enabled: false,
+            enabled: true,
             tenant_id: "default",
             poll_interval_minutes: 60,
             storage_dir: ".apphud-etl",
             incoming_dir: ".apphud-etl/incoming",
             alerts_stale_hours: 30,
-            remote_fetch_enabled: false,
+            source: "none",
+            gcs_bucket: "your-gcs-bucket",
+            gcs_prefix: "apphud/exports",
+            s3_bucket: "your-s3-bucket",
+            s3_prefix: "apphud/exports",
         },
         defaults: {
             tenant_id: "tenant_default",
@@ -289,9 +292,6 @@ export function buildExampleSimpleConfig() {
             analytics_login_path: "/sessions",
             analytics_login_email_secret_ref: "login",
             analytics_login_password_secret_ref: "password",
-            etl_exports_api_base_url: "https://api.apphud.com/v1",
-            etl_exports_list_path: "/apps/{app_id}/etl-exports",
-            etl_exports_download_path: "/apps/{app_id}/etl-exports/{export_id}",
         },
     };
 }

package/dist/src/services/analyticsService.js

@@ -249,6 +249,25 @@ export class AnalyticsService {
             includeRaw: input.include_raw,
             auth,
         });
+        if (resolved.code === "METRIC_AMBIGUOUS") {
+            throw new ApphudMcpError("METRIC_AMBIGUOUS", `Metric key '${input.metric_key}' matched multiple dashboard metrics`, {
+                statusCode: 400,
+                details: {
+                    metric_key: input.metric_key,
+                    candidates: resolved.candidates ?? [],
+                    available_metrics: resolved.available_metrics ?? [],
+                },
+            });
+        }
+        if (resolved.value === null) {
+            throw new ApphudMcpError("METRIC_NOT_FOUND", `Metric key '${input.metric_key}' not found in analytics payload`, {
+                statusCode: 404,
+                details: {
+                    metric_key: input.metric_key,
+                    available_metrics: resolved.available_metrics ?? [],
+                },
+            });
+        }
         return {
             app_id: app.appId,
             apphud_app_id: input.apphud_app_id ?? app.appId,
@@ -802,6 +821,16 @@ export class AnalyticsService {
     }
     async resolveMetricValue(app, options) {
         const warnings = [];
+        const availableMetrics = new Set();
+        let ambiguousCandidates;
+        const collectExtractionMeta = (extracted) => {
+            for (const metricName of extracted.available_metrics ?? []) {
+                availableMetrics.add(metricName);
+            }
+            if (extracted.code === "METRIC_AMBIGUOUS" && extracted.candidates && extracted.candidates.length > 0) {
+                ambiguousCandidates = extracted.candidates;
+            }
+        };
         if (options.from && options.to) {
             const dashRange = await this.apphudClient.fetchDashRange(app, {
                 apphudAppId: options.apphudAppId,
@@ -812,6 +841,18 @@ export class AnalyticsService {
                 filters: options.filters,
             });
             const extractedRange = extractMetricValue(dashRange.payload, options.metricKey);
+            collectExtractionMeta(extractedRange);
+            if (extractedRange.code === "METRIC_AMBIGUOUS") {
+                return {
+                    value: null,
+                    source_used: "/dash/range",
+                    raw_payload: this.selectRawPayload(options.auth, options.includeRaw, dashRange.payload),
+                    warnings: [...warnings, "Metric key matched multiple dashboard rows"],
+                    code: "METRIC_AMBIGUOUS",
+                    available_metrics: Array.from(availableMetrics.values()).sort((left, right) => left.localeCompare(right)),
+                    candidates: ambiguousCandidates ?? [],
+                };
+            }
             if (extractedRange.value !== null) {
                 return {
                     value: extractedRange.value,
@@ -843,6 +884,18 @@ export class AnalyticsService {
                 filters: options.filters,
             });
             const extractedChart = extractMetricValue(chart.payload, options.metricKey);
+            collectExtractionMeta(extractedChart);
+            if (extractedChart.code === "METRIC_AMBIGUOUS") {
+                return {
+                    value: null,
+                    source_used: chart.sourcePath,
+                    raw_payload: this.selectRawPayload(options.auth, options.includeRaw, chart.payload),
+                    warnings: [...warnings, "Metric key matched multiple dashboard rows"],
+                    code: "METRIC_AMBIGUOUS",
+                    available_metrics: Array.from(availableMetrics.values()).sort((left, right) => left.localeCompare(right)),
+                    candidates: ambiguousCandidates ?? [],
+                };
+            }
             if (extractedChart.value !== null) {
                 return {
                     value: extractedChart.value,
@@ -868,6 +921,8 @@ export class AnalyticsService {
                 source_used: chart.sourcePath,
                 raw_payload: this.selectRawPayload(options.auth, options.includeRaw, chart.payload),
                 warnings: [...warnings, "Metric not found in analytics payloads"],
+                code: "METRIC_NOT_FOUND",
+                available_metrics: Array.from(availableMetrics.values()).sort((left, right) => left.localeCompare(right)),
             };
         }
         const dashNow = await this.apphudClient.fetchDashNow(app, {
@@ -876,6 +931,18 @@ export class AnalyticsService {
             filters: options.filters,
         });
         const extractedNow = extractMetricValue(dashNow.payload, options.metricKey);
+        collectExtractionMeta(extractedNow);
+        if (extractedNow.code === "METRIC_AMBIGUOUS") {
+            return {
+                value: null,
+                source_used: "/dash/now",
+                raw_payload: this.selectRawPayload(options.auth, options.includeRaw, dashNow.payload),
+                warnings: [...warnings, "Metric key matched multiple dashboard rows"],
+                code: "METRIC_AMBIGUOUS",
+                available_metrics: Array.from(availableMetrics.values()).sort((left, right) => left.localeCompare(right)),
+                candidates: ambiguousCandidates ?? [],
+            };
+        }
         if (extractedNow.value !== null) {
             return {
                 value: extractedNow.value,
@@ -894,6 +961,18 @@ export class AnalyticsService {
             filters: options.filters,
         });
         const extractedChartNow = extractMetricValue(chartNow.payload, options.metricKey);
+        collectExtractionMeta(extractedChartNow);
+        if (extractedChartNow.code === "METRIC_AMBIGUOUS") {
+            return {
+                value: null,
+                source_used: chartNow.sourcePath,
+                raw_payload: this.selectRawPayload(options.auth, options.includeRaw, chartNow.payload),
+                warnings: [...warnings, "Metric key matched multiple dashboard rows"],
+                code: "METRIC_AMBIGUOUS",
+                available_metrics: Array.from(availableMetrics.values()).sort((left, right) => left.localeCompare(right)),
+                candidates: ambiguousCandidates ?? [],
+            };
+        }
         if (extractedChartNow.value !== null) {
             return {
                 value: extractedChartNow.value,
@@ -911,6 +990,8 @@ export class AnalyticsService {
             extracted_from: series.path,
             raw_payload: this.selectRawPayload(options.auth, options.includeRaw, chartNow.payload),
             warnings: [...warnings, "Metric value estimated from last chart point"],
+            code: lastPoint ? undefined : "METRIC_NOT_FOUND",
+            available_metrics: Array.from(availableMetrics.values()).sort((left, right) => left.localeCompare(right)),
         };
     }
     assertRawAccess(auth, includeRaw) {

package/dist/src/services/apphudClient.js

@@ -61,6 +61,13 @@ const METRIC_KEY_ALIASES = {
     subscribers_retention: ["subscribers_retention", "retention", "subscription_retention"],
     cumulative_ltv: ["cumulative_ltv", "ltv", "lifetime_value"],
 };
+const METRIC_KEY_TO_LABELS = {
+    active_subs: ["Active Paid Subscriptions"],
+    active_trial: ["Active Trials"],
+    active_trials: ["Active Trials"],
+    active_intro: ["Active Intro Offers"],
+    active_promo: ["Active Promo Offers"],
+};
 function asRecord(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return {};
@@ -355,6 +362,17 @@ function expandMetricAliases(metricKey) {
     }
     return aliases;
 }
+function resolveMetricLabels(metricKey, aliases) {
+    const labels = new Set();
+    const keysToCheck = new Set([normalizeMetricKey(metricKey), ...aliases]);
+    for (const key of keysToCheck) {
+        const mappedLabels = METRIC_KEY_TO_LABELS[key] ?? [];
+        for (const label of mappedLabels) {
+            labels.add(normalizeMetricKey(label));
+        }
+    }
+    return labels;
+}
 function parseNumericValue(value) {
     if (typeof value === "number" && Number.isFinite(value)) {
         return value;
@@ -514,8 +532,135 @@ function metricNamedKey(record) {
 function isLikelyMetricIdentifier(value) {
     return /[a-z]/.test(value) && value.length >= 3 && value.length <= 80;
 }
+function extractMetricValueFromDashboardGroups(payload, metricKey, aliases) {
+    const expectedLabels = resolveMetricLabels(metricKey, aliases);
+    const matched = [];
+    const available = new Set();
+    const visited = new WeakSet();
+    let hasGroups = false;
+    const walk = (node, path) => {
+        if (Array.isArray(node)) {
+            for (let index = 0; index < node.length; index += 1) {
+                walk(node[index], `${path}[${index}]`);
+            }
+            return;
+        }
+        if (!isRecord(node)) {
+            return;
+        }
+        if (visited.has(node)) {
+            return;
+        }
+        visited.add(node);
+        const groups = asArray(node.groups);
+        if (groups.length > 0) {
+            hasGroups = true;
+            for (let groupIndex = 0; groupIndex < groups.length; groupIndex += 1) {
+                const group = groups[groupIndex];
+                if (!group) {
+                    continue;
+                }
+                const items = asArray(group.items);
+                for (let itemIndex = 0; itemIndex < items.length; itemIndex += 1) {
+                    const item = items[itemIndex];
+                    if (!item) {
+                        continue;
+                    }
+                    const itemPath = `${path}.groups[${groupIndex}].items[${itemIndex}]`;
+                    const names = [item.short_name, item.name, item.raw_key, item.metric, item.key, item.chart_id, item.chartId]
+                        .map((value) => readStringValue(value))
+                        .filter((value) => Boolean(value));
+                    const normalizedNames = new Set(names.map((value) => normalizeMetricKey(value)));
+                    const title = readStringValue(item.name) ?? readStringValue(item.short_name) ?? readStringValue(item.raw_key);
+                    if (title) {
+                        available.add(title);
+                    }
+                    const matchesByAlias = Array.from(normalizedNames).some((name) => aliases.has(name));
+                    const matchesByLabel = Array.from(normalizedNames).some((name) => expectedLabels.has(name));
+                    if (!matchesByAlias && !matchesByLabel) {
+                        continue;
+                    }
+                    const values = asArray(item.values);
+                    for (let valueIndex = 0; valueIndex < values.length; valueIndex += 1) {
+                        const valueEntry = values[valueIndex];
+                        if (!valueEntry) {
+                            continue;
+                        }
+                        if (normalizeMetricKey(String(valueEntry.name ?? "")) !== "value") {
+                            continue;
+                        }
+                        const parsedValue = parseNumericValue(valueEntry.value);
+                        if (parsedValue === null) {
+                            continue;
+                        }
+                        matched.push({
+                            name: title ?? "unknown",
+                            path: `${itemPath}.values[${valueIndex}]`,
+                            value: parsedValue,
+                        });
+                    }
+                }
+            }
+        }
+        for (const [key, value] of Object.entries(node)) {
+            walk(value, `${path}.${key}`);
+        }
+    };
+    walk(payload, "$");
+    if (!hasGroups) {
+        return { kind: "not_applicable" };
+    }
+    const availableMetrics = Array.from(available.values()).sort((left, right) => left.localeCompare(right));
+    if (matched.length === 1) {
+        const singleMatch = matched[0];
+        if (!singleMatch) {
+            return {
+                kind: "not_found",
+                availableMetrics,
+            };
+        }
+        return {
+            kind: "resolved",
+            value: singleMatch.value,
+            path: singleMatch.path,
+        };
+    }
+    if (matched.length > 1) {
+        return {
+            kind: "ambiguous",
+            candidates: matched.map((item) => ({ name: item.name, path: item.path })),
+            availableMetrics,
+        };
+    }
+    return {
+        kind: "not_found",
+        availableMetrics,
+    };
+}
 export function extractMetricValue(payload, metricKey) {
     const aliases = expandMetricAliases(metricKey);
+    const dashboardExtraction = extractMetricValueFromDashboardGroups(payload, metricKey, aliases);
+    if (dashboardExtraction.kind === "resolved") {
+        return {
+            value: dashboardExtraction.value,
+            path: dashboardExtraction.path,
+        };
+    }
+    if (dashboardExtraction.kind === "ambiguous") {
+        return {
+            value: null,
+            code: "METRIC_AMBIGUOUS",
+            candidates: dashboardExtraction.candidates,
+            available_metrics: dashboardExtraction.availableMetrics,
+        };
+    }
+    if (dashboardExtraction.kind === "not_found") {
+        return {
+            value: null,
+            code: "METRIC_NOT_FOUND",
+            available_metrics: dashboardExtraction.availableMetrics,
+        };
+    }
     const search = (node, path, mode, visited) => {
         if (Array.isArray(node)) {
             for (let index = 0; index < node.length; index += 1) {