@sentientui/mcp 0.2.0

package/dist/index.cjs

@@ -0,0 +1,391 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/index.ts
+var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+
+// src/api-client.ts
+var ApiError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "ApiError";
+  }
+  status;
+};
+var ApiClient = class {
+  baseUrl;
+  apiKey;
+  constructor(opts) {
+    this.apiKey = opts.apiKey;
+    this.baseUrl = (opts.baseUrl ?? "https://api.sentient-ui.com").replace(/\/$/, "");
+  }
+  async get(path) {
+    const res = await fetch(`${this.baseUrl}/v1/mgmt${path}`, {
+      headers: {
+        authorization: `Bearer ${this.apiKey}`,
+        "content-type": "application/json"
+      }
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      throw new ApiError(res.status, String(body.error ?? res.statusText));
+    }
+    return res.json();
+  }
+  async post(path, body) {
+    const res = await fetch(`${this.baseUrl}/v1/mgmt${path}`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${this.apiKey}`,
+        "content-type": "application/json"
+      },
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      const errBody = await res.json().catch(() => ({}));
+      throw new ApiError(res.status, String(errBody.error ?? res.statusText));
+    }
+    return res.json();
+  }
+};
+
+// src/server.ts
+var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+
+// src/tools/projects.ts
+var import_zod = require("zod");
+var projectIdSchema = import_zod.z.string().uuid().describe("The project UUID");
+function registerProjectTools(server, client) {
+  server.tool(
+    "list_projects",
+    "List all SentientUI projects for the authenticated account.",
+    {},
+    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)})`
+      ).join("\n");
+      return { content: [{ type: "text", text }] };
+    }
+  );
+  server.tool(
+    "get_project_stats",
+    "Get health stats for a project: event volume, session count, agent calls, and status.",
+    { projectId: projectIdSchema },
+    async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const stats = await client.get(`/projects/${id}/health`);
+      const text = [
+        `Status: ${stats.status}`,
+        `Events (24h): ${stats.events24h}`,
+        `Sessions (24h): ${stats.sessions24h}`,
+        `Agent calls (total): ${stats.agentCalls}`,
+        `Last event: ${stats.lastEventAt ?? "never"}`
+      ].join("\n");
+      return { content: [{ type: "text", text }] };
+    }
+  );
+}
+
+// src/tools/components.ts
+var import_zod2 = require("zod");
+var projectIdSchema2 = import_zod2.z.string().uuid().describe("The project UUID");
+function registerComponentTools(server, client) {
+  server.tool(
+    "list_components",
+    "List all adaptive components in a project with variant counts and impression totals.",
+    { projectId: projectIdSchema2 },
+    async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const components = await client.get(`/projects/${id}/components`);
+      if (!components.length) {
+        return { content: [{ type: "text", text: "No components found for this project." }] };
+      }
+      const text = components.map(
+        (c) => `- ${c.component_id}: ${c.variants.length} variants, ${c.total_impressions} impressions, ${c.total_conversions} conversions`
+      ).join("\n");
+      return { content: [{ type: "text", text }] };
+    }
+  );
+  server.tool(
+    "get_variant_performance",
+    "Get CVR and momentum for all variants in a project over the last 7 days vs prior 7 days.",
+    { projectId: projectIdSchema2 },
+    async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/trends`);
+      if (!data.cvr?.length) {
+        return { content: [{ type: "text", text: "No variant data available yet." }] };
+      }
+      const momentumMap = new Map(data.momentum.map((m) => [m.variantId, m.direction]));
+      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"})`
+      ).join("\n");
+      return { content: [{ type: "text", text }] };
+    }
+  );
+}
+
+// src/tools/insights.ts
+var import_zod3 = require("zod");
+var projectIdSchema3 = import_zod3.z.string().uuid().describe("The project UUID");
+function registerInsightTools(server, client) {
+  server.tool(
+    "get_insights",
+    "Get the latest AI-generated insights: narrator observations and (Growth tier) advisor recommendations.",
+    { projectId: projectIdSchema3 },
+    async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/insights`);
+      if (data.status === "empty") {
+        return { content: [{ type: "text", text: "No insights generated yet. Use refresh_insights to generate." }] };
+      }
+      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()}`);
+      lines.push("");
+      lines.push("Observations:");
+      (data.narratorBullets ?? []).forEach((b) => lines.push(`- ${b}`));
+      if (data.advisorBullets?.length) {
+        lines.push("");
+        lines.push("Recommendations:");
+        data.advisorBullets.forEach((b) => lines.push(`- ${b}`));
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+
+// src/tools/personas.ts
+var import_zod4 = require("zod");
+var projectIdSchema4 = import_zod4.z.string().uuid().describe("The project UUID");
+function registerPersonaTools(server, client) {
+  server.tool(
+    "get_persona_breakdown",
+    "Get the distribution of visitor persona clusters with session counts and reliability scores.",
+    { projectId: projectIdSchema4 },
+    async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/portraits`);
+      if (!data.clusters.length) {
+        return { content: [{ type: "text", text: "No persona clusters yet. More visitor data is needed." }] };
+      }
+      const lines = [
+        `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)}%)`
+        )
+      ];
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+
+// src/tools/goals.ts
+var import_zod5 = require("zod");
+var projectIdSchema5 = import_zod5.z.string().uuid().describe("The project UUID");
+function registerGoalTools(server, client) {
+  server.tool(
+    "get_goal_funnel",
+    "Get goal hit counts, unique-session conversion rates, and per-variant breakdown.",
+    { projectId: projectIdSchema5 },
+    async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/goals`);
+      if (!data.goals.length) {
+        return { content: [{ type: "text", text: "No goals configured for this project." }] };
+      }
+      const lines = data.goals.flatMap((g) => [
+        `${g.goalName}: ${g.hits} hits, ${g.uniqueSessions} unique sessions, ${(g.pct * 100).toFixed(1)}% conversion`,
+        ...g.variants.map((v) => `  ${v.componentId}/${v.variantId}: ${(v.completionRate * 100).toFixed(1)}% per assigned session`),
+        ""
+      ]);
+      return { content: [{ type: "text", text: lines.join("\n").trim() }] };
+    }
+  );
+}
+
+// src/tools/guardrails.ts
+var import_zod6 = require("zod");
+var projectIdSchema6 = import_zod6.z.string().uuid().describe("The project UUID");
+function registerGuardrailTools(server, client) {
+  server.tool(
+    "list_guardrail_events",
+    "List variants currently paused by the guardrail in the last 24 hours.",
+    { projectId: projectIdSchema6 },
+    async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/guardrail-events`);
+      if (!data.guardrailEvents.length) {
+        return { content: [{ type: "text", text: "No active guardrail events in the last 24 hours." }] };
+      }
+      const lines = data.guardrailEvents.map(
+        (e) => `- ${e.componentId}: variants [${e.variantIds.join(", ")}] paused${e.pausedAt ? ` at ${e.pausedAt}` : ""}`
+      );
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+
+// src/tools/layout.ts
+var import_zod7 = require("zod");
+var projectIdSchema7 = import_zod7.z.string().uuid().describe("The project UUID");
+function registerLayoutTools(server, client) {
+  server.tool(
+    "get_layout_stats",
+    "Get per-persona section layout rankings and bandit reward weights.",
+    { projectId: projectIdSchema7 },
+    async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const stats = await client.get(`/projects/${id}/layout-stats`);
+      if (!stats.length) {
+        return { content: [{ type: "text", text: "No layout data yet. More visitor sessions are needed." }] };
+      }
+      const text = stats.map(
+        (s) => `- ${s.persona}: [${s.layoutOrder.join(" \u2192 ")}] (avg reward: ${s.avgReward.toFixed(2)}, ${s.pulls} pulls)`
+      ).join("\n");
+      return { content: [{ type: "text", text }] };
+    }
+  );
+}
+
+// src/tools/variants.ts
+var import_zod8 = require("zod");
+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.",
+    {
+      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")
+    },
+    async ({ projectId, componentId, displayName }) => {
+      const id = encodeURIComponent(projectId);
+      const result = await client.post(
+        `/projects/${id}/variants`,
+        { componentId, displayName }
+      );
+      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.`
+        }]
+      };
+    }
+  );
+  server.tool(
+    "pause_variant",
+    "Pause a variant, stopping traffic from being assigned to it.",
+    {
+      projectId: projectIdSchema8,
+      componentId: import_zod8.z.string().describe("The component ID"),
+      variantId: import_zod8.z.string().describe("The variant ID to pause")
+    },
+    async ({ projectId, componentId, variantId }) => {
+      const id = encodeURIComponent(projectId);
+      await client.post(`/projects/${id}/variants/pause`, { componentId, variantId });
+      return {
+        content: [{
+          type: "text",
+          text: `Variant ${variantId} in component ${componentId} has been paused. No new traffic will be assigned to it.`
+        }]
+      };
+    }
+  );
+  server.tool(
+    "refresh_insights",
+    "Trigger fresh AI insight generation for a project. Returns immediately; use get_insights in ~15 seconds to see results.",
+    { projectId: projectIdSchema8 },
+    async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      await client.post(`/projects/${id}/insights/refresh`);
+      return {
+        content: [{
+          type: "text",
+          text: `Insights are generating for project ${projectId}. Call get_insights in ~15 seconds to see the results.`
+        }]
+      };
+    }
+  );
+}
+
+// src/server.ts
+function createMcpServer(client) {
+  const server = new import_mcp.McpServer({
+    name: "@sentientui/mcp",
+    version: "0.1.0"
+  });
+  registerProjectTools(server, client);
+  registerComponentTools(server, client);
+  registerInsightTools(server, client);
+  registerPersonaTools(server, client);
+  registerGoalTools(server, client);
+  registerGuardrailTools(server, client);
+  registerLayoutTools(server, client);
+  registerVariantWriteTools(server, client);
+  return server;
+}
+
+// src/demo.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_node_os = require("os");
+var CONFIG_DIR = (0, import_node_path.join)((0, import_node_os.homedir)(), ".config", "sentientui");
+var CONFIG_FILE = (0, import_node_path.join)(CONFIG_DIR, "mcp-anon.json");
+var API_BASE = process.env.SENTIENTUI_API_URL ?? "https://api.sentient-ui.com";
+function readCachedToken() {
+  try {
+    return JSON.parse((0, import_node_fs.readFileSync)(CONFIG_FILE, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function writeCachedToken(cfg) {
+  (0, import_node_fs.mkdirSync)(CONFIG_DIR, { recursive: true, mode: 448 });
+  (0, import_node_fs.writeFileSync)(CONFIG_FILE, JSON.stringify(cfg, null, 2), { encoding: "utf-8", mode: 384 });
+}
+async function resolveDemoToken() {
+  const cached = readCachedToken();
+  if (cached?.token) {
+    process.stderr.write(
+      `[sentientui-mcp] Running in demo mode (${CONFIG_FILE}). Set SENTIENTUI_API_KEY for full access.
+`
+    );
+    return cached.token;
+  }
+  process.stderr.write("[sentientui-mcp] No API key found. Provisioning anonymous demo token...\n");
+  const res = await fetch(`${API_BASE}/v1/mcp/demo`, { method: "POST" });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(`Demo provisioning failed: ${String(body.error ?? res.statusText)}`);
+  }
+  const data = await res.json();
+  writeCachedToken({ token: data.token, projectId: data.projectId });
+  process.stderr.write(
+    `[sentientui-mcp] Demo token provisioned (${data.callsRemaining} calls/month). Set SENTIENTUI_API_KEY to remove this limit.
+`
+  );
+  return data.token;
+}
+
+// src/index.ts
+async function main() {
+  let apiKey = process.env.SENTIENTUI_API_KEY;
+  if (!apiKey) {
+    apiKey = await resolveDemoToken();
+  }
+  const client = new ApiClient({ apiKey });
+  const server = createMcpServer(client);
+  const transport = new import_stdio.StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  process.stderr.write(`[sentientui-mcp] fatal: ${String(err)}
+`);
+  process.exit(1);
+});

package/dist/index.d.cts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/api-client.ts
+var ApiError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "ApiError";
+  }
+  status;
+};
+var ApiClient = class {
+  baseUrl;
+  apiKey;
+  constructor(opts) {
+    this.apiKey = opts.apiKey;
+    this.baseUrl = (opts.baseUrl ?? "https://api.sentient-ui.com").replace(/\/$/, "");
+  }
+  async get(path) {
+    const res = await fetch(`${this.baseUrl}/v1/mgmt${path}`, {
+      headers: {
+        authorization: `Bearer ${this.apiKey}`,
+        "content-type": "application/json"
+      }
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      throw new ApiError(res.status, String(body.error ?? res.statusText));
+    }
+    return res.json();
+  }
+  async post(path, body) {
+    const res = await fetch(`${this.baseUrl}/v1/mgmt${path}`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${this.apiKey}`,
+        "content-type": "application/json"
+      },
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      const errBody = await res.json().catch(() => ({}));
+      throw new ApiError(res.status, String(errBody.error ?? res.statusText));
+    }
+    return res.json();
+  }
+};
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/tools/projects.ts
+import { z } from "zod";
+var projectIdSchema = z.string().uuid().describe("The project UUID");
+function registerProjectTools(server, client) {
+  server.tool(
+    "list_projects",
+    "List all SentientUI projects for the authenticated account.",
+    {},
+    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)})`
+      ).join("\n");
+      return { content: [{ type: "text", text }] };
+    }
+  );
+  server.tool(
+    "get_project_stats",
+    "Get health stats for a project: event volume, session count, agent calls, and status.",
+    { projectId: projectIdSchema },
+    async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const stats = await client.get(`/projects/${id}/health`);
+      const text = [
+        `Status: ${stats.status}`,
+        `Events (24h): ${stats.events24h}`,
+        `Sessions (24h): ${stats.sessions24h}`,
+        `Agent calls (total): ${stats.agentCalls}`,
+        `Last event: ${stats.lastEventAt ?? "never"}`
+      ].join("\n");
+      return { content: [{ type: "text", text }] };
+    }
+  );
+}
+
+// src/tools/components.ts
+import { z as z2 } from "zod";
+var projectIdSchema2 = z2.string().uuid().describe("The project UUID");
+function registerComponentTools(server, client) {
+  server.tool(
+    "list_components",
+    "List all adaptive components in a project with variant counts and impression totals.",
+    { projectId: projectIdSchema2 },
+    async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const components = await client.get(`/projects/${id}/components`);
+      if (!components.length) {
+        return { content: [{ type: "text", text: "No components found for this project." }] };
+      }
+      const text = components.map(
+        (c) => `- ${c.component_id}: ${c.variants.length} variants, ${c.total_impressions} impressions, ${c.total_conversions} conversions`
+      ).join("\n");
+      return { content: [{ type: "text", text }] };
+    }
+  );
+  server.tool(
+    "get_variant_performance",
+    "Get CVR and momentum for all variants in a project over the last 7 days vs prior 7 days.",
+    { projectId: projectIdSchema2 },
+    async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/trends`);
+      if (!data.cvr?.length) {
+        return { content: [{ type: "text", text: "No variant data available yet." }] };
+      }
+      const momentumMap = new Map(data.momentum.map((m) => [m.variantId, m.direction]));
+      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"})`
+      ).join("\n");
+      return { content: [{ type: "text", text }] };
+    }
+  );
+}
+
+// src/tools/insights.ts
+import { z as z3 } from "zod";
+var projectIdSchema3 = z3.string().uuid().describe("The project UUID");
+function registerInsightTools(server, client) {
+  server.tool(
+    "get_insights",
+    "Get the latest AI-generated insights: narrator observations and (Growth tier) advisor recommendations.",
+    { projectId: projectIdSchema3 },
+    async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/insights`);
+      if (data.status === "empty") {
+        return { content: [{ type: "text", text: "No insights generated yet. Use refresh_insights to generate." }] };
+      }
+      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()}`);
+      lines.push("");
+      lines.push("Observations:");
+      (data.narratorBullets ?? []).forEach((b) => lines.push(`- ${b}`));
+      if (data.advisorBullets?.length) {
+        lines.push("");
+        lines.push("Recommendations:");
+        data.advisorBullets.forEach((b) => lines.push(`- ${b}`));
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+
+// src/tools/personas.ts
+import { z as z4 } from "zod";
+var projectIdSchema4 = z4.string().uuid().describe("The project UUID");
+function registerPersonaTools(server, client) {
+  server.tool(
+    "get_persona_breakdown",
+    "Get the distribution of visitor persona clusters with session counts and reliability scores.",
+    { projectId: projectIdSchema4 },
+    async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/portraits`);
+      if (!data.clusters.length) {
+        return { content: [{ type: "text", text: "No persona clusters yet. More visitor data is needed." }] };
+      }
+      const lines = [
+        `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)}%)`
+        )
+      ];
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+
+// src/tools/goals.ts
+import { z as z5 } from "zod";
+var projectIdSchema5 = z5.string().uuid().describe("The project UUID");
+function registerGoalTools(server, client) {
+  server.tool(
+    "get_goal_funnel",
+    "Get goal hit counts, unique-session conversion rates, and per-variant breakdown.",
+    { projectId: projectIdSchema5 },
+    async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/goals`);
+      if (!data.goals.length) {
+        return { content: [{ type: "text", text: "No goals configured for this project." }] };
+      }
+      const lines = data.goals.flatMap((g) => [
+        `${g.goalName}: ${g.hits} hits, ${g.uniqueSessions} unique sessions, ${(g.pct * 100).toFixed(1)}% conversion`,
+        ...g.variants.map((v) => `  ${v.componentId}/${v.variantId}: ${(v.completionRate * 100).toFixed(1)}% per assigned session`),
+        ""
+      ]);
+      return { content: [{ type: "text", text: lines.join("\n").trim() }] };
+    }
+  );
+}
+
+// src/tools/guardrails.ts
+import { z as z6 } from "zod";
+var projectIdSchema6 = z6.string().uuid().describe("The project UUID");
+function registerGuardrailTools(server, client) {
+  server.tool(
+    "list_guardrail_events",
+    "List variants currently paused by the guardrail in the last 24 hours.",
+    { projectId: projectIdSchema6 },
+    async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/guardrail-events`);
+      if (!data.guardrailEvents.length) {
+        return { content: [{ type: "text", text: "No active guardrail events in the last 24 hours." }] };
+      }
+      const lines = data.guardrailEvents.map(
+        (e) => `- ${e.componentId}: variants [${e.variantIds.join(", ")}] paused${e.pausedAt ? ` at ${e.pausedAt}` : ""}`
+      );
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+
+// src/tools/layout.ts
+import { z as z7 } from "zod";
+var projectIdSchema7 = z7.string().uuid().describe("The project UUID");
+function registerLayoutTools(server, client) {
+  server.tool(
+    "get_layout_stats",
+    "Get per-persona section layout rankings and bandit reward weights.",
+    { projectId: projectIdSchema7 },
+    async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const stats = await client.get(`/projects/${id}/layout-stats`);
+      if (!stats.length) {
+        return { content: [{ type: "text", text: "No layout data yet. More visitor sessions are needed." }] };
+      }
+      const text = stats.map(
+        (s) => `- ${s.persona}: [${s.layoutOrder.join(" \u2192 ")}] (avg reward: ${s.avgReward.toFixed(2)}, ${s.pulls} pulls)`
+      ).join("\n");
+      return { content: [{ type: "text", text }] };
+    }
+  );
+}
+
+// src/tools/variants.ts
+import { z as z8 } from "zod";
+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.",
+    {
+      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")
+    },
+    async ({ projectId, componentId, displayName }) => {
+      const id = encodeURIComponent(projectId);
+      const result = await client.post(
+        `/projects/${id}/variants`,
+        { componentId, displayName }
+      );
+      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.`
+        }]
+      };
+    }
+  );
+  server.tool(
+    "pause_variant",
+    "Pause a variant, stopping traffic from being assigned to it.",
+    {
+      projectId: projectIdSchema8,
+      componentId: z8.string().describe("The component ID"),
+      variantId: z8.string().describe("The variant ID to pause")
+    },
+    async ({ projectId, componentId, variantId }) => {
+      const id = encodeURIComponent(projectId);
+      await client.post(`/projects/${id}/variants/pause`, { componentId, variantId });
+      return {
+        content: [{
+          type: "text",
+          text: `Variant ${variantId} in component ${componentId} has been paused. No new traffic will be assigned to it.`
+        }]
+      };
+    }
+  );
+  server.tool(
+    "refresh_insights",
+    "Trigger fresh AI insight generation for a project. Returns immediately; use get_insights in ~15 seconds to see results.",
+    { projectId: projectIdSchema8 },
+    async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      await client.post(`/projects/${id}/insights/refresh`);
+      return {
+        content: [{
+          type: "text",
+          text: `Insights are generating for project ${projectId}. Call get_insights in ~15 seconds to see the results.`
+        }]
+      };
+    }
+  );
+}
+
+// src/server.ts
+function createMcpServer(client) {
+  const server = new McpServer({
+    name: "@sentientui/mcp",
+    version: "0.1.0"
+  });
+  registerProjectTools(server, client);
+  registerComponentTools(server, client);
+  registerInsightTools(server, client);
+  registerPersonaTools(server, client);
+  registerGoalTools(server, client);
+  registerGuardrailTools(server, client);
+  registerLayoutTools(server, client);
+  registerVariantWriteTools(server, client);
+  return server;
+}
+
+// src/demo.ts
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+var CONFIG_DIR = join(homedir(), ".config", "sentientui");
+var CONFIG_FILE = join(CONFIG_DIR, "mcp-anon.json");
+var API_BASE = process.env.SENTIENTUI_API_URL ?? "https://api.sentient-ui.com";
+function readCachedToken() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function writeCachedToken(cfg) {
+  mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
+  writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2), { encoding: "utf-8", mode: 384 });
+}
+async function resolveDemoToken() {
+  const cached = readCachedToken();
+  if (cached?.token) {
+    process.stderr.write(
+      `[sentientui-mcp] Running in demo mode (${CONFIG_FILE}). Set SENTIENTUI_API_KEY for full access.
+`
+    );
+    return cached.token;
+  }
+  process.stderr.write("[sentientui-mcp] No API key found. Provisioning anonymous demo token...\n");
+  const res = await fetch(`${API_BASE}/v1/mcp/demo`, { method: "POST" });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(`Demo provisioning failed: ${String(body.error ?? res.statusText)}`);
+  }
+  const data = await res.json();
+  writeCachedToken({ token: data.token, projectId: data.projectId });
+  process.stderr.write(
+    `[sentientui-mcp] Demo token provisioned (${data.callsRemaining} calls/month). Set SENTIENTUI_API_KEY to remove this limit.
+`
+  );
+  return data.token;
+}
+
+// src/index.ts
+async function main() {
+  let apiKey = process.env.SENTIENTUI_API_KEY;
+  if (!apiKey) {
+    apiKey = await resolveDemoToken();
+  }
+  const client = new ApiClient({ apiKey });
+  const server = createMcpServer(client);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  process.stderr.write(`[sentientui-mcp] fatal: ${String(err)}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@sentientui/mcp",
+  "version": "0.2.0",
+  "description": "MCP server for SentientUI — exposes project data and actions to AI agents",
+  "type": "module",
+  "bin": {
+    "sentientui-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "pnpm build && pnpm typecheck"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}