@sentientui/mcp 0.8.0 → 0.8.2

package/dist/{chunk-E34O3H2Z.js → chunk-GLL5CMBY.js}

@@ -7,16 +7,15 @@ var ApiError = class extends Error {
     this.status = status;
     this.name = "ApiError";
   }
-  status;
 };
 var ApiClient = class {
-  baseUrl;
-  apiKey;
   constructor(opts) {
+    var _a;
     this.apiKey = opts.apiKey;
-    this.baseUrl = (opts.baseUrl ?? "https://api.sentient-ui.com").replace(/\/$/, "");
+    this.baseUrl = ((_a = opts.baseUrl) != null ? _a : "https://api.sentient-ui.com").replace(/\/$/, "");
   }
   async get(path) {
+    var _a;
     const res = await fetch(`${this.baseUrl}/v1/mgmt${path}`, {
       headers: {
         authorization: `Bearer ${this.apiKey}`,
@@ -25,11 +24,12 @@ var ApiClient = class {
     });
     if (!res.ok) {
       const body = await res.json().catch(() => ({}));
-      throw new ApiError(res.status, String(body.error ?? res.statusText));
+      throw new ApiError(res.status, String((_a = body.error) != null ? _a : res.statusText));
     }
     return res.json();
   }
   async post(path, body) {
+    var _a;
     const res = await fetch(`${this.baseUrl}/v1/mgmt${path}`, {
       method: "POST",
       headers: {
@@ -40,35 +40,64 @@ var ApiClient = class {
     });
     if (!res.ok) {
       const errBody = await res.json().catch(() => ({}));
-      throw new ApiError(res.status, String(errBody.error ?? res.statusText));
+      throw new ApiError(res.status, String((_a = errBody.error) != null ? _a : res.statusText));
     }
     return res.json();
   }
 };
 
 // src/server.ts
-import { createRequire } from "module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 // src/tools/projects.ts
+import { z as z2 } from "zod";
+
+// src/tools/common.ts
 import { z } from "zod";
 var projectIdSchema = z.string().uuid().describe("The project UUID");
-function createProjectGuidance(err) {
+function apiErrorGuidance(err, extra) {
+  if (extra && Object.prototype.hasOwnProperty.call(extra, err.message)) {
+    return extra[err.message];
+  }
   switch (err.message) {
     case "insufficient_scope":
-      return "Creating a project needs an account login. Connect via the hosted MCP URL (https://api.sentient-ui.com/mcp) and sign in \u2014 a project-scoped server key (sk_\u2026) cannot create projects.";
+      return "This action needs an account login. Connect via the hosted MCP URL (https://api.sentient-ui.com/mcp) and sign in \u2014 a project-scoped server key (sk_\u2026) or anonymous demo token cannot do this.";
     case "demo_read_only":
-      return "Demo mode is read-only. Create a SentientUI account and sign in to make projects.";
+      return "Demo mode is read-only. Create a SentientUI account and sign in (or use a project server key) to make changes.";
     case "insufficient_role":
-      return "Your account role cannot create projects \u2014 this needs the account owner or an admin.";
-    case "project_limit_reached":
-      return "You've reached your plan's project limit. Upgrade your plan or remove an existing project, then try again.";
-    case "name_required":
-      return "A project name is required to create a project.";
+      return "Your account role does not permit this action \u2014 it needs the account owner or an admin.";
     default:
-      return null;
+      break;
+  }
+  if (err.status === 402) {
+    return `This feature requires a higher plan (${err.message}). Upgrade your SentientUI plan, then try again.`;
   }
+  if (err.status === 403) {
+    return `Access denied (${err.message}). Check that your key or login has access to this project.`;
+  }
+  return null;
 }
+function withApiErrorGuidance(fn, extra) {
+  return async (args) => {
+    try {
+      return await fn(args);
+    } catch (err) {
+      if (err instanceof ApiError) {
+        const guidance = apiErrorGuidance(err, extra);
+        if (guidance) {
+          return { content: [{ type: "text", text: guidance }], isError: true };
+        }
+      }
+      throw err;
+    }
+  };
+}
+
+// src/tools/projects.ts
+var CREATE_PROJECT_GUIDANCE = {
+  project_limit_reached: "You've reached your plan's project limit. Upgrade your plan or remove an existing project, then try again.",
+  name_required: "A project name is required to create a project."
+};
 function registerProjectTools(server, client) {
   server.registerTool(
     "create_project",
@@ -76,16 +105,16 @@ function registerProjectTools(server, client) {
       title: "Create project",
       description: "Create a NEW SentientUI project (onboarding). Returns the project id and its pk_ public key for the SDK. Requires an account login: this works when connected via OAuth (the hosted MCP URL) but NOT with a project-scoped sk_ server key or an anonymous demo token. After it succeeds, call get_integration_guide and help the user install @sentientui/react with the returned key.",
       inputSchema: {
-        name: z.string().min(1).describe("Human-readable project name"),
-        contextType: z.enum(["saas", "ecommerce", "marketing", "landing", "internal"]).optional().describe("What kind of product this is; defaults to saas"),
-        framework: z.enum(["next", "react", "core"]).optional().describe("How the site is built \u2014 next, react, or core (website builder/CMS); defaults to next"),
-        websiteUrl: z.string().optional().describe("Production site origin to allow-list so the SDK's events aren't origin-blocked on day one")
+        name: z2.string().min(1).describe("Human-readable project name"),
+        contextType: z2.enum(["saas", "ecommerce", "marketing", "landing", "internal"]).optional().describe("What kind of product this is; defaults to saas"),
+        framework: z2.enum(["next", "react", "core"]).optional().describe("How the site is built \u2014 next, react, or core (website builder/CMS); defaults to next"),
+        websiteUrl: z2.string().optional().describe("Production site origin to allow-list so the SDK's events aren't origin-blocked on day one")
       },
       outputSchema: {
-        projectId: z.string().describe("The new project UUID"),
-        publicKey: z.string().describe("The pk_ public key to configure the SDK with"),
-        name: z.string().describe("The project name"),
-        contextType: z.string().describe("The resolved context type")
+        projectId: z2.string().describe("The new project UUID"),
+        publicKey: z2.string().describe("The pk_ public key to configure the SDK with"),
+        name: z2.string().describe("The project name"),
+        contextType: z2.string().describe("The resolved context type")
       },
       annotations: {
         readOnlyHint: false,
@@ -94,41 +123,31 @@ function registerProjectTools(server, client) {
         openWorldHint: false
       }
     },
-    async ({ name, contextType, framework, websiteUrl }) => {
-      try {
-        const created = await client.post("/projects", {
+    withApiErrorGuidance(async ({ name, contextType, framework, websiteUrl }) => {
+      const created = await client.post("/projects", {
+        name,
+        contextType,
+        framework,
+        origin: websiteUrl
+      });
+      const resolvedContextType = contextType != null ? contextType : "saas";
+      return {
+        content: [{
+          type: "text",
+          text: [
+            `Created project "${name}" (id: ${created.id}, type: ${resolvedContextType}).`,
+            `Public key: ${created.apiKey}`,
+            `Next: install @sentientui/react with this key. Ask me to pull the setup guide (get_integration_guide) and I'll wrap your first component.`
+          ].join("\n")
+        }],
+        structuredContent: {
+          projectId: created.id,
+          publicKey: created.apiKey,
           name,
-          contextType,
-          framework,
-          origin: websiteUrl
-        });
-        const resolvedContextType = contextType ?? "saas";
-        return {
-          content: [{
-            type: "text",
-            text: [
-              `Created project "${name}" (id: ${created.id}, type: ${resolvedContextType}).`,
-              `Public key: ${created.apiKey}`,
-              `Next: install @sentientui/react with this key. Ask me to pull the setup guide (get_integration_guide) and I'll wrap your first component.`
-            ].join("\n")
-          }],
-          structuredContent: {
-            projectId: created.id,
-            publicKey: created.apiKey,
-            name,
-            contextType: resolvedContextType
-          }
-        };
-      } catch (err) {
-        if (err instanceof ApiError) {
-          const guidance = createProjectGuidance(err);
-          if (guidance) {
-            return { content: [{ type: "text", text: guidance }], isError: true };
-          }
+          contextType: resolvedContextType
         }
-        throw err;
-      }
-    }
+      };
+    }, CREATE_PROJECT_GUIDANCE)
   );
   server.registerTool(
     "list_projects",
@@ -137,12 +156,12 @@ function registerProjectTools(server, client) {
       description: "List all SentientUI projects for the authenticated account.",
       inputSchema: {},
       outputSchema: {
-        projects: z.array(
-          z.object({
-            id: z.string().describe("Project UUID"),
-            name: z.string(),
-            contextType: z.string(),
-            createdAt: z.string().describe("ISO date (YYYY-MM-DD)")
+        projects: z2.array(
+          z2.object({
+            id: z2.string().describe("Project UUID"),
+            name: z2.string(),
+            contextType: z2.string(),
+            createdAt: z2.string().describe("ISO date (YYYY-MM-DD)")
           })
         ).describe("All projects for the account (empty if none)")
       },
@@ -152,7 +171,7 @@ function registerProjectTools(server, client) {
         openWorldHint: false
       }
     },
-    async () => {
+    withApiErrorGuidance(async () => {
       const projects = await client.get("/projects");
       const text = projects.length === 0 ? "No projects found." : projects.map(
         (p) => `- ${p.name} (id: ${p.id}, type: ${p.context_type}, created: ${p.created_at.slice(0, 10)})`
@@ -168,7 +187,7 @@ function registerProjectTools(server, client) {
           }))
         }
       };
-    }
+    })
   );
   server.registerTool(
     "get_project_stats",
@@ -177,11 +196,11 @@ function registerProjectTools(server, client) {
       description: "Get health stats for a project: event volume, session count, agent calls, and status.",
       inputSchema: { projectId: projectIdSchema },
       outputSchema: {
-        status: z.string().describe("Overall project health status"),
-        events24h: z.number().describe("Events in the last 24 hours"),
-        sessions24h: z.number().describe("Sessions in the last 24 hours"),
-        agentCalls: z.number().describe("Total agent (MCP/API) calls"),
-        lastEventAt: z.string().nullable().describe("ISO timestamp of the last event, or null")
+        status: z2.string().describe("Overall project health status"),
+        events24h: z2.number().describe("Events in the last 24 hours"),
+        sessions24h: z2.number().describe("Sessions in the last 24 hours"),
+        agentCalls: z2.number().describe("Total agent (MCP/API) calls"),
+        lastEventAt: z2.string().nullable().describe("ISO timestamp of the last event, or null")
       },
       annotations: {
         readOnlyHint: true,
@@ -189,7 +208,8 @@ function registerProjectTools(server, client) {
         openWorldHint: false
       }
     },
-    async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId }) => {
+      var _a;
       const id = encodeURIComponent(projectId);
       const stats = await client.get(`/projects/${id}/health`);
       const text = [
@@ -197,7 +217,7 @@ function registerProjectTools(server, client) {
         `Events (24h): ${stats.events24h}`,
         `Sessions (24h): ${stats.sessions24h}`,
         `Agent calls (total): ${stats.agentCalls}`,
-        `Last event: ${stats.lastEventAt ?? "never"}`
+        `Last event: ${(_a = stats.lastEventAt) != null ? _a : "never"}`
       ].join("\n");
       return {
         content: [{ type: "text", text }],
@@ -209,12 +229,12 @@ function registerProjectTools(server, client) {
           lastEventAt: stats.lastEventAt
         }
       };
-    }
+    })
   );
 }
 
 // src/tools/components.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 
 // src/ui/templates.ts
 var VIZ_TITLES = {
@@ -473,21 +493,20 @@ function registerUiResources(server) {
 }
 
 // src/tools/components.ts
-var projectIdSchema2 = z2.string().uuid().describe("The project UUID");
 function registerComponentTools(server, client) {
   server.registerTool(
     "list_components",
     {
       title: "List components",
       description: "List all adaptive components in a project with variant counts and impression totals.",
-      inputSchema: { projectId: projectIdSchema2 },
+      inputSchema: { projectId: projectIdSchema },
       outputSchema: {
-        components: z2.array(
-          z2.object({
-            componentId: z2.string(),
-            variantCount: z2.number(),
-            impressions: z2.number(),
-            conversions: z2.number()
+        components: z3.array(
+          z3.object({
+            componentId: z3.string(),
+            variantCount: z3.number(),
+            impressions: z3.number(),
+            conversions: z3.number()
           })
         ).describe("Adaptive components in the project (empty if none)")
       },
@@ -497,7 +516,7 @@ function registerComponentTools(server, client) {
         openWorldHint: false
       }
     },
-    async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId }) => {
       const id = encodeURIComponent(projectId);
       const { components } = await client.get(`/projects/${id}/components`);
       const structuredContent = {
@@ -518,23 +537,23 @@ function registerComponentTools(server, client) {
         (c) => `- ${c.component_id}: ${c.variants.length} variants, ${c.total_impressions} impressions, ${c.total_conversions} conversions`
       ).join("\n");
       return { content: [{ type: "text", text }], structuredContent };
-    }
+    })
   );
   server.registerTool(
     "get_variant_performance",
     {
       title: "Variant performance",
       description: "Get CVR and momentum for all variants in a project over the last 7 days vs prior 7 days.",
-      inputSchema: { projectId: projectIdSchema2 },
+      inputSchema: { projectId: projectIdSchema },
       _meta: uiMeta("variant-performance"),
       outputSchema: {
-        variants: z2.array(
-          z2.object({
-            variantId: z2.string(),
-            currentCvr: z2.number().describe("Conversion rate over the last 7 days (0-1)"),
-            priorCvr: z2.number().describe("Conversion rate over the prior 7 days (0-1)"),
-            deltaPp: z2.number().describe("Change in percentage points"),
-            momentum: z2.string().describe("Momentum direction: gaining, losing, or stable")
+        variants: z3.array(
+          z3.object({
+            variantId: z3.string(),
+            currentCvr: z3.number().describe("Conversion rate over the last 7 days (0-1)"),
+            priorCvr: z3.number().describe("Conversion rate over the prior 7 days (0-1)"),
+            deltaPp: z3.number().describe("Change in percentage points"),
+            momentum: z3.string().describe("Momentum direction: gaining, losing, or stable")
           })
         ).describe("Per-variant performance (empty if no data yet)")
       },
@@ -544,20 +563,24 @@ function registerComponentTools(server, client) {
         openWorldHint: false
       }
     },
-    async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId }) => {
+      var _a, _b, _c;
       const id = encodeURIComponent(projectId);
       const data = await client.get(`/projects/${id}/trends`);
-      const momentumMap = new Map((data.momentum ?? []).map((m) => [m.variantId, m.direction]));
+      const momentumMap = new Map(((_a = data.momentum) != null ? _a : []).map((m) => [m.variantId, m.direction]));
       const structuredContent = {
-        variants: (data.cvr ?? []).map((v) => ({
-          variantId: v.variantId,
-          currentCvr: v.currentCvr,
-          priorCvr: v.priorCvr,
-          deltaPp: v.deltaPp,
-          momentum: momentumMap.get(v.variantId) ?? "stable"
-        }))
+        variants: ((_b = data.cvr) != null ? _b : []).map((v) => {
+          var _a2;
+          return {
+            variantId: v.variantId,
+            currentCvr: v.currentCvr,
+            priorCvr: v.priorCvr,
+            deltaPp: v.deltaPp,
+            momentum: (_a2 = momentumMap.get(v.variantId)) != null ? _a2 : "stable"
+          };
+        })
       };
-      if (!data.cvr?.length) {
+      if (!((_c = data.cvr) == null ? void 0 : _c.length)) {
         return {
           content: [{ type: "text", text: "No variant data available yet." }],
           structuredContent,
@@ -565,29 +588,31 @@ function registerComponentTools(server, client) {
         };
       }
       const text = data.cvr.map(
-        (v) => `- ${v.variantId}: CVR ${(v.currentCvr * 100).toFixed(2)}% (prior ${(v.priorCvr * 100).toFixed(2)}%, ${v.deltaPp > 0 ? "+" : ""}${v.deltaPp.toFixed(1)} pp, ${momentumMap.get(v.variantId) ?? "stable"})`
+        (v) => {
+          var _a2;
+          return `- ${v.variantId}: CVR ${(v.currentCvr * 100).toFixed(2)}% (prior ${(v.priorCvr * 100).toFixed(2)}%, ${v.deltaPp > 0 ? "+" : ""}${v.deltaPp.toFixed(1)} pp, ${(_a2 = momentumMap.get(v.variantId)) != null ? _a2 : "stable"})`;
+        }
       ).join("\n");
       return { content: [{ type: "text", text }], structuredContent, _meta: uiMeta("variant-performance") };
-    }
+    })
   );
 }
 
 // src/tools/insights.ts
-import { z as z3 } from "zod";
-var projectIdSchema3 = z3.string().uuid().describe("The project UUID");
+import { z as z4 } from "zod";
 function registerInsightTools(server, client) {
   server.registerTool(
     "get_insights",
     {
       title: "Get insights",
       description: "Get the latest AI-generated insights: narrator observations and (Growth tier) advisor recommendations.",
-      inputSchema: { projectId: projectIdSchema3 },
+      inputSchema: { projectId: projectIdSchema },
       outputSchema: {
-        status: z3.enum(["ok", "empty"]).describe("Whether insights exist yet"),
-        observations: z3.array(z3.string()).describe("Narrator observations"),
-        recommendations: z3.array(z3.string()).describe("Advisor recommendations (Growth tier)"),
-        isStale: z3.boolean().describe("True when the insights are older than ~6h"),
-        generatedAt: z3.string().nullable().describe("ISO timestamp the insights were generated, or null")
+        status: z4.enum(["ok", "empty"]).describe("Whether insights exist yet"),
+        observations: z4.array(z4.string()).describe("Narrator observations"),
+        recommendations: z4.array(z4.string()).describe("Advisor recommendations (Growth tier)"),
+        isStale: z4.boolean().describe("True when the insights are older than ~6h"),
+        generatedAt: z4.string().nullable().describe("ISO timestamp the insights were generated, or null")
       },
       annotations: {
         readOnlyHint: true,
@@ -595,7 +620,8 @@ function registerInsightTools(server, client) {
         openWorldHint: false
       }
     },
-    async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId }) => {
+      var _a, _b, _c, _d;
       const id = encodeURIComponent(projectId);
       const data = await client.get(`/projects/${id}/insights`);
       if (data.status === "empty") {
@@ -610,8 +636,8 @@ function registerInsightTools(server, client) {
           }
         };
       }
-      const observations = data.narratorBullets ?? [];
-      const recommendations = data.advisorBullets ?? [];
+      const observations = (_a = data.narratorBullets) != null ? _a : [];
+      const recommendations = (_b = data.advisorBullets) != null ? _b : [];
       const lines = [];
       if (data.isStale) lines.push("\u26A0 Insights are stale (>6h old). Consider calling refresh_insights.");
       if (data.generatedAt) lines.push(`Generated: ${new Date(data.generatedAt).toUTCString()}`);
@@ -629,33 +655,32 @@ function registerInsightTools(server, client) {
           status: "ok",
           observations,
           recommendations,
-          isStale: data.isStale ?? false,
-          generatedAt: data.generatedAt ?? null
+          isStale: (_c = data.isStale) != null ? _c : false,
+          generatedAt: (_d = data.generatedAt) != null ? _d : null
         }
       };
-    }
+    })
   );
 }
 
 // src/tools/personas.ts
-import { z as z4 } from "zod";
-var projectIdSchema4 = z4.string().uuid().describe("The project UUID");
+import { z as z5 } from "zod";
 function registerPersonaTools(server, client) {
   server.registerTool(
     "get_persona_breakdown",
     {
       title: "Persona breakdown",
       description: "Get the distribution of visitor persona clusters with session counts and reliability scores.",
-      inputSchema: { projectId: projectIdSchema4 },
+      inputSchema: { projectId: projectIdSchema },
       _meta: uiMeta("persona-breakdown"),
       outputSchema: {
-        totalSessions: z4.number().describe("Total sessions across all clusters"),
-        clusters: z4.array(
-          z4.object({
-            label: z4.string(),
-            sessionCount: z4.number(),
-            sharePct: z4.number().describe("Share of total traffic (0-100)"),
-            reliability: z4.number().describe("Average cluster reliability (0-1)")
+        totalSessions: z5.number().describe("Total sessions across all clusters"),
+        clusters: z5.array(
+          z5.object({
+            label: z5.string(),
+            sessionCount: z5.number(),
+            sharePct: z5.number().describe("Share of total traffic (0-100)"),
+            reliability: z5.number().describe("Average cluster reliability (0-1)")
           })
         ).describe("Persona clusters (empty until enough visitor data)")
       },
@@ -665,7 +690,7 @@ function registerPersonaTools(server, client) {
         openWorldHint: false
       }
     },
-    async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId }) => {
       const id = encodeURIComponent(projectId);
       const data = await client.get(`/projects/${id}/portraits`);
       const structuredContent = {
@@ -694,33 +719,32 @@ function registerPersonaTools(server, client) {
         })
       ];
       return { content: [{ type: "text", text: lines.join("\n") }], structuredContent, _meta: uiMeta("persona-breakdown") };
-    }
+    })
   );
 }
 
 // src/tools/goals.ts
