@sentientui/mcp 0.7.0 → 0.8.1

package/dist/lib.cjs

@@ -36,7 +36,7 @@ var import_node_module = require("module");
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 
 // src/tools/projects.ts
-var import_zod = require("zod");
+var import_zod2 = require("zod");
 
 // src/api-client.ts
 var ApiError = class extends Error {
@@ -45,16 +45,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}`,
@@ -63,11 +62,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: {
@@ -78,14 +78,51 @@ 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/tools/projects.ts
+// src/tools/common.ts
+var import_zod = require("zod");
 var projectIdSchema = import_zod.z.string().uuid().describe("The project UUID");
+function apiErrorGuidance(err) {
+  switch (err.message) {
+    case "insufficient_scope":
+      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 (or use a project server key) to make changes.";
+    case "insufficient_role":
+      return "Your account role does not permit this action \u2014 it needs the account owner or an admin.";
+    default:
+      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) {
+  return async (args) => {
+    try {
+      return await fn(args);
+    } catch (err) {
+      if (err instanceof ApiError) {
+        const guidance = apiErrorGuidance(err);
+        if (guidance) {
+          return { content: [{ type: "text", text: guidance }], isError: true };
+        }
+      }
+      throw err;
+    }
+  };
+}
+
+// src/tools/projects.ts
 function createProjectGuidance(err) {
   switch (err.message) {
     case "insufficient_scope":
@@ -109,16 +146,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: import_zod.z.string().min(1).describe("Human-readable project name"),
-        contextType: import_zod.z.enum(["saas", "ecommerce", "marketing", "internal"]).optional().describe("What kind of product this is; defaults to saas"),
-        framework: import_zod.z.enum(["next", "react", "core"]).optional().describe("How the site is built \u2014 next, react, or core (website builder/CMS); defaults to next"),
-        websiteUrl: import_zod.z.string().optional().describe("Production site origin to allow-list so the SDK's events aren't origin-blocked on day one")
+        name: import_zod2.z.string().min(1).describe("Human-readable project name"),
+        contextType: import_zod2.z.enum(["saas", "ecommerce", "marketing", "landing", "internal"]).optional().describe("What kind of product this is; defaults to saas"),
+        framework: import_zod2.z.enum(["next", "react", "core"]).optional().describe("How the site is built \u2014 next, react, or core (website builder/CMS); defaults to next"),
+        websiteUrl: import_zod2.z.string().optional().describe("Production site origin to allow-list so the SDK's events aren't origin-blocked on day one")
       },
       outputSchema: {
-        projectId: import_zod.z.string().describe("The new project UUID"),
-        publicKey: import_zod.z.string().describe("The pk_ public key to configure the SDK with"),
-        name: import_zod.z.string().describe("The project name"),
-        contextType: import_zod.z.string().describe("The resolved context type")
+        projectId: import_zod2.z.string().describe("The new project UUID"),
+        publicKey: import_zod2.z.string().describe("The pk_ public key to configure the SDK with"),
+        name: import_zod2.z.string().describe("The project name"),
+        contextType: import_zod2.z.string().describe("The resolved context type")
       },
       annotations: {
         readOnlyHint: false,
@@ -135,7 +172,7 @@ function registerProjectTools(server, client) {
           framework,
           origin: websiteUrl
         });
-        const resolvedContextType = contextType ?? "saas";
+        const resolvedContextType = contextType != null ? contextType : "saas";
         return {
           content: [{
             type: "text",
@@ -170,12 +207,12 @@ function registerProjectTools(server, client) {
       description: "List all SentientUI projects for the authenticated account.",
       inputSchema: {},
       outputSchema: {
-        projects: import_zod.z.array(
-          import_zod.z.object({
-            id: import_zod.z.string().describe("Project UUID"),
-            name: import_zod.z.string(),
-            contextType: import_zod.z.string(),
-            createdAt: import_zod.z.string().describe("ISO date (YYYY-MM-DD)")
+        projects: import_zod2.z.array(
+          import_zod2.z.object({
+            id: import_zod2.z.string().describe("Project UUID"),
+            name: import_zod2.z.string(),
+            contextType: import_zod2.z.string(),
+            createdAt: import_zod2.z.string().describe("ISO date (YYYY-MM-DD)")
           })
         ).describe("All projects for the account (empty if none)")
       },
@@ -185,7 +222,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)})`
@@ -201,7 +238,7 @@ function registerProjectTools(server, client) {
           }))
         }
       };
