@capivv/mcp-server 0.1.0

package/dist/tools/import-products.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+export function registerImportProductsTool(server, client) {
+    server.tool('capivv_import_products', 'Import products from connected App Store Connect or Google Play Console into Capivv. Returns a preview of what will be imported including suggested products, entitlements, and offerings.', { app_id: z.string().describe('App ID to import products for') }, async ({ app_id }) => {
+        const preview = await client.getImportPreview(app_id);
+        const newProducts = preview.suggestion.products.filter((p) => !p.already_exists);
+        const newEntitlements = preview.suggestion.entitlements.filter((e) => !e.already_exists);
+        const summary = {
+            new_products: newProducts.length,
+            new_entitlements: newEntitlements.length,
+            new_offerings: preview.suggestion.offerings.length,
+            existing_counts: preview.existing_counts,
+            warnings: preview.suggestion.warnings,
+            store_errors: preview.store_errors,
+            details: preview.suggestion,
+        };
+        return { content: [{ type: 'text', text: JSON.stringify(summary, null, 2) }] };
+    });
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CapivvClient } from '../client.js';
+export declare function registerAllTools(server: McpServer, client: CapivvClient): void;

package/dist/tools/index.js

@@ -0,0 +1,22 @@
+import { registerStatusTool } from './status.js';
+import { registerListAppsTool } from './list-apps.js';
+import { registerListProductsTool } from './list-products.js';
+import { registerImportProductsTool } from './import-products.js';
+import { registerListOfferingsTool } from './list-offerings.js';
+import { registerCreateOfferingTool } from './create-offering.js';
+import { registerListRulesTool } from './list-rules.js';
+import { registerApplyRuleTool } from './apply-rule.js';
+import { registerListExperimentsTool } from './list-experiments.js';
+import { registerGetAnalyticsTool } from './get-analytics.js';
+export function registerAllTools(server, client) {
+    registerStatusTool(server, client);
+    registerListAppsTool(server, client);
+    registerListProductsTool(server, client);
+    registerImportProductsTool(server, client);
+    registerListOfferingsTool(server, client);
+    registerCreateOfferingTool(server, client);
+    registerListRulesTool(server, client);
+    registerApplyRuleTool(server, client);
+    registerListExperimentsTool(server, client);
+    registerGetAnalyticsTool(server, client);
+}

package/dist/tools/list-apps.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CapivvClient } from '../client.js';
+export declare function registerListAppsTool(server: McpServer, client: CapivvClient): void;

package/dist/tools/list-apps.js

@@ -0,0 +1,6 @@
+export function registerListAppsTool(server, client) {
+    server.tool('capivv_list_apps', 'List all apps registered in your Capivv account with their platform, bundle ID, and creation date.', async () => {
+        const apps = await client.listApps();
+        return { content: [{ type: 'text', text: JSON.stringify(apps, null, 2) }] };
+    });
+}

package/dist/tools/list-experiments.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CapivvClient } from '../client.js';
+export declare function registerListExperimentsTool(server: McpServer, client: CapivvClient): void;

package/dist/tools/list-experiments.js

@@ -0,0 +1,34 @@
+export function registerListExperimentsTool(server, client) {
+    server.tool('capivv_list_experiments', 'List A/B experiments with their status, variants, and current results including leading variant, confidence, and uplift.', async () => {
+        const [experiments, summaries] = await Promise.all([
+            client.listExperiments(),
+            client.getExperimentSummaries(),
+        ]);
+        const summaryMap = new Map(summaries.map((s) => [s.experiment_id, s]));
+        const merged = experiments.map((exp) => {
+            const summary = summaryMap.get(exp.id);
+            return {
+                id: exp.id,
+                name: exp.name,
+                status: exp.status,
+                target_metric: exp.target_metric,
+                variants: exp.variants.map((v) => ({
+                    name: v.name,
+                    is_control: v.is_control,
+                    traffic_percent: v.traffic_percent,
+                    conversion_rate: v.conversion_rate,
+                    uplift_percent: v.uplift_percent,
+                })),
+                ...(summary
+                    ? {
+                        total_participants: summary.total_participants,
+                        leading_variant: summary.leading_variant,
+                        confidence: summary.confidence,
+                        days_running: summary.days_running,
+                    }
+                    : {}),
+            };
+        });
+        return { content: [{ type: 'text', text: JSON.stringify(merged, null, 2) }] };
+    });
+}

package/dist/tools/list-offerings.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CapivvClient } from '../client.js';
+export declare function registerListOfferingsTool(server: McpServer, client: CapivvClient): void;

package/dist/tools/list-offerings.js

