@sentientui/mcp 0.17.6 → 0.18.0

package/AGENTS.md

@@ -43,6 +43,9 @@ Server keys start with `sk_` — required for the management API. Public keys (`
 | `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 |
+| `get_cell_matrix` | "Who sees what": per-(visitor type, region) generation state + traffic share. A missing cell = they see the original |
+| `get_cell_detail` | One cell's generated option, its stored rationale, and a plain-language performance verdict |
+| `generate_cell` | Queues async AI generation for one cell (also retries failed ones). Paid plan; check `get_cell_matrix` for progress |
 
 ## Canonical Workflows
 

package/README.md

@@ -101,6 +101,9 @@ A sandboxed demo token is provisioned automatically — 10 calls/month, read-onl
 | `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 |
+| `get_cell_matrix` | The "Who sees what" matrix: which visitor types have an AI-generated version live in each personalizable region, with traffic share and auto-fill status |
+| `get_cell_detail` | One cell's story: the generated option, why it was written (stored rationale), and how it performs vs the original |
+| `generate_cell` | Queue AI generation of a version for one (visitor type, region) cell — brand-locked, live in under a minute (paid plan) |
 
 > **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.
 >

package/dist/{chunk-FBRHD7R7.js → chunk-PX6RCSB2.js}

@@ -44,10 +44,9 @@ var ApiClient = class {
     var _a, _b;
     const res = await fetch(`${this.baseUrl}/v1/mgmt${path}`, {
       method,
-      headers: {
-        authorization: `Bearer ${this.apiKey}`,
-        "content-type": "application/json"
-      },
+      headers: __spreadValues({
+        authorization: `Bearer ${this.apiKey}`
+      }, body !== void 0 ? { "content-type": "application/json" } : {}),
       body: body !== void 0 ? JSON.stringify(body) : void 0
     });
     if (res.ok) return res.json();
@@ -1857,6 +1856,15 @@ useLayoutOrder(). Non-React sites: sections: ['#hero', '#pricing', '#faq'] (CSS
 the theme's natural order) in window.sentient \u2014 the snippet reorders those elements within
 their shared parent, and applies nothing if any selector drifts.
 
+## No-code install order (snippet)
+
+Three tags in <head>, in this order: the window.sentient config, the inline pre-paint script,
+then the deferred loader. The middle tag is optional but recommended \u2014 the loader is deferred,
+so on a return visit the page can paint its original state before the loader runs; the inline
+script applies the last served decision from the visitor's own device first, with no network
+call and no cloak. Get its exact bytes from the dashboard's Install page, or from
+renderSnippetPrePaintScript() in '@sentientui/snippet/install'.
+
 ## Testing the integration
 
 Use '@sentientui/react/testing': renderWithSentient(ui, { variants, slots, persona }) forces
@@ -2018,8 +2026,158 @@ function registerAgentTrafficTools(server, client) {
   );
 }
 
+// src/tools/cells.ts
+import { z as z15 } from "zod";
+var personaOutput = z15.object({
+  key: z15.string(),
+  displayName: z15.string(),
+  description: z15.string().nullable(),
+  share: z15.number().describe("Fraction of 30-day decided sessions")
+});
+var cellOutput = z15.object({
+  slotId: z15.string(),
+  persona: z15.string(),
+  status: z15.string().describe("pending | generating | live | error | rejected"),
+  requestedBy: z15.string(),
+  armId: z15.string().nullable(),
+  rationale: z15.string().nullable(),
+  error: z15.string().nullable(),
+  updatedAt: z15.string(),
+  performance: z15.object({
+    shown: z15.number(),
+    conversions: z15.number(),
+    deltaPct: z15.number().nullable().describe("Signed % vs the original conversion rate"),
+    tier: z15.string().describe("early | no_baseline | winning | losing | flat")
+  }).optional().describe("Present on live cells: the at-a-glance readout")
+});
+function registerCellTools(server, client) {
+  server.registerTool(
+    "get_cell_matrix",
+    {
+      title: "Persona \xD7 slot cell matrix",
+      description: 'The "Who sees what" matrix: which visitor types (personas) have an AI-generated version live in each personalizable region (slot), with per-persona traffic share and the first-miss auto-fill setting. A cell with no row means that visitor type sees the original.' + UNTRUSTED_FIELDS_NOTE,
+      inputSchema: { projectId: projectIdSchema },
+      outputSchema: {
+        slots: z15.array(z15.object({ slotId: z15.string(), displayName: z15.string(), supportsForms: z15.boolean() })),
+        personas: z15.array(personaOutput),
+        cells: z15.array(cellOutput),
+        autoFill: z15.boolean(),
+        personaSource: z15.string().describe("Active persona-set source: default | declared | discovered"),
+        undecidedShare: z15.number()
+      },
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/cells`);
+      const byCell = new Map(data.cells.map((c) => [`${c.slotId}::${c.persona}`, c]));
+      const lines = [
+        `Slots: ${data.slots.map((s) => untrusted(s.displayName)).join(", ") || "(none published)"}`,
+        `Auto-fill on first miss: ${data.autoFill ? "ON" : "off"} \xB7 persona source: ${data.personaSource}`
+      ];
+      for (const p of data.personas) {
+        const states = data.slots.map((s) => {
+          const c = byCell.get(`${s.slotId}::${p.key}`);
+          return `${untrusted(s.displayName, 40)}: ${c ? c.status : "original"}`;
+        });
+        lines.push(`- ${untrusted(p.displayName)} (${Math.round(p.share * 100)}% of visitors) \u2014 ${states.join(" \xB7 ")}`);
+      }
+      lines.push(`Undecided visitors (${Math.round(data.undecidedShare * 100)}%) always see the original.`);
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        structuredContent: data
+      };
+    })
+  );
+  server.registerTool(
+    "get_cell_detail",
+    {
+      title: "Cell story",
+      description: "One cell's full story: the generated option a visitor type sees in a slot, why it was written (the stored generation rationale), and how it is performing vs the original (deterministic plain-language verdict)." + UNTRUSTED_FIELDS_NOTE,
+      inputSchema: {
+        projectId: projectIdSchema,
+        slotId: z15.string().min(1).max(128).describe("The slot id (a matrix column)"),
+        persona: z15.string().min(1).max(64).describe("The persona key (a matrix row)")
+      },
+      outputSchema: {
+        cell: cellOutput.nullable(),
+        arm: z15.object({
+          id: z15.string(),
+          displayName: z15.string().nullable(),
+          content: z15.string().nullable(),
+          blocks: z15.unknown().nullable()
+        }).nullable(),
+        performance: z15.object({
+          shown: z15.number(),
+          conversions: z15.number(),
+          conversionRate: z15.number(),
+          baselineShown: z15.number(),
+          baselineConversions: z15.number(),
+          baselineConversionRate: z15.number()
+        }).nullable(),
+        verdict: z15.string()
+      },
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, slotId, persona }) => {
+      var _a, _b;
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/cells/detail?slotId=${encodeURIComponent(slotId)}&persona=${encodeURIComponent(persona)}`);
+      const lines = [];
+      if (data.arm) {
+        lines.push(
+          data.arm.content !== null ? `They see: "${untrusted(data.arm.content, 300)}"` : `They see a designed layout (option ${untrusted(data.arm.id, 64)}).`
+        );
+      } else {
+        lines.push("No generated version is live for this cell.");
+      }
+      if ((_a = data.cell) == null ? void 0 : _a.rationale) lines.push(`Why this exists: ${untrusted(data.cell.rationale, 500)}`);
+      if ((_b = data.cell) == null ? void 0 : _b.error) lines.push(`Last attempt failed: ${untrusted(data.cell.error, 300)}`);
+      lines.push(data.verdict);
+      if (data.performance) {
+        lines.push(`Shown ${data.performance.shown} times, ${data.performance.conversions} conversions.`);
+      }
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        structuredContent: data
+      };
+    })
+  );
+  server.registerTool(
+    "generate_cell",
+    {
+      title: "Generate a cell version",
+      description: "Queue AI generation of a version for one (persona, slot) cell. The worker writes it asynchronously (usually under a minute), brand-locked, and it goes live as a named option the optimizer explores. Also works to regenerate or retry a failed cell. Requires a paid plan (anonymous demo tokens are read-only).",
+      inputSchema: {
+        projectId: projectIdSchema,
+        slotId: z15.string().min(1).max(128).describe("The slot id (a matrix column)"),
+        persona: z15.string().min(1).max(64).describe("The persona key (a matrix row)")
+      },
+      outputSchema: {
+        slotId: z15.string(),
+        persona: z15.string(),
+        status: z15.literal("pending").describe("Queued \u2014 check get_cell_matrix for progress")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, slotId, persona }) => {
+      const id = encodeURIComponent(projectId);
+      await client.post(`/projects/${id}/cells/generate`, { slotId, persona });
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Writing a version of ${untrusted(slotId, 64)} for ${untrusted(persona, 64)} \u2014 it usually goes live in under a minute. Check get_cell_matrix (status flips pending \u2192 live) or get_cell_detail for the story once it lands.`
+          }
+        ],
+        structuredContent: { slotId, persona, status: "pending" }
+      };
+    })
+  );
+}
+
 // src/server.ts
