@sentientui/mcp 0.26.0 → 0.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -4,7 +4,33 @@ SentientUI is a UI personalization platform that assigns visitors to variant com
4
4
 
5
5
  ## Key Concepts
6
6
 
7
- **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.
7
+ **Audiences — and what makes each one serve.** When a visitor fits several, the order is declared › retargeting › discovered › campaign › arrival › everyone.
8
+
9
+ - **Everyone** (key `unknown`) — every visitor no other audience claims; usually most of the traffic.
10
+ - **Declared persona** (a bare key such as `developer`) — a role the site already knows, e.g. from sign-in. It serves **only on visits where the site declares it**: the `persona` prop on `<AdaptiveRoot>` / `<AdaptiveProvider>`, `init({ persona })` in `@sentientui/core`, or `window.sentient.persona` on the script tag (a string, or a function read once at start-up). The value must be exactly a key from the dashboard's Matrix → Audiences → Personas list. Adding a persona there only names it: one the site never sends has no visitors, and versions written for it reach nobody. Undeclared visitors are never guessed into a declared persona — for anonymous traffic use campaigns, arrival types or discovered audiences.
11
+ - **Discovered audience** (`d-…`) — found in real behaviour; it serves only after it is promoted, which needs evidence that it wants something different.
12
+ - **Campaign, arrival type, retargeting group** (`c-…`, `a-…`, `r-…`) — visitors who arrived on a named campaign's link, arrived a certain way, or were moved into a retargeting group after a campaign. A version restricted to one of these ("Show to", `manage_tests` `restrict_versions`) is shown only to them. A declared persona cannot be a "Show to" target.
13
+ - **Behaviour groups** (`get_persona_breakdown` `behaviourGroups`) — visitors whose visit patterns look alike ("Behaviour group 2"). Reporting only: they are **not** personas or audiences, nothing is shown to them, and they are never named after an audience. `get_persona_breakdown` `personas` counts the audience each visit was actually **served as** — the same number as the Matrix share in `get_cell_matrix`.
14
+ - **Names never target.** A version's display name, or a key in code `variants`, does not choose who sees it. To give one audience one version every time, pin it (`manage_approvals` `pin`, or the dashboard's "Always show this to …"). Pinned visitors stop teaching the optimizer for that component.
15
+
16
+ **Hybrid components need Migrate first.** An `<Adaptive>` with children **and** `variants` whose id already ran a variants test keeps serving that old test. Generated or dashboard-written versions for it do not serve — even when approved — until it is migrated (dashboard Matrix → Components → the component → Migrate…, or `manage_tests` `migrate_component`). Check before you generate for one.
17
+
18
+ **Funnels need a source per step.** A funnel is an ordered list of goal ids, and every step must have something that sends it — a page-visit goal, a click or form goal, `useGoal` in the browser, or `trackServerGoal` from the backend. A step nothing sends never fills, and the funnel reads as broken. Join a component to a funnel with `<Adaptive id="…" funnel="<funnelId>">`.
19
+
20
+ **Server goals — the exact call.** From a route handler, server action or webhook only (it needs the secret key):
21
+
22
+ ```ts
23
+ import { trackServerGoal } from '@sentientui/react/server'; // non-React backend: '@sentientui/core/server'
24
+
25
+ await trackServerGoal({
26
+ serverKey: process.env.SENTIENT_SECRET_KEY!, // the project's sk_ key
27
+ userId: user.id, // the id the site identifies the visitor with, e.g. <AdaptiveRoot userId={user.id}>
28
+ name: 'subscribed', // the goal id, exactly as defined
29
+ dedupeKey: user.id, // your own id for this conversion; a retry counts once
30
+ });
31
+ ```
32
+
33
+ In the visitor's own request, pass `sessionId: readSessionCookie(cookies, publicKey)` (same import) instead of `userId`. It resolves `'recorded'`, `'skipped_no_visitor'` or `'failed'` and never throws. There is no `sentientui.trackServerGoal(name, visitorId)` form.
8
34
 
