@sentientui/mcp 0.19.0 → 0.21.0

package/AGENTS.md

@@ -9,43 +9,65 @@ SentientUI is a UI personalization platform that assigns visitors to variant com
 **Variant** — a version of an adaptive component. There are **two kinds**, and the difference matters:
 
 - **Code-native variants** are declared in the customer's code (`<Adaptive variants={{…}}>`). They **register automatically** the first time the SDK requests an assignment after deploy, and they go **live immediately** — there is no draft step and no `create_variant` call. Their content lives in the repo, not in SentientUI.
-- **No-code / managed variants** have no code; their content is stored on the SentientUI API (dashboard WYSIWYG, `<AdaptiveText>`, or `create_variant`). These start as **draft** after `create_variant` and must be activated from the dashboard before traffic is assigned. There is no MCP tool to activate or resume variants.
+- **No-code / managed variants** have no code; their content is stored on the SentientUI API (dashboard WYSIWYG, `<AdaptiveText>`, or `create_variant`). These start as **draft** after `create_variant`; no traffic is assigned until one is activated — with `update_variant` (`status: active`) or from the dashboard. `update_variant` `status: draft` takes it back out of serving, and `delete_variant_draft` removes a draft entirely.
 
 Only call `create_variant` for the no-code path. If the user is writing (or you are writing) the variant in code, do **not** call `create_variant` — deploying the code registers it.
 
