@sentientui/mcp 0.2.0 → 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

@@ -0,0 +1,124 @@
+# @sentientui/mcp
+
+MCP server for [SentientUI](https://sentient-ui.com) — gives AI agents in Claude Code, Cursor, and Copilot direct access to your experiment data and management actions.
+
+## Quick start
+
+**1. Get a server key**
+
+Dashboard → Project → **Settings → API key → Server key** → Generate (requires Starter or Growth plan).
+
+**2. Add to your AI assistant**
+
+**Claude Code** — `~/.claude/settings.json`:
+```json
+{
+  "mcpServers": {
+    "sentientui": {
+      "command": "npx",
+      "args": ["-y", "@sentientui/mcp"],
+      "env": {
+        "SENTIENTUI_API_KEY": "sk_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+**Cursor** — `~/.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "sentientui": {
+      "command": "npx",
+      "args": ["-y", "@sentientui/mcp"],
+      "env": {
+        "SENTIENTUI_API_KEY": "sk_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+**VS Code + Copilot** — `.vscode/mcp.json`:
+```json
+{
+  "servers": {
+    "sentientui": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@sentientui/mcp"],
+      "env": {
+        "SENTIENTUI_API_KEY": "sk_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+**3. Restart your IDE.** The server connects at startup.
+
+## Demo mode
+
+No account? Run without an API key:
+
+```bash
+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`.
+
+## Tools
+
+| Tool | What it does |
+|------|-------------|
+| `list_projects` | List all projects in the account |
+| `get_project_stats` | Events, sessions, agent calls, and health status |
+| `list_components` | All adaptive components with variant counts |
+| `get_variant_performance` | CVR, momentum, and impressions per variant (7d vs prior 7d) |
+| `get_insights` | AI-generated narrator observations and advisor recommendations |
+| `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 per variant |
+| `list_guardrail_events` | Variants auto-paused by the guardrail (last 24h) |
+| `get_layout_stats` | Per-persona section layout rankings and reward weights |
+| `create_variant` | Create a new draft variant (Starter+) |
+| `pause_variant` | Pause a variant to stop traffic assignment |
+
+## Example prompts
+
+- *"What projects do I have?"*
+- *"Show me the CVR trends for the hero banner this week"*
+- *"Are any variants paused by the guardrail right now?"*
+- *"What do the AI insights say about what changed this week?"*
+- *"Refresh insights for project X"*
+- *"Create a new variant called 'short-copy' for the pricing CTA"*
+
+## Configuration
+
+| 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. |
+
+## 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.
+
+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+
+- A SentientUI account (or use demo mode)

package/dist/index.cjs

@@ -379,7 +379,7 @@ async function main() {
   if (!apiKey) {
     apiKey = await resolveDemoToken();
   }
-  const client = new ApiClient({ apiKey });
+  const client = new ApiClient({ apiKey, baseUrl: process.env.SENTIENTUI_API_URL });
   const server = createMcpServer(client);
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);

package/dist/index.js

@@ -378,7 +378,7 @@ async function main() {
   if (!apiKey) {
     apiKey = await resolveDemoToken();
   }
-  const client = new ApiClient({ apiKey });
+  const client = new ApiClient({ apiKey, baseUrl: process.env.SENTIENTUI_API_URL });
   const server = createMcpServer(client);
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentientui/mcp",
-  "version": "0.2.0",
+  "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",