-import { z as z5 } from "zod";
-var projectIdSchema5 = z5.string().uuid().describe("The project UUID");
+import { z as z6 } from "zod";
 function registerGoalTools(server, client) {
   server.registerTool(
     "get_goal_funnel",
     {
       title: "Goal funnel",
       description: "Get goal hit counts, unique-session conversion rates, and per-variant breakdown.",
-      inputSchema: { projectId: projectIdSchema5 },
+      inputSchema: { projectId: projectIdSchema },
       _meta: uiMeta("goal-funnel"),
       outputSchema: {
-        goals: z5.array(
-          z5.object({
-            goalName: z5.string(),
-            hits: z5.number(),
-            uniqueSessions: z5.number(),
-            conversionRate: z5.number().describe("Unique-session conversion rate (0-1)"),
-            variants: z5.array(
-              z5.object({
-                componentId: z5.string(),
-                variantId: z5.string(),
-                completionRate: z5.number().describe("Completion rate per assigned session (0-1)")
+        goals: z6.array(
+          z6.object({
+            goalName: z6.string(),
+            hits: z6.number(),
+            uniqueSessions: z6.number(),
+            conversionRate: z6.number().describe("Unique-session conversion rate (0-1)"),
+            variants: z6.array(
+              z6.object({
+                componentId: z6.string(),
+                variantId: z6.string(),
+                completionRate: z6.number().describe("Completion rate per assigned session (0-1)")
               })
             ).describe("Per-variant breakdown")
           })
@@ -732,7 +756,7 @@ function registerGoalTools(server, client) {
         openWorldHint: false
       }
     },
-    async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId }) => {
       const id = encodeURIComponent(projectId);
       const data = await client.get(`/projects/${id}/goals`);
       const structuredContent = {
@@ -761,26 +785,25 @@ function registerGoalTools(server, client) {
         ""
       ]);
       return { content: [{ type: "text", text: lines.join("\n").trim() }], structuredContent, _meta: uiMeta("goal-funnel") };
-    }
+    })
   );
 }
 
 // src/tools/guardrails.ts
-import { z as z6 } from "zod";
-var projectIdSchema6 = z6.string().uuid().describe("The project UUID");
+import { z as z7 } from "zod";
 function registerGuardrailTools(server, client) {
   server.registerTool(
     "list_guardrail_events",
     {
       title: "List guardrail events",
       description: "List variants currently paused by the guardrail in the last 24 hours.",
-      inputSchema: { projectId: projectIdSchema6 },
+      inputSchema: { projectId: projectIdSchema },
       outputSchema: {
-        events: z6.array(
-          z6.object({
-            componentId: z6.string(),
-            variantIds: z6.array(z6.string()).describe("Variants paused by the guardrail"),
-            pausedAt: z6.string().nullable().describe("ISO timestamp the pause fired, or null")
+        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")
           })
         ).describe("Guardrail events in the last 24h (empty if none)")
       },
@@ -790,7 +813,7 @@ function registerGuardrailTools(server, client) {
         openWorldHint: false
       }
     },
-    async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId }) => {
       const id = encodeURIComponent(projectId);
       const data = await client.get(`/projects/${id}/guardrail-events`);
       const structuredContent = {
@@ -810,28 +833,27 @@ function registerGuardrailTools(server, client) {
         (e) => `- ${e.componentId}: variants [${e.variantIds.join(", ")}] paused${e.pausedAt ? ` at ${e.pausedAt}` : ""}`
       );
       return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
-    }
+    })
   );
 }
 
 // src/tools/layout.ts
-import { z as z7 } from "zod";
-var projectIdSchema7 = z7.string().uuid().describe("The project UUID");
+import { z as z8 } from "zod";
 function registerLayoutTools(server, client) {
   server.registerTool(
     "get_layout_stats",
     {
       title: "Layout stats",
       description: "Get per-persona section layout rankings and bandit reward weights.",
-      inputSchema: { projectId: projectIdSchema7 },
+      inputSchema: { projectId: projectIdSchema },
       _meta: uiMeta("layout-stats"),
       outputSchema: {
-        layouts: z7.array(
-          z7.object({
-            persona: z7.string(),
-            layoutOrder: z7.array(z7.string()).describe("Ranked section order for this persona"),
-            pulls: z7.number().describe("Number of times this arm was served"),
-            avgReward: z7.number().describe("Average bandit reward weight")
+        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")
           })
         ).describe("Per-persona layout rankings (empty until enough sessions)")
       },
@@ -841,7 +863,7 @@ function registerLayoutTools(server, client) {
         openWorldHint: false
       }
     },
-    async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId }) => {
       const id = encodeURIComponent(projectId);
       const stats = await client.get(`/projects/${id}/layout-stats`);
       const structuredContent = {
@@ -863,13 +885,12 @@ function registerLayoutTools(server, client) {
         (s) => `- ${s.persona}: [${s.layoutOrder.join(" \u2192 ")}] (avg reward: ${s.avgReward.toFixed(2)}, ${s.pulls} pulls)`
       ).join("\n");
       return { content: [{ type: "text", text }], structuredContent, _meta: uiMeta("layout-stats") };
-    }
+    })
   );
 }
 
 // src/tools/variants.ts