9
35
  **Variant** — a version of an adaptive component. There are **two kinds**, and the difference matters:
10
36
 
@@ -23,6 +49,17 @@ Only call `create_variant` for the no-code path. If the user is writing (or you
23
49
 
24
50
  **Layout stats** — per-persona section ordering driven by a bandit algorithm. `pulls` = times a layout was applied, `avgReward` = normalized conversion signal (not raw CVR).
25
51
 
52
+ ## Excluding your team and test sites
53
+
54
+ Visits marked **internal** still see your versions — so QA on staging keeps working — but never count in any report (People, conversions, the Matrix share, funnels) and never teach the optimizer. Reports and `get_traffic_breakdown` list them as **Your team / test sites**. They are set up in the dashboard under **Settings → Internal traffic**, four ways:
55
+
56
+ - **Internal sites** — switch on any allowed domain (staging, preview, `localhost`); every visit from it is internal. Only allowed domains can be chosen.
57
+ - **Team emails & domains** — `@example.com` for a whole team, `name@example.com` for one person. They match visitors the site identifies with their email: `identify(userId, { email })` (core, or `useSentient()` in React) or `window.SentientSnippet.identify(userId, { email })` on the script tag. The SDK sends a SHA-256 of the trimmed, lowercased address and its domain — never the address — and exact rules are stored as the same hash and shown masked.
58
+ - **Browser link** — `https://<site>/?sentient_internal=<token>` opened once marks that browser; `?sentient_internal=off` stops it. Rotating the link un-marks every browser.
59
+ - **Code flag** — `<AdaptiveRoot internal={…}>` / `<AdaptiveProvider internal>`, `init({ internal })` in `@sentientui/core`, or `window.sentient.internal` (a boolean, or a function read once at start-up). Example: `internal={user.email.endsWith('@example.com')}` — the email never leaves the site.
60
+
61
+ It applies from when it is turned on: earlier visits can't be separated, because which site a visit came from was not recorded before. A visit marked internal after it already trained (a late identify, a rule added later) drops out of every report on the next read but is not untrained. There is no report filter or IP rule. `get_internal_traffic_rules` reads the rules (read-only; a person changes them in the dashboard).
62
+
26
63
  ## Auth
27
64
 
28
65
  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.
@@ -36,7 +73,7 @@ Every write tool changes what real visitors see or what the project accepts —
36
73
  |------|--------|-------|
37
74
  | `list_projects` | read | Start here to get project IDs (an `sk_` key sees only its own project) |
38
75
  | `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` |
39
- | `get_project_stats` | read | Health status + 24h events and People count. `agentCalls` counts calls to the `/v1/agent` API (all retained history) — not MCP tool calls |
76
+ | `get_project_stats` | read | Health status + 24h events and People count. `agentCalls` counts calls to the `/v1/agent` API (all retained history) — not MCP tool calls. `rejectedOrigins` lists sustained domains being turned away (not allowed; count = minutes with traffic) |
40
77
  | `add_origin` | write | Allow-list a site origin so the SDK's events from it are accepted. Idempotent |
41
78
  | `list_components` | read | Components + variant counts + impression totals |
42
79
  | `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 |
@@ -55,7 +92,7 @@ Every write tool changes what real visitors see or what the project accepts —
55
92
  | `list_funnels` | read | Defined multi-step funnels |
56
93
  | `get_funnel_report` | read | Step-by-step funnel drop-off |
57
94
  | `list_guardrail_events` | read | Every variant still paused by a guardrail; `days` narrows to recent pauses |
58
- | `get_persona_breakdown` | read | Cluster distribution + avg reliability per cluster (all retained sessions, not windowed) |
95
+ | `get_persona_breakdown` | read | Visitors per audience they were served as (30 days, the Matrix share) + behaviour groups (not audiences) |
59
96
  | `get_stage_breakdown` | read | E-commerce funnel stages: stage mix (observed vs hinted), arrival channel x stage, stage moves between visits, tested holdout lift per first-visit context and channel (the headline lift's always-valid test, all-time, alpha split over 23 series), versions per context with evidence (windowed, observational) |
60
97
  | `get_layout_stats` | read | Per-persona layout order + bandit pulls/reward (cumulative state, not windowed) |
61
98
  | `get_insights` | read | Ranked measured findings (tier + sample, low-sample flagged; `limit`, default 10) + (Growth) AI narrations, which are unmeasured |
@@ -66,7 +103,8 @@ Every write tool changes what real visitors see or what the project accepts —
66
103
  | `list_cell_reviews` | read | Generated versions waiting for approval |
67
104
  | `review_cell` | write | Approve (publishes to live traffic) or reject one waiting version |
68
105
  | `get_agent_traffic` | read | AI crawlers / automated browser sessions / agent API callers reading the site (windowed; paid plans) |
69
- | `get_traffic_breakdown` | read | Where traffic came from: People vs visitors we couldn't confirm vs automated (7 groups, windowed) |
106
+ | `get_traffic_breakdown` | read | Where traffic came from: People vs visitors we couldn't confirm vs automated vs your team / test sites (windowed) |
107
+ | `get_internal_traffic_rules` | read | How the project keeps its team and test sites out of its numbers: internal sites, team email domains and masked emails, browser link, sessions marked internal (7 days) |
70
108
  | `get_agent_legibility` | read | Whether agent-read pages are machine-legible, with fixes (paid plans) |
71
109
  | `get_agent_access` | read | Which areas a person has allowed agents to change (read this before a write; only a person can change it) |
72
110
  | `list_campaigns` | read | Named campaigns, retargeting groups and campaigns seen in traffic; with `campaignId`, one campaign card |
@@ -116,9 +154,16 @@ The evidence state (from the brief) drives the change. It is keyed on the server
116
154
  3. Review mode: `list_cell_reviews`, show the user the version, then `review_cell` with `approve` or `reject`
117
155
 
118
156
  **Understand the audience**
119
- 1. `get_persona_breakdown` — cluster sizes + reliability
120
- 2. `get_layout_stats` — what layout order each persona gets
121
- 3. `get_insights` — AI narrative on what changed
157
+ 1. `get_audiences` — declared and discovered audiences, and what blocks promotion
158
+ 2. `get_cell_matrix` — each audience's served share and what it sees (a declared persona at 0% is one the site never declares)
159
+ 3. `get_persona_breakdown` — who was served as which audience (the Matrix share), and, apart, behaviour groups (descriptive, never audiences)
160
+ 4. `get_layout_stats` — what layout order each persona gets
161
+ 5. `get_insights` — AI narrative on what changed
162
+
163
+ **"Why doesn't audience X see its version?"**
164
+ 1. `get_cell_matrix` — is X's share 0? A declared persona the site never sends has no visitors: give the user the declaration line for their setup (see Audiences above)
165
+ 2. Is the component a hybrid with an old variants test? Its new versions wait for `migrate_component`
166
+ 3. Is the version waiting for approval (`list_cell_reviews`) or restricted to a campaign?
122
167
 
123
168
  **Validate before going live (shadow mode)**
124
169
  - Shadow mode is enabled/disabled in the dashboard (Project Settings)
@@ -137,3 +182,10 @@ The evidence state (from the brief) drives the change. It is keyed on the server
137
182
  - Using `restore_variant` to activate a draft — it is for retired variants; activate drafts with `update_variant` `status: active`
138
183
  - Using a `pk_` key instead of `sk_` — it will be rejected
139
184
  - Interpreting `avgReward` in layout stats as a conversion rate — it's a bandit reward signal, not CVR
185
+ - Reporting a behaviour group as an audience's visitors — behaviour groups are not personas; an audience's visitors are `get_persona_breakdown` `personas` (= the Matrix share)
186
+ - Expecting a declared persona to serve because it is in the vocabulary — the site has to declare it on the visit
187
+ - Naming a version (or a code `variants` key) after an audience and expecting it to target them — pin it instead
188
+ - Generating versions for a hybrid component that still has its old variants test — nothing serves until `migrate_component`
189
+ - Building a funnel over goal ids nothing sends — every step needs a source
190
+ - Writing any other call shape for server goals than the `trackServerGoal({ … })` block above
191
+ - Telling a user to filter staging or team traffic out of a report — there is no report filter or IP rule; point them to Settings → Internal traffic (it applies from when it is turned on), and read the current rules with `get_internal_traffic_rules`
package/README.md CHANGED
@@ -87,7 +87,7 @@ A demo token is provisioned automatically — 10 calls/month, read-only (write t
87
87
  |------|--------|-------------|
88
88
  | `list_projects` | read | List the projects this credential can see (an `sk_` key sees only its own project) |
89
89
  | `create_project` | write | Create a project and return its `pk_` public key (account login only — not an `sk_` key or demo token) |
90
- | `get_project_stats` | read | Ingestion health: status, 24h events and People (with how many are being analysed or automated), and calls to the `/v1/agent` API (`agentCalls` — not MCP tool calls) |
90
+ | `get_project_stats` | read | Ingestion health: status, 24h events and People (with how many are being analysed or automated), and calls to the `/v1/agent` API (`agentCalls` — not MCP tool calls), plus sustained domains the snippet runs on that are turned away (not allowed) |
91
91
  | `add_origin` | write | Allow-list a site origin so the SDK's events from it are accepted (idempotent) |
92
92
  | `list_components` | read | Adaptive components with variant counts and impressions |
93
93
  | `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) |
