@sentientui/mcp 0.2.1 → 0.2.2

package/AGENTS.md

@@ -0,0 +1,70 @@
+# SentientUI — AI Agent Guide
+
+SentientUI is a UI personalization platform that assigns visitors to variant components and reorders page sections per persona. The MCP gives agents read + limited write access to project data.
+
+## Key Concepts
+
+**Persona / Cluster** — visitors are clustered by behavior into labeled groups. A `reliability_score` (0–1) measures confidence in the assignment. Low reliability means the engine won't personalize for that session even if a cluster is assigned.
+
+**Variant** — a version of an adaptive component. Variants start as **draft** after `create_variant`; they must be activated from the dashboard before traffic is assigned. There is no MCP tool to activate or resume variants.
+
+**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).
+
+**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.
+
+**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.
+
+## Tool Quick Reference
+
+| Tool | Notes |
+|------|-------|
+| `list_projects` | Start here to get project IDs |
+| `get_project_stats` | Health status + 24h event/session volume |
+| `list_components` | Components + variant counts + impression totals |
+| `get_variant_performance` | CVR 7d vs prior 7d + momentum direction |
+| `get_persona_breakdown` | Cluster distribution + avg reliability per cluster |
+| `get_goal_funnel` | Goal hit counts + per-variant completion rates |
+| `list_guardrail_events` | Auto-paused variants (last 24h) |
+| `get_layout_stats` | Per-persona layout order + bandit pulls/reward |
+| `get_insights` | Narrator bullets + (Growth) advisor bullets |
+| `refresh_insights` | Async trigger — wait ~15s then call `get_insights` |
+| `create_variant` | Creates DRAFT — user must activate in dashboard |
+| `pause_variant` | Stops traffic; no MCP resume |
+
+## Canonical Workflows
+
+**Diagnose a conversion drop**
+1. `get_project_stats` — confirm events are flowing
+2. `get_goal_funnel` — find which goals/variants are down
+3. `get_variant_performance` — check CVR momentum
+4. `list_guardrail_events` — see if the guardrail fired
+5. `refresh_insights` → wait 15s → `get_insights` — read AI summary
+
+**Add a new variant**
+1. `list_components` — confirm the component ID
+2. `create_variant` — creates draft
+3. Tell the user to activate it from the dashboard
+
+**Understand the audience**
+1. `get_persona_breakdown` — cluster sizes + reliability
+2. `get_layout_stats` — what layout order each persona gets
+3. `get_insights` — AI narrative on what changed
+
+**Validate before going live (shadow mode)**
+- Shadow mode is enabled/disabled in the dashboard (Project Settings)
+- When ON: personalization runs silently, no live impact
+- When confident: turn OFF to start serving personalized experiences
+
+## 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
+- Calling `pause_variant` without warning the user it's irreversible via MCP
+- 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

@@ -6,7 +6,7 @@ MCP server for [SentientUI](https://sentient-ui.com) — gives AI agents in Clau
 
 **1. Get a server key**
 
-Dashboard → **Settings → API Keys → Create server key** (`sk_live_...`).
+Dashboard → Project → **Settings → API key → Server key** → Generate (requires Starter or Growth plan).
 
 **2. Add to your AI assistant**
 
@@ -107,6 +107,17 @@ The server key you provide is passed as a `Bearer` token on every call to the Se
 
 Server keys start with `sk_` (not `pk_`). Public keys (`pk_`) are for the React SDK only and will be rejected by the management API.
 
+## AI agent context
+
+`AGENTS.md` (included in this package) gives your AI assistant deeper context about SentientUI concepts, tool ordering, and common pitfalls. Wire it up once and it applies to every conversation.
+
+| Assistant | How to use |
+|-----------|-----------|
+| **Claude Code** | Copy to `~/.claude/skills/sentientui/SKILL.md` |
+| **Cursor** | Copy to `.cursor/rules/sentientui.mdc` |
+| **GitHub Copilot** | Append to `.github/copilot-instructions.md` |
+| **Other** | Paste into your assistant's system prompt |
+
 ## Requirements
 
 - Node.js 18+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentientui/mcp",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "MCP server for SentientUI — exposes project data and actions to AI agents",
   "type": "module",
   "bin": {
@@ -18,7 +18,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "tsup",