@sentientui/mcp 0.2.1 → 0.3.0

package/AGENTS.md

@@ -0,0 +1,87 @@
+# SentientUI — AI Agent Guide
+
+SentientUI is a UI personalization platform that assigns visitors to variant components and reorders page sections per persona. The MCP gives agents read + limited write access to project data.
+
+## Key Concepts
+
+**Persona / Cluster** — visitors are clustered by behavior into labeled groups. A `reliability_score` (0–1) measures confidence in the assignment. Low reliability means the engine won't personalize for that session even if a cluster is assigned.
+
+**Variant** — a version of an adaptive component. There are **two kinds**, and the difference matters:
+
+- **Code-native variants** are declared in the customer's code (`<Adaptive variants={{…}}>`). They **register automatically** the first time the SDK requests an assignment after deploy, and they go **live immediately** — there is no draft step and no `create_variant` call. Their content lives in the repo, not in SentientUI.
+- **No-code / managed variants** have no code; their content is stored on the SentientUI API (dashboard WYSIWYG, `<AdaptiveText>`, or `create_variant`). These start as **draft** after `create_variant` and must be activated from the dashboard before traffic is assigned. There is no MCP tool to activate or resume variants.
+
+Only call `create_variant` for the no-code path. If the user is writing (or you are writing) the variant in code, do **not** call `create_variant` — deploying the code registers it.
+
+**Guardrail** — automatic safety circuit that pauses variants whose CVR drops below threshold. `list_guardrail_events` shows what's been paused. Pausing via `pause_variant` is irreversible via MCP (no resume tool).
+
+**Shadow mode** — project-level flag (toggled in dashboard settings). When ON: personalization is computed and logged but visitors receive the default layout/variant. Use it to validate the algorithm before committing to live changes.
+
+**Insights** — AI-generated. Two tiers: narrator observations (all plans) + advisor recommendations (Growth tier). Insights go stale after 6 hours. Always check `isStale` before presenting them.
+
+**Layout stats** — per-persona section ordering driven by a bandit algorithm. `pulls` = times a layout was applied, `avgReward` = normalized conversion signal (not raw CVR).
+
+## Auth
+
+Server keys start with `sk_` — required for the management API. Public keys (`pk_`) are for the React SDK only and will be rejected. Key is scoped to the account; all owned projects are accessible.
+
+## Tool Quick Reference
+
+| Tool | Notes |
+|------|-------|
+| `list_projects` | Start here to get project IDs |
+| `get_project_stats` | Health status + 24h event/session volume |
+| `list_components` | Components + variant counts + impression totals |
+| `get_variant_performance` | CVR 7d vs prior 7d + momentum direction |
+| `get_persona_breakdown` | Cluster distribution + avg reliability per cluster |
+| `get_goal_funnel` | Goal hit counts + per-variant completion rates |
+| `list_guardrail_events` | Auto-paused variants (last 24h) |
+| `get_layout_stats` | Per-persona layout order + bandit pulls/reward |
+| `get_insights` | Narrator bullets + (Growth) advisor bullets |
+| `refresh_insights` | Async trigger — wait ~15s then call `get_insights` |
+| `get_variant_brief` | **Start here to optimize a component.** Insight-driven brief for writing a new CODE-NATIVE variant: performance, audience, insights, data-sufficiency + best-practice fallback, and code instructions |
+| `create_variant` | Creates a no-code **managed text** DRAFT — user must activate in dashboard. Fallback only; not for code-native variants |
+| `pause_variant` | Stops traffic; no MCP resume |
+
+## Canonical Workflows
+
+**Diagnose a conversion drop**
+1. `get_project_stats` — confirm events are flowing
+2. `get_goal_funnel` — find which goals/variants are down
+3. `get_variant_performance` — check CVR momentum
+4. `list_guardrail_events` — see if the guardrail fired
+5. `refresh_insights` → wait 15s → `get_insights` — read AI summary
+
+**Optimize a component with a new variant (code-native — recommended)**
+1. `list_components` — confirm the component ID
+2. `get_variant_brief` — pull performance, audience, insights, data-sufficiency, best-practice priors, and code instructions for that component
+3. Find `<Adaptive id="...">` in the repo and add a new on-brand variant key to its `variants` map (and to the `AdaptiveRoot` `components` list if SSR). Match the project's existing components and design system.
+4. Do **not** call `create_variant`. Commit, push, deploy — the variant auto-registers on the first assignment and goes live.
+5. Optional: enable shadow mode for the component first to validate before serving.
+
+Data sufficiency (from the brief) drives the change: when it reports **SUFFICIENT**, target the specific weakness; when **COLLECTING** or **EMPTY** (no data yet), apply the best-practice priors for the project's context type — use your best judgment and make one conservative change.
+
+**Add a no-code managed text variant (fallback — text only, less powerful)**
+1. `list_components` — confirm the component ID
+2. `create_variant` with `content` — creates a managed text draft (generate the copy from `get_variant_brief` context)
+3. Tell the user to activate it from the dashboard
+
+**Understand the audience**
+1. `get_persona_breakdown` — cluster sizes + reliability
+2. `get_layout_stats` — what layout order each persona gets
+3. `get_insights` — AI narrative on what changed
+
+**Validate before going live (shadow mode)**
+- Shadow mode is enabled/disabled in the dashboard (Project Settings)
+- When ON: personalization runs silently, no live impact
+- When confident: turn OFF to start serving personalized experiences
+
+## Common Mistakes
+
+- Presenting stale insights without checking `isStale` — always check, and offer to `refresh_insights`
+- Assuming `create_variant` is live — it's always a draft
+- Calling `create_variant` for a variant that's being written in code — it creates an empty managed draft, not your code variant. Code-native variants auto-register on deploy; only use `create_variant` for no-code/managed variants whose content lives in SentientUI
+- Optimizing a component without calling `get_variant_brief` first — it gives you the performance, audience, insights, and data-sufficiency fallback you need to write a variant that actually makes sense (and the right steps when there is no data yet)
+- Calling `pause_variant` without warning the user it's irreversible via MCP
+- Using a `pk_` key instead of `sk_` — it will be rejected
+- Interpreting `avgReward` in layout stats as a conversion rate — it's a bandit reward signal, not CVR