-    }
+    })
   );
   server.registerTool(
     "get_project_stats",
@@ -210,11 +247,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: import_zod.z.string().describe("Overall project health status"),
-        events24h: import_zod.z.number().describe("Events in the last 24 hours"),
-        sessions24h: import_zod.z.number().describe("Sessions in the last 24 hours"),
-        agentCalls: import_zod.z.number().describe("Total agent (MCP/API) calls"),
-        lastEventAt: import_zod.z.string().nullable().describe("ISO timestamp of the last event, or null")
+        status: import_zod2.z.string().describe("Overall project health status"),
+        events24h: import_zod2.z.number().describe("Events in the last 24 hours"),
+        sessions24h: import_zod2.z.number().describe("Sessions in the last 24 hours"),
+        agentCalls: import_zod2.z.number().describe("Total agent (MCP/API) calls"),
+        lastEventAt: import_zod2.z.string().nullable().describe("ISO timestamp of the last event, or null")
       },
       annotations: {
         readOnlyHint: true,
@@ -222,7 +259,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 = [
@@ -230,7 +268,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 }],
@@ -242,12 +280,12 @@ function registerProjectTools(server, client) {
           lastEventAt: stats.lastEventAt
         }
       };
-    }
+    })
   );
 }
 
 // src/tools/components.ts
