@sentientui/mcp 0.3.1 → 0.3.3

package/AGENTS.md

@@ -17,7 +17,7 @@ Only call `create_variant` for the no-code path. If the user is writing (or you
 
 **Shadow mode** — project-level flag (toggled in dashboard settings). When ON: personalization is computed and logged but visitors receive the default layout/variant. Use it to validate the algorithm before committing to live changes.
 
-**Insights** — AI-generated. Two tiers: narrator observations (all plans) + advisor recommendations (Growth tier). Insights go stale after 6 hours. Always check `isStale` before presenting them.
+**Insights** — AI-generated. Two tiers: narrator observations (generation requires Starter+; Free plans can only view already-stored bullets) + advisor recommendations (Growth tier). Insights go stale after 6 hours. Always check `isStale` before presenting them.
 
 **Layout stats** — per-persona section ordering driven by a bandit algorithm. `pulls` = times a layout was applied, `avgReward` = normalized conversion signal (not raw CVR).
 
@@ -57,7 +57,7 @@ Server keys start with `sk_` — required for the management API. Public keys (`
 2. `get_variant_brief` — pull performance, audience, insights, data-sufficiency, best-practice priors, and code instructions for that component
 3. Find `<Adaptive id="...">` in the repo and add a new on-brand variant key to its `variants` map (and to the `AdaptiveRoot` `components` list if SSR). Match the project's existing components and design system.
 4. Do **not** call `create_variant`. Commit, push, deploy — the variant auto-registers on the first assignment and goes live.
-5. Optional: enable shadow mode for the component first to validate before serving.
+5. Optional: enable shadow mode (project-level, in dashboard settings — it applies to the whole project, not a single component) first to validate before serving.
 
 Data sufficiency (from the brief) drives the change: when it reports **SUFFICIENT**, target the specific weakness; when **COLLECTING** or **EMPTY** (no data yet), apply the best-practice priors for the project's context type — use your best judgment and make one conservative change.
 

package/README.md

@@ -10,7 +10,11 @@ Dashboard → Project → **Settings → API key → Server key** → Generate (
 
 **2. Add to your AI assistant**
 
-**Claude Code** — `~/.claude/settings.json`:
+**Claude Code** — one command:
+```bash
+claude mcp add sentientui -e SENTIENTUI_API_KEY=sk_your_key_here -- npx -y @sentientui/mcp
+```
+Or check a project-scoped `.mcp.json` into your repo:
 ```json
 {
   "mcpServers": {
@@ -18,7 +22,7 @@ Dashboard → Project → **Settings → API key → Server key** → Generate (
       "command": "npx",
       "args": ["-y", "@sentientui/mcp"],
       "env": {
-        "SENTIENTUI_API_KEY": "sk_live_your_key_here"
+        "SENTIENTUI_API_KEY": "sk_your_key_here"
       }
     }
   }
@@ -33,7 +37,7 @@ Dashboard → Project → **Settings → API key → Server key** → Generate (
       "command": "npx",
       "args": ["-y", "@sentientui/mcp"],
       "env": {
-        "SENTIENTUI_API_KEY": "sk_live_your_key_here"
+        "SENTIENTUI_API_KEY": "sk_your_key_here"
       }
     }
   }
@@ -49,7 +53,7 @@ Dashboard → Project → **Settings → API key → Server key** → Generate (
       "command": "npx",
       "args": ["-y", "@sentientui/mcp"],
       "env": {
-        "SENTIENTUI_API_KEY": "sk_live_your_key_here"
+        "SENTIENTUI_API_KEY": "sk_your_key_here"
       }
     }
   }
@@ -66,7 +70,7 @@ No account? Run without an API key:
 npx @sentientui/mcp
 ```
 
-A sandboxed demo token is provisioned automatically — 10 calls/month, no sign-up required. The token is cached in `~/.config/sentientui/mcp-anon.json`.
+A sandboxed demo token is provisioned automatically — 10 calls/month, read-only (write tools require an account with an `sk_` key), no sign-up required. The token is cached in `~/.config/sentientui/mcp-anon.json`.
 
 ## Tools
 
@@ -82,6 +86,8 @@ A sandboxed demo token is provisioned automatically — 10 calls/month, no sign-
 | `get_goal_funnel` | Goal hit counts and conversion rates per variant |
 | `list_guardrail_events` | Variants auto-paused by the guardrail (last 24h) |
 | `get_layout_stats` | Per-persona section layout rankings and reward weights |
+| `get_integration_guide` | SentientUI adaptive-ladder setup guide (static — same for every project) |
+| `get_test_brief` | What to test and how, for the project's current state |
 | `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 |
@@ -104,8 +110,8 @@ A sandboxed demo token is provisioned automatically — 10 calls/month, no sign-
 
 | Environment variable | Default | Description |
 |----------------------|---------|-------------|
-| `SENTIENTUI_API_KEY` | — | Your `sk_live_...` server key. Required (or demo mode activates). |
-| `SENTIENTUI_API_URL` | `https://api.sentient-ui.com` | Override for self-hosted or staging deployments. |
+| `SENTIENTUI_API_KEY` | — | Your `sk_...` server key. Required (or demo mode activates). |
+| `SENTIENTUI_API_URL` | `https://api.sentient-ui.com` | Override for staging or a custom API endpoint. |
 
 ## Auth model
 

package/dist/index.cjs

@@ -259,7 +259,7 @@ var projectIdSchema8 = import_zod8.z.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 Starter or Growth plan.",
+    "Create a NO-CODE managed text variant for a component (content stored in SentientUI, rendered by <AdaptiveText>). Use this ONLY for text-only variants the user wants without a code change. For variants that will live in the codebase (full components \u2014 copy, markup, styling), use get_variant_brief and write the variant in code instead; those auto-register on deploy and do not need create_variant. Requires a paid plan (server keys are Starter+; anonymous demo tokens are read-only).",
     {
       projectId: projectIdSchema8,
       componentId: import_zod8.z.string().describe("The component ID to add a variant to"),
@@ -580,16 +580,17 @@ 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; wraps the app; writes .env.local; scaffolds an example).
-2. \`npm run dev\`, then open the app with \`?sentient_persona=buyer\` vs
+   @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).
-3. To learn from real traffic: create a project at https://sentient-ui.com and set
+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.
 
-Manual setup: 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.
-
 ## Rung 1 \u2014 Style (CSS only)
 
 Persona attributes on <html> (zero declaration):

package/dist/index.js

@@ -258,7 +258,7 @@ 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 Starter or Growth plan.",
+    "Create a NO-CODE managed text variant for a component (content stored in SentientUI, rendered by <AdaptiveText>). Use this ONLY for text-only variants the user wants without a code change. For variants that will live in the codebase (full components \u2014 copy, markup, styling), use get_variant_brief and write the variant in code instead; those auto-register on deploy and do not need create_variant. Requires 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"),
@@ -579,16 +579,17 @@ 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; wraps the app; writes .env.local; scaffolds an example).
-2. \`npm run dev\`, then open the app with \`?sentient_persona=buyer\` vs
+   @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).
-3. To learn from real traffic: create a project at https://sentient-ui.com and set
+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.
 
-Manual setup: 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.
-
 ## Rung 1 \u2014 Style (CSS only)
 
 Persona attributes on <html> (zero declaration):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentientui/mcp",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "MCP server for SentientUI — exposes project data and actions to AI agents",
   "type": "module",
   "bin": {