@sentientui/mcp 0.3.4 → 0.4.1

package/dist/chunk-ZXI3OZKA.js

@@ -0,0 +1,725 @@
+#!/usr/bin/env node
+
+// 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 { createRequire } from "module";
+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 createProjectGuidance(err) {
+  switch (err.message) {
+    case "insufficient_scope":
+      return "Creating a project needs an account login. Connect via the hosted MCP URL (https://api.sentient-ui.com/mcp) and sign in \u2014 a project-scoped server key (sk_\u2026) cannot create projects.";
+    case "demo_read_only":
+      return "Demo mode is read-only. Create a SentientUI account and sign in to make projects.";
+    case "insufficient_role":
+      return "Your account role cannot create projects \u2014 this needs the account owner or an admin.";
+    case "project_limit_reached":
+      return "You've reached your plan's project limit. Upgrade your plan or remove an existing project, then try again.";
+    case "name_required":
+      return "A project name is required to create a project.";
+    default:
+      return null;
+  }
+}
+function registerProjectTools(server, client) {
+  server.tool(
+    "create_project",
+    "Create a NEW SentientUI project (onboarding). Returns the project id and its pk_ public key for the SDK. Requires an account login: this works when connected via OAuth (the hosted MCP URL) but NOT with a project-scoped sk_ server key or an anonymous demo token. After it succeeds, call get_integration_guide and help the user install @sentientui/react with the returned key.",
+    {
+      name: z.string().min(1).describe("Human-readable project name"),
+      contextType: z.enum(["saas", "ecommerce", "marketing", "internal"]).optional().describe("What kind of product this is; defaults to saas"),
+      framework: z.enum(["next-app", "next-pages", "react", "core"]).optional().describe("Frontend framework, used to tailor setup; defaults to next-app"),
+      websiteUrl: z.string().optional().describe("Production site origin to allow-list so the SDK's events aren't origin-blocked on day one")
+    },
+    async ({ name, contextType, framework, websiteUrl }) => {
+      try {
+        const created = await client.post("/projects", {
+          name,
+          contextType,
+          framework,
+          origin: websiteUrl
+        });
+        return {
+          content: [{
+            type: "text",
+            text: [
+              `Created project "${name}" (id: ${created.id}, type: ${contextType ?? "saas"}).`,
+              `Public key: ${created.apiKey}`,
+              `Next: install @sentientui/react with this key. Ask me to pull the setup guide (get_integration_guide) and I'll wrap your first component.`
+            ].join("\n")
+          }]
+        };
+      } catch (err) {
+        if (err instanceof ApiError) {
+          const guidance = createProjectGuidance(err);
+          if (guidance) {
+            return { content: [{ type: "text", text: guidance }], isError: true };
+          }
+        }
+        throw err;
+      }
+    }
+  );
+  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) => {
+          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") }] };
+    }
+  );
+}
+
+// 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 NO-CODE managed text variant for a component (content stored in SentientUI, rendered by <AdaptiveText>). Use this ONLY for text-only variants the user wants without a code change. For variants that will live in the codebase (full components \u2014 copy, markup, styling), use get_variant_brief and write the variant in code instead; those auto-register on deploy and do not need create_variant. Requires a paid plan (server keys are Starter+; anonymous demo tokens are read-only).",
+    {
+      projectId: projectIdSchema8,
+      componentId: z8.string().describe("The component ID to add a variant to"),
+      displayName: z8.string().describe("Human-readable name for the new variant"),
+      content: z8.string().optional().describe("The text content for this managed variant (rendered by <AdaptiveText>). Generate it from get_variant_brief context; omit only to create an empty placeholder to fill in from the dashboard.")
+    },
+    async ({ projectId, componentId, displayName, content }) => {
+      const id = encodeURIComponent(projectId);
+      const result = await client.post(
+        `/projects/${id}/variants`,
+        { 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: `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).`
+        }]
+      };
+    }
+  );
+  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/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/tools/integration-guide.ts
+var GUIDE = `# SentientUI integration guide \u2014 the adaptive ladder
+
+SentientUI adapts a site per visitor type (personas: buyer, researcher, deal_seeker, browser,
+unknown), learning from real conversions. Decisions are locked per session: Visit 1 learns,
+Visit 2 converts. Integrate one rung at a time.
+
+## Setup (60 seconds, no account)
+
+1. Run \`npx @sentientui/cli init\` (detects Next App/Pages, Vite, Remix, CRA; installs
+   @sentientui/react; writes .env.local; scaffolds an example). It does NOT edit your layout \u2014
+   it prints the wrap snippet for step 2.
+2. Wrap the root layout with <AdaptiveRoot apiKey context> (from '@sentientui/react/next';
+   other React apps use <AdaptiveProvider> from '@sentientui/react') and add
+   suppressHydrationWarning to <html> \u2014 an inline script sets persona attributes pre-paint.
+   Nothing adapts and nothing is tracked until this wrap is in place.
+3. \`npm run dev\`, then open the app with \`?sentient_persona=buyer\` vs
+   \`?sentient_persona=deal_seeker\` to see it adapt. No API key needed (keyless local mode).
+4. To learn from real traffic: create a project at https://sentient-ui.com and set
+   NEXT_PUBLIC_SENTIENT_API_KEY=pk_... in .env.local.
+
+## Rung 1 \u2014 Style (CSS only)
+
+Persona attributes on <html> (zero declaration):
+
+    html[data-sentient-persona='deal_seeker'] .discount-banner { display: block; }
+    html[data-sentient-confidence='low'] .discount-banner { display: none; }
+
+Learned style tokens (element-scoped, SSR-safe):
+
+    const t = useAdaptiveTokens('hero', {
+      tone: ['calm', 'urgent'],   // first value = baseline
+    });
+    return <section {...t.props} className="hero">\u2026</section>;
+    // CSS: .hero[data-tone='urgent'] .cta { font-weight: 700; }
+
+Rules: 1-4 dims, 2-6 values each, enum values only. For animation values, always add a
+prefers-reduced-motion: reduce override in CSS.
+
+## Rung 2 \u2014 Swap (alternate content)
+
+    const { value, bind } = useAdaptive('buy-box', {
+      variants: { calm: <CalmBuyBox/>, urgent: <UrgentBuyBox/> },  // first key = baseline
+      goal: 'buy_click',                                            // REQUIRED
+    });
+    return <div {...bind}>{value}</div>;
+
+Always attach bind \u2014 it wires exposure tracking and goal listeners. <Adaptive> is the wrapper
+form; <AdaptiveText> swaps dashboard-managed text.
+
+## Rung 3 \u2014 Reorder (structure)
+
+    <AdaptiveGroup id="pricing-area" arrangements={{
+      standard:     ['plans', 'faq', 'social'],   // first key = baseline
+      social_first: ['social', 'plans', 'faq'],
+    }}>
+      <PlanGrid key="plans"/> <Faq key="faq"/> <Testimonials key="social"/>
+    </AdaptiveGroup>
+
+Declared orders of keyed children only. Page-level: sections={[...]} on AdaptiveRoot +
+useLayoutOrder().
+
+## Testing the integration
+
+Use '@sentientui/react/testing': renderWithSentient(ui, { variants, slots, persona }) forces
+deterministic outcomes so tests never depend on what the optimizer serves.
+`;
+function registerIntegrationGuideTools(server) {
+  server.tool(
+    "get_integration_guide",
+    "Get the SentientUI adaptive-ladder integration guide: setup (keyless and keyed) plus copy-pasteable examples for every rung (Style, Swap, Reorder). Use this to integrate SentientUI into a codebase.",
+    {},
+    async () => ({ content: [{ type: "text", text: GUIDE }] })
+  );
+}
+
+// src/server.ts
+var { version: PKG_VERSION } = createRequire(import.meta.url)("../package.json");
+function createMcpServer(client) {
+  const server = new McpServer({
+    name: "@sentientui/mcp",
+    version: PKG_VERSION
+  });
+  registerProjectTools(server, client);
+  registerComponentTools(server, client);
+  registerInsightTools(server, client);
+  registerPersonaTools(server, client);
+  registerGoalTools(server, client);
+  registerGuardrailTools(server, client);
+  registerLayoutTools(server, client);
+  registerVariantBriefTools(server, client);
+  registerTestBriefTools(server, client);
+  registerVariantWriteTools(server, client);
+  registerIntegrationGuideTools(server);
+  return server;
+}
+
+export {
+  ApiError,
+  ApiClient,
+  createMcpServer
+};