-var import_zod2 = require("zod");
+var import_zod3 = require("zod");
 
 // src/ui/templates.ts
 var VIZ_TITLES = {
@@ -506,21 +544,20 @@ function registerUiResources(server) {
 }
 
 // src/tools/components.ts
-var projectIdSchema2 = import_zod2.z.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: import_zod2.z.array(
-          import_zod2.z.object({
-            componentId: import_zod2.z.string(),
-            variantCount: import_zod2.z.number(),
-            impressions: import_zod2.z.number(),
-            conversions: import_zod2.z.number()
+        components: import_zod3.z.array(
+          import_zod3.z.object({
+            componentId: import_zod3.z.string(),
+            variantCount: import_zod3.z.number(),
+            impressions: import_zod3.z.number(),
+            conversions: import_zod3.z.number()
           })
         ).describe("Adaptive components in the project (empty if none)")
       },
@@ -530,7 +567,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 = {
@@ -551,23 +588,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: import_zod2.z.array(
-          import_zod2.z.object({
-            variantId: import_zod2.z.string(),
-            currentCvr: import_zod2.z.number().describe("Conversion rate over the last 7 days (0-1)"),
-            priorCvr: import_zod2.z.number().describe("Conversion rate over the prior 7 days (0-1)"),
-            deltaPp: import_zod2.z.number().describe("Change in percentage points"),
-            momentum: import_zod2.z.string().describe("Momentum direction: gaining, losing, or stable")
+        variants: import_zod3.z.array(
+          import_zod3.z.object({
+            variantId: import_zod3.z.string(),
+            currentCvr: import_zod3.z.number().describe("Conversion rate over the last 7 days (0-1)"),
+            priorCvr: import_zod3.z.number().describe("Conversion rate over the prior 7 days (0-1)"),
+            deltaPp: import_zod3.z.number().describe("Change in percentage points"),
+            momentum: import_zod3.z.string().describe("Momentum direction: gaining, losing, or stable")
           })
         ).describe("Per-variant performance (empty if no data yet)")
       },
@@ -577,20 +614,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,
@@ -598,29 +639,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
-var import_zod3 = require("zod");
-var projectIdSchema3 = import_zod3.z.string().uuid().describe("The project UUID");
+var import_zod4 = require("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: import_zod3.z.enum(["ok", "empty"]).describe("Whether insights exist yet"),
-        observations: import_zod3.z.array(import_zod3.z.string()).describe("Narrator observations"),
-        recommendations: import_zod3.z.array(import_zod3.z.string()).describe("Advisor recommendations (Growth tier)"),
-        isStale: import_zod3.z.boolean().describe("True when the insights are older than ~6h"),
-        generatedAt: import_zod3.z.string().nullable().describe("ISO timestamp the insights were generated, or null")
+        status: import_zod4.z.enum(["ok", "empty"]).describe("Whether insights exist yet"),
+        observations: import_zod4.z.array(import_zod4.z.string()).describe("Narrator observations"),
+        recommendations: import_zod4.z.array(import_zod4.z.string()).describe("Advisor recommendations (Growth tier)"),
+        isStale: import_zod4.z.boolean().describe("True when the insights are older than ~6h"),
+        generatedAt: import_zod4.z.string().nullable().describe("ISO timestamp the insights were generated, or null")
       },
       annotations: {
         readOnlyHint: true,
@@ -628,7 +671,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") {
@@ -643,8 +687,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()}`);
@@ -662,33 +706,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
-var import_zod4 = require("zod");
-var projectIdSchema4 = import_zod4.z.string().uuid().describe("The project UUID");
+var import_zod5 = require("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: import_zod4.z.number().describe("Total sessions across all clusters"),
-        clusters: import_zod4.z.array(
-          import_zod4.z.object({
-            label: import_zod4.z.string(),
-            sessionCount: import_zod4.z.number(),
-            sharePct: import_zod4.z.number().describe("Share of total traffic (0-100)"),
-            reliability: import_zod4.z.number().describe("Average cluster reliability (0-1)")
+        totalSessions: import_zod5.z.number().describe("Total sessions across all clusters"),
+        clusters: import_zod5.z.array(
+          import_zod5.z.object({
+            label: import_zod5.z.string(),
+            sessionCount: import_zod5.z.number(),
+            sharePct: import_zod5.z.number().describe("Share of total traffic (0-100)"),
+            reliability: import_zod5.z.number().describe("Average cluster reliability (0-1)")
           })
         ).describe("Persona clusters (empty until enough visitor data)")
       },
@@ -698,7 +741,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 = {
@@ -727,33 +770,32 @@ function registerPersonaTools(server, client) {
         })
       ];
       return { content: [{ type: "text", text: lines.join("\n") }], structuredContent, _meta: uiMeta("persona-breakdown") };
-    }
+    })
   );
 }
 
 // src/tools/goals.ts
-var import_zod5 = require("zod");
-var projectIdSchema5 = import_zod5.z.string().uuid().describe("The project UUID");
+var import_zod6 = require("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: import_zod5.z.array(
-          import_zod5.z.object({
-            goalName: import_zod5.z.string(),
-            hits: import_zod5.z.number(),
-            uniqueSessions: import_zod5.z.number(),
-            conversionRate: import_zod5.z.number().describe("Unique-session conversion rate (0-1)"),
-            variants: import_zod5.z.array(
-              import_zod5.z.object({
-                componentId: import_zod5.z.string(),
-                variantId: import_zod5.z.string(),
-                completionRate: import_zod5.z.number().describe("Completion rate per assigned session (0-1)")
+        goals: import_zod6.z.array(
+          import_zod6.z.object({
+            goalName: import_zod6.z.string(),
+            hits: import_zod6.z.number(),
+            uniqueSessions: import_zod6.z.number(),
+            conversionRate: import_zod6.z.number().describe("Unique-session conversion rate (0-1)"),
+            variants: import_zod6.z.array(
+              import_zod6.z.object({
+                componentId: import_zod6.z.string(),
+                variantId: import_zod6.z.string(),
+                completionRate: import_zod6.z.number().describe("Completion rate per assigned session (0-1)")
               })
             ).describe("Per-variant breakdown")
           })
@@ -765,7 +807,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 = {
@@ -794,26 +836,25 @@ function registerGoalTools(server, client) {
         ""
       ]);
       return { content: [{ type: "text", text: lines.join("\n").trim() }], structuredContent, _meta: uiMeta("goal-funnel") };
-    }
+    })
   );
 }
 
 // src/tools/guardrails.ts
-var import_zod6 = require("zod");
-var projectIdSchema6 = import_zod6.z.string().uuid().describe("The project UUID");
+var import_zod7 = require("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: import_zod6.z.array(
-          import_zod6.z.object({
-            componentId: import_zod6.z.string(),
-            variantIds: import_zod6.z.array(import_zod6.z.string()).describe("Variants paused by the guardrail"),
-            pausedAt: import_zod6.z.string().nullable().describe("ISO timestamp the pause fired, or null")
+        events: import_zod7.z.array(
+          import_zod7.z.object({
+            componentId: import_zod7.z.string(),
+            variantIds: import_zod7.z.array(import_zod7.z.string()).describe("Variants paused by the guardrail"),
+            pausedAt: import_zod7.z.string().nullable().describe("ISO timestamp the pause fired, or null")
           })
         ).describe("Guardrail events in the last 24h (empty if none)")
       },
@@ -823,7 +864,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 = {
@@ -843,28 +884,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
-var import_zod7 = require("zod");
-var projectIdSchema7 = import_zod7.z.string().uuid().describe("The project UUID");
+var import_zod8 = require("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: import_zod7.z.array(
-          import_zod7.z.object({
-            persona: import_zod7.z.string(),
-            layoutOrder: import_zod7.z.array(import_zod7.z.string()).describe("Ranked section order for this persona"),
-            pulls: import_zod7.z.number().describe("Number of times this arm was served"),
-            avgReward: import_zod7.z.number().describe("Average bandit reward weight")
+        layouts: import_zod8.z.array(
+          import_zod8.z.object({
+            persona: import_zod8.z.string(),
+            layoutOrder: import_zod8.z.array(import_zod8.z.string()).describe("Ranked section order for this persona"),
+            pulls: import_zod8.z.number().describe("Number of times this arm was served"),
+            avgReward: import_zod8.z.number().describe("Average bandit reward weight")
           })
         ).describe("Per-persona layout rankings (empty until enough sessions)")
       },
@@ -874,7 +914,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 = {
@@ -896,13 +936,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
-var import_zod8 = require("zod");
-var projectIdSchema8 = import_zod8.z.string().uuid().describe("The project UUID");
+var import_zod9 = require("zod");
 function registerVariantWriteTools(server, client) {
   server.registerTool(
     "create_variant",
@@ -910,17 +949,17 @@ 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: import_zod8.z.string().describe("The component ID to add a variant to"),
-        displayName: import_zod8.z.string().describe("Human-readable name for the new variant"),
-        content: import_zod8.z.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: import_zod9.z.string().describe("The component ID to add a variant to"),
+        displayName: import_zod9.z.string().describe("Human-readable name for the new variant"),
+        content: import_zod9.z.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.")
       },
       outputSchema: {
-        variantId: import_zod8.z.string().describe("The new variant ID"),
-        displayName: import_zod8.z.string(),
-        componentId: import_zod8.z.string(),
-        state: import_zod8.z.literal("draft").describe("New managed variants start in draft state"),
-        hasContent: import_zod8.z.boolean().describe("Whether text content was provided at creation")
+        variantId: import_zod9.z.string().describe("The new variant ID"),
+        displayName: import_zod9.z.string(),
+        componentId: import_zod9.z.string(),
+        state: import_zod9.z.literal("draft").describe("New managed variants start in draft state"),
+        hasContent: import_zod9.z.boolean().describe("Whether text content was provided at creation")
       },
       annotations: {
         readOnlyHint: false,
@@ -929,7 +968,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`,
@@ -949,7 +988,7 @@ function registerVariantWriteTools(server, client) {
           hasContent: Boolean(content)
         }
       };
-    }
+    })
   );
   server.registerTool(
     "pause_variant",
@@ -957,14 +996,14 @@ function registerVariantWriteTools(server, client) {
       title: "Pause variant",
       description: "Pause a variant, stopping traffic from being assigned to it.",
       inputSchema: {
-        projectId: projectIdSchema8,
-        componentId: import_zod8.z.string().describe("The component ID"),
-        variantId: import_zod8.z.string().describe("The variant ID to pause")
+        projectId: projectIdSchema,
+        componentId: import_zod9.z.string().describe("The component ID"),
+        variantId: import_zod9.z.string().describe("The variant ID to pause")
       },
       outputSchema: {
-        variantId: import_zod8.z.string(),
-        componentId: import_zod8.z.string(),
-        paused: import_zod8.z.literal(true).describe("The variant is now paused")
+        variantId: import_zod9.z.string(),
+        componentId: import_zod9.z.string(),
+        paused: import_zod9.z.literal(true).describe("The variant is now paused")
       },
       annotations: {
         readOnlyHint: false,
@@ -973,7 +1012,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 {
@@ -983,17 +1022,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: import_zod8.z.string(),
-        status: import_zod8.z.literal("generating").describe("Generation has been triggered")
+        projectId: import_zod9.z.string(),
+        status: import_zod9.z.literal("generating").describe("Generation has been triggered")
       },
       annotations: {
         readOnlyHint: false,
@@ -1002,7 +1041,7 @@ function registerVariantWriteTools(server, client) {
         openWorldHint: false
       }
     },
-    async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId }) => {
       const id = encodeURIComponent(projectId);
       await client.post(`/projects/${id}/insights/refresh`);
       return {
@@ -1012,13 +1051,12 @@ function registerVariantWriteTools(server, client) {
         }],
         structuredContent: { projectId, status: "generating" }
       };
-    }
+    })
   );
 }
 
 // src/tools/variant-brief.ts