-import { z as z8 } from "zod";
-var projectIdSchema8 = z8.string().uuid().describe("The project UUID");
+import { z as z9 } from "zod";
 function registerVariantWriteTools(server, client) {
   server.registerTool(
     "create_variant",
@@ -877,17 +898,20 @@ function registerVariantWriteTools(server, client) {
       title: "Create managed variant",
       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: projectIdSchema8,
-        componentId: z8.string().describe("The component ID to add a variant to"),
-        displayName: z8.string().describe("Human-readable name for the new variant"),
-        content: z8.string().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.")
+        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.")
       },
       outputSchema: {
-        variantId: z8.string().describe("The new variant ID"),
-        displayName: z8.string(),
-        componentId: z8.string(),
-        state: z8.literal("draft").describe("New managed variants start in draft state"),
-        hasContent: z8.boolean().describe("Whether text content was provided at creation")
+        variantId: z9.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")
       },
       annotations: {
         readOnlyHint: false,
@@ -896,7 +920,7 @@ function registerVariantWriteTools(server, client) {
         openWorldHint: false
       }
     },
-    async ({ projectId, componentId, displayName, content }) => {
+    withApiErrorGuidance(async ({ projectId, componentId, displayName, content }) => {
       const id = encodeURIComponent(projectId);
       const result = await client.post(
         `/projects/${id}/variants`,
@@ -916,7 +940,7 @@ function registerVariantWriteTools(server, client) {
           hasContent: Boolean(content)
         }
       };
-    }
+    })
   );
   server.registerTool(
     "pause_variant",
@@ -924,14 +948,14 @@ function registerVariantWriteTools(server, client) {
       title: "Pause variant",
       description: "Pause a variant, stopping traffic from being assigned to it.",
       inputSchema: {
-        projectId: projectIdSchema8,
-        componentId: z8.string().describe("The component ID"),
-        variantId: z8.string().describe("The variant ID to pause")
+        projectId: projectIdSchema,
+        componentId: z9.string().describe("The component ID"),
+        variantId: z9.string().describe("The variant ID to pause")
       },
       outputSchema: {
-        variantId: z8.string(),
-        componentId: z8.string(),
-        paused: z8.literal(true).describe("The variant is now paused")
+        variantId: z9.string(),
+        componentId: z9.string(),
+        paused: z9.literal(true).describe("The variant is now paused")
       },
       annotations: {
         readOnlyHint: false,
@@ -940,7 +964,7 @@ function registerVariantWriteTools(server, client) {
         openWorldHint: false
       }
     },
-    async ({ projectId, componentId, variantId }) => {
+    withApiErrorGuidance(async ({ projectId, componentId, variantId }) => {
       const id = encodeURIComponent(projectId);
       await client.post(`/projects/${id}/variants/pause`, { componentId, variantId });
       return {
@@ -950,17 +974,17 @@ function registerVariantWriteTools(server, client) {
         }],
         structuredContent: { variantId, componentId, paused: true }
       };
-    }
+    })
   );
   server.registerTool(
     "refresh_insights",
     {
       title: "Refresh insights",
       description: "Trigger fresh AI insight generation for a project. Returns immediately; use get_insights in ~15 seconds to see results.",
-      inputSchema: { projectId: projectIdSchema8 },
+      inputSchema: { projectId: projectIdSchema },
       outputSchema: {
-        projectId: z8.string(),
-        status: z8.literal("generating").describe("Generation has been triggered")
+        projectId: z9.string(),
+        status: z9.literal("generating").describe("Generation has been triggered")
       },
       annotations: {
         readOnlyHint: false,
@@ -969,7 +993,7 @@ function registerVariantWriteTools(server, client) {
         openWorldHint: false
       }
     },
-    async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId }) => {
       const id = encodeURIComponent(projectId);
       await client.post(`/projects/${id}/insights/refresh`);
       return {
@@ -979,13 +1003,12 @@ function registerVariantWriteTools(server, client) {
         }],
         structuredContent: { projectId, status: "generating" }
       };
-    }
+    })
   );
 }
 
 // src/tools/variant-brief.ts
