apphud-mcp 0.2.5 → 0.2.6

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 dashboard analytics endpoints (apps, events, metrics, cohorts).
+MCP server for Apphud dashboard analytics endpoints and Product Hub mutations (paywalls, placements, items).
 
 ## Quick Start
 
@@ -101,6 +101,12 @@ The endpoint also accepts `toolName` and stringified `arguments` JSON for compat
 ## Useful Tools
 
 - `apphud_apps_list`
+- `apphud_paywall_item_add`
+- `apphud_placement_item_set_enabled`
+- `apphud_paywall_item_delete`
+- `apphud_placement_item_delete`
+- `apphud_placement_delete`
+- `apphud_paywall_config_delete`
 - `apphud_analytics_events_list`
 - `apphud_analytics_metrics_list`
 - `apphud_analytics_metric_value`

package/dist/src/domain/constants.js

@@ -14,10 +14,18 @@ const ANALYTICS_TOOL_PERMISSIONS = [
     "apphud_analytics_cohorts_ltv",
     "apphud_analytics_query_raw",
 ];
+const PRODUCT_HUB_MUTATION_TOOL_PERMISSIONS = [
+    "apphud_paywall_item_add",
+    "apphud_placement_item_set_enabled",
+    "apphud_paywall_item_delete",
+    "apphud_placement_item_delete",
+    "apphud_placement_delete",
+    "apphud_paywall_config_delete",
+];
 export const TOOL_PERMISSIONS = {
     analyst: new Set(ANALYTICS_TOOL_PERMISSIONS),
     support: new Set(ANALYTICS_TOOL_PERMISSIONS),
-    admin: new Set(ANALYTICS_TOOL_PERMISSIONS),
+    admin: new Set([...ANALYTICS_TOOL_PERMISSIONS, ...PRODUCT_HUB_MUTATION_TOOL_PERMISSIONS]),
 };
 export const METRIC_REVENUE_EVENT_TYPES = [
     "trial_converted",

package/dist/src/http/server.js

@@ -60,7 +60,7 @@ export function createHttpServer(container) {
     app.get("/status", async (_req, res) => {
         res.status(200).json({
             status: "ok",
-            mode: "analytics_only",
+            mode: "analytics_and_product_hub",
             node_env: container.config.nodeEnv,
             timestamp: new Date().toISOString(),
         });

package/dist/src/mcp/server.js

@@ -11,7 +11,7 @@ function jsonResult(payload, isError = false) {
 export function createMcpServer(container) {
     const server = new McpServer({
         name: "apphud-mcp",
-        version: "0.2.4",
+        version: "0.2.6",
     });
     for (const [toolName, definition] of getRemoteToolEntries()) {
         server.tool(toolName, definition.description, definition.inputShape, async (input) => {

package/dist/src/services/analyticsService.js

@@ -975,6 +975,131 @@ export class AnalyticsService {
             response: this.selectRawPayload(auth, true, raw.payload),
         };
     }
+    async paywallItemAdd(auth, input) {
+        const app = await this.resolveApp(auth, input.app_id, input.apphud_app_id);
+        this.assertRawAccess(auth, input.include_raw);
+        const created = await this.apphudClient.createPaywallItem(app, {
+            apphudAppId: input.apphud_app_id,
+            paywallConfigId: input.paywall_config_id,
+            productBundleId: input.product_bundle_id,
+        });
+        return {
+            app_id: app.appId,
+            apphud_app_id: created.apphudAppId,
+            paywall_config_id: created.paywallConfigId,
+            product_bundle_id: input.product_bundle_id,
+            source: "apphud_dashboard_api",
+            source_used: created.sourcePath,
+            status: created.status,
+            item: created.item,
+            created: true,
+            retrieved_at: new Date().toISOString(),
+            raw_payload: this.selectRawPayload(auth, input.include_raw, created.payload),
+        };
+    }
+    async placementItemSetEnabled(auth, input) {
+        const app = await this.resolveApp(auth, input.app_id, input.apphud_app_id);
+        this.assertRawAccess(auth, input.include_raw);
+        const updated = await this.apphudClient.setPlacementItemEnabled(app, {
+            apphudAppId: input.apphud_app_id,
+            placementId: input.placement_id,
+            placementItemId: input.placement_item_id,
+            paywallConfigId: input.paywall_config_id,
+            enabled: input.enabled,
+        });
+        return {
+            app_id: app.appId,
+            apphud_app_id: updated.apphudAppId,
+            placement_id: updated.placementId,
+            placement_item_id: updated.placementItemId,
+            enabled: input.enabled,
+            state: input.enabled ? "active" : "disabled",
+            source: "apphud_dashboard_api",
+            source_used: updated.sourcePath,
+            status: updated.status,
+            item: updated.item,
+            updated: true,
+            retrieved_at: new Date().toISOString(),
+            raw_payload: this.selectRawPayload(auth, input.include_raw, updated.payload),
+        };
+    }
+    async paywallItemDelete(auth, input) {
+        const app = await this.resolveApp(auth, input.app_id, input.apphud_app_id);
+        this.assertRawAccess(auth, input.include_raw);
+        const result = await this.apphudClient.deletePaywallItem(app, {
+            paywallItemId: input.paywall_item_id,
+        });
+        return {
+            app_id: app.appId,
+            apphud_app_id: input.apphud_app_id ?? app.appId,
+            paywall_item_id: result.paywallItemId,
+            deleted: true,
+            source: "apphud_dashboard_api",
+            source_used: result.sourcePath,
+            status: result.status,
+            retrieved_at: new Date().toISOString(),
+            raw_payload: this.selectRawPayload(auth, input.include_raw, result.payload),
+        };
+    }
+    async placementItemDelete(auth, input) {
+        const app = await this.resolveApp(auth, input.app_id, input.apphud_app_id);
+        this.assertRawAccess(auth, input.include_raw);
+        const result = await this.apphudClient.deletePlacementItem(app, {
+            apphudAppId: input.apphud_app_id,
+            placementId: input.placement_id,
+            placementItemId: input.placement_item_id,
+        });
+        return {
+            app_id: app.appId,
+            apphud_app_id: result.apphudAppId,
+            placement_id: result.placementId,
+            placement_item_id: result.placementItemId,
+            deleted: true,
+            source: "apphud_dashboard_api",
+            source_used: result.sourcePath,
+            status: result.status,
+            retrieved_at: new Date().toISOString(),
+            raw_payload: this.selectRawPayload(auth, input.include_raw, result.payload),
+        };
+    }
+    async placementDelete(auth, input) {
+        const app = await this.resolveApp(auth, input.app_id, input.apphud_app_id);
+        this.assertRawAccess(auth, input.include_raw);
+        const result = await this.apphudClient.deletePlacement(app, {
+            apphudAppId: input.apphud_app_id,
+            placementId: input.placement_id,
+        });
+        return {
+            app_id: app.appId,
+            apphud_app_id: result.apphudAppId,
+            placement_id: result.placementId,
+            deleted: true,
+            source: "apphud_dashboard_api",
+            source_used: result.sourcePath,
+            status: result.status,
+            retrieved_at: new Date().toISOString(),
+            raw_payload: this.selectRawPayload(auth, input.include_raw, result.payload),
+        };
+    }
+    async paywallConfigDelete(auth, input) {
+        const app = await this.resolveApp(auth, input.app_id, input.apphud_app_id);
+        this.assertRawAccess(auth, input.include_raw);
+        const result = await this.apphudClient.deletePaywallConfig(app, {
+            apphudAppId: input.apphud_app_id,
+            paywallConfigId: input.paywall_config_id,
+        });
+        return {
+            app_id: app.appId,
+            apphud_app_id: result.apphudAppId,
+            paywall_config_id: result.paywallConfigId,
+            deleted: true,
+            source: "apphud_dashboard_api",
+            source_used: result.sourcePath,
+            status: result.status,
+            retrieved_at: new Date().toISOString(),
+            raw_payload: this.selectRawPayload(auth, input.include_raw, result.payload),
+        };
+    }
     async resolveApp(auth, appId, apphudAppId) {
         const explicitAppId = appId?.trim() || apphudAppId?.trim();
         if (explicitAppId) {

package/dist/src/services/apphudClient.js

@@ -122,6 +122,31 @@ function asArray(value) {
     }
     return value.filter((item) => !!item && typeof item === "object");
 }
+function extractFirstRecord(value) {
+    const root = asRecord(value);
+    const data = asRecord(root.data);
+    const directCandidates = [data.results, data.result, root.results, root.result];
+    for (const candidate of directCandidates) {
+        const record = asRecord(candidate);
+        if (Object.keys(record).length > 0) {
+            return record;
+        }
+    }
+    const listCandidates = [data.results, data.items, root.results, root.items];
+    for (const candidate of listCandidates) {
+        const rows = asArray(candidate);
+        if (rows.length > 0) {
+            return rows[0];
+        }
+    }
+    if (Object.keys(data).length > 0) {
+        return data;
+    }
+    if (Object.keys(root).length > 0) {
+        return root;
+    }
+    return undefined;
+}
 function readStringValue(value) {
     if (typeof value === "string" && value.trim().length > 0) {
         return value.trim();
@@ -1787,6 +1812,219 @@ export class ApphudClient {
             status: response.status,
         };
     }
+    async createPaywallItem(app, options) {
+        const apphudAppId = options.apphudAppId ?? app.appId;
+        const paywallConfigId = encodeURIComponent(options.paywallConfigId);
+        const encodedAppId = encodeURIComponent(apphudAppId);
+        const body = {
+            product_bundle_id: options.productBundleId,
+        };
+        const result = await this.requestAnalyticsWithFallback(app, [
+            {
+                path: `/paywall_configs/${paywallConfigId}/paywall_items`,
+                method: "POST",
+                body,
+            },
+            {
+                path: `/api/v1/paywall_configs/${paywallConfigId}/paywall_items`,
+                method: "POST",
+                body,
+            },
+            {
+                path: `/apps/${encodedAppId}/paywall_configs/${paywallConfigId}/paywall_items`,
+                method: "POST",
+                body,
+            },
+        ], "create paywall item");
+        return {
+            apphudAppId,
+            paywallConfigId: options.paywallConfigId,
+            sourcePath: result.sourcePath,
+            status: result.status,
+            payload: result.payload,
+            item: extractFirstRecord(result.payload),
+        };
+    }
+    async setPlacementItemEnabled(app, options) {
+        const apphudAppId = options.apphudAppId ?? app.appId;
+        const encodedAppId = encodeURIComponent(apphudAppId);
+        const placementId = encodeURIComponent(options.placementId);
+        const placementItemId = encodeURIComponent(options.placementItemId);
+        const body = {
+            active: options.enabled,
+        };
+        if (options.paywallConfigId && options.paywallConfigId.trim().length > 0) {
+            body.paywall_config_id = options.paywallConfigId;
+        }
+        const result = await this.requestAnalyticsWithFallback(app, [
+            {
+                path: `/apps/${encodedAppId}/placements/${placementId}/items/${placementItemId}`,
+                method: "PUT",
+                body,
+            },
+            {
+                path: `/api/v1/apps/${encodedAppId}/placements/${placementId}/items/${placementItemId}`,
+                method: "PUT",
+                body,
+            },
+            {
+                path: `/placements/${placementId}/items/${placementItemId}`,
+                method: "PUT",
+                body,
+            },
+        ], "update placement item state");
+        return {
+            apphudAppId,
+            placementId: options.placementId,
+            placementItemId: options.placementItemId,
+            sourcePath: result.sourcePath,
+            status: result.status,
+            payload: result.payload,
+            item: extractFirstRecord(result.payload),
+        };
+    }
+    async deletePaywallItem(app, options) {
+        const paywallItemId = encodeURIComponent(options.paywallItemId);
+        const result = await this.requestAnalyticsWithFallback(app, [
+            {
+                path: `/paywall_items/${paywallItemId}`,
+                method: "DELETE",
+            },
+            {
+                path: `/api/v1/paywall_items/${paywallItemId}`,
+                method: "DELETE",
+            },
+        ], "delete paywall item");
+        return {
+            paywallItemId: options.paywallItemId,
+            sourcePath: result.sourcePath,
+            status: result.status,
+            payload: result.payload,
+        };
+    }
+    async deletePlacementItem(app, options) {
+        const apphudAppId = options.apphudAppId ?? app.appId;
+        const encodedAppId = encodeURIComponent(apphudAppId);
+        const placementId = encodeURIComponent(options.placementId);
+        const placementItemId = encodeURIComponent(options.placementItemId);
+        const result = await this.requestAnalyticsWithFallback(app, [
+            {
+                path: `/apps/${encodedAppId}/placements/${placementId}/items/${placementItemId}`,
+                method: "DELETE",
+            },
+            {
+                path: `/api/v1/apps/${encodedAppId}/placements/${placementId}/items/${placementItemId}`,
+                method: "DELETE",
+            },
+        ], "delete placement item");
+        return {
+            apphudAppId,
+            placementId: options.placementId,
+            placementItemId: options.placementItemId,
+            sourcePath: result.sourcePath,
+            status: result.status,
+            payload: result.payload,
+        };
+    }
+    async deletePlacement(app, options) {
+        const apphudAppId = options.apphudAppId ?? app.appId;
+        const encodedAppId = encodeURIComponent(apphudAppId);
+        const placementId = encodeURIComponent(options.placementId);
+        const result = await this.requestAnalyticsWithFallback(app, [
+            {
+                path: `/apps/${encodedAppId}/placements/${placementId}`,
+                method: "DELETE",
+            },
+            {
+                path: `/api/v1/apps/${encodedAppId}/placements/${placementId}`,
+                method: "DELETE",
+            },
+            {
+                path: `/placements/${placementId}`,
+                method: "DELETE",
+            },
+        ], "delete placement");
+        return {
+            apphudAppId,
+            placementId: options.placementId,
+            sourcePath: result.sourcePath,
+            status: result.status,
+            payload: result.payload,
+        };
+    }
+    async deletePaywallConfig(app, options) {
+        const apphudAppId = options.apphudAppId ?? app.appId;
+        const encodedAppId = encodeURIComponent(apphudAppId);
+        const paywallConfigId = encodeURIComponent(options.paywallConfigId);
+        const result = await this.requestAnalyticsWithFallback(app, [
+            {
+                path: `/paywall_configs/${paywallConfigId}`,
+                method: "DELETE",
+            },
+            {
+                path: `/api/v1/paywall_configs/${paywallConfigId}`,
+                method: "DELETE",
+            },
+            {
+                path: `/apps/${encodedAppId}/paywall_configs/${paywallConfigId}`,
+                method: "DELETE",
+            },
+        ], "delete paywall config");
+        return {
+            apphudAppId,
+            paywallConfigId: options.paywallConfigId,
+            sourcePath: result.sourcePath,
+            status: result.status,
+            payload: result.payload,
+        };
+    }
+    async requestAnalyticsWithFallback(app, attempts, operation) {
+        let lastError;
+        for (const attempt of attempts) {
+            try {
+                const response = await this.requestAnalytics({
+                    app,
+                    path: attempt.path,
+                    method: attempt.method,
+                    query: attempt.query,
+                    body: attempt.body,
+                });
+                return {
+                    status: response.status,
+                    payload: response.payload,
+                    sourcePath: attempt.path,
+                };
+            }
+            catch (error) {
+                if (!shouldTryNextAnalyticsCandidate(error)) {
+                    throw error;
+                }
+                lastError = error;
+            }
+        }
+        if (lastError && isApphudMcpError(lastError)) {
+            const status = getAnalyticsStatusFromError(lastError);
+            if (status === 404 || status === 405) {
+                throw new ApphudMcpError("APPHUD_ANALYTICS_API_UNAVAILABLE", `Cannot ${operation}: endpoint is unavailable for this Apphud profile`, {
+                    statusCode: 403,
+                    actionHint: "Check Apphud dashboard permissions and endpoint availability for current account profile",
+                    details: {
+                        status,
+                        attempted_paths: attempts.map((attempt) => `${attempt.method} ${attempt.path}`),
+                    },
+                });
+            }
+        }
+        if (lastError) {
+            throw lastError;
+        }
+        throw new ApphudMcpError("UPSTREAM_ERROR", `Cannot ${operation}: no endpoint attempts configured`, {
+            statusCode: 502,
+            details: {
+                attempted_paths: attempts.map((attempt) => `${attempt.method} ${attempt.path}`),
+            },
+        });
+    }
     async requestAnalytics(input) {
         const baseUrl = this.config.apphudAnalyticsApiBaseUrl.replace(/\/$/, "");
         const cleanPath = this.normalizeAnalyticsPath(input.path);
@@ -1800,7 +2038,7 @@ export class ApphudClient {
         }
         const headers = new Headers();
         headers.set("Accept", "application/json");
-        if (input.method !== "GET") {
+        if (input.method === "POST" || input.method === "PUT") {
             headers.set("Content-Type", "application/json");
         }
         const analyticsSecretRef = this.config.apphudAnalyticsAuthSecretRef ??
@@ -1909,10 +2147,11 @@ export class ApphudClient {
     async executeAnalyticsHttpRequest(url, method, headers, body, endpoint) {
         let response;
         try {
+            const hasBody = method === "POST" || method === "PUT" || (method === "DELETE" && body !== undefined && Object.keys(body).length > 0);
             response = await fetch(url, {
                 method,
                 headers,
-                body: method === "GET" ? undefined : JSON.stringify(body ?? {}),
+                body: hasBody ? JSON.stringify(body ?? {}) : undefined,
                 signal: AbortSignal.timeout(10_000),
             });
         }

package/dist/src/tools/remoteTools.js

@@ -27,6 +27,12 @@ const baseInputShape = {
 };
 export const REMOTE_TOOL_NAMES = [
     "apphud_apps_list",
+    "apphud_paywall_item_add",
+    "apphud_placement_item_set_enabled",
+    "apphud_paywall_item_delete",
+    "apphud_placement_item_delete",
+    "apphud_placement_delete",
+    "apphud_paywall_config_delete",
     "apphud_analytics_events_list",
     "apphud_analytics_active_subscriptions",
     "apphud_analytics_capabilities_get",
@@ -58,6 +64,118 @@ const REMOTE_TOOL_DEFINITIONS = {
             include_raw: input.include_raw,
         }),
     },
+    apphud_paywall_item_add: {
+        description: "Add product to paywall config (creates paywall item)",
+        inputShape: {
+            ...baseInputShape,
+            app_id: z.string().min(1).optional(),
+            apphud_app_id: z.string().min(1).optional(),
+            paywall_config_id: z.string().min(1),
+            product_bundle_id: z.string().min(1),
+            include_raw: z.boolean().optional(),
+        },
+        appIdSelector: appIdFromInput,
+        execute: async (container, auth, input) => container.analyticsService.paywallItemAdd(auth, {
+            app_id: input.app_id,
+            apphud_app_id: input.apphud_app_id,
+            paywall_config_id: input.paywall_config_id,
+            product_bundle_id: input.product_bundle_id,
+            include_raw: input.include_raw,
+        }),
+    },
+    apphud_placement_item_set_enabled: {
+        description: "Enable/disable placement item state",
+        inputShape: {
+            ...baseInputShape,
+            app_id: z.string().min(1).optional(),
+            apphud_app_id: z.string().min(1).optional(),
+            placement_id: z.string().min(1),
+            placement_item_id: z.string().min(1),
+            paywall_config_id: z.string().min(1).optional(),
+            enabled: z.boolean(),
+            include_raw: z.boolean().optional(),
+        },
+        appIdSelector: appIdFromInput,
+        execute: async (container, auth, input) => container.analyticsService.placementItemSetEnabled(auth, {
+            app_id: input.app_id,
+            apphud_app_id: input.apphud_app_id,
+            placement_id: input.placement_id,
+            placement_item_id: input.placement_item_id,
+            paywall_config_id: input.paywall_config_id,
+            enabled: input.enabled,
+            include_raw: input.include_raw,
+        }),
+    },
+    apphud_paywall_item_delete: {
+        description: "Delete paywall item by id",
+        inputShape: {
+            ...baseInputShape,
+            app_id: z.string().min(1).optional(),
+            apphud_app_id: z.string().min(1).optional(),
+            paywall_item_id: z.string().min(1),
+            include_raw: z.boolean().optional(),
+        },
+        appIdSelector: appIdFromInput,
+        execute: async (container, auth, input) => container.analyticsService.paywallItemDelete(auth, {
+            app_id: input.app_id,
+            apphud_app_id: input.apphud_app_id,
+            paywall_item_id: input.paywall_item_id,
+            include_raw: input.include_raw,
+        }),
+    },
+    apphud_placement_item_delete: {
+        description: "Delete placement item by id",
+        inputShape: {
+            ...baseInputShape,
+            app_id: z.string().min(1).optional(),
+            apphud_app_id: z.string().min(1).optional(),
+            placement_id: z.string().min(1),
+            placement_item_id: z.string().min(1),
+            include_raw: z.boolean().optional(),
+        },
+        appIdSelector: appIdFromInput,
+        execute: async (container, auth, input) => container.analyticsService.placementItemDelete(auth, {
+            app_id: input.app_id,
+            apphud_app_id: input.apphud_app_id,
+            placement_id: input.placement_id,
+            placement_item_id: input.placement_item_id,
+            include_raw: input.include_raw,
+        }),
+    },
+    apphud_placement_delete: {
+        description: "Delete placement by id",
+        inputShape: {
+            ...baseInputShape,
+            app_id: z.string().min(1).optional(),
+            apphud_app_id: z.string().min(1).optional(),
+            placement_id: z.string().min(1),
+            include_raw: z.boolean().optional(),
+        },
+        appIdSelector: appIdFromInput,
+        execute: async (container, auth, input) => container.analyticsService.placementDelete(auth, {
+            app_id: input.app_id,
+            apphud_app_id: input.apphud_app_id,
+            placement_id: input.placement_id,
+            include_raw: input.include_raw,
+        }),
+    },
+    apphud_paywall_config_delete: {
+        description: "Delete paywall config by id",
+        inputShape: {
+            ...baseInputShape,
+            app_id: z.string().min(1).optional(),
+            apphud_app_id: z.string().min(1).optional(),
+            paywall_config_id: z.string().min(1),
+            include_raw: z.boolean().optional(),
+        },
+        appIdSelector: appIdFromInput,
+        execute: async (container, auth, input) => container.analyticsService.paywallConfigDelete(auth, {
+            app_id: input.app_id,
+            apphud_app_id: input.apphud_app_id,
+            paywall_config_id: input.paywall_config_id,
+            include_raw: input.include_raw,
+        }),
+    },
     apphud_analytics_events_list: {
         description: "List raw subscription events from Apphud dashboard event feed",
         inputShape: {

package/package.json

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