apphud-mcp 0.1.7 → 0.2.1

package/README.md

@@ -1,13 +1,27 @@
 # apphud-mcp <img src="./assets/apphud-mcp-logo.svg" alt="apphud + mcp" height="28" />
 
-Zero-config MCP server for Apphud Dashboard Analytics.
+Zero-config MCP server for Apphud Dashboard Analytics with local SQLite storage.
 
 ## 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:
@@ -37,10 +51,10 @@ Zero-config MCP server for Apphud Dashboard Analytics.
 ## What Changed
 
 - Default mode is analytics-only.
-- No Apphud app API keys required for basic usage.
-- No Postgres required.
+- 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
 
@@ -52,6 +66,25 @@ Ask MCP to call:
 
 ## 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`

package/dist/src/app.js

@@ -4,6 +4,7 @@ import { RateLimiter } from "./security/rateLimiter.js";
 import { AppService } from "./services/appService.js";
 import { AnalyticsService } from "./services/analyticsService.js";
 import { ApphudClient } from "./services/apphudClient.js";
+import { EtlService } from "./services/etlService.js";
 import { AuditService } from "./services/auditService.js";
 import { ToolGuard } from "./services/toolGuard.js";
 export function createServiceContainer(options) {
@@ -12,6 +13,7 @@ export function createServiceContainer(options) {
     const appService = new AppService();
     const apphudClient = new ApphudClient(config, secretStore);
     const analyticsService = new AnalyticsService(appService, apphudClient);
+    const etlService = new EtlService(config, apphudClient);
     const auditService = new AuditService(config);
     const rateLimiter = new RateLimiter(config.rateLimitPerMinute);
     const toolGuard = new ToolGuard(rateLimiter, auditService);
@@ -21,11 +23,14 @@ export function createServiceContainer(options) {
         appService,
         apphudClient,
         analyticsService,
+        etlService,
         auditService,
         toolGuard,
-        close: async () => Promise.resolve(),
+        close: async () => {
+            await etlService.close();
+        },
     };
 }
-export async function initializeServiceContainer(_container) {
-    return Promise.resolve();
+export async function initializeServiceContainer(container) {
+    await container.etlService.start();
 }

package/dist/src/config/env.js

@@ -2,7 +2,7 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import "dotenv/config";
 const VALID_ROLES = new Set(["analyst", "support", "admin"]);
-const VALID_STORAGE_BACKENDS = new Set(["postgres", "memory"]);
+const VALID_STORAGE_BACKENDS = new Set(["sqlite", "postgres", "memory"]);
 const VALID_APP_STATUSES = new Set(["active", "disabled"]);
 function parseNumber(value, fallback) {
     if (value === undefined || value === null || value === "") {
@@ -148,7 +148,7 @@ export function loadEnvConfig(options = {}) {
     const databaseUrlRaw = simpleConfig.database_url ?? process.env.DATABASE_URL;
     const databaseUrl = typeof databaseUrlRaw === "string" && databaseUrlRaw.trim().length > 0 ? databaseUrlRaw : undefined;
     const parsedStorageBackend = parseStorageBackend(simpleConfig.storage?.backend) ?? parseStorageBackend(process.env.STORAGE_BACKEND);
-    const storageBackend = parsedStorageBackend ?? (databaseUrl ? "postgres" : "memory");
+    const storageBackend = parsedStorageBackend ?? (databaseUrl ? "postgres" : "sqlite");
     if (storageBackend === "postgres" && !databaseUrl) {
         throw new Error("DATABASE_URL is required for postgres storage backend. Set database_url or switch to storage.backend=memory");
     }
@@ -178,11 +178,36 @@ export function loadEnvConfig(options = {}) {
     const analyticsLoginPasswordSecretRef = typeof analyticsLoginPasswordSecretRefRaw === "string" && analyticsLoginPasswordSecretRefRaw.trim().length > 0
         ? analyticsLoginPasswordSecretRefRaw
         : "password";
+    const sqlitePathRaw = simpleConfig.storage?.sqlite_path ?? process.env.SQLITE_PATH;
+    const sqlitePath = typeof sqlitePathRaw === "string" && sqlitePathRaw.trim().length > 0 ? sqlitePathRaw.trim() : ".apphud-mcp/apphud.db";
+    const etlStorageDirRaw = simpleConfig.etl?.storage_dir ?? process.env.ETL_STORAGE_DIR;
+    const etlStorageDir = typeof etlStorageDirRaw === "string" && etlStorageDirRaw.trim().length > 0
+        ? etlStorageDirRaw.trim()
+        : ".apphud-etl";
+    const etlIncomingDirRaw = simpleConfig.etl?.incoming_dir ?? process.env.ETL_INCOMING_DIR;
+    const etlIncomingDir = typeof etlIncomingDirRaw === "string" && etlIncomingDirRaw.trim().length > 0
+        ? etlIncomingDirRaw.trim()
+        : `${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}";
     return {
         nodeEnv: simpleConfig.node_env ?? process.env.NODE_ENV ?? "development",
         port: parseNumber(simpleConfig.transport?.port ?? process.env.PORT, 8080),
         databaseUrl,
         storageBackend,
+        sqlitePath,
         bootstrapApps,
         defaultTenantId,
         defaultRole,
@@ -209,7 +234,17 @@ 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),
+        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),
         httpEnabled: parseBoolean(simpleConfig.transport?.http_enabled ?? process.env.HTTP_ENABLED, false),
         mcpStdioEnabled: parseBoolean(simpleConfig.transport?.mcp_stdio_enabled ?? process.env.MCP_STDIO_ENABLED, true),
     };
@@ -217,7 +252,17 @@ export function loadEnvConfig(options = {}) {
 export function buildExampleSimpleConfig() {
     return {
         storage: {
-            backend: "memory",
+            backend: "sqlite",
+            sqlite_path: ".apphud-mcp/apphud.db",
+        },
+        etl: {
+            enabled: false,
+            tenant_id: "default",
+            poll_interval_minutes: 60,
+            storage_dir: ".apphud-etl",
+            incoming_dir: ".apphud-etl/incoming",
+            alerts_stale_hours: 30,
+            remote_fetch_enabled: false,
         },
         defaults: {
             tenant_id: "tenant_default",
@@ -244,6 +289,9 @@ 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/domain/constants.js

@@ -1,51 +1,99 @@
 export const TOOL_PERMISSIONS = {
     analyst: new Set([
         "apphud_apps_list",
+        "apphud_apps_list_local",
+        "apphud_dashboard_local",
         "apphud_analytics_events_list",
+        "apphud_analytics_events_list_local",
         "apphud_analytics_active_subscriptions",
+        "apphud_analytics_active_subscriptions_local",
         "apphud_analytics_capabilities_get",
+        "apphud_analytics_capabilities_get_local",
         "apphud_analytics_metrics_list",
+        "apphud_analytics_metrics_list_local",
         "apphud_analytics_metric_value",
+        "apphud_analytics_metric_value_local",
         "apphud_analytics_metric_timeseries",
+        "apphud_analytics_metric_timeseries_local",
         "apphud_analytics_metric_breakdown",
+        "apphud_analytics_metric_breakdown_local",
         "apphud_analytics_revenue_summary",
+        "apphud_analytics_revenue_summary_local",
         "apphud_analytics_subscriptions_summary",
+        "apphud_analytics_subscriptions_summary_local",
         "apphud_analytics_conversion_trial_to_paid",
+        "apphud_analytics_conversion_trial_to_paid_local",
         "apphud_analytics_cohorts_retention",
+        "apphud_analytics_cohorts_retention_local",
         "apphud_analytics_cohorts_ltv",
+        "apphud_analytics_cohorts_ltv_local",
         "apphud_analytics_query_raw",
+        "apphud_analytics_query_raw_local",
+        "apphud_etl_local_status",
     ]),
     support: new Set([
         "apphud_apps_list",
+        "apphud_apps_list_local",
+        "apphud_dashboard_local",
         "apphud_analytics_events_list",
+        "apphud_analytics_events_list_local",
         "apphud_analytics_active_subscriptions",
+        "apphud_analytics_active_subscriptions_local",
         "apphud_analytics_capabilities_get",
+        "apphud_analytics_capabilities_get_local",
         "apphud_analytics_metrics_list",
+        "apphud_analytics_metrics_list_local",
         "apphud_analytics_metric_value",
+        "apphud_analytics_metric_value_local",
         "apphud_analytics_metric_timeseries",
+        "apphud_analytics_metric_timeseries_local",
         "apphud_analytics_metric_breakdown",
+        "apphud_analytics_metric_breakdown_local",
         "apphud_analytics_revenue_summary",
+        "apphud_analytics_revenue_summary_local",
         "apphud_analytics_subscriptions_summary",
+        "apphud_analytics_subscriptions_summary_local",
         "apphud_analytics_conversion_trial_to_paid",
+        "apphud_analytics_conversion_trial_to_paid_local",
         "apphud_analytics_cohorts_retention",
+        "apphud_analytics_cohorts_retention_local",
         "apphud_analytics_cohorts_ltv",
+        "apphud_analytics_cohorts_ltv_local",
         "apphud_analytics_query_raw",
+        "apphud_analytics_query_raw_local",
+        "apphud_etl_local_status",
     ]),
     admin: new Set([
         "apphud_apps_list",
+        "apphud_apps_list_local",
+        "apphud_dashboard_local",
         "apphud_analytics_events_list",
+        "apphud_analytics_events_list_local",
         "apphud_analytics_active_subscriptions",
+        "apphud_analytics_active_subscriptions_local",
         "apphud_analytics_capabilities_get",
+        "apphud_analytics_capabilities_get_local",
         "apphud_analytics_metrics_list",
+        "apphud_analytics_metrics_list_local",
         "apphud_analytics_metric_value",
+        "apphud_analytics_metric_value_local",
         "apphud_analytics_metric_timeseries",
+        "apphud_analytics_metric_timeseries_local",
         "apphud_analytics_metric_breakdown",
+        "apphud_analytics_metric_breakdown_local",
         "apphud_analytics_revenue_summary",
+        "apphud_analytics_revenue_summary_local",
         "apphud_analytics_subscriptions_summary",
+        "apphud_analytics_subscriptions_summary_local",
         "apphud_analytics_conversion_trial_to_paid",
+        "apphud_analytics_conversion_trial_to_paid_local",
         "apphud_analytics_cohorts_retention",
+        "apphud_analytics_cohorts_retention_local",
         "apphud_analytics_cohorts_ltv",
+        "apphud_analytics_cohorts_ltv_local",
         "apphud_analytics_query_raw",
+        "apphud_analytics_query_raw_local",
+        "apphud_etl_local_status",
     ]),
 };
 export const METRIC_REVENUE_EVENT_TYPES = [