-import { z as z9 } from "zod";
-var projectIdSchema9 = z9.string().uuid().describe("The project UUID");
+import { z as z10 } from "zod";
 var GOAL_TARGET = 500;
 var BEST_PRACTICE_PRIORS = {
   ecommerce: [
@@ -1023,11 +1046,12 @@ var GENERIC_PRIORS = [
   "Add one credible proof point near the action."
 ];
 function priorsFor(contextType) {
-  return BEST_PRACTICE_PRIORS[contextType] ?? GENERIC_PRIORS;
+  var _a;
+  return (_a = BEST_PRACTICE_PRIORS[contextType]) != null ? _a : GENERIC_PRIORS;
 }
 function computeDataState(impressions, insights, avgReliability) {
   if (impressions === 0) return "empty";
-  const insightsReady = insights?.status === "ok" && !insights.isStale;
+  const insightsReady = (insights == null ? void 0 : insights.status) === "ok" && !insights.isStale;
   const reliable = avgReliability === null || avgReliability >= 0.3;
   if (impressions < GOAL_TARGET || !insightsReady || !reliable) return "collecting";
   return "sufficient";
@@ -1045,7 +1069,7 @@ function guidanceFor(dataState, contextType) {
 async function settled(p) {
   try {
     return await p;
-  } catch {
+  } catch (e) {
     return null;
   }
 }
@@ -1056,16 +1080,16 @@ function registerVariantBriefTools(server, client) {
       title: "Variant brief",
       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: projectIdSchema9,
-        componentId: z9.string().describe('The component ID to write a new variant for (matches <Adaptive id="...">).')
+        projectId: projectIdSchema,
+        componentId: z10.string().describe('The component ID to write a new variant for (matches <Adaptive id="...">).')
       },
       outputSchema: {
-        componentId: z9.string(),
-        contextType: z9.string().describe("The project's context type (or 'unknown')"),
-        dataState: z9.enum(["sufficient", "collecting", "empty"]).describe("Data-sufficiency assessment"),
-        existingVariantIds: z9.array(z9.string()).describe("Variant IDs already in use (do not reuse)"),
-        priors: z9.array(z9.string()).describe("Best-practice priors applied for this context type"),
-        markdown: z9.string().describe("The full variant brief in Markdown")
+        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")
       },
       annotations: {
         readOnlyHint: true,
@@ -1073,7 +1097,8 @@ function registerVariantBriefTools(server, client) {
         openWorldHint: false
       }
     },
-    async ({ projectId, componentId }) => {
+    withApiErrorGuidance(async ({ projectId, componentId }) => {
+      var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n;
       const id = encodeURIComponent(projectId);
       const [projects, componentsEnvelope, trends, portraits, insights] = await Promise.all([
         settled(client.get("/projects")),
@@ -1083,19 +1108,19 @@ function registerVariantBriefTools(server, client) {
         settled(client.get(`/projects/${id}/portraits`)),
         settled(client.get(`/projects/${id}/insights`))
       ]);
-      const project = projects?.find((p) => p.id === projectId) ?? null;
-      const contextType = project?.context_type ?? "unknown";
-      const components = componentsEnvelope?.components ?? [];
-      const component = components.find((c) => c.component_id === componentId) ?? null;
-      const impressions = component?.total_impressions ?? 0;
-      const conversions = component?.total_conversions ?? 0;
+      const project = (_a = projects == null ? void 0 : projects.find((p) => p.id === projectId)) != null ? _a : null;
+      const contextType = (_b = project == null ? void 0 : project.context_type) != null ? _b : "unknown";
+      const components = (_c = componentsEnvelope == null ? void 0 : componentsEnvelope.components) != null ? _c : [];
+      const component = (_d = components.find((c) => c.component_id === componentId)) != null ? _d : null;
+      const impressions = (_e = component == null ? void 0 : component.total_impressions) != null ? _e : 0;
+      const conversions = (_f = component == null ? void 0 : component.total_conversions) != null ? _f : 0;
       const componentCvr = impressions > 0 ? conversions / impressions * 100 : 0;
-      const existingVariantIds = component?.variants.map((v) => v.variant_id) ?? [];
+      const existingVariantIds = (_g = component == null ? void 0 : component.variants.map((v) => v.variant_id)) != null ? _g : [];
       const variantIdSet = new Set(existingVariantIds);
-      const momentumMap = new Map((trends?.momentum ?? []).map((m) => [m.variantId, m.direction]));
-      const variantPerf = (trends?.cvr ?? []).filter((v) => variantIdSet.has(v.variantId));
-      const clusters = portraits?.clusters ?? [];
-      const totalSessions = portraits?.totalSessions ?? 0;
+      const momentumMap = new Map(((_h = trends == null ? void 0 : trends.momentum) != null ? _h : []).map((m) => [m.variantId, m.direction]));
+      const variantPerf = ((_i = trends == null ? void 0 : trends.cvr) != null ? _i : []).filter((v) => variantIdSet.has(v.variantId));
+      const clusters = (_j = portraits == null ? void 0 : portraits.clusters) != null ? _j : [];
+      const totalSessions = (_k = portraits == null ? void 0 : portraits.totalSessions) != null ? _k : 0;
       const avgReliability = clusters.length ? clusters.reduce((s, c) => s + c.avgReliability, 0) / clusters.length : null;
       const dataState = computeDataState(impressions, insights, avgReliability);
       const lines = [];
@@ -1120,7 +1145,7 @@ function registerVariantBriefTools(server, client) {
         lines.push("Current variant performance (7d vs prior 7d):");
         for (const v of variantPerf) {
           lines.push(
-            `- ${v.variantId}: ${(v.currentCvr * 100).toFixed(2)}% CVR (${v.deltaPp > 0 ? "+" : ""}${v.deltaPp.toFixed(1)} pp, ${momentumMap.get(v.variantId) ?? "stable"})`
+            `- ${v.variantId}: ${(v.currentCvr * 100).toFixed(2)}% CVR (${v.deltaPp > 0 ? "+" : ""}${v.deltaPp.toFixed(1)} pp, ${(_l = momentumMap.get(v.variantId)) != null ? _l : "stable"})`
           );
         }
         lines.push("");
@@ -1135,8 +1160,8 @@ function registerVariantBriefTools(server, client) {
       }
       if (insights && insights.status === "ok") {
         if (insights.isStale) lines.push("\u26A0 Insights are stale (>6h). Consider refresh_insights for a fresher read.");
-        const narrator = insights.narratorBullets ?? [];
-        const advisor = insights.advisorBullets ?? [];
+        const narrator = (_m = insights.narratorBullets) != null ? _m : [];
+        const advisor = (_n = insights.advisorBullets) != null ? _n : [];
         if (narrator.length) {
           lines.push("Insights \u2014 observations:");
           narrator.forEach((b) => lines.push(`- ${b}`));
@@ -1176,17 +1201,16 @@ function registerVariantBriefTools(server, client) {
           markdown
         }
       };
-    }
+    })
   );
 }
 
 // src/tools/test-brief.ts
-import { z as z10 } from "zod";
-var projectIdSchema10 = z10.string().uuid().describe("The project UUID");
+import { z as z11 } from "zod";
 async function settled2(p) {
   try {
     return await p;
-  } catch {
+  } catch (e) {
     return null;
   }
 }
@@ -1197,14 +1221,14 @@ function registerTestBriefTools(server, client) {
       title: "Test brief",
       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: projectIdSchema10,
-        componentId: z10.string().describe('The component ID to write a test for (matches <Adaptive id="...">).')
+        projectId: projectIdSchema,
+        componentId: z11.string().describe('The component ID to write a test for (matches <Adaptive id="...">).')
       },
       outputSchema: {
-        componentId: z10.string(),
-        forcedVariantId: z10.string().describe("The non-control variant the example forces"),
-        goalName: z10.string().describe("The goal the example asserts fires"),
-        markdown: z10.string().describe("The full test brief in Markdown")
+        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")
       },
       annotations: {
         readOnlyHint: true,
@@ -1212,20 +1236,21 @@ function registerTestBriefTools(server, client) {
         openWorldHint: false
       }
     },
-    async ({ projectId, componentId }) => {
+    withApiErrorGuidance(async ({ projectId, componentId }) => {
+      var _a, _b, _c, _d, _e, _f, _g, _h;
       const id = encodeURIComponent(projectId);
       const [componentsEnvelope, goalsRes] = await Promise.all([
         // mgmt API returns a paginated envelope: { components, total, page, limit }.
         settled2(client.get(`/projects/${id}/components`)),
         settled2(client.get(`/projects/${id}/goals`))
       ]);
-      const components = componentsEnvelope?.components ?? [];
-      const component = components.find((c) => c.component_id === componentId) ?? null;
-      const variantIds = component?.variants.map((v) => v.variant_id) ?? [];
-      const goals = Array.isArray(goalsRes) ? goalsRes : goalsRes?.goals ?? [];
-      const goalName = goals[0]?.goalName ?? "signup";
-      const controlId = variantIds[0] ?? "control";
-      const forcedId = variantIds.find((v) => v !== controlId) ?? "variant_b";
+      const components = (_a = componentsEnvelope == null ? void 0 : componentsEnvelope.components) != null ? _a : [];
+      const component = (_b = components.find((c) => c.component_id === componentId)) != null ? _b : null;
+      const variantIds = (_c = component == null ? void 0 : component.variants.map((v) => v.variant_id)) != null ? _c : [];
+      const goals = Array.isArray(goalsRes) ? goalsRes : (_d = goalsRes == null ? void 0 : goalsRes.goals) != null ? _d : [];
+      const goalName = (_f = (_e = goals[0]) == null ? void 0 : _e.goalName) != null ? _f : "signup";
+      const controlId = (_g = variantIds[0]) != null ? _g : "control";
+      const forcedId = (_h = variantIds.find((v) => v !== controlId)) != null ? _h : "variant_b";
       const lines = [];
       lines.push(`# Test brief \u2014 ${componentId}`);
       lines.push("");
@@ -1281,12 +1306,12 @@ function registerTestBriefTools(server, client) {
         content: [{ type: "text", text: markdown }],
         structuredContent: { componentId, forcedVariantId: forcedId, goalName, markdown }
       };
-    }
+    })
   );
 }
 
 // src/tools/integration-guide.ts
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 var GUIDE = `# SentientUI integration guide \u2014 the adaptive ladder
 
 SentientUI adapts a site per visitor type (personas: buyer, researcher, deal_seeker, browser,
@@ -1361,7 +1386,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: z11.string().describe("The full integration guide in Markdown")
+        guide: z12.string().describe("The full integration guide in Markdown")
       },
       annotations: {
         readOnlyHint: true,
@@ -1377,7 +1402,7 @@ function registerIntegrationGuideTools(server) {
 }
 
 // src/server.ts
-var { version: PKG_VERSION } = createRequire(import.meta.url)("../package.json");
+var PKG_VERSION = true ? "0.8.2" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new McpServer(
     {