apphud-mcp 0.2.2 → 0.2.5

package/dist/src/tools/remoteTools.js

@@ -0,0 +1,398 @@
+import { z } from "zod";
+import { ApphudMcpError } from "../errors/toolError.js";
+import { resolveAuth } from "../security/authResolver.js";
+const authSchema = z
+    .object({
+    tenant_id: z.string().min(1),
+    role: z.enum(["analyst", "support", "admin"]),
+    actor_id: z.string().min(1).optional(),
+})
+    .optional();
+const analyticsPlatformSchema = z.enum(["ios", "android", "web"]);
+const analyticsFiltersSchema = z
+    .record(z.union([z.string(), z.number(), z.boolean(), z.null()]))
+    .optional();
+const analyticsEventsFiltersSchema = z
+    .object({
+    user_id: z.string().min(1).optional(),
+    product_id: z.string().min(1).optional(),
+    event_type: z.string().min(1).optional(),
+    country: z.string().min(1).optional(),
+    platform: analyticsPlatformSchema.optional(),
+})
+    .optional();
+const baseInputShape = {
+    tenant_id: z.string().optional(),
+    auth: authSchema,
+};
+export const REMOTE_TOOL_NAMES = [
+    "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",
+];
+const REMOTE_TOOL_NAME_SET = new Set(REMOTE_TOOL_NAMES);
+function appIdFromInput(input) {
+    const appId = typeof input.app_id === "string" ? input.app_id.trim() : "";
+    const apphudAppId = typeof input.apphud_app_id === "string" ? input.apphud_app_id.trim() : "";
+    return appId || apphudAppId || undefined;
+}
+const REMOTE_TOOL_DEFINITIONS = {
+    apphud_apps_list: {
+        description: "List apps available in authenticated Apphud dashboard account",
+        inputShape: {
+            ...baseInputShape,
+            include_raw: z.boolean().optional(),
+        },
+        execute: async (container, auth, input) => container.analyticsService.appsList(auth, {
+            include_raw: input.include_raw,
+        }),
+    },
+    apphud_analytics_events_list: {
+        description: "List raw subscription events from Apphud dashboard event feed",
+        inputShape: {
+            ...baseInputShape,
+            app_id: z.string().min(1).optional(),
+            apphud_app_id: z.string().min(1).optional(),
+            from: z.string().datetime(),
+            to: z.string().datetime(),
+            limit: z.number().int().min(1).max(500).optional(),
+            cursor: z.string().min(1).optional(),
+            filters: analyticsEventsFiltersSchema,
+            include_raw: z.boolean().optional(),
+        },
+        appIdSelector: appIdFromInput,
+        execute: async (container, auth, input) => container.analyticsService.eventsList(auth, {
+            app_id: input.app_id,
+            apphud_app_id: input.apphud_app_id,
+            from: input.from,
+            to: input.to,
+            limit: input.limit,
+            cursor: input.cursor,
+            filters: input.filters,
+            include_raw: input.include_raw,
+        }),
+    },
+    apphud_analytics_active_subscriptions: {
+        description: "Fetch active paid subscriptions directly from Apphud analytics endpoint",
+        inputShape: {
+            ...baseInputShape,
+            app_id: z.string().min(1).optional(),
+            apphud_app_id: z.string().min(1).optional(),
+            platform: analyticsPlatformSchema.optional(),
+            include_raw: z.boolean().optional(),
+        },
+        appIdSelector: appIdFromInput,
+        execute: async (container, auth, input) => container.analyticsService.activeSubscriptions(auth, {
+            app_id: input.app_id,
+            apphud_app_id: input.apphud_app_id,
+            platform: input.platform,
+            include_raw: input.include_raw,
+        }),
+    },
+    apphud_analytics_capabilities_get: {
+        description: "Get analytics capabilities and available metrics",
+        inputShape: {
+            ...baseInputShape,
+            app_id: z.string().min(1).optional(),
+            apphud_app_id: z.string().min(1).optional(),
+            include_raw: z.boolean().optional(),
+        },
+        appIdSelector: appIdFromInput,
+        execute: async (container, auth, input) => container.analyticsService.capabilities(auth, {
+            app_id: input.app_id,
+            apphud_app_id: input.apphud_app_id,
+            include_raw: input.include_raw,
+        }),
+    },
+    apphud_analytics_metrics_list: {
+        description: "List analytics metric keys",
+        inputShape: {
+            ...baseInputShape,
+            app_id: z.string().min(1).optional(),
+            apphud_app_id: z.string().min(1).optional(),
+            include_raw: z.boolean().optional(),
+        },
+        appIdSelector: appIdFromInput,
+        execute: async (container, auth, input) => container.analyticsService.metricsList(auth, {
+            app_id: input.app_id,
+            apphud_app_id: input.apphud_app_id,
+            include_raw: input.include_raw,
+        }),
+    },
+    apphud_analytics_metric_value: {
+        description: "Get single metric value for period/snapshot",
+        inputShape: {
+            ...baseInputShape,
+            app_id: z.string().min(1).optional(),
+            apphud_app_id: z.string().min(1).optional(),
+            metric_key: z.string().min(1),
+            from: z.string().datetime().optional(),
+            to: z.string().datetime().optional(),
+            platform: analyticsPlatformSchema.optional(),
+            filters: analyticsFiltersSchema,
+            include_raw: z.boolean().optional(),
+        },
+        appIdSelector: appIdFromInput,
+        execute: async (container, auth, input) => container.analyticsService.metricValue(auth, {
+            app_id: input.app_id,
+            apphud_app_id: input.apphud_app_id,
+            metric_key: input.metric_key,
+            from: input.from,
+            to: input.to,
+            platform: input.platform,
+            filters: input.filters,
+            include_raw: input.include_raw,
+        }),
+    },
+    apphud_analytics_metric_timeseries: {
+        description: "Get metric timeseries by date range",
+        inputShape: {
+            ...baseInputShape,
+            app_id: z.string().min(1).optional(),
+            apphud_app_id: z.string().min(1).optional(),
+            metric_key: z.string().min(1),
+            from: z.string().datetime(),
+            to: z.string().datetime(),
+            granularity: z.enum(["day", "week"]).optional(),
+            platform: analyticsPlatformSchema.optional(),
+            filters: analyticsFiltersSchema,
+            include_raw: z.boolean().optional(),
+        },
+        appIdSelector: appIdFromInput,
+        execute: async (container, auth, input) => container.analyticsService.metricTimeseries(auth, {
+            app_id: input.app_id,
+            apphud_app_id: input.apphud_app_id,
+            metric_key: input.metric_key,
+            from: input.from,
+            to: input.to,
+            granularity: input.granularity,
+            platform: input.platform,
+            filters: input.filters,
+            include_raw: input.include_raw,
+        }),
+    },
+    apphud_analytics_metric_breakdown: {
+        description: "Get metric breakdown by dimension",
+        inputShape: {
+            ...baseInputShape,
+            app_id: z.string().min(1).optional(),
+            apphud_app_id: z.string().min(1).optional(),
+            metric_key: z.string().min(1),
+            from: z.string().datetime(),
+            to: z.string().datetime(),
+            dimension: z.string().min(1),
+            granularity: z.enum(["day", "week"]).optional(),
+            platform: analyticsPlatformSchema.optional(),
+            filters: analyticsFiltersSchema,
+            limit: z.number().int().min(1).max(200).optional(),
+            include_raw: z.boolean().optional(),
+        },
+        appIdSelector: appIdFromInput,
+        execute: async (container, auth, input) => container.analyticsService.metricBreakdown(auth, {
+            app_id: input.app_id,
+            apphud_app_id: input.apphud_app_id,
+            metric_key: input.metric_key,
+            from: input.from,
+            to: input.to,
+            dimension: input.dimension,
+            granularity: input.granularity,
+            platform: input.platform,
+            filters: input.filters,
+            limit: input.limit,
+            include_raw: input.include_raw,
+        }),
+    },
+    apphud_analytics_revenue_summary: {
+        description: "Get revenue summary for date range",
+        inputShape: {
+            ...baseInputShape,
+            app_id: z.string().min(1).optional(),
+            apphud_app_id: z.string().min(1).optional(),
+            from: z.string().datetime(),
+            to: z.string().datetime(),
+            platform: analyticsPlatformSchema.optional(),
+            filters: analyticsFiltersSchema,
+            compare_prev_period: z.boolean().optional(),
+            include_raw: z.boolean().optional(),
+        },
+        appIdSelector: appIdFromInput,
+        execute: async (container, auth, input) => container.analyticsService.revenueSummary(auth, {
+            app_id: input.app_id,
+            apphud_app_id: input.apphud_app_id,
+            from: input.from,
+            to: input.to,
+            platform: input.platform,
+            filters: input.filters,
+            compare_prev_period: input.compare_prev_period,
+            include_raw: input.include_raw,
+        }),
+    },
+    apphud_analytics_subscriptions_summary: {
+        description: "Get subscriptions KPI summary",
+        inputShape: {
+            ...baseInputShape,
+            app_id: z.string().min(1).optional(),
+            apphud_app_id: z.string().min(1).optional(),
+            from: z.string().datetime().optional(),
+            to: z.string().datetime().optional(),
+            platform: analyticsPlatformSchema.optional(),
+            filters: analyticsFiltersSchema,
+            include_raw: z.boolean().optional(),
+        },
+        appIdSelector: appIdFromInput,
+        execute: async (container, auth, input) => container.analyticsService.subscriptionsSummary(auth, {
+            app_id: input.app_id,
+            apphud_app_id: input.apphud_app_id,
+            from: input.from,
+            to: input.to,
+            platform: input.platform,
+            filters: input.filters,
+            include_raw: input.include_raw,
+        }),
+    },
+    apphud_analytics_conversion_trial_to_paid: {
+        description: "Get trial to paid conversion summary",
+        inputShape: {
+            ...baseInputShape,
+            app_id: z.string().min(1).optional(),
+            apphud_app_id: z.string().min(1).optional(),
+            from: z.string().datetime(),
+            to: z.string().datetime(),
+            platform: analyticsPlatformSchema.optional(),
+            filters: analyticsFiltersSchema,
+            include_raw: z.boolean().optional(),
+        },
+        appIdSelector: appIdFromInput,
+        execute: async (container, auth, input) => container.analyticsService.conversionTrialToPaid(auth, {
+            app_id: input.app_id,
+            apphud_app_id: input.apphud_app_id,
+            from: input.from,
+            to: input.to,
+            platform: input.platform,
+            filters: input.filters,
+            include_raw: input.include_raw,
+        }),
+    },
+    apphud_analytics_cohorts_retention: {
+        description: "Get cohorts retention from analytics",
+        inputShape: {
+            ...baseInputShape,
+            app_id: z.string().min(1).optional(),
+            apphud_app_id: z.string().min(1).optional(),
+            from: z.string().datetime(),
+            to: z.string().datetime(),
+            granularity: z.enum(["day", "week"]).optional(),
+            max_periods: z.number().int().min(1).max(104).optional(),
+            platform: analyticsPlatformSchema.optional(),
+            filters: analyticsFiltersSchema,
+            include_raw: z.boolean().optional(),
+        },
+        appIdSelector: appIdFromInput,
+        execute: async (container, auth, input) => container.analyticsService.cohortsRetention(auth, {
+            app_id: input.app_id,
+            apphud_app_id: input.apphud_app_id,
+            from: input.from,
+            to: input.to,
+            granularity: input.granularity,
+            max_periods: input.max_periods,
+            platform: input.platform,
+            filters: input.filters,
+            include_raw: input.include_raw,
+        }),
+    },
+    apphud_analytics_cohorts_ltv: {
+        description: "Get cohorts cumulative LTV from analytics",
+        inputShape: {
+            ...baseInputShape,
+            app_id: z.string().min(1).optional(),
+            apphud_app_id: z.string().min(1).optional(),
+            from: z.string().datetime(),
+            to: z.string().datetime(),
+            granularity: z.enum(["day", "week"]).optional(),
+            max_periods: z.number().int().min(1).max(104).optional(),
+            platform: analyticsPlatformSchema.optional(),
+            filters: analyticsFiltersSchema,
+            include_raw: z.boolean().optional(),
+        },
+        appIdSelector: appIdFromInput,
+        execute: async (container, auth, input) => container.analyticsService.cohortsLtv(auth, {
+            app_id: input.app_id,
+            apphud_app_id: input.apphud_app_id,
+            from: input.from,
+            to: input.to,
+            granularity: input.granularity,
+            max_periods: input.max_periods,
+            platform: input.platform,
+            filters: input.filters,
+            include_raw: input.include_raw,
+        }),
+    },
+    apphud_analytics_query_raw: {
+        description: "Low-level analytics query tool (value/timeseries/breakdown/raw)",
+        inputShape: {
+            ...baseInputShape,
+            app_id: z.string().min(1).optional(),
+            apphud_app_id: z.string().min(1).optional(),
+            query: z.object({
+                shape: z.enum(["value", "timeseries", "breakdown", "raw"]),
+                metric_key: z.string().optional(),
+                from: z.string().datetime().optional(),
+                to: z.string().datetime().optional(),
+                granularity: z.enum(["day", "week"]).optional(),
+                dimension: z.string().optional(),
+                endpoint_path: z.string().optional(),
+                method: z.enum(["GET", "POST"]).optional(),
+                query_params: z.record(z.string()).optional(),
+                body: z.record(z.unknown()).optional(),
+                filters: analyticsFiltersSchema,
+                platform: analyticsPlatformSchema.optional(),
+                limit: z.number().int().min(1).max(500).optional(),
+            }),
+            include_raw: z.boolean().optional(),
+        },
+        appIdSelector: appIdFromInput,
+        execute: async (container, auth, input) => container.analyticsService.queryRaw(auth, {
+            app_id: input.app_id,
+            apphud_app_id: input.apphud_app_id,
+            query: input.query,
+            include_raw: input.include_raw,
+        }),
+    },
+};
+export function getRemoteToolEntries() {
+    return Object.entries(REMOTE_TOOL_DEFINITIONS);
+}
+export function isRemoteToolName(toolName) {
+    return REMOTE_TOOL_NAME_SET.has(toolName);
+}
+export async function executeRemoteTool(container, toolName, rawInput) {
+    const definition = REMOTE_TOOL_DEFINITIONS[toolName];
+    const parseResult = z.object(definition.inputShape).safeParse(rawInput ?? {});
+    if (!parseResult.success) {
+        throw new ApphudMcpError("INVALID_PAYLOAD", "Tool input validation failed", {
+            statusCode: 400,
+            details: {
+                tool_name: toolName,
+                issues: parseResult.error.issues.map((issue) => ({
+                    path: issue.path.join("."),
+                    message: issue.message,
+                })),
+            },
+        });
+    }
+    const input = parseResult.data;
+    const auth = resolveAuth(input, container.config);
+    const appId = definition.appIdSelector?.(input);
+    return container.toolGuard.run(auth, toolName, async () => definition.execute(container, auth, input), appId ? { appId } : undefined);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apphud-mcp",
-  "version": "0.2.2",
+  "version": "0.2.5",
   "type": "module",
   "description": "MCP server for Apphud dashboard analytics",
   "license": "MIT",