apphud-mcp 0.2.2 → 0.2.5

package/README.md

@@ -1,20 +1,17 @@
 # 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 dashboard analytics endpoints (apps, events, metrics, cohorts).
 
 ## Quick Start
 
-1. Cursor MCP config (no extra config file required):
+1. Add MCP server:
 
 ```json
 {
   "mcpServers": {
     "apphud-mcp": {
-      "command": "node",
-      "args": [
-        "/Users/you/apphud-mcp/dist/src/cli.js",
-        "start"
-      ],
+      "command": "npx",
+      "args": ["-y", "apphud-mcp@0.2.2", "start"],
       "env": {
         "login": "your@apphud.email",
         "password": "your_apphud_password"
@@ -24,56 +21,87 @@ Zero-config MCP server for Apphud Dashboard Analytics with local SQLite storage.
 }
 ```
 
-2. Restart MCP server in Cursor.
+2. Restart MCP server.
+3. Check dashboard access:
+   - `apphud_apps_list`
+   - `apphud_analytics_events_list` (requires `from`/`to`)
+   - `apphud_analytics_metric_timeseries` (requires `metric_key`, `from`, `to`)
 
-3. Check local ETL status:
-   - `apphud_etl_local_status`
-   - `apphud_apps_list_local`
-   - `apphud_dashboard_local`
+## HTTP Tool Calls
 
-Optional config file (`apphud-mcp.config.json`) is only needed if you want custom paths or custom ETL polling.
+If `HTTP_ENABLED=true`, you can call tools over HTTP (stable payload path for web clients):
 
-## What Changed
-
-- 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
+```bash
+curl -sS -X POST http://localhost:8080/tools/call \
+  -H 'content-type: application/json' \
+  -d '{
+    "name":"apphud_analytics_metric_timeseries",
+    "arguments":{
+      "app_id":"your_app_id",
+      "metric_key":"revenue_gross",
+      "from":"2026-02-01T00:00:00.000Z",
+      "to":"2026-02-21T23:59:59.000Z"
+    }
+  }'
+```
 
-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`
+The endpoint also accepts `toolName` and stringified `arguments` JSON for compatibility with buggy wrappers.
+
+## 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
 
-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`

package/dist/src/cli.js

@@ -34,26 +34,32 @@ Usage:
   apphud-mcp start [--config <path>] [--config-json '<json>']
   apphud-mcp init-config [--out <path>] [--force]
 
-Zero-config quick start (ETL enabled by default):
+Zero-config quick start:
   1) Add MCP server using:
-     npx -y apphud-mcp@0.2.1 start
+     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
+  3) Use analytics tools:
+     apphud_apps_list
+     apphud_analytics_events_list
+     apphud_analytics_metric_timeseries
 
 Defaults:
   - SQLite DB: .apphud-mcp/apphud.db
   - ETL storage: .apphud-etl
   - Poll interval: 60 minutes
-  - Remote ETL fetch: enabled
+  - ETL worker enabled; source is none until you set GCS/S3
 
-Optional disable flags:
-  ETL_ENABLED=false
-  ETL_REMOTE_FETCH_ENABLED=false
+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,9 +232,6 @@ 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, true),
         etlTenantId,
@@ -244,7 +239,11 @@ export function loadEnvConfig(options = {}) {
         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, true),
+        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),
     };
