apphud-mcp 0.2.4 → 0.2.5

package/README.md

@@ -1,6 +1,6 @@
 # apphud-mcp <img src="./assets/apphud-mcp-logo.svg" alt="apphud + mcp" height="28" />
 
-MCP server for Apphud analytics with storage-based ETL ingestion (GCS/S3) and local SQLite query cache.
+MCP server for Apphud dashboard analytics endpoints (apps, events, metrics, cohorts).
 
 ## Quick Start
 
@@ -14,10 +14,7 @@ MCP server for Apphud analytics with storage-based ETL ingestion (GCS/S3) and lo
       "args": ["-y", "apphud-mcp@0.2.2", "start"],
       "env": {
         "login": "your@apphud.email",
-        "password": "your_apphud_password",
-        "ETL_SOURCE": "gcs",
-        "ETL_GCS_BUCKET": "your-bucket",
-        "ETL_GCS_PREFIX": "apphud/exports"
+        "password": "your_apphud_password"
       }
     }
   }
@@ -25,10 +22,30 @@ MCP server for Apphud analytics with storage-based ETL ingestion (GCS/S3) and lo
 ```
 
 2. Restart MCP server.
-3. Check ingestion:
-   - `apphud_etl_local_status`
-   - `apphud_apps_list_local`
-   - `apphud_dashboard_local`
+3. Check dashboard access:
+   - `apphud_apps_list`
+   - `apphud_analytics_events_list` (requires `from`/`to`)
+   - `apphud_analytics_metric_timeseries` (requires `metric_key`, `from`, `to`)
+
+## HTTP Tool Calls
+
+If `HTTP_ENABLED=true`, you can call tools over HTTP (stable payload path for web clients):
+
+```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"
+    }
+  }'
+```
+
+The endpoint also accepts `toolName` and stringified `arguments` JSON for compatibility with buggy wrappers.
 
 ## ETL Setup
 
@@ -83,11 +100,18 @@ MCP server for Apphud analytics with storage-based ETL ingestion (GCS/S3) and lo
 
 ## Useful Tools
 
-- `apphud_etl_local_status`
-- `apphud_dashboard_local`
-- `apphud_apps_list_local`
-- `apphud_analytics_*_local`
-- `apphud_analytics_*` (remote analytics endpoints)
+- `apphud_apps_list`
+- `apphud_analytics_events_list`
+- `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`
 
 ## Development
 

package/dist/src/cli.js

@@ -40,10 +40,10 @@ Zero-config quick 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

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;