package/README.md

@@ -6,7 +6,7 @@ MCP server for [SentientUI](https://sentient-ui.com) — gives AI agents in Clau
 
 **1. Get a server key**
 
-Dashboard → **Settings → API Keys → Create server key** (`sk_live_...`).
+Dashboard → Project → **Settings → API key → Server key** → Generate (requires Starter or Growth plan).
 
 **2. Add to your AI assistant**
 
@@ -82,9 +82,14 @@ A sandboxed demo token is provisioned automatically — 10 calls/month, no sign-
 | `get_goal_funnel` | Goal hit counts and conversion rates per variant |
 | `list_guardrail_events` | Variants auto-paused by the guardrail (last 24h) |
 | `get_layout_stats` | Per-persona section layout rankings and reward weights |
-| `create_variant` | Create a new draft variant (Starter+) |
+| `get_variant_brief` | Insight-driven brief for writing a new **code-native** variant: performance, audience, insights, data-sufficiency (with a best-practice fallback when there's no data yet), and step-by-step code instructions |
+| `create_variant` | Create a no-code (managed) text variant (Starter+) — fallback for text-only variants without a code change |
 | `pause_variant` | Pause a variant to stop traffic assignment |
 
+> **Code-native vs no-code variants.** Variants you declare in your app (`<Adaptive variants={{…}}>`) register automatically the first time the SDK requests an assignment after you deploy — they go live immediately and need **no** `create_variant` call. Use `create_variant` only for **no-code** variants whose content is stored in SentientUI and rendered without a code change; these start as drafts you activate from the dashboard.
+>
+> **Optimizing a component?** Call `get_variant_brief` first. It returns the component's performance, audience, insights, and a data-sufficiency assessment — then your AI assistant writes a new on-brand variant directly into your code (which auto-registers on deploy). When there's no data yet, the brief falls back to best-practice priors for your project's context type so the assistant still makes a sensible change.
+
 ## Example prompts
 
 - *"What projects do I have?"*
@@ -92,6 +97,7 @@ A sandboxed demo token is provisioned automatically — 10 calls/month, no sign-
 - *"Are any variants paused by the guardrail right now?"*
 - *"What do the AI insights say about what changed this week?"*
 - *"Refresh insights for project X"*
+- *"Optimize my hero CTA — pull the brief and add a new variant in the code"*
 - *"Create a new variant called 'short-copy' for the pricing CTA"*
 
 ## Configuration
@@ -107,6 +113,17 @@ The server key you provide is passed as a `Bearer` token on every call to the Se
 
 Server keys start with `sk_` (not `pk_`). Public keys (`pk_`) are for the React SDK only and will be rejected by the management API.
 
+## AI agent context
+
+`AGENTS.md` (included in this package) gives your AI assistant deeper context about SentientUI concepts, tool ordering, and common pitfalls. Wire it up once and it applies to every conversation.
+
+| Assistant | How to use |
+|-----------|-----------|
+| **Claude Code** | Copy to `~/.claude/skills/sentientui/SKILL.md` |
+| **Cursor** | Copy to `.cursor/rules/sentientui.mdc` |
+| **GitHub Copilot** | Append to `.github/copilot-instructions.md` |
+| **Other** | Paste into your assistant's system prompt |
+
 ## Requirements
 
 - Node.js 18+

package/dist/index.cjs

@@ -175,9 +175,10 @@ function registerPersonaTools(server, client) {
         `Total sessions: ${data.totalSessions}`,
         "",
         "Clusters:",
-        ...data.clusters.map(
-          (c) => `- ${c.label}: ${c.sessionCount} sessions (${(c.sessionCount / data.totalSessions * 100).toFixed(1)}% of traffic, reliability ${(c.avgReliability * 100).toFixed(0)}%)`
-        )
+        ...data.clusters.map((c) => {
+          const pct = data.totalSessions > 0 ? c.sessionCount / data.totalSessions * 100 : 0;
+          return `- ${c.label}: ${c.sessionCount} sessions (${pct.toFixed(1)}% of traffic, reliability ${(c.avgReliability * 100).toFixed(0)}%)`;
+        })
       ];
       return { content: [{ type: "text", text: lines.join("\n") }] };
     }
@@ -258,22 +259,24 @@ var projectIdSchema8 = import_zod8.z.string().uuid().describe("The project UUID"
 function registerVariantWriteTools(server, client) {
   server.tool(
     "create_variant",
-    "Create a new draft variant for a component. Requires Starter or Growth plan.",
+    "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 Starter or Growth plan.",
     {
       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")
+      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.")
     },
-    async ({ projectId, componentId, displayName }) => {
+    async ({ projectId, componentId, displayName, content }) => {
       const id = encodeURIComponent(projectId);
       const result = await client.post(
         `/projects/${id}/variants`,
-        { componentId, displayName }
+        { componentId, displayName, content }
       );
+      const contentNote = content ? " with the provided text content" : " (empty \u2014 add its text content from the dashboard or via a follow-up update)";
       return {
         content: [{
           type: "text",
-          text: `Variant created: ${result.variantId} ("${result.displayName}") for component ${componentId}. It is in draft state \u2014 activate it from the dashboard.`
+          text: `Managed text variant created: ${result.variantId} ("${result.displayName}") for component ${componentId}${contentNote}. It is in draft state \u2014 activate it from the dashboard. Reminder: this is a no-code managed variant; for code-native variants, edit the code instead (see get_variant_brief).`
         }]
       };
     }
@@ -314,6 +317,259 @@ function registerVariantWriteTools(server, client) {
   );
 }
 
+// src/tools/variant-brief.ts
+var import_zod9 = require("zod");
+var projectIdSchema9 = import_zod9.z.string().uuid().describe("The project UUID");
+var GOAL_TARGET = 500;
+var BEST_PRACTICE_PRIORS = {
+  ecommerce: [
+    "Lead with the core benefit/value, not features.",
+    "Make the primary action (add to cart / buy) unmistakable and high-contrast.",
+    "Reduce purchase anxiety near the decision: free returns, shipping, secure checkout, guarantees.",
+    'Add credible social proof (ratings, review count, "X sold").',
+    "Use urgency/scarcity only when it is genuinely true (low stock, real deadline).",
+    "Cut friction: fewer steps, clearer pricing, no surprise costs."
+  ],
+  saas: [
+    "Lead with the outcome the user gets, not the mechanism.",
+    'Make the primary CTA action-oriented and specific (e.g. "Start free trial").',
+    'Reduce signup friction (fewer fields, SSO, "no credit card required").',
+    "Add proof near the CTA: customer logos, a hard metric, a short testimonial.",
+    "Address the target persona's top objection inline."
+  ],
+  landing: [
+    "One clear message and one primary action above the fold.",
+    "Match the headline to the traffic source / campaign intent.",
+    "Make the CTA specific and benefit-led.",
+    "Add a single strong proof point; remove competing distractions."
+  ],
+  marketplace: [
+    "Reduce choice overload: guide the visitor to a clear next step.",
+    "Surface trust and liquidity signals (ratings, counts, recency).",
+    "Make the primary action on each listing obvious.",
+    "Reassure on safety/guarantees near the point of decision."
+  ]
+};
+var GENERIC_PRIORS = [
+  "Make the primary action unmistakable and benefit-led.",
+  "Lead with the outcome/value for the visitor.",
+  "Remove friction and distractions around the decision.",
+  "Add one credible proof point near the action."
+];
+function priorsFor(contextType) {
+  return BEST_PRACTICE_PRIORS[contextType] ?? GENERIC_PRIORS;
+}
+function computeDataState(impressions, insights, avgReliability) {
+  if (impressions === 0) return "empty";
+  const insightsReady = insights?.status === "ok" && !insights.isStale;
+  const reliable = avgReliability === null || avgReliability >= 0.3;
+  if (impressions < GOAL_TARGET || !insightsReady || !reliable) return "collecting";
+  return "sufficient";
+}
+function guidanceFor(dataState, contextType) {
+  switch (dataState) {
+    case "sufficient":
+      return "There is enough data. Target the specific weakness above \u2014 the underperforming variant/persona \u2014 with your change. Set basis to the signal you used.";
+    case "collecting":
+      return "Limited data so far. Lean on the best-practice priors below, lightly informed by the early signal. Make one focused change rather than a redesign.";
+    case "empty":
+      return `No data yet \u2014 use your best judgment. Apply the best-practice priors for a ${contextType} surface below. Make one conservative, high-confidence change, and consider enabling shadow mode for this component so it is validated before it serves real traffic.`;
+  }
+}
+async function settled(p) {
+  try {
+    return await p;
+  } catch {
+    return null;
+  }
+}
+function registerVariantBriefTools(server, client) {
+  server.tool(
+    "get_variant_brief",
+    "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.",
+    {
+      projectId: projectIdSchema9,
+      componentId: import_zod9.z.string().describe('The component ID to write a new variant for (matches <Adaptive id="...">).')
+    },
+    async ({ projectId, componentId }) => {
+      const id = encodeURIComponent(projectId);
+      const [projects, components, trends, portraits, insights] = await Promise.all([
+        settled(client.get("/projects")),
+        settled(client.get(`/projects/${id}/components`)),
+        settled(client.get(`/projects/${id}/trends`)),
+        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 component = components?.find((c) => c.component_id === componentId) ?? null;
+      const impressions = component?.total_impressions ?? 0;
+      const conversions = component?.total_conversions ?? 0;
+      const componentCvr = impressions > 0 ? conversions / impressions * 100 : 0;
+      const existingVariantIds = component?.variants.map((v) => v.variant_id) ?? [];
+      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 avgReliability = clusters.length ? clusters.reduce((s, c) => s + c.avgReliability, 0) / clusters.length : null;
+      const dataState = computeDataState(impressions, insights, avgReliability);
+      const lines = [];
+      lines.push(`# Variant brief \u2014 ${componentId}`);
+      lines.push(`Project context type: ${contextType}`);
+      lines.push("");
+      if (!component) {
+        lines.push(
+          `Note: no component named "${componentId}" has reported data yet. If this is a new <Adaptive> you are adding, that is expected \u2014 it registers automatically on first assignment after deploy. Proceed using the best-practice priors below.`
+        );
+        lines.push("");
+      } else {
+        lines.push(
+          `Component performance: ${impressions} impressions, ${conversions} conversions, ${componentCvr.toFixed(2)}% CVR.`
+        );
+        lines.push(
+          `Existing variant IDs (do not reuse these): ${existingVariantIds.length ? existingVariantIds.join(", ") : "(none)"}`
+        );
+        lines.push("");
+      }
+      if (variantPerf.length) {
+        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"})`
+          );
+        }
+        lines.push("");
+      }
+      if (clusters.length) {
+        lines.push(`Audience (${totalSessions} sessions):`);
+        for (const c of clusters) {
+          const share = totalSessions > 0 ? (c.sessionCount / totalSessions * 100).toFixed(0) : "0";
+          lines.push(`- ${c.label}: ${share}% of traffic (reliability ${(c.avgReliability * 100).toFixed(0)}%)`);
+        }
+        lines.push("");
+      }
+      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 ?? [];
+        if (narrator.length) {
+          lines.push("Insights \u2014 observations:");
+          narrator.forEach((b) => lines.push(`- ${b}`));
+        }
+        if (advisor.length) {
+          lines.push("Insights \u2014 recommendations:");
+          advisor.forEach((b) => lines.push(`- ${b}`));
+        }
+        lines.push("");
+      } else {
+        lines.push("Insights: none generated yet.");
+        lines.push("");
+      }
+      lines.push(`## Data sufficiency: ${dataState.toUpperCase()}`);
+      lines.push(guidanceFor(dataState, contextType));
+      lines.push("");
+      lines.push(`## Best-practice priors (${contextType})`);
+      priorsFor(contextType).forEach((p) => lines.push(`- ${p}`));
+      lines.push("");
+      lines.push("## How to implement (code-native variant)");
+      lines.push(`1. Search the repository for <Adaptive id="${componentId}"> (and any matching useAssignment("${componentId}") usage).`);
+      lines.push('2. Add a new key to its `variants` map with on-brand JSX that matches the surrounding components and the project\'s design system. Pick a short, descriptive new variant id that is not in the existing list above (e.g. "value_led", "social_proof", "urgency").');
+      lines.push("3. If the component is server-rendered via <AdaptiveRoot>, add the new variant id to that component's entry in the `components` list so it is included in SSR preloading.");
+      lines.push("4. Do NOT call create_variant \u2014 that creates a separate no-code MANAGED draft. Code-native variants register automatically on the first assignment after you deploy, and go live immediately.");
+      lines.push("5. Commit, push, and deploy. Optionally enable shadow mode for this component first if you want to validate before serving real traffic.");
+      lines.push("");
+      lines.push("Make the change reflect the data sufficiency above: data-driven when SUFFICIENT, best-practice-led when COLLECTING or EMPTY.");
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+
+// src/tools/test-brief.ts
+var import_zod10 = require("zod");
+var projectIdSchema10 = import_zod10.z.string().uuid().describe("The project UUID");
+async function settled2(p) {
+  try {
+    return await p;
+  } catch {
+    return null;
+  }
+}
+function registerTestBriefTools(server, client) {
+  server.tool(
+    "get_test_brief",
+    "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).",
+    {
+      projectId: projectIdSchema10,
+      componentId: import_zod10.z.string().describe('The component ID to write a test for (matches <Adaptive id="...">).')
+    },
+    async ({ projectId, componentId }) => {
+      const id = encodeURIComponent(projectId);
+      const [components, goalsRes] = await Promise.all([
+        settled2(client.get(`/projects/${id}/components`)),
+        settled2(client.get(`/projects/${id}/goals`))
+      ]);
+      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 lines = [];
+      lines.push(`# Test brief \u2014 ${componentId}`);
+      lines.push("");
+      lines.push("This project uses **`@sentientui/react/testing`**. By default SentientUI serves the *control* variant and default layout in tests and sends no events, so existing tests are unaffected. Pass a scenario to force a specific variant/layout.");
+      if (!component) {
+        lines.push("");
+        lines.push(`Note: no component named "${componentId}" has reported data yet. If you are adding this \`<Adaptive>\`, that is expected \u2014 the example below uses placeholder variant IDs; replace them with the ones you declare in \`variants={{ \u2026 }}\`.`);
+      }
+      lines.push("");
+      lines.push("## React Testing Library");
+      lines.push("```tsx");
+      lines.push(`import { renderWithSentient } from '@sentientui/react/testing';`);
+      lines.push(`import { screen } from '@testing-library/react';`);
+      lines.push("");
+      lines.push(`test('${componentId}: forces the "${forcedId}" variant', () => {`);
+      lines.push(`  renderWithSentient(<YourPage />, { variants: { ${componentId}: '${forcedId}' } });`);
+      lines.push(`  // assert on the ${forcedId} variant's content:`);
+      lines.push(`  // expect(screen.getByText('\u2026')).toBeInTheDocument();`);
+      lines.push("});");
+      lines.push("```");
+      lines.push("");
+      lines.push("## Assert a goal fires (with the mock server)");
+      lines.push("```tsx");
+      lines.push(`import { setupSentientServer } from '@sentientui/react/testing/node';`);
+      lines.push(`import { getSentientEvents, hasFiredGoal } from '@sentientui/react/testing';`);
+      lines.push("");
+      lines.push(`const s = setupSentientServer();`);
+      lines.push(`afterAll(() => s.server.close());`);
+      lines.push("");
+      lines.push(`test('${componentId}: fires the ${goalName} goal', async () => {`);
+      lines.push(`  s.use({ variants: { ${componentId}: '${forcedId}' } });`);
+      lines.push(`  // \u2026render with a live client, trigger the interaction\u2026`);
+      lines.push(`  expect(hasFiredGoal(getSentientEvents(), '${goalName}')).toBe(true);`);
+      lines.push("});");
+      lines.push("```");
+      lines.push("");
+      lines.push("## E2E (Playwright / Cypress)");
+      lines.push(`Use \`mockSentient\` to force variants/layout, stub the API, and capture events:`);
+      lines.push("```ts");
+      lines.push(`import { mockSentient } from '@sentientui/react/testing';`);
+      lines.push("");
+      lines.push(`const s = await mockSentient(page, { variants: { ${componentId}: '${forcedId}' } });`);
+      lines.push(`await page.goto('/');`);
+      lines.push(`expect(s.events().some((e) => e.goalType === '${goalName}')).toBe(true);`);
+      lines.push("```");
+      lines.push(`Cypress: \`mockSentientCypress(cy, scenario)\` in a beforeEach. **Prefer mockSentient in CI \u2014 it writes nothing.**`);
+      lines.push(`The URL param below is fine for a quick local pin, but a live client still creates an (automation-flagged) session:`);
+      lines.push("```ts");
+      lines.push(`await page.goto('/?sentient_variant=${componentId}:${forcedId}');`);
+      lines.push("```");
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+
 // src/server.ts
 function createMcpServer(client) {
   const server = new import_mcp.McpServer({
@@ -327,6 +583,8 @@ function createMcpServer(client) {
   registerGoalTools(server, client);
   registerGuardrailTools(server, client);
   registerLayoutTools(server, client);
+  registerVariantBriefTools(server, client);
+  registerTestBriefTools(server, client);
   registerVariantWriteTools(server, client);
   return server;
 }

package/dist/index.js

@@ -174,9 +174,10 @@ function registerPersonaTools(server, client) {
         `Total sessions: ${data.totalSessions}`,
         "",
         "Clusters:",
-        ...data.clusters.map(
-          (c) => `- ${c.label}: ${c.sessionCount} sessions (${(c.sessionCount / data.totalSessions * 100).toFixed(1)}% of traffic, reliability ${(c.avgReliability * 100).toFixed(0)}%)`
-        )
+        ...data.clusters.map((c) => {
+          const pct = data.totalSessions > 0 ? c.sessionCount / data.totalSessions * 100 : 0;
+          return `- ${c.label}: ${c.sessionCount} sessions (${pct.toFixed(1)}% of traffic, reliability ${(c.avgReliability * 100).toFixed(0)}%)`;
+        })
       ];
       return { content: [{ type: "text", text: lines.join("\n") }] };
     }
@@ -257,22 +258,24 @@ var projectIdSchema8 = z8.string().uuid().describe("The project UUID");
 function registerVariantWriteTools(server, client) {
   server.tool(
     "create_variant",
-    "Create a new draft variant for a component. Requires Starter or Growth plan.",
+    "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 Starter or Growth plan.",
     {
       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")
+      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.")
     },
-    async ({ projectId, componentId, displayName }) => {
+    async ({ projectId, componentId, displayName, content }) => {
       const id = encodeURIComponent(projectId);
       const result = await client.post(
         `/projects/${id}/variants`,
-        { componentId, displayName }
+        { componentId, displayName, content }
       );
+      const contentNote = content ? " with the provided text content" : " (empty \u2014 add its text content from the dashboard or via a follow-up update)";
       return {
         content: [{
           type: "text",
-          text: `Variant created: ${result.variantId} ("${result.displayName}") for component ${componentId}. It is in draft state \u2014 activate it from the dashboard.`
+          text: `Managed text variant created: ${result.variantId} ("${result.displayName}") for component ${componentId}${contentNote}. It is in draft state \u2014 activate it from the dashboard. Reminder: this is a no-code managed variant; for code-native variants, edit the code instead (see get_variant_brief).`
         }]
       };
     }
@@ -313,6 +316,259 @@ function registerVariantWriteTools(server, client) {
   );
 }
 
+// src/tools/variant-brief.ts
+import { z as z9 } from "zod";
+var projectIdSchema9 = z9.string().uuid().describe("The project UUID");
+var GOAL_TARGET = 500;
+var BEST_PRACTICE_PRIORS = {
+  ecommerce: [
+    "Lead with the core benefit/value, not features.",
+    "Make the primary action (add to cart / buy) unmistakable and high-contrast.",
+    "Reduce purchase anxiety near the decision: free returns, shipping, secure checkout, guarantees.",
+    'Add credible social proof (ratings, review count, "X sold").',
+    "Use urgency/scarcity only when it is genuinely true (low stock, real deadline).",
+    "Cut friction: fewer steps, clearer pricing, no surprise costs."
+  ],
+  saas: [
+    "Lead with the outcome the user gets, not the mechanism.",
+    'Make the primary CTA action-oriented and specific (e.g. "Start free trial").',
+    'Reduce signup friction (fewer fields, SSO, "no credit card required").',
+    "Add proof near the CTA: customer logos, a hard metric, a short testimonial.",
+    "Address the target persona's top objection inline."
+  ],
+  landing: [
+    "One clear message and one primary action above the fold.",
+    "Match the headline to the traffic source / campaign intent.",
+    "Make the CTA specific and benefit-led.",
+    "Add a single strong proof point; remove competing distractions."
+  ],
+  marketplace: [
+    "Reduce choice overload: guide the visitor to a clear next step.",
+    "Surface trust and liquidity signals (ratings, counts, recency).",
+    "Make the primary action on each listing obvious.",
+    "Reassure on safety/guarantees near the point of decision."
+  ]
+};
+var GENERIC_PRIORS = [
+  "Make the primary action unmistakable and benefit-led.",
+  "Lead with the outcome/value for the visitor.",
+  "Remove friction and distractions around the decision.",
+  "Add one credible proof point near the action."
+];
+function priorsFor(contextType) {
+  return BEST_PRACTICE_PRIORS[contextType] ?? GENERIC_PRIORS;
+}
+function computeDataState(impressions, insights, avgReliability) {
+  if (impressions === 0) return "empty";
+  const insightsReady = insights?.status === "ok" && !insights.isStale;
+  const reliable = avgReliability === null || avgReliability >= 0.3;
+  if (impressions < GOAL_TARGET || !insightsReady || !reliable) return "collecting";
+  return "sufficient";
+}
+function guidanceFor(dataState, contextType) {
+  switch (dataState) {
+    case "sufficient":
+      return "There is enough data. Target the specific weakness above \u2014 the underperforming variant/persona \u2014 with your change. Set basis to the signal you used.";
+    case "collecting":
+      return "Limited data so far. Lean on the best-practice priors below, lightly informed by the early signal. Make one focused change rather than a redesign.";
+    case "empty":
+      return `No data yet \u2014 use your best judgment. Apply the best-practice priors for a ${contextType} surface below. Make one conservative, high-confidence change, and consider enabling shadow mode for this component so it is validated before it serves real traffic.`;
+  }
+}
+async function settled(p) {
+  try {
+    return await p;
+  } catch {
+    return null;
+  }
+}
+function registerVariantBriefTools(server, client) {
+  server.tool(
+    "get_variant_brief",
+    "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.",
+    {
+      projectId: projectIdSchema9,
+      componentId: z9.string().describe('The component ID to write a new variant for (matches <Adaptive id="...">).')
+    },
+    async ({ projectId, componentId }) => {
+      const id = encodeURIComponent(projectId);
+      const [projects, components, trends, portraits, insights] = await Promise.all([
+        settled(client.get("/projects")),
+        settled(client.get(`/projects/${id}/components`)),
+        settled(client.get(`/projects/${id}/trends`)),
+        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 component = components?.find((c) => c.component_id === componentId) ?? null;
+      const impressions = component?.total_impressions ?? 0;
+      const conversions = component?.total_conversions ?? 0;
+      const componentCvr = impressions > 0 ? conversions / impressions * 100 : 0;
+      const existingVariantIds = component?.variants.map((v) => v.variant_id) ?? [];
+      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 avgReliability = clusters.length ? clusters.reduce((s, c) => s + c.avgReliability, 0) / clusters.length : null;
+      const dataState = computeDataState(impressions, insights, avgReliability);
+      const lines = [];
+      lines.push(`# Variant brief \u2014 ${componentId}`);
+      lines.push(`Project context type: ${contextType}`);
+      lines.push("");
+      if (!component) {
+        lines.push(
+          `Note: no component named "${componentId}" has reported data yet. If this is a new <Adaptive> you are adding, that is expected \u2014 it registers automatically on first assignment after deploy. Proceed using the best-practice priors below.`
+        );
+        lines.push("");
+      } else {
+        lines.push(
+          `Component performance: ${impressions} impressions, ${conversions} conversions, ${componentCvr.toFixed(2)}% CVR.`
+        );
+        lines.push(
+          `Existing variant IDs (do not reuse these): ${existingVariantIds.length ? existingVariantIds.join(", ") : "(none)"}`
+        );
+        lines.push("");
+      }
+      if (variantPerf.length) {
+        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"})`
+          );
+        }
+        lines.push("");
+      }
+      if (clusters.length) {
+        lines.push(`Audience (${totalSessions} sessions):`);
+        for (const c of clusters) {
+          const share = totalSessions > 0 ? (c.sessionCount / totalSessions * 100).toFixed(0) : "0";
+          lines.push(`- ${c.label}: ${share}% of traffic (reliability ${(c.avgReliability * 100).toFixed(0)}%)`);
+        }
+        lines.push("");
+      }
+      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 ?? [];
+        if (narrator.length) {
+          lines.push("Insights \u2014 observations:");
+          narrator.forEach((b) => lines.push(`- ${b}`));
+        }
+        if (advisor.length) {
+          lines.push("Insights \u2014 recommendations:");
+          advisor.forEach((b) => lines.push(`- ${b}`));
+        }
+        lines.push("");
+      } else {
+        lines.push("Insights: none generated yet.");
+        lines.push("");
+      }
+      lines.push(`## Data sufficiency: ${dataState.toUpperCase()}`);
+      lines.push(guidanceFor(dataState, contextType));
+      lines.push("");
+      lines.push(`## Best-practice priors (${contextType})`);
+      priorsFor(contextType).forEach((p) => lines.push(`- ${p}`));
+      lines.push("");
+      lines.push("## How to implement (code-native variant)");
+      lines.push(`1. Search the repository for <Adaptive id="${componentId}"> (and any matching useAssignment("${componentId}") usage).`);
+      lines.push('2. Add a new key to its `variants` map with on-brand JSX that matches the surrounding components and the project\'s design system. Pick a short, descriptive new variant id that is not in the existing list above (e.g. "value_led", "social_proof", "urgency").');
+      lines.push("3. If the component is server-rendered via <AdaptiveRoot>, add the new variant id to that component's entry in the `components` list so it is included in SSR preloading.");
+      lines.push("4. Do NOT call create_variant \u2014 that creates a separate no-code MANAGED draft. Code-native variants register automatically on the first assignment after you deploy, and go live immediately.");
+      lines.push("5. Commit, push, and deploy. Optionally enable shadow mode for this component first if you want to validate before serving real traffic.");
+      lines.push("");
+      lines.push("Make the change reflect the data sufficiency above: data-driven when SUFFICIENT, best-practice-led when COLLECTING or EMPTY.");
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+
+// src/tools/test-brief.ts
+import { z as z10 } from "zod";
+var projectIdSchema10 = z10.string().uuid().describe("The project UUID");
+async function settled2(p) {
+  try {
+    return await p;
+  } catch {
+    return null;
+  }
+}
+function registerTestBriefTools(server, client) {
+  server.tool(
+    "get_test_brief",
+    "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).",
+    {
+      projectId: projectIdSchema10,
+      componentId: z10.string().describe('The component ID to write a test for (matches <Adaptive id="...">).')
+    },
+    async ({ projectId, componentId }) => {
+      const id = encodeURIComponent(projectId);
+      const [components, goalsRes] = await Promise.all([
+        settled2(client.get(`/projects/${id}/components`)),
+        settled2(client.get(`/projects/${id}/goals`))
+      ]);
+      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 lines = [];
+      lines.push(`# Test brief \u2014 ${componentId}`);
+      lines.push("");
+      lines.push("This project uses **`@sentientui/react/testing`**. By default SentientUI serves the *control* variant and default layout in tests and sends no events, so existing tests are unaffected. Pass a scenario to force a specific variant/layout.");
+      if (!component) {
+        lines.push("");
+        lines.push(`Note: no component named "${componentId}" has reported data yet. If you are adding this \`<Adaptive>\`, that is expected \u2014 the example below uses placeholder variant IDs; replace them with the ones you declare in \`variants={{ \u2026 }}\`.`);
+      }
+      lines.push("");
+      lines.push("## React Testing Library");
+      lines.push("```tsx");
+      lines.push(`import { renderWithSentient } from '@sentientui/react/testing';`);
+      lines.push(`import { screen } from '@testing-library/react';`);
+      lines.push("");
+      lines.push(`test('${componentId}: forces the "${forcedId}" variant', () => {`);
+      lines.push(`  renderWithSentient(<YourPage />, { variants: { ${componentId}: '${forcedId}' } });`);
+      lines.push(`  // assert on the ${forcedId} variant's content:`);
+      lines.push(`  // expect(screen.getByText('\u2026')).toBeInTheDocument();`);
+      lines.push("});");
+      lines.push("```");
+      lines.push("");
+      lines.push("## Assert a goal fires (with the mock server)");
+      lines.push("```tsx");
+      lines.push(`import { setupSentientServer } from '@sentientui/react/testing/node';`);
+      lines.push(`import { getSentientEvents, hasFiredGoal } from '@sentientui/react/testing';`);
+      lines.push("");
+      lines.push(`const s = setupSentientServer();`);
+      lines.push(`afterAll(() => s.server.close());`);
+      lines.push("");
+      lines.push(`test('${componentId}: fires the ${goalName} goal', async () => {`);
+      lines.push(`  s.use({ variants: { ${componentId}: '${forcedId}' } });`);
+      lines.push(`  // \u2026render with a live client, trigger the interaction\u2026`);
+      lines.push(`  expect(hasFiredGoal(getSentientEvents(), '${goalName}')).toBe(true);`);
+      lines.push("});");
+      lines.push("```");
+      lines.push("");
+      lines.push("## E2E (Playwright / Cypress)");
+      lines.push(`Use \`mockSentient\` to force variants/layout, stub the API, and capture events:`);
+      lines.push("```ts");
+      lines.push(`import { mockSentient } from '@sentientui/react/testing';`);
+      lines.push("");
+      lines.push(`const s = await mockSentient(page, { variants: { ${componentId}: '${forcedId}' } });`);
+      lines.push(`await page.goto('/');`);
+      lines.push(`expect(s.events().some((e) => e.goalType === '${goalName}')).toBe(true);`);
+      lines.push("```");
+      lines.push(`Cypress: \`mockSentientCypress(cy, scenario)\` in a beforeEach. **Prefer mockSentient in CI \u2014 it writes nothing.**`);
+      lines.push(`The URL param below is fine for a quick local pin, but a live client still creates an (automation-flagged) session:`);
+      lines.push("```ts");
+      lines.push(`await page.goto('/?sentient_variant=${componentId}:${forcedId}');`);
+      lines.push("```");
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+
 // src/server.ts
 function createMcpServer(client) {
   const server = new McpServer({
@@ -326,6 +582,8 @@ function createMcpServer(client) {
   registerGoalTools(server, client);
   registerGuardrailTools(server, client);
   registerLayoutTools(server, client);
+  registerVariantBriefTools(server, client);
+  registerTestBriefTools(server, client);
   registerVariantWriteTools(server, client);
   return server;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentientui/mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "MCP server for SentientUI — exposes project data and actions to AI agents",
   "type": "module",
   "bin": {
@@ -18,15 +18,9 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "AGENTS.md"
   ],
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "dev": "tsx src/index.ts",
-    "prepublishOnly": "pnpm build && pnpm typecheck"
-  },
   "publishConfig": {
     "access": "public"
   },
@@ -40,5 +34,11 @@
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx src/index.ts"
   }
-}
+}