@@ -262,7 +261,11 @@ export function buildExampleSimpleConfig() {
             storage_dir: ".apphud-etl",
             incoming_dir: ".apphud-etl/incoming",
             alerts_stale_hours: 30,
-            remote_fetch_enabled: true,
+            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/domain/constants.js

@@ -1,100 +1,23 @@
+const ANALYTICS_TOOL_PERMISSIONS = [
+    "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",
+];
 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",
-    ]),
+    analyst: new Set(ANALYTICS_TOOL_PERMISSIONS),
+    support: new Set(ANALYTICS_TOOL_PERMISSIONS),
+    admin: new Set(ANALYTICS_TOOL_PERMISSIONS),
 };
 export const METRIC_REVENUE_EVENT_TYPES = [
     "trial_converted",

package/dist/src/http/server.js

@@ -1,11 +1,59 @@
 import express from "express";
-import { toToolError } from "../errors/toolError.js";
+import { ApphudMcpError, isApphudMcpError, toToolError } from "../errors/toolError.js";
+import { executeRemoteTool, isRemoteToolName, REMOTE_TOOL_NAMES } from "../tools/remoteTools.js";
 function sendError(res, error) {
+    if (isApphudMcpError(error)) {
+        res.status(error.statusCode).json(toToolError(error));
+        return;
+    }
     res.status(500).json(toToolError(error));
 }
+export function normalizeToolCallPayload(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        throw new ApphudMcpError("INVALID_PAYLOAD", "Request body must be an object", { statusCode: 400 });
+    }
+    const body = payload;
+    const params = body.params;
+    const jsonRpcParams = params && typeof params === "object" && !Array.isArray(params) ? params : undefined;
+    const toolNameRaw = body.name ??
+        body.tool ??
+        body.toolName ??
+        jsonRpcParams?.name ??
+        jsonRpcParams?.tool ??
+        jsonRpcParams?.toolName;
+    if (typeof toolNameRaw !== "string" || toolNameRaw.trim().length === 0) {
+        throw new ApphudMcpError("INVALID_PAYLOAD", "tool name is required (name or toolName)", { statusCode: 400 });
+    }
+    const inputRaw = body.arguments ??
+        body.payload ??
+        body.input ??
+        jsonRpcParams?.arguments ??
+        jsonRpcParams?.payload ??
+        jsonRpcParams?.input;
+    if (inputRaw === undefined || inputRaw === null) {
+        return { toolName: toolNameRaw.trim(), input: {} };
+    }
+    if (typeof inputRaw === "string") {
+        try {
+            const parsed = JSON.parse(inputRaw);
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                throw new Error("arguments string must decode to object");
+            }
+            return { toolName: toolNameRaw.trim(), input: parsed };
+        }
+        catch {
+            throw new ApphudMcpError("INVALID_PAYLOAD", "arguments string must be valid JSON object", { statusCode: 400 });
+        }
+    }
+    if (!inputRaw || typeof inputRaw !== "object" || Array.isArray(inputRaw)) {
+        throw new ApphudMcpError("INVALID_PAYLOAD", "arguments must be an object", { statusCode: 400 });
+    }
+    return { toolName: toolNameRaw.trim(), input: inputRaw };
+}
 export function createHttpServer(container) {
     const app = express();
     app.disable("x-powered-by");
+    app.use(express.json({ limit: "1mb" }));
     app.get("/health", async (_req, res) => {
         res.status(200).json({ status: "ok" });
     });
@@ -17,7 +65,39 @@ export function createHttpServer(container) {
             timestamp: new Date().toISOString(),
         });
     });
+    async function handleToolCall(req, res) {
+        try {
+            const { toolName, input } = normalizeToolCallPayload(req.body);
+            if (!isRemoteToolName(toolName)) {
+                throw new ApphudMcpError("TOOL_NOT_FOUND", `Unsupported tool: ${toolName}`, {
+                    statusCode: 404,
+                    details: { supported_tools: REMOTE_TOOL_NAMES },
+                });
+            }
+            const result = await executeRemoteTool(container, toolName, input);
+            res.status(200).json({
+                ok: true,
+                tool: toolName,
+                result,
+            });
+        }
+        catch (error) {
+            sendError(res, error);
+        }
+    }
+    app.post("/tools/call", (req, res) => {
+        void handleToolCall(req, res);
+    });
+    app.post("/api/tools/call", (req, res) => {
+        void handleToolCall(req, res);
+    });
     app.use((error, _req, res, _next) => {
+        if (error instanceof SyntaxError) {
+            sendError(res, new ApphudMcpError("INVALID_PAYLOAD", "Invalid JSON body", {
+                statusCode: 400,
+            }));
+            return;
+        }
         sendError(res, error);
     });
     return app;