@@ -0,0 +1,6 @@
+export function registerListOfferingsTool(server, client) {
+    server.tool('capivv_list_offerings', 'List offerings (product bundles shown to users) with their packages and associated products.', async () => {
+        const offerings = await client.listOfferings();
+        return { content: [{ type: 'text', text: JSON.stringify(offerings, null, 2) }] };
+    });
+}

package/dist/tools/list-products.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CapivvClient } from '../client.js';
+export declare function registerListProductsTool(server: McpServer, client: CapivvClient): void;

package/dist/tools/list-products.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export function registerListProductsTool(server, client) {
+    server.tool('capivv_list_products', 'List products (in-app purchases and subscriptions) with their store IDs, types, and linked entitlements. Optionally filter by app.', { app_id: z.string().optional().describe('Filter products by app ID') }, async ({ app_id }) => {
+        const products = await client.listProducts(app_id);
+        const result = { products };
+        // E.4.1: Suggest creating offerings when products exist but none are configured
+        if (products.length > 0) {
+            const offerings = await client.listOfferings().catch(() => []);
+            if (offerings.length === 0) {
+                result._suggestion =
+                    'You have products but no offerings. Create an offering to bundle products for your paywall. Use the capivv_create_offering tool.';
+            }
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/list-rules.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CapivvClient } from '../client.js';
+export declare function registerListRulesTool(server: McpServer, client: CapivvClient): void;

package/dist/tools/list-rules.js

@@ -0,0 +1,13 @@
+export function registerListRulesTool(server, client) {
+    server.tool('capivv_list_rules', 'List all YAML-based business rules with their status, priority, and last update time.', async () => {
+        const rules = await client.listRules();
+        const summary = rules.map((r) => ({
+            id: r.id,
+            name: r.name,
+            priority: r.priority,
+            is_enabled: r.is_enabled,
+            updated_at: r.updated_at,
+        }));
+        return { content: [{ type: 'text', text: JSON.stringify(summary, null, 2) }] };
+    });
+}

package/dist/tools/status.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CapivvClient } from '../client.js';
+export declare function registerStatusTool(server: McpServer, client: CapivvClient): void;

package/dist/tools/status.js

@@ -0,0 +1,62 @@
+const STEP_GUIDANCE = {
+    app_created: 'Create your first app with capivv_list_apps to see current apps, or create one in the Capivv dashboard.',
+    entitlement_created: 'Define entitlements to control feature access. Entitlements are granted when users purchase products.',
+    store_credentials_configured: 'Connect your App Store Connect or Google Play credentials in the Capivv dashboard under Settings > Developer > Integrations.',
+    product_created: 'Import products from your connected store using capivv_import_products, or create them manually in the dashboard.',
+    offering_created: 'Bundle your products into an offering using capivv_create_offering. Offerings are what your paywall displays.',
+    sdk_key_viewed: 'Generate an API key in the Capivv dashboard under Settings > Developer > API Keys, then integrate the SDK.',
+    store_connected: 'Connect your app store credentials to enable automatic product import.',
+    import_reviewed: 'Review the suggested imports using capivv_import_products to see what will be created.',
+    import_completed: 'Approve and run the import to create all suggested entities.',
+};
+export function registerStatusTool(server, client) {
+    server.tool('capivv_status', 'Get the current status of your Capivv subscription platform including setup progress, resource counts, and key metrics.', async () => {
+        const [apps, products, entitlements, offerings, rules, onboarding, analytics] = await Promise.allSettled([
+            client.listApps(),
+            client.listProducts(),
+            client.listEntitlements(),
+            client.listOfferings(),
+            client.listRules(),
+            client.getOnboarding(),
+            client.getAnalyticsOverview(),
+        ]);
+        const count = (r) => r.status === 'fulfilled' ? r.value.length : 0;
+        const result = {
+            resources: {
+                apps: count(apps),
+                products: count(products),
+                entitlements: count(entitlements),
+                offerings: count(offerings),
+                rules: count(rules),
+            },
+        };
+        if (onboarding.status === 'fulfilled') {
+            const ob = onboarding.value;
+            result.onboarding = {
+                is_complete: ob.is_complete,
+                completed_steps: ob.completed_steps,
+                total_steps: ob.total_steps,
+                next_step: ob.next_step,
+            };
+            // E.4.2: Include next step guidance when setup is incomplete
+            if (!ob.is_complete && ob.next_step) {
+                const guidance = STEP_GUIDANCE[ob.next_step];
+                if (guidance) {
+                    result._suggestion = `Setup incomplete (${ob.completed_steps}/${ob.total_steps}). Next step: ${guidance}`;
+                }
+            }
+        }
+        if (analytics.status === 'fulfilled') {
+            const a = analytics.value;
+            result.analytics = {
+                mrr: a.mrr_formatted,
+                arr: a.arr_formatted,
+                active_subscriptions: a.active_subscriptions,
+                trialing_subscriptions: a.trialing_subscriptions,
+                churn_rate: a.churn_rate,
+                arpu: a.arpu_formatted,
+            };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,184 @@
+export interface App {
+    id: string;
+    name: string;
+    platform: string;
+    bundle_id: string;
+    archived_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface Product {
+    id: string;
+    app_id: string;
+    external_id: string;
+    product_type: string;
+    display_name: string;
+    description: string | null;
+    entitlement_ids: string[];
+    created_at: string;
+    updated_at: string;
+}
+export interface Entitlement {
+    id: string;
+    identifier: string;
+    display_name: string;
+    description: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface Package {
+    identifier: string;
+    product_id: string;
+    display_name: string;
+    package_type: string;
+    position: number;
+}
+export interface Offering {
+    id: string;
+    app_id: string;
+    identifier: string;
+    display_name: string;
+    description: string | null;
+    is_default: boolean;
+    packages: Package[];
+    created_at: string;
+    updated_at: string;
+}
+export interface Rule {
+    id: string;
+    name: string;
+    content: string;
+    priority: number;
+    is_enabled: boolean;
+    updated_at: string;
+}
+export interface ExperimentVariant {
+    id: string;
+    name: string;
+    is_control: boolean;
+    traffic_percent: number;
+    sample_size: number;
+    conversion_count: number;
+    conversion_rate: number | null;
+    uplift_percent: number | null;
+}
+export interface Experiment {
+    id: string;
+    name: string;
+    description: string | null;
+    status: string;
+    target_metric: string | null;
+    start_date: string | null;
+    end_date: string | null;
+    confidence_level: number;
+    variants: ExperimentVariant[];
+}
+export interface ExperimentSummary {
+    experiment_id: string;
+    experiment_name: string;
+    status: string;
+    total_participants: number;
+    leading_variant: string | null;
+    uplift: number | null;
+    confidence: number | null;
+    days_running: number;
+}
+export interface PeriodComparison {
+    mrr_change_percent: number;
+    subscriptions_change_percent: number;
+}
+export interface AnalyticsOverview {
+    mrr: number;
+    mrr_formatted: string;
+    arr: number;
+    arr_formatted: string;
+    active_subscriptions: number;
+    trialing_subscriptions: number;
+    churn_rate: number;
+    arpu: number;
+    arpu_formatted: string;
+    period_comparison: PeriodComparison | null;
+}
+export interface OnboardingProgress {
+    onboarding_mode: string;
+    welcome_seen: boolean;
+    app_created: boolean;
+    entitlement_created: boolean;
+    store_credentials_configured: boolean;
+    product_created: boolean;
+    offering_created: boolean;
+    sdk_key_viewed: boolean;
+    store_connected: boolean;
+    import_reviewed: boolean;
+    import_completed: boolean;
+}
+export interface OnboardingResponse {
+    progress: OnboardingProgress;
+    is_complete: boolean;
+    completed_steps: number;
+    total_steps: number;
+    next_step: string | null;
+}
+export interface SuggestedProduct {
+    external_id: string;
+    product_type: string;
+    display_name: string;
+    source: string;
+    already_exists: boolean;
+}
+export interface SuggestedEntitlement {
+    identifier: string;
+    display_name: string;
+    already_exists: boolean;
+}
+export interface SuggestedOffering {
+    identifier: string;
+    display_name: string;
+    is_default: boolean;
+}
+export interface ImportSuggestion {
+    products: SuggestedProduct[];
+    entitlements: SuggestedEntitlement[];
+    offerings: SuggestedOffering[];
+    warnings: string[];
+}
+export interface ExistingEntityCounts {
+    apps: number;
+    products: number;
+    entitlements: number;
+    offerings: number;
+}
+export interface StoreError {
+    source: string;
+    message: string;
+}
+export interface ImportPreviewResponse {
+    suggestion: ImportSuggestion;
+    existing_counts: ExistingEntityCounts;
+    store_errors: StoreError[];
+}
+export interface CreateOfferingRequest {
+    app_id: string;
+    identifier: string;
+    display_name: string;
+    description?: string;
+    is_default?: boolean;
+    packages: Array<{
+        identifier: string;
+        product_id: string;
+        display_name: string;
+        package_type: string;
+        position: number;
+    }>;
+}
+export interface CreateRuleRequest {
+    name: string;
+    content: string;
+    priority: number;
+    is_enabled: boolean;
+}
+export interface ValidateRuleResponse {
+    is_valid: boolean;
+    errors: string[];
+    warnings: string[];
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+// API response types mirrored from crates/capivv-cli/src/client.rs
+// and dashboard/src/types/api.ts
+export {};

package/mcp.json

@@ -0,0 +1,149 @@
+{
+  "name": "@capivv/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for managing Capivv subscription platform via AI assistants",
+  "transport": "stdio",
+  "command": "npx",
+  "args": ["-y", "@capivv/mcp-server"],
+  "env": {
+    "CAPIVV_API_KEY": {
+      "required": true,
+      "description": "API key from the Capivv dashboard (Settings > Developer > API Keys)"
+    },
+    "CAPIVV_API_URL": {
+      "required": false,
+      "description": "API base URL (default: https://api.capivv.com)"
+    },
+    "CAPIVV_ORG_ID": {
+      "required": false,
+      "description": "Organization ID for multi-org accounts"
+    }
+  },
+  "tools": [
+    {
+      "name": "capivv_status",
+      "description": "Get the current status of your Capivv subscription platform including setup progress, resource counts, and key metrics."
+    },
+    {
+      "name": "capivv_list_apps",
+      "description": "List all apps registered in your Capivv account with their platform, bundle ID, and creation date."
+    },
+    {
+      "name": "capivv_list_products",
+      "description": "List products (in-app purchases and subscriptions) with their store IDs, types, and linked entitlements. Optionally filter by app.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "app_id": {
+            "type": "string",
+            "description": "Filter products by app ID"
+          }
+        }
+      }
+    },
+    {
+      "name": "capivv_import_products",
+      "description": "Import products from connected App Store Connect or Google Play Console into Capivv. Returns a preview of what will be imported including suggested products, entitlements, and offerings.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "app_id": {
+            "type": "string",
+            "description": "App ID to import products for"
+          }
+        },
+        "required": ["app_id"]
+      }
+    },
+    {
+      "name": "capivv_list_offerings",
+      "description": "List offerings (product bundles shown to users) with their packages and associated products."
+    },
+    {
+      "name": "capivv_create_offering",
+      "description": "Create a new offering to bundle products for your paywall. Specify products and their display order.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "app_id": {
+            "type": "string",
+            "description": "App ID"
+          },
+          "identifier": {
+            "type": "string",
+            "description": "Unique identifier for the offering"
+          },
+          "display_name": {
+            "type": "string",
+            "description": "Display name for the offering"
+          },
+          "packages": {
+            "type": "array",
+            "description": "Packages in the offering",
+            "items": {
+              "type": "object",
+              "properties": {
+                "identifier": { "type": "string" },
+                "display_name": { "type": "string" },
+                "product_id": { "type": "string" },
+                "package_type": { "type": "string" }
+              },
+              "required": ["identifier", "display_name", "product_id", "package_type"]
+            }
+          }
+        },
+        "required": ["app_id", "identifier", "display_name", "packages"]
+      }
+    },
+    {
+      "name": "capivv_list_rules",
+      "description": "List all YAML-based business rules with their status, priority, and last update time."
+    },
+    {
+      "name": "capivv_apply_rule",
+      "description": "Apply a YAML rule configuration. Validates the rule first, then creates or updates it. Returns validation errors if the YAML is invalid.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Rule name"
+          },
+          "yaml_content": {
+            "type": "string",
+            "description": "YAML rule content"
+          }
+        },
+        "required": ["name", "yaml_content"]
+      }
+    },
+    {
+      "name": "capivv_list_experiments",
+      "description": "List A/B experiments with their status, variants, and current results including leading variant, confidence, and uplift."
+    },
+    {
+      "name": "capivv_get_analytics",
+      "description": "Get key subscription business metrics: MRR, ARR, active subscriptions, churn rate, ARPU, and period-over-period comparison."
+    }
+  ],
+  "resources": [
+    {
+      "uri": "capivv://status",
+      "name": "status",
+      "description": "Current Capivv platform status as JSON including resource counts, onboarding progress, and analytics.",
+      "mimeType": "application/json"
+    },
+    {
+      "uriTemplate": "capivv://rules/{ruleId}",
+      "name": "rule",
+      "description": "Individual rule YAML content by rule ID.",
+      "mimeType": "text/yaml"
+    },
+    {
+      "uri": "capivv://docs/concepts",
+      "name": "concepts",
+      "description": "Glossary of Capivv subscription platform concepts (15 terms).",
+      "mimeType": "application/json"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@capivv/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for managing Capivv subscription platform via AI assistants",
+  "type": "module",
+  "bin": {
+    "capivv-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/",
+    "mcp.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/capivv/capivv.git",
+    "directory": "packages/mcp-server"
+  },
+  "homepage": "https://github.com/capivv/capivv/tree/main/packages/mcp-server",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "capivv",
+    "subscriptions",
+    "in-app-purchases"
+  ],
+  "author": "Capivv Team",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}