-**Guardrail** — automatic safety circuit that pauses variants whose CVR drops below threshold. `list_guardrail_events` shows what's been paused. Pausing via `pause_variant` is irreversible via MCP (no resume tool).
+**Guardrail** — automatic safety circuit that pauses a variant once its CVR is shown (anytime-valid bounds, checked every 5 minutes) to be more than the configured threshold below the best variant's. `list_guardrail_events` lists every variant a guardrail has paused that is still paused (`days` narrows it to recent pauses). `resume_variant` clears a pause — a guardrail pause or one from `pause_variant` — so check why the guardrail fired before resuming.
 
 **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 (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.
+**Insights** — AI-generated. Two tiers: narrator observations (`refresh_insights` needs Starter or higher and an editor/admin role, since each refresh is a paid model call; Free plans can only view already-stored bullets) + advisor recommendations (Growth tier). Insights go stale after 6 hours. Always check `isStale` before presenting them.
+
+**Review mode** — project-level setting (dashboard). When ON, `generate_cell` output does not publish on its own: it waits in `list_cell_reviews` until `review_cell` approves (publishes) or rejects it. When OFF, a generated version publishes automatically once the worker writes it — `generate_cell` tells you which applies.
 
 **Layout stats** — per-persona section ordering driven by a bandit algorithm. `pulls` = times a layout was applied, `avgReward` = normalized conversion signal (not raw CVR).
 
 ## Auth
 
-Server keys start with `sk_` — required for the management API. Public keys (`pk_`) are for the React SDK only and will be rejected. Key is scoped to the account; all owned projects are accessible.
+Server keys start with `sk_` — required for the management API, available on every plan including Free. Public keys (`pk_`) are for the React SDK only and will be rejected. An `sk_` key is scoped to **one project**: `list_projects` returns only that project and other project ids are refused. For several projects, connect by URL with an OAuth sign-in. `create_project` needs that OAuth login.
 
 ## Tool Quick Reference
 
-| Tool | Notes |
-|------|-------|
-| `list_projects` | Start here to get project IDs |
-| `create_project` | Onboard a new user: creates a project + returns its `pk_` key. Needs an account login (OAuth) — refuses `sk_` project keys and demo tokens. Follow with `get_integration_guide` |
-| `get_project_stats` | Health status + 24h event/session volume |
-| `list_components` | Components + variant counts + impression totals |
-| `get_variant_performance` | Per-(component, variant) rate with its n (converting / exposed sessions, range/from/to; default 7d), plus the server's evidence verdict on that windowed rate vs the component's baseline (`verdict`: ahead / behind / unclear; `verdictBasis` says window, or all_time on older APIs) and the all-time verdict as reliability (`evidenceState`, `reliabilityVerdict`). Only ahead/behind is a result; the preceding-window change is an untested descriptor |
-| `get_persona_breakdown` | Cluster distribution + avg reliability per cluster |
-| `get_goal_funnel` | Goal hit counts + per-variant all-time completion rates, each with its n and a low-sample flag (descriptive — no verdict) |
-| `list_guardrail_events` | Auto-paused variants (last 24h) |
-| `get_layout_stats` | Per-persona layout order + bandit pulls/reward |
-| `get_insights` | Ranked measured findings (tier + sample, low-sample flagged; `limit`, default 10) + (Growth) AI narrations, which are unmeasured |
-| `refresh_insights` | Async trigger — wait ~15s then call `get_insights` |
-| `get_variant_brief` | **Start here to optimize a component.** Evidence-driven brief for writing a new CODE-NATIVE variant: each arm's rate with n and server evidence verdict, audience, measured findings for the component, evidence state (EMPTY / COLLECTING / DIRECTIONAL / DECIDED) + 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 |
+Every write tool changes what real visitors see or what the project accepts — confirm with the user before calling one.
+
+<!-- mcp-tools:start -->
+| Tool | Access | Notes |
+|------|--------|-------|
+| `list_projects` | read | Start here to get project IDs (an `sk_` key sees only its own project) |
+| `create_project` | write | Onboard a new user: creates a project + returns its `pk_` key. Needs an account login (OAuth) — refuses `sk_` project keys and demo tokens. Follow with `get_integration_guide` |
+| `get_project_stats` | read | Health status + 24h event/session volume. `agentCalls` counts calls to the `/v1/agent` API (all retained history) — not MCP tool calls |
+| `add_origin` | write | Allow-list a site origin so the SDK's events from it are accepted. Idempotent |
+| `list_components` | read | Components + variant counts + impression totals |
+| `get_variant_performance` | read | Per-(component, variant) rate with its n (converting / exposed sessions, range/from/to; default 7d), plus the server's evidence verdict on that windowed rate vs the component's baseline (`verdict`: ahead / behind / unclear; `verdictBasis` says window, or all_time on older APIs) and the all-time verdict as reliability (`evidenceState`, `reliabilityVerdict`). Only ahead/behind is a result; the preceding-window change is an untested descriptor |
+| `get_variant_brief` | read | **Start here to optimize a component.** Evidence-driven brief for writing a new CODE-NATIVE variant: each arm's rate with n and server evidence verdict, audience, measured findings for the component, evidence state (EMPTY / COLLECTING / DIRECTIONAL / DECIDED) + best-practice fallback, and code instructions |
+| `get_test_brief` | read | Ready-to-paste test code that forces one of a component's real variants |
+| `create_variant` | write | Creates a no-code **managed text** DRAFT. Fallback only; not for code-native variants |
+| `update_variant` | write | Managed variants only: rename, change text, or `status: active` (starts serving) / `status: draft` (stops) |
+| `delete_variant_draft` | write | Deletes a managed variant that is still a draft |
+| `pause_variant` | write | Stops new traffic to a variant. Undo with `resume_variant` |
+| `resume_variant` | write | Clears a pause — manual or guardrail |
+| `retire_variant` | write | Archives an active variant (409 if it is the promoted one — unpromote first). Undo with `restore_variant` |
+| `restore_variant` | write | Brings a retired variant back to active. Does not unpause it |
+| `get_goal_funnel` | read | Per-goal conversion summary (windowed) + descriptive per-variant all-time completion rates, each with its n and a low-sample flag (descriptive — no verdict). Not a step funnel; for drop-off use `get_funnel_report` |
+| `list_goals` | read | Defined goals, including ones with no conversions yet |
+| `define_goal` | write | Create a new goal. Create-only: an existing id (even archived) is refused, and it never sets or changes the primary goal — that stays a dashboard decision |
+| `list_funnels` | read | Defined multi-step funnels |
+| `get_funnel_report` | read | Step-by-step funnel drop-off |
+| `list_guardrail_events` | read | Every variant still paused by a guardrail; `days` narrows to recent pauses |
+| `get_persona_breakdown` | read | Cluster distribution + avg reliability per cluster (all retained sessions, not windowed) |
+| `get_layout_stats` | read | Per-persona layout order + bandit pulls/reward (cumulative state, not windowed) |
+| `get_insights` | read | Ranked measured findings (tier + sample, low-sample flagged; `limit`, default 10) + (Growth) AI narrations, which are unmeasured |
+| `refresh_insights` | write | Async trigger — wait ~15s then call `get_insights`. Starter+ and an editor/admin role |
+| `get_cell_matrix` | read | "Who sees what": per-(visitor type, region) generation state + traffic share. A missing cell = they see the original |
+| `get_cell_detail` | read | One cell's generated option, its stored rationale, and a plain-language performance verdict |
+| `generate_cell` | write | Queues async AI generation for one cell (also retries failed ones). Publishes automatically, or waits for `review_cell` when review mode is on. Free includes 5 generations/month |
+| `list_cell_reviews` | read | Generated versions waiting for approval |
+| `review_cell` | write | Approve (publishes to live traffic) or reject one waiting version |
+| `get_agent_traffic` | read | AI crawlers / agentic browsers / agent API callers reading the site (windowed; paid plans) |
+| `get_agent_legibility` | read | Whether agent-read pages are machine-legible, with fixes (paid plans) |
+| `get_integration_guide` | read | SDK setup guide (static) |
+<!-- mcp-tools:end -->
 
 ## Canonical Workflows
 
@@ -63,12 +85,21 @@ Server keys start with `sk_` — required for the management API. Public keys (`
 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 (project-level, in dashboard settings — it applies to the whole project, not a single component) first to validate before serving.
 
-The evidence state (from the brief) drives the change. It is keyed on the server's evidence tiers, never on a traffic count: only **DECIDED** (an arm reliably ahead of or behind the baseline, at the multiple-comparison-corrected strong bar) is a result to build on. **DIRECTIONAL** (early/moderate/inconclusive signals), **COLLECTING** (below the 100-visit floor per arm) and **EMPTY** all mean: apply the best-practice priors for the project's context type and make one conservative change. Never call an arm better or worse from its raw rate.
+The evidence state (from the brief) drives the change. It is keyed on the server's evidence tiers, never on a traffic count: only **DECIDED** (an arm reliably ahead of or behind the baseline, at the multiple-comparison-corrected strong bar) is a result to build on. **DIRECTIONAL** (early/moderate/likely-worse/inconclusive signals — likely-worse means probably behind the baseline, wrong about one time in five, so do not build on that arm but do not treat it as decided either), **COLLECTING** (below the 100-visit floor per arm) and **EMPTY** all mean: apply the best-practice priors for the project's context type and make one conservative change. Never call an arm better or worse from its raw rate.
 
 **Add a no-code managed text variant (fallback — text only, less powerful)**
 1. `list_components` — confirm the component ID
 2. `create_variant` with `content` — creates a managed text draft (generate the copy from `get_variant_brief` context)
-3. Tell the user to activate it from the dashboard
+3. Show the user the draft; once they confirm, `update_variant` with `status: active` starts serving it (or they activate it from the dashboard)
+
+**Pause, and undo a pause**
+1. Confirm with the user before `pause_variant` — it stops new traffic immediately
+2. `resume_variant` puts it back; for a guardrail pause, check `list_guardrail_events` and the variant's evidence first — the guardrail fired for a reason
+
+**Fill generated versions**
+1. `get_cell_matrix` — which (visitor type, region) cells are empty
+2. Confirm with the user, then `generate_cell` — the result says whether the project auto-publishes or uses review mode
+3. Review mode: `list_cell_reviews`, show the user the version, then `review_cell` with `approve` or `reject`
 
 **Understand the audience**
 1. `get_persona_breakdown` — cluster sizes + reliability
@@ -83,10 +114,12 @@ The evidence state (from the brief) drives the change. It is keyed on the server
 ## Common Mistakes
 
 - Presenting stale insights without checking `isStale` — always check, and offer to `refresh_insights`
-- Assuming `create_variant` is live — it's always a draft
+- Assuming `create_variant` is live — it's always a draft until `update_variant` sets `status: active`
 - Calling `create_variant` for a variant that's being written in code — it creates an empty managed draft, not your code variant. Code-native variants auto-register on deploy; only use `create_variant` for no-code/managed variants whose content lives in SentientUI
 - Optimizing a component without calling `get_variant_brief` first — it gives you the per-arm evidence, audience, findings, and evidence-state fallback you need to write a variant that actually makes sense (and the right steps when there is no data yet)
 - Ranking variants by raw conversion rate — a rate on 10 sessions is noise. Only a server `verdict` of ahead/behind is a comparison; every rate carries its n for this reason
-- Calling `pause_variant` without warning the user it's irreversible via MCP
+- Calling any write tool (`pause_variant`, `retire_variant`, `update_variant`, `review_cell`, …) without the user's confirmation — they change what real visitors see
+- Resuming a guardrail-paused variant without checking why the guardrail fired
+- Using `restore_variant` to activate a draft — it is for retired variants; activate drafts with `update_variant` `status: active`
 - Using a `pk_` key instead of `sk_` — it will be rejected
 - Interpreting `avgReward` in layout stats as a conversion rate — it's a bandit reward signal, not CVR

package/README.md

@@ -14,7 +14,7 @@ MCP server for [SentientUI](https://sentient-ui.com) — gives AI agents in Clau
 
 **1. Get a server key**
 
-Dashboard → Project → **Settings → API key → Server key** → Generate (requires Starter or Growth plan).
+Dashboard → Project → **Settings → API key → Server key** → Generate. Available on every plan, including Free. A server key belongs to **one project**: it can read and change only that project, and generating a new one revokes the previous key.
 
 **2. Add to your AI assistant**
 
@@ -78,36 +78,53 @@ No account? Run without an API key:
 npx @sentientui/mcp
 ```
 
-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`.
+A demo token is provisioned automatically — 10 calls/month, read-only (write tools require an account with an `sk_` key or an OAuth sign-in), no sign-up required. It points at an **empty** sandbox project with no fixture data, so the read tools return empty results: it shows the tool surface, not a populated example. The token is cached in `~/.config/sentientui/mcp-anon.json`.
 
 ## Tools
 
-| Tool | What it does |
-|------|-------------|
-| `list_projects` | List all projects in the account |
-| `create_project` | Create a new project and return its `pk_` public key (account login required — not usable with an `sk_` project key or demo token) |
-| `get_project_stats` | Events, sessions, agent calls, and health status |
-| `list_components` | All adaptive components with variant counts |
-| `get_variant_performance` | Per-(component, variant) conversion with its sample, plus the server's evidence verdict vs the baseline (windowed rates: range 7d/30d/90d/all or from/to; default 7d; the verdict judges the windowed rate, with all-time reliability reported separately — all-time only on APIs without window evidence) |
-| `get_insights` | Ranked measured findings with tier and sample (low samples flagged), plus AI narrations marked as unmeasured |
-| `refresh_insights` | Trigger fresh AI insight generation |
-| `get_persona_breakdown` | Visitor cluster distribution with reliability scores |
-| `get_goal_funnel` | Goal hit counts and conversion rates (windowed; default 30d), plus all-time per-variant rates with their n |
-| `list_goals` | Defined goals (id, role, event, status) — includes goals with no conversions yet, so agents can wire a dashboard-defined goal into code |
-| `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` | Ready-to-paste test code (RTL, mock server, Playwright/Cypress) that forces one of the component's real variants |
-| `get_variant_brief` | Evidence-driven brief for writing a new **code-native** variant: per-arm rates with n and evidence verdicts, audience, measured findings, an evidence state (with a best-practice fallback while nothing is decided), 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) |
-
-> **Generated versions.** An `<Adaptive id="…">` that wraps your original as children (no `variants`) registers as a personalizable region once it is mounted and deployed. Its versions per visitor type are written in SentientUI — inspect and fill them with `get_cell_matrix`, `get_cell_detail`, and `generate_cell` — with no code change or redeploy.
+<!-- mcp-tools:start -->
+| Tool | Access | What it does |
+|------|--------|-------------|
+| `list_projects` | read | List the projects this credential can see (an `sk_` key sees only its own project) |
+| `create_project` | write | Create a project and return its `pk_` public key (account login only — not an `sk_` key or demo token) |
+| `get_project_stats` | read | Ingestion health: status, 24h events and sessions, and calls to the `/v1/agent` API (`agentCalls` — not MCP tool calls) |
+| `add_origin` | write | Allow-list a site origin so the SDK's events from it are accepted (idempotent) |
+| `list_components` | read | Adaptive components with variant counts and impressions |
+| `get_variant_performance` | read | Per-(component, variant) rates with their n and the server's evidence verdict vs the baseline (range 7d/30d/90d/all or from/to; default 7d; the verdict judges the windowed rate, with all-time reliability reported separately) |
+| `get_variant_brief` | read | Evidence-driven brief for writing a new **code-native** variant: per-arm rates with n and evidence verdicts, audience, measured findings, an evidence state (with a best-practice fallback while nothing is decided), and step-by-step code instructions |
+| `get_test_brief` | read | Ready-to-paste test code (RTL, mock server, Playwright/Cypress) that forces one of a component's real variants |
+| `create_variant` | write | Create a no-code managed text variant as a draft — fallback for text-only variants without a code change |
+| `update_variant` | write | Edit a managed variant's name or text, or activate a draft (`status: active` — it starts serving) / move it back to draft |
+| `delete_variant_draft` | write | Delete a managed variant that is still a draft |
+| `pause_variant` | write | Pause a variant so no new traffic is assigned to it (undo with `resume_variant`) |
+| `resume_variant` | write | Resume a paused variant — manual or guardrail pause |
+| `retire_variant` | write | Retire (archive) an active variant (undo with `restore_variant`; a promoted variant must be unpromoted first) |
+| `restore_variant` | write | Bring a retired variant back to active (does not unpause it) |
+| `get_goal_funnel` | read | Per-goal conversion summary (windowed; default 30d) with descriptive all-time per-variant rates — not a step funnel (use `get_funnel_report` for drop-off); the id is kept for compatibility |
+| `list_goals` | read | Defined goals (id, role, event, status), including ones with no conversions yet |
+| `define_goal` | write | Create a new goal (secondary or guardrail). Create-only: refuses an existing goal id and never sets or changes the primary goal |
+| `list_funnels` | read | Defined multi-step funnels |
+| `get_funnel_report` | read | Step-by-step funnel drop-off |
+| `list_guardrail_events` | read | Every variant currently paused by a guardrail (pass `days` to see only pauses from the last N days) |
+| `get_persona_breakdown` | read | Visitor clusters with session counts and reliability (all retained sessions) |
+| `get_layout_stats` | read | Per-persona section order with bandit pulls and reward (cumulative state) |
+| `get_insights` | read | Ranked measured findings with their sample (low samples flagged), plus AI narrations marked unmeasured |
+| `refresh_insights` | write | Regenerate AI insights — needs Starter or higher and an editor/admin role (a paid model call); advisor recommendations are Growth+ |
+| `get_cell_matrix` | read | The "Who sees what" matrix of generated versions per visitor type and region |
+| `get_cell_detail` | read | One cell's generated version, why it was written, and how it performs |
+| `generate_cell` | write | Queue AI generation for one cell — publishes automatically, or waits for approval when review mode is on (Free includes 5 generations/month) |
+| `list_cell_reviews` | read | Generated versions waiting for approval (review mode) |
+| `review_cell` | write | Approve (publish) or reject one generated version waiting for review |
+| `get_agent_traffic` | read | Which AI crawlers, agentic browsers and agent API callers read the site (windowed; paid plans) |
+| `get_agent_legibility` | read | Whether the pages agents read are machine-legible, with fixes (paid plans) |
+| `get_integration_guide` | read | SDK setup guide (static — same for every project) |
+<!-- mcp-tools:end -->
+
+> **Write tools ask first.** Every write tool changes what real visitors see or what the project accepts, so an assistant should confirm with you before calling one. The common ones are reversible: `pause_variant` → `resume_variant`, `retire_variant` → `restore_variant`, `update_variant` `status: active` → `status: draft`.
 >
-> **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.
+> **Generated versions.** An `<Adaptive id="…">` that wraps your original as children (no `variants`) registers as a personalizable region once it is mounted and deployed. Its versions per visitor type are written in SentientUI — inspect and fill them with `get_cell_matrix`, `get_cell_detail`, and `generate_cell` — with no code change or redeploy. When the project has review mode on, a generated version waits in `list_cell_reviews` until `review_cell` approves it.
+>
+> **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 — activate one with `update_variant` (`status: active`) or from the dashboard.
 >
 > **Optimizing a component?** Call `get_variant_brief` first. It returns each variant's rate with its sample and the server's evidence verdict, the audience, measured findings, and an evidence-state assessment — then your AI assistant writes a new on-brand variant directly into your code (which auto-registers on deploy). While nothing is decided, the brief falls back to best-practice priors for your project's context type so the assistant still makes a sensible change.
 
@@ -130,7 +147,7 @@ A sandboxed demo token is provisioned automatically — 10 calls/month, read-onl
 
 ## Auth model
 
-The server key you provide is passed as a `Bearer` token on every call to the SentientUI management API. It is scoped to your account — all projects you own are accessible. Keys are never logged or stored by the MCP package; they exist only in the process environment.
+The server key you provide is passed as a `Bearer` token on every call to the SentientUI management API. It is scoped to **one project**: `list_projects` returns only that project, and calls naming any other project are refused. To work across several projects, connect by URL with an OAuth sign-in instead. Keys are never logged or stored by the MCP package; they exist only in the process environment.
 
 Server keys start with `sk_` (not `pk_`). Public keys (`pk_`) are for the React SDK only and will be rejected by the management API.