-var PKG_VERSION = true ? "0.17.6" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.18.0" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new McpServer(
     {
@@ -2054,6 +2212,7 @@ function createMcpServer(client) {
   registerVariantWriteTools(server, client);
   registerIntegrationGuideTools(server);
   registerAgentTrafficTools(server, client);
+  registerCellTools(server, client);
   return server;
 }
 

package/dist/index.cjs

@@ -48,10 +48,9 @@ var ApiClient = class {
     var _a2, _b;
     const res = await fetch(`${this.baseUrl}/v1/mgmt${path}`, {
       method,
-      headers: {
-        authorization: `Bearer ${this.apiKey}`,
-        "content-type": "application/json"
-      },
+      headers: __spreadValues({
+        authorization: `Bearer ${this.apiKey}`
+      }, body !== void 0 ? { "content-type": "application/json" } : {}),
       body: body !== void 0 ? JSON.stringify(body) : void 0
     });
     if (res.ok) return res.json();
@@ -1863,6 +1862,15 @@ useLayoutOrder(). Non-React sites: sections: ['#hero', '#pricing', '#faq'] (CSS
 the theme's natural order) in window.sentient \u2014 the snippet reorders those elements within
 their shared parent, and applies nothing if any selector drifts.
 
+## No-code install order (snippet)
+
+Three tags in <head>, in this order: the window.sentient config, the inline pre-paint script,
+then the deferred loader. The middle tag is optional but recommended \u2014 the loader is deferred,
+so on a return visit the page can paint its original state before the loader runs; the inline
+script applies the last served decision from the visitor's own device first, with no network
+call and no cloak. Get its exact bytes from the dashboard's Install page, or from
+renderSnippetPrePaintScript() in '@sentientui/snippet/install'.
+
 ## Testing the integration
 
 Use '@sentientui/react/testing': renderWithSentient(ui, { variants, slots, persona }) forces
@@ -2024,8 +2032,158 @@ function registerAgentTrafficTools(server, client) {
   );
 }
 
+// src/tools/cells.ts
+var import_zod15 = require("zod");
+var personaOutput = import_zod15.z.object({
+  key: import_zod15.z.string(),
+  displayName: import_zod15.z.string(),
+  description: import_zod15.z.string().nullable(),
+  share: import_zod15.z.number().describe("Fraction of 30-day decided sessions")
+});
+var cellOutput = import_zod15.z.object({
+  slotId: import_zod15.z.string(),
+  persona: import_zod15.z.string(),
+  status: import_zod15.z.string().describe("pending | generating | live | error | rejected"),
+  requestedBy: import_zod15.z.string(),
+  armId: import_zod15.z.string().nullable(),
+  rationale: import_zod15.z.string().nullable(),
+  error: import_zod15.z.string().nullable(),
+  updatedAt: import_zod15.z.string(),
+  performance: import_zod15.z.object({
+    shown: import_zod15.z.number(),
+    conversions: import_zod15.z.number(),
+    deltaPct: import_zod15.z.number().nullable().describe("Signed % vs the original conversion rate"),
+    tier: import_zod15.z.string().describe("early | no_baseline | winning | losing | flat")
+  }).optional().describe("Present on live cells: the at-a-glance readout")
+});
+function registerCellTools(server, client) {
+  server.registerTool(
+    "get_cell_matrix",
+    {
+      title: "Persona \xD7 slot cell matrix",
+      description: 'The "Who sees what" matrix: which visitor types (personas) have an AI-generated version live in each personalizable region (slot), with per-persona traffic share and the first-miss auto-fill setting. A cell with no row means that visitor type sees the original.' + UNTRUSTED_FIELDS_NOTE,
+      inputSchema: { projectId: projectIdSchema },
+      outputSchema: {
+        slots: import_zod15.z.array(import_zod15.z.object({ slotId: import_zod15.z.string(), displayName: import_zod15.z.string(), supportsForms: import_zod15.z.boolean() })),
+        personas: import_zod15.z.array(personaOutput),
+        cells: import_zod15.z.array(cellOutput),
+        autoFill: import_zod15.z.boolean(),
+        personaSource: import_zod15.z.string().describe("Active persona-set source: default | declared | discovered"),
+        undecidedShare: import_zod15.z.number()
+      },
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/cells`);
+      const byCell = new Map(data.cells.map((c) => [`${c.slotId}::${c.persona}`, c]));
+      const lines = [
+        `Slots: ${data.slots.map((s) => untrusted(s.displayName)).join(", ") || "(none published)"}`,
+        `Auto-fill on first miss: ${data.autoFill ? "ON" : "off"} \xB7 persona source: ${data.personaSource}`
+      ];
+      for (const p of data.personas) {
+        const states = data.slots.map((s) => {
+          const c = byCell.get(`${s.slotId}::${p.key}`);
+          return `${untrusted(s.displayName, 40)}: ${c ? c.status : "original"}`;
+        });
+        lines.push(`- ${untrusted(p.displayName)} (${Math.round(p.share * 100)}% of visitors) \u2014 ${states.join(" \xB7 ")}`);
+      }
+      lines.push(`Undecided visitors (${Math.round(data.undecidedShare * 100)}%) always see the original.`);
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        structuredContent: data
+      };
+    })
+  );
+  server.registerTool(
+    "get_cell_detail",
+    {
+      title: "Cell story",
+      description: "One cell's full story: the generated option a visitor type sees in a slot, why it was written (the stored generation rationale), and how it is performing vs the original (deterministic plain-language verdict)." + UNTRUSTED_FIELDS_NOTE,
+      inputSchema: {
+        projectId: projectIdSchema,
+        slotId: import_zod15.z.string().min(1).max(128).describe("The slot id (a matrix column)"),
+        persona: import_zod15.z.string().min(1).max(64).describe("The persona key (a matrix row)")
+      },
+      outputSchema: {
+        cell: cellOutput.nullable(),
+        arm: import_zod15.z.object({
+          id: import_zod15.z.string(),
+          displayName: import_zod15.z.string().nullable(),
+          content: import_zod15.z.string().nullable(),
+          blocks: import_zod15.z.unknown().nullable()
+        }).nullable(),
+        performance: import_zod15.z.object({
+          shown: import_zod15.z.number(),
+          conversions: import_zod15.z.number(),
+          conversionRate: import_zod15.z.number(),
+          baselineShown: import_zod15.z.number(),
+          baselineConversions: import_zod15.z.number(),
+          baselineConversionRate: import_zod15.z.number()
+        }).nullable(),
+        verdict: import_zod15.z.string()
+      },
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, slotId, persona }) => {
+      var _a2, _b;
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/cells/detail?slotId=${encodeURIComponent(slotId)}&persona=${encodeURIComponent(persona)}`);
+      const lines = [];
+      if (data.arm) {
+        lines.push(
+          data.arm.content !== null ? `They see: "${untrusted(data.arm.content, 300)}"` : `They see a designed layout (option ${untrusted(data.arm.id, 64)}).`
+        );
+      } else {
+        lines.push("No generated version is live for this cell.");
+      }
+      if ((_a2 = data.cell) == null ? void 0 : _a2.rationale) lines.push(`Why this exists: ${untrusted(data.cell.rationale, 500)}`);
+      if ((_b = data.cell) == null ? void 0 : _b.error) lines.push(`Last attempt failed: ${untrusted(data.cell.error, 300)}`);
+      lines.push(data.verdict);
+      if (data.performance) {
+        lines.push(`Shown ${data.performance.shown} times, ${data.performance.conversions} conversions.`);
+      }
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        structuredContent: data
+      };
+    })
+  );
+  server.registerTool(
+    "generate_cell",
+    {
+      title: "Generate a cell version",
+      description: "Queue AI generation of a version for one (persona, slot) cell. The worker writes it asynchronously (usually under a minute), brand-locked, and it goes live as a named option the optimizer explores. Also works to regenerate or retry a failed cell. Requires a paid plan (anonymous demo tokens are read-only).",
+      inputSchema: {
+        projectId: projectIdSchema,
+        slotId: import_zod15.z.string().min(1).max(128).describe("The slot id (a matrix column)"),
+        persona: import_zod15.z.string().min(1).max(64).describe("The persona key (a matrix row)")
+      },
+      outputSchema: {
+        slotId: import_zod15.z.string(),
+        persona: import_zod15.z.string(),
+        status: import_zod15.z.literal("pending").describe("Queued \u2014 check get_cell_matrix for progress")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, slotId, persona }) => {
+      const id = encodeURIComponent(projectId);
+      await client.post(`/projects/${id}/cells/generate`, { slotId, persona });
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Writing a version of ${untrusted(slotId, 64)} for ${untrusted(persona, 64)} \u2014 it usually goes live in under a minute. Check get_cell_matrix (status flips pending \u2192 live) or get_cell_detail for the story once it lands.`
+          }
+        ],
+        structuredContent: { slotId, persona, status: "pending" }
+      };
+    })
+  );
+}
+
 // src/server.ts
-var PKG_VERSION = true ? "0.17.6" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.18.0" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new import_mcp.McpServer(
     {
@@ -2060,6 +2218,7 @@ function createMcpServer(client) {
   registerVariantWriteTools(server, client);
   registerIntegrationGuideTools(server);
   registerAgentTrafficTools(server, client);
+  registerCellTools(server, client);
   return server;
 }
 

package/dist/index.js

@@ -2,7 +2,7 @@
 import {
   ApiClient,
   createMcpServer
-} from "./chunk-FBRHD7R7.js";
+} from "./chunk-PX6RCSB2.js";
 
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/lib.cjs

@@ -79,10 +79,9 @@ var ApiClient = class {
     var _a, _b;
     const res = await fetch(`${this.baseUrl}/v1/mgmt${path}`, {
       method,
-      headers: {
-        authorization: `Bearer ${this.apiKey}`,
-        "content-type": "application/json"
-      },
+      headers: __spreadValues({
+        authorization: `Bearer ${this.apiKey}`
+      }, body !== void 0 ? { "content-type": "application/json" } : {}),
       body: body !== void 0 ? JSON.stringify(body) : void 0
     });
     if (res.ok) return res.json();
@@ -1887,6 +1886,15 @@ useLayoutOrder(). Non-React sites: sections: ['#hero', '#pricing', '#faq'] (CSS
 the theme's natural order) in window.sentient \u2014 the snippet reorders those elements within
 their shared parent, and applies nothing if any selector drifts.
 
+## No-code install order (snippet)
+
+Three tags in <head>, in this order: the window.sentient config, the inline pre-paint script,
+then the deferred loader. The middle tag is optional but recommended \u2014 the loader is deferred,
+so on a return visit the page can paint its original state before the loader runs; the inline
+script applies the last served decision from the visitor's own device first, with no network
+call and no cloak. Get its exact bytes from the dashboard's Install page, or from
+renderSnippetPrePaintScript() in '@sentientui/snippet/install'.
+
 ## Testing the integration
 
 Use '@sentientui/react/testing': renderWithSentient(ui, { variants, slots, persona }) forces
@@ -2048,8 +2056,158 @@ function registerAgentTrafficTools(server, client) {
   );
 }
 
+// src/tools/cells.ts
+var import_zod15 = require("zod");
+var personaOutput = import_zod15.z.object({
+  key: import_zod15.z.string(),
+  displayName: import_zod15.z.string(),
+  description: import_zod15.z.string().nullable(),
+  share: import_zod15.z.number().describe("Fraction of 30-day decided sessions")
+});
+var cellOutput = import_zod15.z.object({
+  slotId: import_zod15.z.string(),
+  persona: import_zod15.z.string(),
+  status: import_zod15.z.string().describe("pending | generating | live | error | rejected"),
+  requestedBy: import_zod15.z.string(),
+  armId: import_zod15.z.string().nullable(),
+  rationale: import_zod15.z.string().nullable(),
+  error: import_zod15.z.string().nullable(),
+  updatedAt: import_zod15.z.string(),
+  performance: import_zod15.z.object({
+    shown: import_zod15.z.number(),
+    conversions: import_zod15.z.number(),
+    deltaPct: import_zod15.z.number().nullable().describe("Signed % vs the original conversion rate"),
+    tier: import_zod15.z.string().describe("early | no_baseline | winning | losing | flat")
+  }).optional().describe("Present on live cells: the at-a-glance readout")
+});
+function registerCellTools(server, client) {
+  server.registerTool(
+    "get_cell_matrix",
+    {
+      title: "Persona \xD7 slot cell matrix",
+      description: 'The "Who sees what" matrix: which visitor types (personas) have an AI-generated version live in each personalizable region (slot), with per-persona traffic share and the first-miss auto-fill setting. A cell with no row means that visitor type sees the original.' + UNTRUSTED_FIELDS_NOTE,
+      inputSchema: { projectId: projectIdSchema },
+      outputSchema: {
+        slots: import_zod15.z.array(import_zod15.z.object({ slotId: import_zod15.z.string(), displayName: import_zod15.z.string(), supportsForms: import_zod15.z.boolean() })),
+        personas: import_zod15.z.array(personaOutput),
+        cells: import_zod15.z.array(cellOutput),
+        autoFill: import_zod15.z.boolean(),
+        personaSource: import_zod15.z.string().describe("Active persona-set source: default | declared | discovered"),
+        undecidedShare: import_zod15.z.number()
+      },
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/cells`);
+      const byCell = new Map(data.cells.map((c) => [`${c.slotId}::${c.persona}`, c]));
+      const lines = [
+        `Slots: ${data.slots.map((s) => untrusted(s.displayName)).join(", ") || "(none published)"}`,
+        `Auto-fill on first miss: ${data.autoFill ? "ON" : "off"} \xB7 persona source: ${data.personaSource}`
+      ];
+      for (const p of data.personas) {
+        const states = data.slots.map((s) => {
+          const c = byCell.get(`${s.slotId}::${p.key}`);
+          return `${untrusted(s.displayName, 40)}: ${c ? c.status : "original"}`;
+        });
+        lines.push(`- ${untrusted(p.displayName)} (${Math.round(p.share * 100)}% of visitors) \u2014 ${states.join(" \xB7 ")}`);
+      }
+      lines.push(`Undecided visitors (${Math.round(data.undecidedShare * 100)}%) always see the original.`);
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        structuredContent: data
+      };
+    })
+  );
+  server.registerTool(
+    "get_cell_detail",
+    {
+      title: "Cell story",
+      description: "One cell's full story: the generated option a visitor type sees in a slot, why it was written (the stored generation rationale), and how it is performing vs the original (deterministic plain-language verdict)." + UNTRUSTED_FIELDS_NOTE,
+      inputSchema: {
+        projectId: projectIdSchema,
+        slotId: import_zod15.z.string().min(1).max(128).describe("The slot id (a matrix column)"),
+        persona: import_zod15.z.string().min(1).max(64).describe("The persona key (a matrix row)")
+      },
+      outputSchema: {
+        cell: cellOutput.nullable(),
+        arm: import_zod15.z.object({
+          id: import_zod15.z.string(),
+          displayName: import_zod15.z.string().nullable(),
+          content: import_zod15.z.string().nullable(),
+          blocks: import_zod15.z.unknown().nullable()
+        }).nullable(),
+        performance: import_zod15.z.object({
+          shown: import_zod15.z.number(),
+          conversions: import_zod15.z.number(),
+          conversionRate: import_zod15.z.number(),
+          baselineShown: import_zod15.z.number(),
+          baselineConversions: import_zod15.z.number(),
+          baselineConversionRate: import_zod15.z.number()
+        }).nullable(),
+        verdict: import_zod15.z.string()
+      },
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, slotId, persona }) => {
+      var _a, _b;
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/cells/detail?slotId=${encodeURIComponent(slotId)}&persona=${encodeURIComponent(persona)}`);
+      const lines = [];
+      if (data.arm) {
+        lines.push(
+          data.arm.content !== null ? `They see: "${untrusted(data.arm.content, 300)}"` : `They see a designed layout (option ${untrusted(data.arm.id, 64)}).`
+        );
+      } else {
+        lines.push("No generated version is live for this cell.");
+      }
+      if ((_a = data.cell) == null ? void 0 : _a.rationale) lines.push(`Why this exists: ${untrusted(data.cell.rationale, 500)}`);
+      if ((_b = data.cell) == null ? void 0 : _b.error) lines.push(`Last attempt failed: ${untrusted(data.cell.error, 300)}`);
+      lines.push(data.verdict);
+      if (data.performance) {
+        lines.push(`Shown ${data.performance.shown} times, ${data.performance.conversions} conversions.`);
+      }
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        structuredContent: data
+      };
+    })
+  );
+  server.registerTool(
+    "generate_cell",
+    {
+      title: "Generate a cell version",
+      description: "Queue AI generation of a version for one (persona, slot) cell. The worker writes it asynchronously (usually under a minute), brand-locked, and it goes live as a named option the optimizer explores. Also works to regenerate or retry a failed cell. Requires a paid plan (anonymous demo tokens are read-only).",
+      inputSchema: {
+        projectId: projectIdSchema,
+        slotId: import_zod15.z.string().min(1).max(128).describe("The slot id (a matrix column)"),
+        persona: import_zod15.z.string().min(1).max(64).describe("The persona key (a matrix row)")
+      },
+      outputSchema: {
+        slotId: import_zod15.z.string(),
+        persona: import_zod15.z.string(),
+        status: import_zod15.z.literal("pending").describe("Queued \u2014 check get_cell_matrix for progress")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, slotId, persona }) => {
+      const id = encodeURIComponent(projectId);
+      await client.post(`/projects/${id}/cells/generate`, { slotId, persona });
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Writing a version of ${untrusted(slotId, 64)} for ${untrusted(persona, 64)} \u2014 it usually goes live in under a minute. Check get_cell_matrix (status flips pending \u2192 live) or get_cell_detail for the story once it lands.`
+          }
+        ],
+        structuredContent: { slotId, persona, status: "pending" }
+      };
+    })
+  );
+}
+
 // src/server.ts
-var PKG_VERSION = true ? "0.17.6" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.18.0" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new import_mcp.McpServer(
     {
@@ -2084,6 +2242,7 @@ function createMcpServer(client) {
   registerVariantWriteTools(server, client);
   registerIntegrationGuideTools(server);
   registerAgentTrafficTools(server, client);
+  registerCellTools(server, client);
   return server;
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/lib.js

@@ -4,7 +4,7 @@ import {
   ApiError,
   PUBLIC_UI_RESOURCE_URIS,
   createMcpServer
-} from "./chunk-FBRHD7R7.js";
+} from "./chunk-PX6RCSB2.js";
 export {
   ApiClient,
   ApiError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentientui/mcp",
-  "version": "0.17.6",
+  "version": "0.18.0",
   "description": "MCP server for SentientUI — exposes project data and actions to AI agents",
   "license": "MIT",
   "homepage": "https://sentient-ui.com",