@capivv/mcp-server 0.5.51 → 0.5.54

package/dist/client.d.ts

@@ -65,6 +65,29 @@ export declare class CapivvClient {
         prior_alpha?: number;
         prior_beta?: number;
     }): Promise<unknown>;
+    /**
+     * V0.5.52 — issue #18 CUPED. Bayesian posterior with variance
+     * reduction using a named pre-experiment covariate.
+     */
+    getExperimentPosteriorCuped(input: {
+        experiment_id: string;
+        covariate_name: string;
+        decision_threshold_pct?: number;
+        prior_alpha?: number;
+        prior_beta?: number;
+    }): Promise<unknown>;
+    /**
+     * V0.5.53 — issue #18 slice 5. Revenue posterior with optional
+     * trim/winsorize for heavy-tailed ARPU distributions.
+     */
+    getExperimentPosteriorRevenue(input: {
+        experiment_id: string;
+        decision_threshold?: number;
+        prior_alpha?: number;
+        prior_beta?: number;
+        trim_top_pct?: number;
+        winsorize_top_pct?: number;
+    }): Promise<unknown>;
     /**
      * V0.5.48 — issue #18 Primitive 3 follow-up. Upload the Apple
      * promotional-offer signing key. Distinct from the ASC API key

package/dist/client.js

@@ -170,6 +170,38 @@ export class CapivvClient {
         const qs = params.toString() ? `?${params.toString()}` : '';
         return this.get(`/dashboard/experiments/${encodeURIComponent(input.experiment_id)}/posterior${qs}`);
     }
+    /**
+     * V0.5.52 — issue #18 CUPED. Bayesian posterior with variance
+     * reduction using a named pre-experiment covariate.
+     */
+    async getExperimentPosteriorCuped(input) {
+        const params = new URLSearchParams({ covariate_name: input.covariate_name });
+        if (input.decision_threshold_pct !== undefined) {
+            params.set('decision_threshold_pct', String(input.decision_threshold_pct));
+        }
+        if (input.prior_alpha !== undefined) {
+            params.set('prior_alpha', String(input.prior_alpha));
+        }
+        if (input.prior_beta !== undefined) {
+            params.set('prior_beta', String(input.prior_beta));
+        }
+        return this.get(`/dashboard/experiments/${encodeURIComponent(input.experiment_id)}/posterior/cuped?${params.toString()}`);
+    }
+    /**
+     * V0.5.53 — issue #18 slice 5. Revenue posterior with optional
+     * trim/winsorize for heavy-tailed ARPU distributions.
+     */
+    async getExperimentPosteriorRevenue(input) {
+        const params = new URLSearchParams();
+        for (const [k, v] of Object.entries(input)) {
+            if (k === 'experiment_id')
+                continue;
+            if (v !== undefined)
+                params.set(k, String(v));
+        }
+        const qs = params.toString() ? `?${params.toString()}` : '';
+        return this.get(`/dashboard/experiments/${encodeURIComponent(input.experiment_id)}/posterior/revenue${qs}`);
+    }
     /**
      * V0.5.48 — issue #18 Primitive 3 follow-up. Upload the Apple
      * promotional-offer signing key. Distinct from the ASC API key

package/dist/resources/experiment-posterior.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CapivvClient } from '../client.js';
+/**
+ * Bayesian posterior as an MCP resource (issue #18 follow-up). Agents
+ * that auto-attach matching resources get the experiment's posterior +
+ * recommendation in context without an explicit tool call. The list()
+ * walks the active experiments so a "list resources" call surfaces one
+ * URI per experiment.
+ *
+ * Companion tools (capivv_get_experiment_posterior, _cuped, _revenue)
+ * still cover the what-if + CUPED + revenue paths since those take
+ * arguments resources can't express.
+ */
+export declare function registerExperimentPosteriorResource(server: McpServer, client: CapivvClient): void;

package/dist/resources/experiment-posterior.js

