@capivv/mcp-server 0.1.3 → 0.5.0

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;

package/dist/tools/whoami.js

@@ -0,0 +1,31 @@
+// Introduced in V6 Phase A to address the cross-org API key mismatch from the
+// 2026-04-12 customer audit (Defect 3d). Users holding an API key for one org
+// while viewing a different org in the dashboard now have an immediate way to
+// confirm which org and apps their MCP integration reaches.
+export function registerWhoamiTool(server, client) {
+    server.tool('capivv_whoami', 'Show which Capivv workspace (organization) and apps the current API key is connected to. Use this first when something looks wrong — e.g., products or entitlements appear missing — to confirm the MCP is pointed at the right workspace.', async () => {
+        const me = await client.whoami();
+        const lines = [
+            `Workspace: ${me.org_name} (${me.tenant_id})`,
+            `Key type: ${me.key_type ?? 'jwt-session'}`,
+        ];
+        if (me.app_id) {
+            lines.push(`Scoped to app: ${me.app_id}`);
+        }
+        if (me.apps.length === 0) {
+            lines.push('Apps: (none yet — connect a store in the Capivv dashboard to import apps)');
+        }
+        else {
+            lines.push(`Apps (${me.apps.length}):`);
+            for (const app of me.apps) {
+                lines.push(`  • ${app.name} — ${app.bundle_id} (${app.platform})`);
+            }
+        }
+        return {
+            content: [
+                { type: 'text', text: lines.join('\n') },
+                { type: 'text', text: JSON.stringify(me, null, 2) },
+            ],
+        };
+    });
+}