-var import_zod9 = require("zod");
-var projectIdSchema9 = import_zod9.z.string().uuid().describe("The project UUID");
+var import_zod10 = require("zod");
 var GOAL_TARGET = 500;
 var BEST_PRACTICE_PRIORS = {
   ecommerce: [
@@ -1056,11 +1094,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";
@@ -1078,7 +1117,7 @@ function guidanceFor(dataState, contextType) {
 async function settled(p) {
   try {
     return await p;
-  } catch {
+  } catch (e) {
     return null;
   }
 }
@@ -1089,16 +1128,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: import_zod9.z.string().describe('The component ID to write a new variant for (matches <Adaptive id="...">).')
+        projectId: projectIdSchema,
+        componentId: import_zod10.z.string().describe('The component ID to write a new variant for (matches <Adaptive id="...">).')
       },
       outputSchema: {
-        componentId: import_zod9.z.string(),
-        contextType: import_zod9.z.string().describe("The project's context type (or 'unknown')"),
-        dataState: import_zod9.z.enum(["sufficient", "collecting", "empty"]).describe("Data-sufficiency assessment"),
-        existingVariantIds: import_zod9.z.array(import_zod9.z.string()).describe("Variant IDs already in use (do not reuse)"),
-        priors: import_zod9.z.array(import_zod9.z.string()).describe("Best-practice priors applied for this context type"),
-        markdown: import_zod9.z.string().describe("The full variant brief in Markdown")
+        componentId: import_zod10.z.string(),
+        contextType: import_zod10.z.string().describe("The project's context type (or 'unknown')"),
+        dataState: import_zod10.z.enum(["sufficient", "collecting", "empty"]).describe("Data-sufficiency assessment"),
+        existingVariantIds: import_zod10.z.array(import_zod10.z.string()).describe("Variant IDs already in use (do not reuse)"),
+        priors: import_zod10.z.array(import_zod10.z.string()).describe("Best-practice priors applied for this context type"),
+        markdown: import_zod10.z.string().describe("The full variant brief in Markdown")
       },
       annotations: {
         readOnlyHint: true,
@@ -1106,7 +1145,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")),
@@ -1116,19 +1156,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 = [];
@@ -1153,7 +1193,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("");
@@ -1168,8 +1208,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}`));
@@ -1209,17 +1249,16 @@ function registerVariantBriefTools(server, client) {
           markdown
         }
       };
-    }
+    })
   );
 }
 
 // src/tools/test-brief.ts
-var import_zod10 = require("zod");
-var projectIdSchema10 = import_zod10.z.string().uuid().describe("The project UUID");
+var import_zod11 = require("zod");
 async function settled2(p) {
   try {
     return await p;
-  } catch {
+  } catch (e) {
     return null;
   }
 }
@@ -1230,14 +1269,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: import_zod10.z.string().describe('The component ID to write a test for (matches <Adaptive id="...">).')
+        projectId: projectIdSchema,
+        componentId: import_zod11.z.string().describe('The component ID to write a test for (matches <Adaptive id="...">).')
       },
       outputSchema: {
-        componentId: import_zod10.z.string(),
-        forcedVariantId: import_zod10.z.string().describe("The non-control variant the example forces"),
-        goalName: import_zod10.z.string().describe("The goal the example asserts fires"),
-        markdown: import_zod10.z.string().describe("The full test brief in Markdown")
+        componentId: import_zod11.z.string(),
+        forcedVariantId: import_zod11.z.string().describe("The non-control variant the example forces"),
+        goalName: import_zod11.z.string().describe("The goal the example asserts fires"),
+        markdown: import_zod11.z.string().describe("The full test brief in Markdown")
       },
       annotations: {
         readOnlyHint: true,
@@ -1245,20 +1284,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("");
@@ -1314,12 +1354,12 @@ function registerTestBriefTools(server, client) {
         content: [{ type: "text", text: markdown }],
         structuredContent: { componentId, forcedVariantId: forcedId, goalName, markdown }
       };
-    }
+    })
   );
 }
 
 // src/tools/integration-guide.ts
-var import_zod11 = require("zod");
+var import_zod12 = require("zod");
 var GUIDE = `# SentientUI integration guide \u2014 the adaptive ladder
 
 SentientUI adapts a site per visitor type (personas: buyer, researcher, deal_seeker, browser,
@@ -1394,7 +1434,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: import_zod11.z.string().describe("The full integration guide in Markdown")
+        guide: import_zod12.z.string().describe("The full integration guide in Markdown")
       },
       annotations: {
         readOnlyHint: true,