@sentientui/mcp 0.12.0 → 0.13.0

package/dist/{chunk-BMOKDBGH.js → chunk-ZJ2JZ5RR.js}

@@ -730,7 +730,7 @@ function registerGoalTools(server, client) {
     "get_goal_funnel",
     {
       title: "Goal funnel",
-      description: "Get goal hit counts, unique-session conversion rates, and per-variant breakdown.",
+      description: "Get goal hit counts, unique-session conversion rates, and per-variant breakdown. This is a flat per-goal list \u2014 for multi-step funnel drop-off, use get_funnel_report.",
       inputSchema: { projectId: projectIdSchema },
       _meta: uiMeta("goal-funnel"),
       outputSchema: {
@@ -865,8 +865,137 @@ function registerGoalTools(server, client) {
   );
 }
 
-// src/tools/guardrails.ts
+// src/tools/funnels.ts
 import { z as z7 } from "zod";
+var funnelIdSchema = z7.string().describe('Funnel slug (from list_funnels), e.g. "checkout"');
+function registerFunnelTools(server, client) {
+  server.registerTool(
+    "list_funnels",
+    {
+      title: "List funnels",
+      description: `List the project's multi-step funnels \u2014 ordered goal steps plus the components serving them. Use get_funnel_report for a funnel's drop-off numbers. Reference a funnelId verbatim from code: <Adaptive funnel="<funnelId>">.`,
+      inputSchema: { projectId: projectIdSchema },
+      outputSchema: {
+        funnels: z7.array(
+          z7.object({
+            funnelId: z7.string().describe("Stable slug \u2014 use this exact string in code and in get_funnel_report"),
+            displayName: z7.string(),
+            status: z7.string().describe("draft | active | archived"),
+            windowDays: z7.number().describe("Conversion window in days"),
+            source: z7.string().describe("user | chat | editor | sdk"),
+            steps: z7.array(
+              z7.object({
+                stepIndex: z7.number(),
+                goalId: z7.string(),
+                weight: z7.number().nullable().describe("Manual optimizer credit for reaching this step (null = automatic end-weighted)")
+              })
+            ).describe("Ordered steps"),
+            components: z7.array(z7.object({ componentId: z7.string(), stepIndex: z7.number().nullable() })).describe("Components serving this funnel (stepIndex null = whole funnel)")
+          })
+        ).describe("Defined funnels (empty if none)")
+      },
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId }) => {
+      var _a;
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/funnels`);
+      const structuredContent = {
+        funnels: ((_a = data.funnels) != null ? _a : []).map((f) => ({
+          funnelId: f.funnel_id,
+          displayName: f.display_name,
+          status: f.status,
+          windowDays: f.window_days,
+          source: f.source,
+          // NUMERIC arrives serialized as a string; coerce.
+          steps: f.steps.map((s) => ({
+            stepIndex: s.step_index,
+            goalId: s.goal_id,
+            weight: s.weight == null ? null : Number(s.weight)
+          })),
+          components: f.components.map((c) => {
+            var _a2;
+            return { componentId: c.component_id, stepIndex: (_a2 = c.step_index) != null ? _a2 : null };
+          })
+        }))
+      };
+      if (structuredContent.funnels.length === 0) {
+        return {
+          content: [{
+            type: "text",
+            text: "No funnels defined yet. Build one in the dashboard (Goals \u2192 Funnels tab) or via the goal chat \u2014 a funnel is 2-12 ordered goal steps, e.g. add_to_cart \u2192 checkout \u2192 purchase."
+          }],
+          structuredContent
+        };
+      }
+      const lines = structuredContent.funnels.map(
+        (f) => `${f.funnelId} (${f.status}) \u2014 ${f.displayName}: ${f.steps.map((s) => s.goalId).join(" \u2192 ")}`
+      );
+      lines.push("", 'Reference a funnelId verbatim from code: <Adaptive funnel="<funnelId>">. Use get_funnel_report for drop-off numbers.');
+      return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
+    })
+  );
+  server.registerTool(
+    "get_funnel_report",
+    {
+      title: "Funnel drop-off report",
+      description: 'Per-step reach and drop-off for one funnel over its conversion window, with per-variant and audience splits per step, final-step revenue, and the holdout ("without optimization") comparison.',
+      inputSchema: { projectId: projectIdSchema, funnelId: funnelIdSchema },
+      outputSchema: {
+        funnelId: z7.string(),
+        displayName: z7.string(),
+        windowDays: z7.number(),
+        currency: z7.string().describe("Project display currency (ISO-4217) for the revenue fields"),
+        steps: z7.array(
+          z7.object({
+            stepIndex: z7.number(),
+            goalId: z7.string(),
+            displayName: z7.string(),
+            reached: z7.number().describe("Distinct visitors reaching this step in-window"),
+            dropOffFromPrevious: z7.number().nullable().describe("1 - reached/previousReached (null on the first step)"),
+            neverFired: z7.boolean().describe("True when the step goal has never been recorded anywhere \u2014 likely a typo"),
+            variants: z7.array(z7.object({
+              componentId: z7.string(),
+              variantId: z7.string(),
+              reached: z7.number(),
+              assigned: z7.number().describe("Distinct sessions served this variant in-window (the rate denominator)")
+            })),
+            personas: z7.array(z7.object({ label: z7.string(), reached: z7.number() }))
+          })
+        ),
+        revenue: z7.number().nullable().describe("Final-step revenue in the project currency (null when no valued conversions)"),
+        avgOrderValue: z7.number().nullable(),
+        revenuePerEnteringVisitor: z7.number().nullable(),
+        holdoutCompletion: z7.object({ entered: z7.number(), reached: z7.number() }).nullable().describe('Holdout visitors entering vs finishing \u2014 the "without optimization" line')
+      },
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, funnelId }) => {
+      const data = await client.get(`/projects/${encodeURIComponent(projectId)}/funnels/${encodeURIComponent(funnelId)}/report`);
+      const lines = [`${data.displayName} \u2014 last ${data.windowDays} days`];
+      for (const s of data.steps) {
+        lines.push(
+          `${s.stepIndex + 1}. ${s.displayName}: ${s.reached} reached` + (s.dropOffFromPrevious != null ? ` (${Math.round(s.dropOffFromPrevious * 100)}% drop-off from previous)` : "") + (s.neverFired ? " [never recorded \u2014 check the goal name]" : "")
+        );
+        for (const v of s.variants) {
+          lines.push(`   ${v.componentId}/${v.variantId}: ${v.reached}/${v.assigned} assigned sessions reached this step`);
+        }
+      }
+      if (data.revenue != null) {
+        lines.push(
+          `Revenue: ${data.revenue.toFixed(2)} ${data.currency}` + (data.avgOrderValue != null ? ` (${data.avgOrderValue.toFixed(2)} ${data.currency} avg order)` : "") + (data.revenuePerEnteringVisitor != null ? `, ${data.revenuePerEnteringVisitor.toFixed(2)} ${data.currency} per entering visitor` : "")
+        );
+      }
+      if (data.holdoutCompletion && data.holdoutCompletion.entered > 0) {
+        lines.push(`Without optimization: ${data.holdoutCompletion.reached} of ${data.holdoutCompletion.entered} holdout visitors finished.`);
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }], structuredContent: data };
+    })
+  );
+}
+
+// src/tools/guardrails.ts
+import { z as z8 } from "zod";
 function registerGuardrailTools(server, client) {
   server.registerTool(
     "list_guardrail_events",
@@ -875,11 +1004,11 @@ function registerGuardrailTools(server, client) {
       description: "List variants currently paused by the guardrail in the last 24 hours.",
       inputSchema: { projectId: projectIdSchema },
       outputSchema: {
-        events: z7.array(
-          z7.object({
-            componentId: z7.string(),
-            variantIds: z7.array(z7.string()).describe("Variants paused by the guardrail"),
-            pausedAt: z7.string().nullable().describe("ISO timestamp the pause fired, or null")
+        events: z8.array(
+          z8.object({
+            componentId: z8.string(),
+            variantIds: z8.array(z8.string()).describe("Variants paused by the guardrail"),
+            pausedAt: z8.string().nullable().describe("ISO timestamp the pause fired, or null")
           })
         ).describe("Guardrail events in the last 24h (empty if none)")
       },
@@ -914,7 +1043,7 @@ function registerGuardrailTools(server, client) {
 }
 
 // src/tools/layout.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 function registerLayoutTools(server, client) {
   server.registerTool(
     "get_layout_stats",
@@ -924,12 +1053,12 @@ function registerLayoutTools(server, client) {
       inputSchema: { projectId: projectIdSchema },
       _meta: uiMeta("layout-stats"),
       outputSchema: {
-        layouts: z8.array(
-          z8.object({
-            persona: z8.string(),
-            layoutOrder: z8.array(z8.string()).describe("Ranked section order for this persona"),
-            pulls: z8.number().describe("Number of times this arm was served"),
-            avgReward: z8.number().describe("Average bandit reward weight")
+        layouts: z9.array(
+          z9.object({
+            persona: z9.string(),
+            layoutOrder: z9.array(z9.string()).describe("Ranked section order for this persona"),
+            pulls: z9.number().describe("Number of times this arm was served"),
+            avgReward: z9.number().describe("Average bandit reward weight")
           })
         ).describe("Per-persona layout rankings (empty until enough sessions)")
       },
@@ -966,7 +1095,7 @@ function registerLayoutTools(server, client) {
 }
 
 // src/tools/variants.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 function registerVariantWriteTools(server, client) {
   server.registerTool(
     "create_variant",
@@ -975,19 +1104,19 @@ function registerVariantWriteTools(server, client) {
       description: "Create a NO-CODE managed text variant for a component (content stored in SentientUI, rendered by <AdaptiveText>). Use this ONLY for text-only variants the user wants without a code change. For variants that will live in the codebase (full components \u2014 copy, markup, styling), use get_variant_brief and write the variant in code instead; those auto-register on deploy and do not need create_variant. Requires a paid plan (server keys are Starter+; anonymous demo tokens are read-only).",
       inputSchema: {
         projectId: projectIdSchema,
-        componentId: z9.string().min(1).max(200).describe("The component ID to add a variant to"),
-        displayName: z9.string().min(1).max(200).describe("Human-readable name for the new variant"),
-        content: z9.string().max(1e4).optional().describe("The text content for this managed variant (rendered by <AdaptiveText>). Generate it from get_variant_brief context; omit only to create an empty placeholder to fill in from the dashboard.")
+        componentId: z10.string().min(1).max(200).describe("The component ID to add a variant to"),
+        displayName: z10.string().min(1).max(200).describe("Human-readable name for the new variant"),
+        content: z10.string().max(1e4).optional().describe("The text content for this managed variant (rendered by <AdaptiveText>). Generate it from get_variant_brief context; omit only to create an empty placeholder to fill in from the dashboard.")
       },
       outputSchema: {
-        variantId: z9.string().describe("The new variant ID"),
+        variantId: z10.string().describe("The new variant ID"),
         // API returns `body.displayName ?? null`, so a successful create can
         // carry a null name — match that contract or outputSchema validation
         // would reject an otherwise-successful response.
-        displayName: z9.string().nullable(),
-        componentId: z9.string(),
-        state: z9.literal("draft").describe("New managed variants start in draft state"),
-        hasContent: z9.boolean().describe("Whether text content was provided at creation")
+        displayName: z10.string().nullable(),
+        componentId: z10.string(),
+        state: z10.literal("draft").describe("New managed variants start in draft state"),
+        hasContent: z10.boolean().describe("Whether text content was provided at creation")
       },
       annotations: {
         readOnlyHint: false,
@@ -1025,13 +1154,13 @@ function registerVariantWriteTools(server, client) {
       description: "Pause a variant, stopping traffic from being assigned to it.",
       inputSchema: {
         projectId: projectIdSchema,
-        componentId: z9.string().describe("The component ID"),
-        variantId: z9.string().describe("The variant ID to pause")
+        componentId: z10.string().describe("The component ID"),
+        variantId: z10.string().describe("The variant ID to pause")
       },
       outputSchema: {
-        variantId: z9.string(),
-        componentId: z9.string(),
-        paused: z9.literal(true).describe("The variant is now paused")
+        variantId: z10.string(),
+        componentId: z10.string(),
+        paused: z10.literal(true).describe("The variant is now paused")
       },
       annotations: {
         readOnlyHint: false,
@@ -1059,8 +1188,8 @@ function registerVariantWriteTools(server, client) {
       description: "Trigger fresh AI insight generation for a project. Returns immediately; use get_insights in ~15 seconds to see results.",
       inputSchema: { projectId: projectIdSchema },
       outputSchema: {
-        projectId: z9.string(),
-        status: z9.literal("generating").describe("Generation has been triggered")
+        projectId: z10.string(),
+        status: z10.literal("generating").describe("Generation has been triggered")
       },
       annotations: {
         readOnlyHint: false,
@@ -1084,7 +1213,7 @@ function registerVariantWriteTools(server, client) {
 }
 
 // src/tools/variant-brief.ts
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 var GOAL_TARGET = 500;
 var BEST_PRACTICE_PRIORS = {
   ecommerce: [
@@ -1157,15 +1286,15 @@ function registerVariantBriefTools(server, client) {
       description: "Get an insight-driven brief for creating a new CODE-NATIVE variant of a component. Returns current variant performance, audience, insights, a data-sufficiency assessment (with a best-practice fallback when there is no data yet), and step-by-step instructions for writing the variant in the customer's code. Use this instead of create_variant when the variant will live in the codebase.",
       inputSchema: {
         projectId: projectIdSchema,
-        componentId: z10.string().describe('The component ID to write a new variant for (matches <Adaptive id="...">).')
+        componentId: z11.string().describe('The component ID to write a new variant for (matches <Adaptive id="...">).')
       },
       outputSchema: {
-        componentId: z10.string(),
-        contextType: z10.string().describe("The project's context type (or 'unknown')"),
-        dataState: z10.enum(["sufficient", "collecting", "empty"]).describe("Data-sufficiency assessment"),
-        existingVariantIds: z10.array(z10.string()).describe("Variant IDs already in use (do not reuse)"),
-        priors: z10.array(z10.string()).describe("Best-practice priors applied for this context type"),
-        markdown: z10.string().describe("The full variant brief in Markdown")
+        componentId: z11.string(),
+        contextType: z11.string().describe("The project's context type (or 'unknown')"),
+        dataState: z11.enum(["sufficient", "collecting", "empty"]).describe("Data-sufficiency assessment"),
+        existingVariantIds: z11.array(z11.string()).describe("Variant IDs already in use (do not reuse)"),
+        priors: z11.array(z11.string()).describe("Best-practice priors applied for this context type"),
+        markdown: z11.string().describe("The full variant brief in Markdown")
       },
       annotations: {
         readOnlyHint: true,
@@ -1282,7 +1411,7 @@ function registerVariantBriefTools(server, client) {
 }
 
 // src/tools/test-brief.ts
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 async function settled2(p) {
   try {
     return await p;
@@ -1298,13 +1427,13 @@ function registerTestBriefTools(server, client) {
       description: "Get a ready-to-paste test for a SentientUI-wrapped component, populated with the component's real variants and goals. This project uses @sentientui/react/testing. Use this so your tests force a specific variant/layout deterministically and never break when the optimizer serves a different version. Returns a React Testing Library example plus the URL-param recipe for E2E (Playwright/Cypress).",
       inputSchema: {
         projectId: projectIdSchema,
-        componentId: z11.string().describe('The component ID to write a test for (matches <Adaptive id="...">).')
+        componentId: z12.string().describe('The component ID to write a test for (matches <Adaptive id="...">).')
       },
       outputSchema: {
-        componentId: z11.string(),
-        forcedVariantId: z11.string().describe("The non-control variant the example forces"),
-        goalName: z11.string().describe("The goal the example asserts fires"),
-        markdown: z11.string().describe("The full test brief in Markdown")
+        componentId: z12.string(),
+        forcedVariantId: z12.string().describe("The non-control variant the example forces"),
+        goalName: z12.string().describe("The goal the example asserts fires"),
+        markdown: z12.string().describe("The full test brief in Markdown")
       },
       annotations: {
         readOnlyHint: true,
@@ -1387,7 +1516,7 @@ function registerTestBriefTools(server, client) {
 }
 
 // src/tools/integration-guide.ts
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 var GUIDE = `# SentientUI integration guide \u2014 the adaptive ladder
 
 SentientUI adapts a site per visitor type (personas: buyer, researcher, deal_seeker, browser,
@@ -1462,7 +1591,7 @@ function registerIntegrationGuideTools(server) {
       description: "Get the SentientUI adaptive-ladder integration guide: setup (keyless and keyed) plus copy-pasteable examples for every rung (Style, Swap, Reorder). Use this to integrate SentientUI into a codebase.",
       inputSchema: {},
       outputSchema: {
-        guide: z12.string().describe("The full integration guide in Markdown")
+        guide: z13.string().describe("The full integration guide in Markdown")
       },
       annotations: {
         readOnlyHint: true,
@@ -1478,7 +1607,7 @@ function registerIntegrationGuideTools(server) {
 }
 
 // src/tools/agent-traffic.ts
-import { z as z13 } from "zod";
+import { z as z14 } from "zod";
 var PLAN_GATE_GUIDANCE = {
   agent_analytics_requires_paid_plan: "Agent analytics requires a paid SentientUI plan (Starter or above). Upgrade at https://sentient-ui.com, then try again."
 };
@@ -1490,19 +1619,19 @@ function registerAgentTrafficTools(server, client) {
       description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, agentic browsers, agent API calls), engine breakdown, and the paths they fetch most. Agent traffic is tracked separately and never counted in conversion rate.",
       inputSchema: { projectId: projectIdSchema },
       outputSchema: {
-        totals: z13.object({ crawler: z13.number(), api: z13.number(), browser: z13.number() }),
-        engines: z13.array(
-          z13.object({
-            engine: z13.string(),
-            intent: z13.string().describe("user | search | training | other"),
-            count: z13.number(),
-            sharePct: z13.number(),
-            lastSeen: z13.string(),
-            firstSeenInRange: z13.boolean().describe("First observed within the queried period")
+        totals: z14.object({ crawler: z14.number(), api: z14.number(), browser: z14.number() }),
+        engines: z14.array(
+          z14.object({
+            engine: z14.string(),
+            intent: z14.string().describe("user | search | training | other"),
+            count: z14.number(),
+            sharePct: z14.number(),
+            lastSeen: z14.string(),
+            firstSeenInRange: z14.boolean().describe("First observed within the queried period")
           })
         ),
-        intents: z13.object({ user: z13.number(), search: z13.number(), training: z13.number(), other: z13.number() }).describe("Crawler fetches by purpose: user = an assistant answering a real person live"),
-        topPaths: z13.array(z13.object({ path: z13.string(), count: z13.number(), engines: z13.number() }))
+        intents: z14.object({ user: z14.number(), search: z14.number(), training: z14.number(), other: z14.number() }).describe("Crawler fetches by purpose: user = an assistant answering a real person live"),
+        topPaths: z14.array(z14.object({ path: z14.string(), count: z14.number(), engines: z14.number() }))
       },
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
@@ -1540,26 +1669,26 @@ function registerAgentTrafficTools(server, client) {
       description: "Whether the pages AI agents actually read are machine-legible: per-path checks for price, product name, positioning, and CTA in the server HTML, plus agent API blocks served without agent data. Each failure comes with a concrete fix.",
       inputSchema: { projectId: projectIdSchema },
       outputSchema: {
-        paths: z13.array(
-          z13.object({
-            path: z13.string(),
-            score: z13.number().describe("0\u2013100, 25 per passing check"),
-            checks: z13.object({
-              price: z13.boolean(),
-              name: z13.boolean(),
-              positioning: z13.boolean(),
-              cta: z13.boolean(),
-              notes: z13.array(z13.string())
+        paths: z14.array(
+          z14.object({
+            path: z14.string(),
+            score: z14.number().describe("0\u2013100, 25 per passing check"),
+            checks: z14.object({
+              price: z14.boolean(),
+              name: z14.boolean(),
+              positioning: z14.boolean(),
+              cta: z14.boolean(),
+              notes: z14.array(z14.string())
             }),
-            fixes: z13.array(z13.object({
-              check: z13.string(),
-              advice: z13.string(),
-              snippet: z13.string().optional()
+            fixes: z14.array(z14.object({
+              check: z14.string(),
+              advice: z14.string(),
+              snippet: z14.string().optional()
             })).optional().describe("Concrete Next.js remediation per failing check"),
-            lastChecked: z13.string()
+            lastChecked: z14.string()
           })
         ),
-        emptyBlocks: z13.array(z13.object({ block: z13.string(), variant: z13.string(), occurrences: z13.number() }))
+        emptyBlocks: z14.array(z14.object({ block: z14.string(), variant: z14.string(), occurrences: z14.number() }))
       },
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
@@ -1596,7 +1725,7 @@ function registerAgentTrafficTools(server, client) {
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.12.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.13.0" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new McpServer(
     {
@@ -1623,6 +1752,7 @@ function createMcpServer(client) {
   registerInsightTools(server, client);
   registerPersonaTools(server, client);
   registerGoalTools(server, client);
+  registerFunnelTools(server, client);
   registerGuardrailTools(server, client);
   registerLayoutTools(server, client);
   registerVariantBriefTools(server, client);