@capivv/mcp-server 0.1.3 → 0.2.0

package/dist/tools/next-step.js

@@ -0,0 +1,123 @@
+function buildSteps(state) {
+    const steps = [];
+    let stepNum = 1;
+    const total = 6;
+    // Step 1: App
+    steps.push({
+        step: stepNum++,
+        total_steps: total,
+        title: 'Register your app',
+        status: state.apps > 0 ? 'done' : 'needed',
+        what: 'Register your app with its platform and bundle ID.',
+        how: 'Use capivv_create_app with name, platform (ios/android/web), and bundle_id (e.g., "com.yourcompany.app").',
+        why: 'Every product and offering belongs to an app. This is the foundation of your setup.',
+    });
+    // Step 2: Entitlements
+    steps.push({
+        step: stepNum++,
+        total_steps: total,
+        title: 'Create entitlements',
+        status: state.entitlements > 0 ? 'done' : 'needed',
+        what: 'Define what features users unlock when they purchase (e.g., "pro", "premium").',
+        how: 'Use capivv_create_entitlement with identifier (e.g., "pro") and display_name (e.g., "Pro Access").',
+        why: 'Entitlements are how your app checks "does this user have access?" They decouple features from specific products.',
+    });
+    // Step 3: Store credentials (can't be done via MCP)
+    const storeStep = state.nextOnboardingStep === 'store_credentials_configured' || state.nextOnboardingStep === 'store_connected'
+        ? 'needed'
+        : state.products > 0
+            ? 'done'
+            : 'optional';
+    steps.push({
+        step: stepNum++,
+        total_steps: total,
+        title: 'Connect store credentials',
+        status: storeStep,
+        what: 'Connect your App Store Connect / Google Play credentials so Capivv can validate receipts and import products.',
+        how: 'Go to the Capivv dashboard → Settings → Developer → Integrations. For iOS: upload your App Store Connect API key (p8 file). For Android: upload your Google Play service account JSON.',
+        why: 'Without store credentials, Capivv cannot verify purchases or automatically sync subscription status changes.',
+    });
+    // Step 4: Products
+    steps.push({
+        step: stepNum++,
+        total_steps: total,
+        title: 'Create products',
+        status: state.products > 0 ? 'done' : 'needed',
+        what: 'Create your subscription or in-app purchase products, linked to entitlements.',
+        how: state.apps > 0
+            ? 'Use capivv_create_product with app_id, external_id (must match your store product ID exactly), product_type, and entitlement_ids. Or use capivv_import_products to auto-import from a connected store.'
+            : 'First complete Step 1 (create an app), then use capivv_create_product.',
+        why: 'Products map to real App Store / Google Play items. The external_id must match exactly or purchase verification will fail.',
+    });
+    // Step 5: Offerings
+    steps.push({
+        step: stepNum++,
+        total_steps: total,
+        title: 'Create an offering',
+        status: state.offerings > 0 ? 'done' : 'needed',
+        what: 'Bundle your products into an offering that your paywall will display.',
+        how: state.products > 0
+            ? 'Use capivv_create_offering with your app_id, an identifier (e.g., "default"), and packages that reference your product IDs.'
+            : 'First complete Step 4 (create products), then use capivv_create_offering.',
+        why: 'The SDK fetches offerings to populate your paywall. Without an offering, your app has nothing to show users.',
+    });
+    // Step 6: SDK integration
+    steps.push({
+        step: stepNum++,
+        total_steps: total,
+        title: 'Integrate the SDK',
+        status: state.onboardingComplete ? 'done' : 'needed',
+        what: 'Add the Capivv SDK to your app, configure it with your public API key, and implement the paywall.',
+        how: 'Get your public key from the Capivv dashboard (Settings → Developer → API Keys). Read capivv://docs/quickstart for code examples, or capivv://docs/guides/ios for a detailed iOS walkthrough.',
+        why: 'The SDK handles user identification, entitlement checking, purchase processing, and receipt validation.',
+    });
+    return steps;
+}
+export function registerNextStepTool(server, client) {
+    server.tool('capivv_next_step', 'Analyze your current Capivv setup and tell you exactly what to do next. Returns a prioritized checklist with clear instructions for each step.', async () => {
+        const [apps, products, entitlements, offerings, rules, onboarding] = await Promise.allSettled([
+            client.listApps(),
+            client.listProducts(),
+            client.listEntitlements(),
+            client.listOfferings(),
+            client.listRules(),
+            client.getOnboarding(),
+        ]);
+        const count = (r) => r.status === 'fulfilled' ? r.value.length : 0;
+        const state = {
+            apps: count(apps),
+            entitlements: count(entitlements),
+            products: count(products),
+            offerings: count(offerings),
+            rules: count(rules),
+            onboardingComplete: onboarding.status === 'fulfilled' && onboarding.value.is_complete,
+            nextOnboardingStep: onboarding.status === 'fulfilled' ? onboarding.value.next_step : null,
+        };
+        const steps = buildSteps(state);
+        const completed = steps.filter((s) => s.status === 'done').length;
+        const needed = steps.filter((s) => s.status === 'needed');
+        const nextStep = needed[0] ?? null;
+        const result = {
+            progress: `${completed}/${steps.length} steps completed`,
+            setup_complete: needed.length === 0,
+            steps,
+        };
+        if (nextStep) {
+            result.next_action = {
+                summary: `Step ${nextStep.step}/${nextStep.total_steps}: ${nextStep.title}`,
+                what: nextStep.what,
+                how: nextStep.how,
+                why: nextStep.why,
+            };
+        }
+        else {
+            result.next_action = {
+                summary: 'Setup complete! Your Capivv integration is ready.',
+                what: 'Your app, entitlements, products, and offerings are all configured.',
+                how: 'Use capivv_get_analytics to monitor your subscription metrics, or capivv_apply_rule to add business rules like trial offers or churn recovery.',
+                why: 'You can now focus on optimizing conversions and reducing churn.',
+            };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/setup-wizard.d.ts

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

package/dist/tools/setup-wizard.js

@@ -0,0 +1,259 @@
+import { z } from 'zod';
+/**
+ * Only the messages we're confident indicate a conflict (existing row) should
+ * trigger the "list and reuse" fallback. Anything else — timeouts, 5xx,
+ * validation errors — is a legitimate failure that the caller needs to see.
+ */
+function isConflictError(msg) {
+    const lower = msg.toLowerCase();
+    return (lower.includes('already exists') ||
+        lower.includes('duplicate') ||
+        lower.includes('409') ||
+        lower.includes('conflict'));
+}
+export function registerSetupWizardTool(server, client) {
+    server.tool('capivv_setup_wizard', `One-shot setup for an EXISTING app: creates an entitlement, products, and offering on an app you've already imported via the Capivv dashboard's store-connect flow.
+
+As of V6 this tool does NOT create apps from scratch — connect your store in the dashboard to import apps with real bundle IDs. Use capivv_list_apps or capivv_whoami to see which apps are available.
+
+Example:
+  bundle_id: "com.mycompany.myapp"   // must already exist; omit if your tenant has exactly one app
+  entitlement_id: "pro"
+  products: [
+    { name: "Monthly", external_id: "com.mycompany.myapp.monthly", billing_period: "month", price_cents: 799 },
+    { name: "Annual", external_id: "com.mycompany.myapp.yearly", billing_period: "year", price_cents: 4999 }
+  ]
+  offering_id: "default"`, {
+        bundle_id: z
+            .string()
+            .optional()
+            .describe('Bundle ID of the existing app to configure. If omitted and the tenant has exactly one app, that app is used.'),
+        entitlement_id: z.string().describe('Entitlement identifier (e.g., "pro", "premium")'),
+        entitlement_name: z
+            .string()
+            .optional()
+            .describe('Entitlement display name (defaults to capitalized identifier)'),
+        products: z
+            .array(z.object({
+            name: z.string().describe('Product display name (e.g., "Monthly Plan")'),
+            external_id: z
+                .string()
+                .describe('Store product ID — must match App Store Connect / Google Play exactly'),
+            billing_period: z
+                .string()
+                .describe('Billing period: week, month, three_months, six_months, or year'),
+            price_cents: z.number().describe('Price in USD cents (e.g., 799 for $7.99)'),
+        }))
+            .describe('Subscription products to create'),
+        offering_id: z.string().optional().describe('Offering identifier (default: "default")'),
+        offering_name: z
+            .string()
+            .optional()
+            .describe('Offering display name (default: based on entitlement)'),
+    }, async (args) => {
+        // Step 0: resolve identity + reachable apps. Every wizard response
+        // carries `tenant` so the caller can see which workspace is being
+        // written to — if this org_name doesn't match expectations, stop.
+        const me = await client.whoami();
+        const result = {
+            success: true,
+            tenant: { tenant_id: me.tenant_id, org_name: me.org_name },
+            resolved_app: null,
+            created: { entitlements: [], products: [] },
+            skipped_existing: [],
+            errors: [],
+            next_steps: [],
+        };
+        // Step 1: resolve which app to configure. No more hardcoded placeholder
+        // app creation — the app must already exist via dashboard import.
+        let selected = null;
+        if (me.apps.length === 0) {
+            result.success = false;
+            result.errors.push(`Workspace "${me.org_name}" has no apps yet. Connect your store in the dashboard (Settings → Developer → Integrations) and import at least one app first, then re-run this wizard.`);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        if (args.bundle_id) {
+            const match = me.apps.find((a) => a.bundle_id === args.bundle_id);
+            if (!match) {
+                result.success = false;
+                result.errors.push(`No app with bundle_id "${args.bundle_id}" in workspace "${me.org_name}". Available: ${me.apps.map((a) => a.bundle_id).join(', ')}.`);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            // whoami returns a subset of App fields — fetch the full row so we
+            // can use it as the appId source.
+            const apps = await client.listApps();
+            selected = apps.find((a) => a.id === match.id) ?? null;
+        }
+        else if (me.apps.length === 1) {
+            const apps = await client.listApps();
+            selected = apps.find((a) => a.id === me.apps[0].id) ?? null;
+        }
+        else {
+            result.success = false;
+            result.errors.push(`Workspace "${me.org_name}" has ${me.apps.length} apps — pass bundle_id to pick one. Options: ${me.apps.map((a) => `${a.bundle_id} (${a.name})`).join(', ')}.`);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        if (!selected) {
+            result.success = false;
+            result.errors.push('Failed to resolve app from the tenant');
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        result.resolved_app = {
+            id: selected.id,
+            name: selected.name,
+            bundle_id: selected.bundle_id ?? '',
+            platform: selected.platform,
+        };
+        const appId = selected.id;
+        // Step 2: Create entitlement. Conflict (already exists) is treated as a
+        // skip, not a failure; everything else aborts loud.
+        let entitlementId;
+        try {
+            const entitlement = await client.createEntitlement({
+                identifier: args.entitlement_id,
+                display_name: args.entitlement_name ??
+                    args.entitlement_id.charAt(0).toUpperCase() + args.entitlement_id.slice(1),
+            });
+            result.created.entitlements.push(entitlement);
+            entitlementId = entitlement.id;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (isConflictError(msg)) {
+                const entitlements = await client.listEntitlements();
+                const existing = entitlements.find((e) => e.identifier === args.entitlement_id);
+                if (existing) {
+                    entitlementId = existing.id;
+                    result.skipped_existing.push(`entitlement:${args.entitlement_id}`);
+                }
+                else {
+                    result.success = false;
+                    result.errors.push(`Entitlement "${args.entitlement_id}" reported as existing but couldn't be found — aborting`);
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                    };
+                }
+            }
+            else {
+                result.success = false;
+                result.errors.push(`Entitlement creation failed: ${msg}`);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+        }
+        // Step 3: Create products
+        const PERIOD_TO_PACKAGE = {
+            week: 'weekly',
+            month: 'monthly',
+            three_months: 'three_month',
+            six_months: 'six_month',
+            year: 'annual',
+        };
+        for (const p of args.products) {
+            try {
+                const product = await client.createProduct({
+                    app_id: appId,
+                    external_id: p.external_id,
+                    product_type: 'subscription',
+                    display_name: p.name,
+                    entitlement_ids: entitlementId ? [entitlementId] : [],
+                    subscription: { billing_period: p.billing_period },
+                    prices: [{ currency: 'USD', amount_cents: p.price_cents, is_default: true }],
+                });
+                result.created.products.push(product);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (isConflictError(msg)) {
+                    const products = await client.listProducts(appId);
+                    const existing = products.find((pr) => pr.external_id === p.external_id);
+                    if (existing) {
+                        result.created.products.push(existing);
+                        result.skipped_existing.push(`product:${p.external_id}`);
+                    }
+                    else {
+                        result.success = false;
+                        result.errors.push(`Product "${p.name}" reported as existing but couldn't be found — aborting`);
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        };
+                    }
+                }
+                else {
+                    result.success = false;
+                    result.errors.push(`Product "${p.name}" creation failed: ${msg}`);
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                    };
+                }
+            }
+        }
+        // Step 4: Create offering
+        if (result.created.products.length > 0) {
+            const offeringId = args.offering_id ?? 'default';
+            const offeringName = args.offering_name ??
+                `${args.entitlement_id.charAt(0).toUpperCase() + args.entitlement_id.slice(1)} Plans`;
+            const packages = result.created.products.map((product, index) => {
+                const inputProduct = args.products.find((p) => p.external_id === product.external_id);
+                const packageType = inputProduct
+                    ? (PERIOD_TO_PACKAGE[inputProduct.billing_period] ?? 'custom')
+                    : 'custom';
+                return {
+                    identifier: packageType,
+                    product_id: product.id,
+                    display_name: product.display_name,
+                    package_type: packageType,
+                    position: index,
+                };
+            });
+            try {
+                result.created.offering = await client.createOffering({
+                    app_id: appId,
+                    identifier: offeringId,
+                    display_name: offeringName,
+                    is_default: true,
+                    packages,
+                });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (isConflictError(msg)) {
+                    const offerings = await client.listOfferings();
+                    const existing = offerings.find((o) => o.identifier === offeringId);
+                    if (existing) {
+                        result.created.offering = existing;
+                        result.skipped_existing.push(`offering:${offeringId}`);
+                    }
+                    else {
+                        result.success = false;
+                        result.errors.push(`Offering "${offeringId}" reported as existing but couldn't be found — aborting`);
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        };
+                    }
+                }
+                else {
+                    result.success = false;
+                    result.errors.push(`Offering creation failed: ${msg}`);
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                    };
+                }
+            }
+        }
+        // Build next steps
+        result.next_steps.push(`Wrote to workspace "${result.tenant.org_name}" (tenant_id: ${result.tenant.tenant_id}, app: ${result.resolved_app.bundle_id}). If that's the wrong workspace, switch your CAPIVV_API_KEY env var before continuing.`);
+        result.next_steps.push('Integrate the SDK: copy the publishable (pk_*) key generated for this app from Settings → Developer → API Keys. Read capivv://docs/quickstart for code examples.');
+        result.next_steps.push('Verify: Run capivv_verify_setup to check that everything is configured correctly.');
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/status.js

@@ -1,3 +1,4 @@
+import { ApiError } from '../client.js';
 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.',
@@ -11,7 +12,7 @@ const STEP_GUIDANCE = {
 };
 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([
+        const settled = await Promise.allSettled([
             client.listApps(),
             client.listProducts(),
             client.listEntitlements(),
@@ -20,6 +21,26 @@ export function registerStatusTool(server, client) {
             client.getOnboarding(),
             client.getAnalyticsOverview(),
         ]);
+        const [apps, products, entitlements, offerings, rules, onboarding, analytics] = settled;
+        // Every call goes through the same Bearer-token auth. If even one returns
+        // 401, the bearer is bad and every count we'd report would be a lie —
+        // short-circuit with a clear message instead of rendering zeros.
+        const authFailure = settled.find((r) => r.status === 'rejected' && r.reason instanceof ApiError && r.reason.status === 401);
+        if (authFailure) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Authentication failed (HTTP 401). Verify CAPIVV_API_KEY (or the Bearer token your MCP client is sending) is a valid sk_* secret key.',
+                    },
+                ],
+            };
+        }
+        const labels = ['apps', 'products', 'entitlements', 'offerings', 'rules', 'onboarding', 'analytics'];
+        const warnings = settled
+            .map((r, i) => (r.status === 'rejected' ? `${labels[i]}: ${r.reason.message}` : null))
+            .filter((w) => w !== null);
         const count = (r) => r.status === 'fulfilled' ? r.value.length : 0;
         const result = {
             resources: {
@@ -30,6 +51,9 @@ export function registerStatusTool(server, client) {
                 rules: count(rules),
             },
         };
+        if (warnings.length) {
+            result._warnings = warnings;
+        }
         if (onboarding.status === 'fulfilled') {
             const ob = onboarding.value;
             result.onboarding = {

package/dist/tools/update-product.d.ts

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

package/dist/tools/update-product.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export function registerUpdateProductTool(server, client) {
+    server.tool('capivv_update_product', 'Update an existing product. Only provided fields are changed.', {
+        product_id: z.string().describe('Product ID to update'),
+        external_id: z.string().optional().describe('New store product ID'),
+        display_name: z.string().optional().describe('New display name'),
+        description: z.string().optional().describe('New description'),
+        entitlement_ids: z
+            .array(z.string())
+            .optional()
+            .describe('New entitlement IDs (replaces existing)'),
+    }, async ({ product_id, ...updates }) => {
+        const product = await client.updateProduct(product_id, updates);
+        return { content: [{ type: 'text', text: JSON.stringify(product, null, 2) }] };
+    });
+}

package/dist/tools/verify-setup.d.ts

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

package/dist/tools/verify-setup.js

@@ -0,0 +1,200 @@
+export function registerVerifySetupTool(server, client) {
+    server.tool('capivv_verify_setup', 'Verify your Capivv setup is complete and correctly configured. Checks apps, entitlements, products, offerings, and store connectivity. Returns a pass/fail checklist with fix instructions for any issues.', async () => {
+        const [apps, products, entitlements, offerings, onboarding, health] = await Promise.allSettled([
+            client.listApps(),
+            client.listProducts(),
+            client.listEntitlements(),
+            client.listOfferings(),
+            client.getOnboarding(),
+            client.healthCheck(),
+        ]);
+        const checks = [];
+        // 1. API connectivity
+        if (health.status === 'fulfilled' && health.value) {
+            checks.push({
+                name: 'API connectivity',
+                status: 'pass',
+                detail: 'Successfully connected to Capivv API.',
+            });
+        }
+        else {
+            checks.push({
+                name: 'API connectivity',
+                status: 'fail',
+                detail: 'Cannot reach Capivv API.',
+                fix: 'Check your CAPIVV_API_KEY and CAPIVV_API_URL environment variables. Ensure the API key is valid and not revoked.',
+            });
+        }
+        // 2. Apps
+        const appList = apps.status === 'fulfilled' ? apps.value : [];
+        if (appList.length > 0) {
+            const platforms = [...new Set(appList.map((a) => a.platform))].join(', ');
+            checks.push({
+                name: 'Apps registered',
+                status: 'pass',
+                detail: `${appList.length} app(s) registered (${platforms}).`,
+            });
+            // Check for missing bundle IDs
+            const missingBundleId = appList.filter((a) => !a.bundle_id);
+            if (missingBundleId.length > 0) {
+                checks.push({
+                    name: 'App bundle IDs',
+                    status: 'warn',
+                    detail: `${missingBundleId.length} app(s) missing bundle ID: ${missingBundleId.map((a) => a.name).join(', ')}.`,
+                    fix: 'Each app should have a bundle_id matching your store listing (e.g., com.yourcompany.yourapp).',
+                });
+            }
+        }
+        else {
+            checks.push({
+                name: 'Apps registered',
+                status: 'fail',
+                detail: 'No apps registered.',
+                fix: 'Use capivv_create_app or capivv_setup_wizard to register your app with its platform and bundle ID.',
+            });
+        }
+        // 3. Entitlements
+        const entitlementList = entitlements.status === 'fulfilled' ? entitlements.value : [];
+        if (entitlementList.length > 0) {
+            const ids = entitlementList.map((e) => e.identifier).join(', ');
+            checks.push({
+                name: 'Entitlements defined',
+                status: 'pass',
+                detail: `${entitlementList.length} entitlement(s): ${ids}.`,
+            });
+        }
+        else {
+            checks.push({
+                name: 'Entitlements defined',
+                status: 'fail',
+                detail: 'No entitlements defined.',
+                fix: 'Use capivv_create_entitlement to define what features users unlock (e.g., identifier: "pro", display_name: "Pro Access").',
+            });
+        }
+        // 4. Products
+        const productList = products.status === 'fulfilled' ? products.value : [];
+        if (productList.length > 0) {
+            checks.push({
+                name: 'Products created',
+                status: 'pass',
+                detail: `${productList.length} product(s) created.`,
+            });
+            // Check products linked to entitlements
+            const unlinked = productList.filter((p) => !p.entitlement_ids || p.entitlement_ids.length === 0);
+            if (unlinked.length > 0) {
+                checks.push({
+                    name: 'Products linked to entitlements',
+                    status: 'warn',
+                    detail: `${unlinked.length} product(s) not linked to any entitlement: ${unlinked.map((p) => p.display_name).join(', ')}.`,
+                    fix: 'Use capivv_update_product to add entitlement_ids to these products. Without entitlement links, purchases won\'t grant feature access.',
+                });
+            }
+            else {
+                checks.push({
+                    name: 'Products linked to entitlements',
+                    status: 'pass',
+                    detail: 'All products are linked to at least one entitlement.',
+                });
+            }
+        }
+        else {
+            checks.push({
+                name: 'Products created',
+                status: 'fail',
+                detail: 'No products created.',
+                fix: 'Use capivv_create_product to create subscription products. The external_id must exactly match your App Store / Google Play product ID.',
+            });
+        }
+        // 5. Offerings
+        const offeringList = offerings.status === 'fulfilled' ? offerings.value : [];
+        if (offeringList.length > 0) {
+            const defaultOffering = offeringList.find((o) => o.is_default);
+            const totalPackages = offeringList.reduce((sum, o) => sum + (o.packages?.length ?? 0), 0);
+            checks.push({
+                name: 'Offerings configured',
+                status: 'pass',
+                detail: `${offeringList.length} offering(s) with ${totalPackages} total package(s).`,
+            });
+            if (!defaultOffering) {
+                checks.push({
+                    name: 'Default offering set',
+                    status: 'warn',
+                    detail: 'No offering is marked as default.',
+                    fix: 'Create or update an offering with is_default: true. The SDK fetches the default offering for paywalls.',
+                });
+            }
+            else {
+                checks.push({
+                    name: 'Default offering set',
+                    status: 'pass',
+                    detail: `Default offering: "${defaultOffering.identifier}" with ${defaultOffering.packages?.length ?? 0} package(s).`,
+                });
+            }
+            // Check for empty offerings
+            const emptyOfferings = offeringList.filter((o) => !o.packages || o.packages.length === 0);
+            if (emptyOfferings.length > 0) {
+                checks.push({
+                    name: 'Offerings have packages',
+                    status: 'warn',
+                    detail: `${emptyOfferings.length} offering(s) have no packages: ${emptyOfferings.map((o) => o.identifier).join(', ')}.`,
+                    fix: 'An offering without packages has nothing to display on your paywall. Add products as packages to these offerings.',
+                });
+            }
+        }
+        else {
+            checks.push({
+                name: 'Offerings configured',
+                status: 'fail',
+                detail: 'No offerings created.',
+                fix: 'Use capivv_create_offering to bundle your products into an offering. This is what your paywall displays to users.',
+            });
+        }
+        // 6. Store credentials (check via onboarding)
+        if (onboarding.status === 'fulfilled') {
+            const ob = onboarding.value;
+            const storeStep = ob.steps?.find((s) => s.key === 'store_credentials_configured' || s.key === 'store_connected');
+            if (storeStep) {
+                if (storeStep.completed) {
+                    checks.push({
+                        name: 'Store credentials connected',
+                        status: 'pass',
+                        detail: 'App store credentials are configured.',
+                    });
+                }
+                else {
+                    checks.push({
+                        name: 'Store credentials connected',
+                        status: 'warn',
+                        detail: 'Store credentials not yet configured.',
+                        fix: 'Go to the Capivv dashboard → Settings → Developer → Integrations. Upload your App Store Connect API key (.p8 file) or Google Play service account JSON. This enables receipt validation and subscription status sync.',
+                    });
+                }
+            }
+        }
+        // Summary
+        const passed = checks.filter((c) => c.status === 'pass').length;
+        const failed = checks.filter((c) => c.status === 'fail').length;
+        const warned = checks.filter((c) => c.status === 'warn').length;
+        let overallStatus;
+        let summary;
+        if (failed === 0 && warned === 0) {
+            overallStatus = 'ready';
+            summary = 'Your Capivv setup is complete and ready for integration!';
+        }
+        else if (failed === 0) {
+            overallStatus = 'mostly_ready';
+            summary = `Setup is functional but has ${warned} warning(s) to address for a production-quality integration.`;
+        }
+        else {
+            overallStatus = 'incomplete';
+            summary = `Setup is incomplete: ${failed} required item(s) missing. Fix the failing checks to get started.`;
+        }
+        const result = {
+            status: overallStatus,
+            summary,
+            score: `${passed}/${checks.length} checks passed`,
+            checks,
+        };
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/whoami.d.ts

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