@@ -106,7 +106,7 @@ A demo token is provisioned automatically — 10 calls/month, read-only (write t
106
106
  | `list_funnels` | read | Defined multi-step funnels |
107
107
  | `get_funnel_report` | read | Step-by-step funnel drop-off |
108
108
  | `list_guardrail_events` | read | Every variant currently paused by a guardrail (pass `days` to see only pauses from the last N days) |
109
- | `get_persona_breakdown` | read | Visitor clusters with session counts and reliability (all retained sessions) |
109
+ | `get_persona_breakdown` | read | Visitors per audience they were served as (30 days — the Matrix share), plus behaviour groups (visitors who behaved alike — never audiences) |
110
110
  | `get_stage_breakdown` | read | E-commerce funnel stages: stage mix, arrival channel x stage, stage moves between visits, tested holdout lift per first-visit context and channel (all-time), and versions per context (windowed, observational) |
111
111
  | `get_layout_stats` | read | Per-persona section order with bandit pulls and reward (cumulative state) |
112
112
  | `get_insights` | read | Ranked measured findings with their sample (low samples flagged), plus AI narrations marked unmeasured |
@@ -117,7 +117,8 @@ A demo token is provisioned automatically — 10 calls/month, read-only (write t
117
117
  | `list_cell_reviews` | read | Generated versions waiting for approval (review mode) |
118
118
  | `review_cell` | write | Approve (publish) or reject one generated version waiting for review |
119
119
  | `get_agent_traffic` | read | Which AI crawlers, automated browser sessions and agent API callers read the site (windowed; paid plans) |
120
- | `get_traffic_breakdown` | read | Where traffic came from: People vs visitors we couldn't confirm vs automated (7 groups, windowed) |
120
+ | `get_traffic_breakdown` | read | Where traffic came from: People vs visitors we couldn't confirm vs automated vs your team / test sites (windowed) |
121
+ | `get_internal_traffic_rules` | read | How the project keeps its team and test sites out of its numbers: internal sites, team email domains and masked emails, browser link, sessions marked internal (7 days) |
121
122
  | `get_agent_legibility` | read | Whether the pages agents read are machine-legible, with fixes (paid plans) |
122
123
  | `get_agent_access` | read | Which areas a person has allowed agents to change (read this before a write; only a person can change it) |
123
124
  | `list_campaigns` | read | Named campaigns, retargeting groups and campaigns seen in traffic; with `campaignId`, one campaign card |
@@ -138,10 +139,27 @@ A demo token is provisioned automatically — 10 calls/month, read-only (write t
138
139
  >
139
140
  > **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.
140
141
  >
142
+ > **Which audiences actually serve.** A *declared* persona serves only on visits where your site declares it (`persona` prop on `<AdaptiveRoot>` / `<AdaptiveProvider>`, `init({ persona })`, or `window.sentient.persona`) — adding it to the vocabulary only names it. A *discovered* audience serves once it is promoted. *Campaigns*, arrival types and retargeting groups reach visitors by how they arrived, which is how to reach anonymous traffic. `get_persona_breakdown` counts the audience each visit was actually served as (the Matrix share); its `behaviourGroups` are descriptive groups of similar behaviour, not personas — never read one as an audience's visitors. A version's name never targets anyone — pin it to an audience instead. Pinned visitors stop teaching the optimizer for that component.
143
+ >
144
+ > **Hybrid components need Migrate.** An `<Adaptive>` with children *and* `variants` whose id already ran a variants test keeps serving that test; generated versions for it do not serve until it is migrated (`manage_tests` `migrate_component`, or Migrate… in the dashboard).
145
+ >
146
+ > **Funnels and server goals.** Every funnel step needs something that sends it. For a step your backend confirms, the call is `trackServerGoal({ serverKey, userId, name, dedupeKey })` from `@sentientui/react/server` (or `@sentientui/core/server`) — see `AGENTS.md` for the exact block.
147
+ >
141
148
  > **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.
142
149
  >
143
150
  > **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.
144
151
 
152
+ ## Excluding your team and test sites
153
+
154
+ Visits marked **internal** still see your versions — so QA on staging keeps working — but never count in any report (People, conversions, the Matrix share, funnels) and never teach the optimizer. Reports and `get_traffic_breakdown` list them as **Your team / test sites**. They are set up in the dashboard under **Settings → Internal traffic**, four ways:
155
+
156
+ - **Internal sites** — switch on any allowed domain (staging, preview, `localhost`); every visit from it is internal. Only allowed domains can be chosen.
157
+ - **Team emails & domains** — `@example.com` for a whole team, `name@example.com` for one person. They match visitors the site identifies with their email: `identify(userId, { email })` (core, or `useSentient()` in React) or `window.SentientSnippet.identify(userId, { email })` on the script tag. The SDK sends a SHA-256 of the trimmed, lowercased address and its domain — never the address — and exact rules are stored as the same hash and shown masked.
158
+ - **Browser link** — `https://<site>/?sentient_internal=<token>` opened once marks that browser; `?sentient_internal=off` stops it. Rotating the link un-marks every browser.
159
+ - **Code flag** — `<AdaptiveRoot internal={…}>` / `<AdaptiveProvider internal>`, `init({ internal })` in `@sentientui/core`, or `window.sentient.internal` (a boolean, or a function read once at start-up). Example: `internal={user.email.endsWith('@example.com')}` — the email never leaves the site.
160
+
161
+ It applies from when it is turned on: earlier visits can't be separated, because which site a visit came from was not recorded before. A visit marked internal after it already trained (a late identify, a rule added later) drops out of every report on the next read but is not untrained. There is no report filter or IP rule. `get_internal_traffic_rules` reads the rules (read-only; a person changes them in the dashboard).
162
+
145
163
  ## Example prompts
146
164
 
147
165
  - *"What projects do I have?"*