@@ -0,0 +1,38 @@
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Bayesian posterior as an MCP resource (issue #18 follow-up). Agents
+ * that auto-attach matching resources get the experiment's posterior +
+ * recommendation in context without an explicit tool call. The list()
+ * walks the active experiments so a "list resources" call surfaces one
+ * URI per experiment.
+ *
+ * Companion tools (capivv_get_experiment_posterior, _cuped, _revenue)
+ * still cover the what-if + CUPED + revenue paths since those take
+ * arguments resources can't express.
+ */
+export function registerExperimentPosteriorResource(server, client) {
+    server.resource('experiment-posterior', new ResourceTemplate('capivv://experiments/{experimentId}/posterior', {
+        list: async () => {
+            const experiments = await client.listExperiments();
+            return {
+                resources: experiments.map((e) => ({
+                    uri: `capivv://experiments/${e.id}/posterior`,
+                    name: `${e.name} — posterior`,
+                    description: `Bayesian posterior (P(B>A), expected loss, credible interval, recommendation) for "${e.name}" [${e.status}]`,
+                    mimeType: 'application/json',
+                })),
+            };
+        },
+    }), { mimeType: 'application/json' }, async (uri, { experimentId }) => {
+        const id = Array.isArray(experimentId) ? experimentId[0] : experimentId;
+        const posterior = await client.getExperimentPosterior({ experiment_id: id });
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: JSON.stringify(posterior, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/resources/index.js

@@ -3,10 +3,12 @@ import { registerRulesResource } from './rules.js';
 import { registerConceptsResource } from './concepts.js';
 import { registerQuickstartResource } from './quickstart.js';
 import { registerGuideResources } from './guides.js';
+import { registerExperimentPosteriorResource } from './experiment-posterior.js';
 export function registerAllResources(server, client) {
     registerStatusResource(server, client);
     registerRulesResource(server, client);
     registerConceptsResource(server);
     registerQuickstartResource(server);
     registerGuideResources(server);
+    registerExperimentPosteriorResource(server, client);
 }

package/dist/tools/get-experiment-posterior-cuped.d.ts

@@ -0,0 +1,23 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CapivvClient } from '../client.js';
+/**
+ * V0.5.52 — CUPED-adjusted Bayesian posterior. Issue #18 analysis
+ * surface slice 4.
+ *
+ * Variance reduction using a per-user pre-experiment covariate
+ * ingested via `Capivv.identify({ preExperimentCovariates: {...} })`
+ * (the v0.5.51 ingest surface). When the covariate is predictive of
+ * the outcome, CUPED produces tighter posterior credible intervals
+ * for the same N — "free power" for small-N mobile experiments.
+ *
+ * Math: subtract the regression-estimated contribution of the
+ * covariate from each user's outcome, then run a Normal-Normal
+ * posterior on the difference of adjusted means. Falls back to the
+ * unadjusted binary posterior when < 30 users have the covariate
+ * (not enough data to fit a stable regression coefficient).
+ *
+ * Response includes the per-arm count of users with covariate
+ * observations so the operator can see how much CUPED actually had
+ * to work with.
+ */
+export declare function registerGetExperimentPosteriorCupedTool(server: McpServer, client: CapivvClient): void;

package/dist/tools/get-experiment-posterior-cuped.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+/**
+ * V0.5.52 — CUPED-adjusted Bayesian posterior. Issue #18 analysis
+ * surface slice 4.
+ *
+ * Variance reduction using a per-user pre-experiment covariate
+ * ingested via `Capivv.identify({ preExperimentCovariates: {...} })`
+ * (the v0.5.51 ingest surface). When the covariate is predictive of
+ * the outcome, CUPED produces tighter posterior credible intervals
+ * for the same N — "free power" for small-N mobile experiments.
+ *
+ * Math: subtract the regression-estimated contribution of the
+ * covariate from each user's outcome, then run a Normal-Normal
+ * posterior on the difference of adjusted means. Falls back to the
+ * unadjusted binary posterior when < 30 users have the covariate
+ * (not enough data to fit a stable regression coefficient).
+ *
+ * Response includes the per-arm count of users with covariate
+ * observations so the operator can see how much CUPED actually had
+ * to work with.
+ */
+export function registerGetExperimentPosteriorCupedTool(server, client) {
+    server.tool('capivv_get_experiment_posterior_cuped', "CUPED-adjusted Bayesian posterior. Pass the same covariate_name you use in Capivv.identify({ preExperimentCovariates: {...} }) — capivv joins each variant's assignments against your covariate data and returns the variance-reduced posterior. Use this when a pre-experiment baseline (e.g. lifetime_revenue_28d) is predictive of conversion.", {
+        experiment_id: z.string().uuid().describe('The experiment to analyze'),
+        covariate_name: z
+            .string()
+            .min(1)
+            .describe('The name of the covariate to adjust against. Must match what the SDK has been writing via `preExperimentCovariates`. Common names: "lifetime_revenue_28d", "session_count_7d", "previous_purchase_count".'),
+        decision_threshold_pct: z
+            .number()
+            .min(0)
+            .optional()
+            .describe('Minimum lift in percentage points to count as "worth shipping." Default 0.'),
+        prior_alpha: z
+            .number()
+            .positive()
+            .optional()
+            .describe('Beta prior α₀. Default 1 (uniform).'),
+        prior_beta: z
+            .number()
+            .positive()
+            .optional()
+            .describe('Beta prior β₀. Default 1 (uniform).'),
+    }, async (args) => {
+        const result = await client.getExperimentPosteriorCuped(args);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/get-experiment-posterior-revenue.d.ts

@@ -0,0 +1,23 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CapivvClient } from '../client.js';
+/**
+ * V0.5.53 — Bayesian posterior on revenue outcomes with optional
+ * trim/winsorize for heavy-tailed ARPU distributions. Issue #18
+ * analysis surface slice 5.
+ *
+ * Revenue is dominated by whales — standard variance estimators
+ * assume thin tails and produce nonsense credible intervals on
+ * small-N mobile data. Trimming (drop top K%) or winsorization (cap
+ * top K% at the threshold percentile) lets the posterior reflect
+ * the typical user without one whale skewing the entire arm.
+ *
+ * Reads conversion_value_micros per user from experiment_assignments.
+ * Non-converters contribute 0 micros (this is the per-user ARPU
+ * metric, not converters-only revenue). All thresholds and outputs
+ * are in micros (1 USD = 1_000_000 micros).
+ *
+ * Recommendation: trim_top_pct=5 or winsorize_top_pct=5 is a
+ * reasonable starting point for typical mobile-subscription revenue.
+ * Set both to 0 for the unadjusted posterior.
+ */
+export declare function registerGetExperimentPosteriorRevenueTool(server: McpServer, client: CapivvClient): void;

package/dist/tools/get-experiment-posterior-revenue.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+/**
+ * V0.5.53 — Bayesian posterior on revenue outcomes with optional
+ * trim/winsorize for heavy-tailed ARPU distributions. Issue #18
+ * analysis surface slice 5.
+ *
+ * Revenue is dominated by whales — standard variance estimators
+ * assume thin tails and produce nonsense credible intervals on
+ * small-N mobile data. Trimming (drop top K%) or winsorization (cap
+ * top K% at the threshold percentile) lets the posterior reflect
+ * the typical user without one whale skewing the entire arm.
+ *
+ * Reads conversion_value_micros per user from experiment_assignments.
+ * Non-converters contribute 0 micros (this is the per-user ARPU
+ * metric, not converters-only revenue). All thresholds and outputs
+ * are in micros (1 USD = 1_000_000 micros).
+ *
+ * Recommendation: trim_top_pct=5 or winsorize_top_pct=5 is a
+ * reasonable starting point for typical mobile-subscription revenue.
+ * Set both to 0 for the unadjusted posterior.
+ */
+export function registerGetExperimentPosteriorRevenueTool(server, client) {
+    server.tool('capivv_get_experiment_posterior_revenue', 'Bayesian posterior on revenue per assigned user (ARPU). Optional trim or winsorize handles whale-skew. Input + output are in micros (1 USD = 1_000_000 micros). Use trim_top_pct=5 or winsorize_top_pct=5 as a robust default for small-N mobile experiments.', {
+        experiment_id: z.string().uuid().describe('The experiment to analyze'),
+        decision_threshold: z
+            .number()
+            .min(0)
+            .optional()
+            .describe('Minimum lift in micros to count as "worth shipping." Default 0.'),
+        prior_alpha: z.number().positive().optional().describe('Beta prior α₀. Default 1.'),
+        prior_beta: z.number().positive().optional().describe('Beta prior β₀. Default 1.'),
+        trim_top_pct: z
+            .number()
+            .min(0)
+            .max(50)
+            .optional()
+            .describe('Drop the top K% by revenue before computing means. Default 0 (no trim). Mutually exclusive with winsorize_top_pct — trim wins if both set.'),
+        winsorize_top_pct: z
+            .number()
+            .min(0)
+            .max(50)
+            .optional()
+            .describe('Cap the top K% at the percentile threshold (preserves N). Default 0 (no winsorize). Use when sample size matters more than tail-handling.'),
+    }, async (args) => {
+        const result = await client.getExperimentPosteriorRevenue(args);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/index.js

@@ -54,6 +54,8 @@ import { registerStartExperimentTool } from './start-experiment.js';
 import { registerStopExperimentTool } from './stop-experiment.js';
 import { registerGetExperimentSummaryTool } from './get-experiment-summary.js';
 import { registerGetExperimentPosteriorTool } from './get-experiment-posterior.js';
+import { registerGetExperimentPosteriorCupedTool } from './get-experiment-posterior-cuped.js';
+import { registerGetExperimentPosteriorRevenueTool } from './get-experiment-posterior-revenue.js';
 import { registerUpdateAppTool } from './update-app.js';
 import { registerDeleteAppTool } from './delete-app.js';
 import { registerArchiveAppTool } from './archive-app.js';
@@ -172,6 +174,8 @@ export function registerAllTools(server, client) {
     registerStopExperimentTool(server, client);
     registerGetExperimentSummaryTool(server, client);
     registerGetExperimentPosteriorTool(server, client);
+    registerGetExperimentPosteriorCupedTool(server, client);
+    registerGetExperimentPosteriorRevenueTool(server, client);
     // Apps gap-fillers (V8 Phase B.6)
     registerUpdateAppTool(server, client);
     registerDeleteAppTool(server, client);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capivv/mcp-server",
-  "version": "0.5.51",
+  "version": "0.5.54",
   "description": "MCP server for managing Capivv subscription platform via AI assistants",
   "type": "module",
   "bin": {