@sentientui/mcp 0.28.1 → 0.29.1
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 +2 -2
- package/README.md +2 -2
- package/dist/{chunk-45KNPF7X.js → chunk-K7BUXTYP.js} +15 -9
- package/dist/index.cjs +15 -9
- package/dist/index.js +1 -1
- package/dist/lib.cjs +15 -9
- package/dist/lib.js +1 -1
- package/package.json +1 -1
package/AGENTS.md
CHANGED
|
@@ -13,7 +13,7 @@ SentientUI is a UI personalization platform that assigns visitors to variant com
|
|
|
13
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
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
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 Components → the component → Migrate…, or `manage_tests` `migrate_component`). Check before you generate for one.
|
|
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 Components → the component → Migrate…, or `manage_tests` `migrate_component`). Sentient migrates it by itself once the code's test has assigned nobody a version for 14 days. Check before you generate for one.
|
|
17
17
|
|
|
18
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
19
|
|
|
@@ -58,7 +58,7 @@ Visits marked **internal** still see your versions — so QA on staging keeps wo
|
|
|
58
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
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
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
|
|
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; `manage_settings` changes them (`set_internal_sites`, `add_internal_email`, `remove_internal_email`) when the project's Agent access allows Project settings.
|
|
62
62
|
|
|
63
63
|
## Auth
|
|
64
64
|
|
package/README.md
CHANGED
|
@@ -148,7 +148,7 @@ A demo token is provisioned automatically — 10 calls/month, read-only (write t
|
|
|
148
148
|
>
|
|
149
149
|
> **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.
|
|
150
150
|
>
|
|
151
|
-
> **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).
|
|
151
|
+
> **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) — automatic once the code's test has assigned nobody a version for 14 days.
|
|
152
152
|
>
|
|
153
153
|
> **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.
|
|
154
154
|
>
|
|
@@ -165,7 +165,7 @@ Visits marked **internal** still see your versions — so QA on staging keeps wo
|
|
|
165
165
|
- **Browser link** — `https://<site>/?sentient_internal=<token>` opened once marks that browser; `?sentient_internal=off` stops it. Rotating the link un-marks every browser.
|
|
166
166
|
- **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.
|
|
167
167
|
|
|
168
|
-
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
|
|
168
|
+
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; `manage_settings` changes them (`set_internal_sites`, `add_internal_email`, `remove_internal_email`) when the project's Agent access allows Project settings.
|
|
169
169
|
|
|
170
170
|
## Example prompts
|
|
171
171
|
|
|
@@ -2072,7 +2072,7 @@ function registerPageElementTools(server, client) {
|
|
|
2072
2072
|
"get_page_elements",
|
|
2073
2073
|
{
|
|
2074
2074
|
title: "Page elements Sentient found on your site",
|
|
2075
|
-
description: "The buttons, headlines, forms and other elements the latest site check found, each with an `id`, what kind it is, its label, its current text and the page it is on. Use an `id` as `targetId` for manage_generation open_pr, which writes the change into your site's code and sends it to your developers as a pull request (the project needs a connected GitHub repo first \u2014 that one step is done in the dashboard, because GitHub asks the repo owner to approve the app). open_pr body: { targetId, label, goalId, arms: [{ displayName, ops }] } with 2\u20134 arms, the first being the element as it is now (ops {}). ops may set: text (plain text), hidden (boolean), href and imageSrc (https URLs), imageAlt, and style with these properties only: color, background, fontSize, fontWeight, textAlign, padding, margin, borderRadius, width, height, maxWidth, border, boxShadow, opacity, lineHeight, letterSpacing, textTransform, gap, fontFamily. Pass `pageUrl` to keep one page. When the site has not been checked yet, ask for a check with manage_settings rescan_site; results land in a few minutes." + UNTRUSTED_FIELDS_NOTE,
|
|
2075
|
+
description: "The buttons, headlines, forms and other elements the latest site check found, each with an `id`, what kind it is, its label, its current text and the page it is on. Use an `id` as `targetId` for manage_generation open_pr, which writes the change into your site's code and sends it to your developers as a pull request (the project needs a connected GitHub repo first \u2014 that one step is done in the dashboard, Settings \u2192 GitHub, because GitHub asks the repo owner to approve the app). An element with no text (a whole form, an image with no id) cannot be found in the code and is refused for open_pr \u2014 offer the no-code path for it. open_pr body: { targetId, label, goalId, arms: [{ displayName, ops }] } with 2\u20134 arms, the first being the element as it is now (ops {}). ops may set: text (plain text), hidden (boolean), href and imageSrc (https URLs), imageAlt, and style with these properties only: color, background, fontSize, fontWeight, textAlign, padding, margin, borderRadius, width, height, maxWidth, border, boxShadow, opacity, lineHeight, letterSpacing, textTransform, gap, fontFamily. Pass `pageUrl` to keep one page. When the site has not been checked yet, ask for a check with manage_settings rescan_site; results land in a few minutes." + UNTRUSTED_FIELDS_NOTE,
|
|
2076
2076
|
inputSchema: {
|
|
2077
2077
|
projectId: projectIdSchema,
|
|
2078
2078
|
pageUrl: z12.string().max(500).optional().describe("Only elements on this page (a path like /pricing, or a full URL)")
|
|
@@ -3883,7 +3883,7 @@ function registerInternalTrafficTools(server, client) {
|
|
|
3883
3883
|
"get_internal_traffic_rules",
|
|
3884
3884
|
{
|
|
3885
3885
|
title: "Internal traffic rules",
|
|
3886
|
-
description: `Read how this project keeps its own team and test sites out of its numbers (dashboard Settings \u2192 Internal traffic): which allowed domains are internal sites, the team email domains and masked exact emails, whether a "mark this browser" link exists, and how many sessions each way marked internal in the last 7 days. Internal visits still see versions (QA works) but never count in any report or teach the optimizer; get_traffic_breakdown lists them as "${INTERNAL_TRAFFIC_LABEL}". Exact emails are stored only as a hash \u2014 this tool returns the masked form, never an address or the hash. Rules apply from when they are turned on
|
|
3886
|
+
description: `Read how this project keeps its own team and test sites out of its numbers (dashboard Settings \u2192 Internal traffic): which allowed domains are internal sites, the team email domains and masked exact emails, whether a "mark this browser" link exists, and how many sessions each way marked internal in the last 7 days. Internal visits still see versions (QA works) but never count in any report or teach the optimizer; get_traffic_breakdown lists them as "${INTERNAL_TRAFFIC_LABEL}". Exact emails are stored only as a hash \u2014 this tool returns the masked form, never an address or the hash. Rules apply from when they are turned on. To change them: manage_settings set_internal_sites, add_internal_email, remove_internal_email.`,
|
|
3887
3887
|
inputSchema: { projectId: projectIdSchema },
|
|
3888
3888
|
outputSchema: {
|
|
3889
3889
|
internalOrigins: z24.array(z24.string()).describe("Allowed domains whose every visit is marked internal"),
|
|
@@ -3958,9 +3958,9 @@ var personaOutput = z25.object({
|
|
|
3958
3958
|
)
|
|
3959
3959
|
});
|
|
3960
3960
|
var blockedOutput = z25.enum(["variant_history"]).nullable().optional().describe(
|
|
3961
|
-
"variant_history: the component's code still runs its own variants test, so versions written here are approved but NOT showing until it is migrated (dashboard Components \u2192 Migrate). Null when the column can serve."
|
|
3961
|
+
"variant_history: the component's code still runs its own variants test, so versions written here are approved but NOT showing until it is migrated (dashboard Components \u2192 Migrate; automatic once that test has assigned nobody a version for 14 days). Null when the column can serve."
|
|
3962
3962
|
);
|
|
3963
|
-
var BLOCKED_LINE = "Not showing yet \u2014 your code's own test still runs here. Versions written for this part of the page are approved but no visitor sees them until it is migrated (Components \u2192 this component \u2192 Migrate).";
|
|
3963
|
+
var BLOCKED_LINE = "Not showing yet \u2014 your code's own test still runs here. Versions written for this part of the page are approved but no visitor sees them until it is migrated (Components \u2192 this component \u2192 Migrate) \u2014 Sentient does it by itself once that test has shown nobody a version for 14 days.";
|
|
3964
3964
|
var NOT_DECLARED_LINE = "not declared yet \u2014 your site has not told us anyone is this persona in 14 days, so nobody sees versions written for them until your code sends it (the persona prop, init({ persona }) or window.sentient.persona)";
|
|
3965
3965
|
var cellOutput = z25.object({
|
|
3966
3966
|
slotId: z25.string(),
|
|
@@ -4803,7 +4803,13 @@ var ACTIONS = {
|
|
|
4803
4803
|
save_insight: a("POST", "structured-insights/:insightId/save", { body: "opt" }),
|
|
4804
4804
|
// Who counts as already past the main goal (spec 2026-11-17).
|
|
4805
4805
|
set_gate_settings: a("PUT", "gate-settings", { body: "req" }),
|
|
4806
|
-
import_known_people: a("POST", "known-people/import", { body: "req" })
|
|
4806
|
+
import_known_people: a("POST", "known-people/import", { body: "req" }),
|
|
4807
|
+
// Internal traffic (2026-11-19): read-only until now, but the API already
|
|
4808
|
+
// let agents change it under the Project settings switch — the MCP was
|
|
4809
|
+
// the only thing in the way of "keep our staging site out of the numbers".
|
|
4810
|
+
set_internal_sites: a("PUT", "internal-traffic/origins", { body: "req" }),
|
|
4811
|
+
add_internal_email: a("POST", "internal-traffic/emails", { body: "req" }),
|
|
4812
|
+
remove_internal_email: a("DELETE", "internal-traffic/emails", { body: "req" })
|
|
4807
4813
|
}
|
|
4808
4814
|
};
|
|
4809
4815
|
var REFUSAL_NOTE = " If this project has turned off agent access for this area, the call is refused with a sentence saying so \u2014 tell the user, don't retry.";
|
|
@@ -4836,7 +4842,7 @@ var TOOLS = {
|
|
|
4836
4842
|
manage_settings: {
|
|
4837
4843
|
title: "Manage project settings",
|
|
4838
4844
|
destructive: true,
|
|
4839
|
-
description:
|
|
4845
|
+
description: 'Change project settings: rename or edit the project, remove an allowed origin, add, remove or test a webhook, remove a captured style, rescan the site, set page meaning, create, refresh or remove a report share link, set previews and the layout and slot models, send a test event, and accept, dismiss or save a structured insight. Also who counts as already converted: set_gate_settings (body { identifiedIsConverted: boolean } \u2014 true only when reaching the main goal is what creates the account, i.e. the main goal is sign-up; not available on stores) and import_known_people (body { people: [{ userId, convertedAt?, converted?, orderCount?, totalSpent?, currency?, lastOrderAt?, customerSince?, tags? }] }, at most 2000 per call \u2014 the site\'s own user ids for people who already reached the main goal; never names, emails, phone numbers or addresses, which are refused). Who counts as your team or a test site (Settings \u2192 Internal traffic; read the rules first with get_internal_traffic_rules): set_internal_sites (body { origins: [...] } \u2014 the WHOLE list of internal sites, each one already an allowed origin; an origin left out stops being internal), add_internal_email (body { value } \u2014 a team email domain such as "@acme.com", or one exact address, which is stored only as a hash) and remove_internal_email (body { domain } or { hash } from get_internal_traffic_rules). Internal visits still see versions but never count or teach the optimizer, from the moment a rule is on; earlier visits are separated where the rule can tell. Confirm the list with the user first. Removals cannot be undone. The three insight actions (accept_insight, dismiss_insight, save_insight) are always allowed: the Project settings switch does not govern them. Pick one `action`; pass the ids it needs.' + REFUSAL_NOTE
|
|
4840
4846
|
}
|
|
4841
4847
|
};
|
|
4842
4848
|
var pathParams = (route) => [...route.matchAll(/:([A-Za-z]+)/g)].map((m) => m[1]);
|
|
@@ -4911,7 +4917,7 @@ Audiences, and what makes each one serve (precedence: declared > retargeting > d
|
|
|
4911
4917
|
- get_persona_breakdown personas counts the audience each visit was actually served as (the same number as the Matrix share in get_cell_matrix). Its behaviourGroups ("Behaviour group N") are visitors who behaved alike: not personas or audiences, they serve nothing \u2014 never report one as an audience's visitors.
|
|
4912
4918
|
- A version's name, or a code variants key, never targets an audience. To give one audience one version, pin it (manage_approvals pin); pinned visitors stop teaching the optimizer for that component.
|
|
4913
4919
|
|
|
4914
|
-
Components: an <Adaptive> with children and variants whose id already ran a variants test keeps serving that old test; dashboard-written or generated versions for it do not serve until it is migrated (dashboard Components -> Migrate..., or manage_tests migrate_component).
|
|
4920
|
+
Components: an <Adaptive> with children and variants whose id already ran a variants test keeps serving that old test; dashboard-written or generated versions for it do not serve until it is migrated (dashboard Components -> Migrate..., or manage_tests migrate_component). Sentient migrates it by itself once the code's test has assigned nobody a version for 14 days.
|
|
4915
4921
|
|
|
4916
4922
|
Funnels: every step must have something that sends it (a page-visit rule, a click or form goal, useGoal in the browser, or trackServerGoal from the server), or that step never fills.
|
|
4917
4923
|
|
|
@@ -4920,7 +4926,7 @@ Server goal, exact shape (server only, never the browser):
|
|
|
4920
4926
|
await trackServerGoal({ serverKey: process.env.SENTIENT_SECRET_KEY!, userId: user.id, name: 'subscribed', dedupeKey: user.id });
|
|
4921
4927
|
userId must be the id the site identifies the visitor with (<AdaptiveRoot userId={user.id}>); in the visitor's own request pass sessionId: readSessionCookie(cookies, publicKey) instead.
|
|
4922
4928
|
|
|
4923
|
-
Excluding the team and test sites (dashboard Settings -> Internal traffic): visits marked internal still see versions (QA works) but never count in any report and never teach the optimizer; get_traffic_breakdown lists them as "Your team / test sites". They are marked by internal sites (allowed domains such as staging or localhost), team emails and domains (they match visitors the site identifies with identify(userId, { email }); the SDK sends only a SHA-256 of the address and its domain, never the address), a browser link, or the code flag (the internal prop on <AdaptiveRoot>/<AdaptiveProvider>, init({ internal }), window.sentient.internal). There is no report filter or IP rule, and visits from before a rule was turned on cannot be separated. Read the rules with get_internal_traffic_rules;
|
|
4929
|
+
Excluding the team and test sites (dashboard Settings -> Internal traffic): visits marked internal still see versions (QA works) but never count in any report and never teach the optimizer; get_traffic_breakdown lists them as "Your team / test sites". They are marked by internal sites (allowed domains such as staging or localhost), team emails and domains (they match visitors the site identifies with identify(userId, { email }); the SDK sends only a SHA-256 of the address and its domain, never the address), a browser link, or the code flag (the internal prop on <AdaptiveRoot>/<AdaptiveProvider>, init({ internal }), window.sentient.internal). There is no report filter or IP rule, and visits from before a rule was turned on cannot be separated. Read the rules with get_internal_traffic_rules; change them with manage_settings set_internal_sites / add_internal_email / remove_internal_email (Agent access: Project settings), after confirming the list with the user.
|
|
4924
4930
|
|
|
4925
4931
|
The main funnel (get_main_funnel): "how is my funnel doing" is answered by the one journey that ends at the project's main goal \u2014 Arrived, the marketer's own steps, the main goal \u2014 counted in people, with those who had already converted left out. It is chosen with manage_goals set_main_funnel and must end at the main goal; with none chosen it is just Arrived -> main goal. Stores get their checkout journey as the main funnel on connect. Use get_funnel_report only for a side journey: it counts one funnel's goals inside a window and includes people who had already converted, so its numbers and the main funnel's do not add up.
|
|
4926
4932
|
|
|
@@ -4931,7 +4937,7 @@ Known people (get_known_people): a person is "known" once they have reached the
|
|
|
4931
4937
|
Write tools change what real visitors see: confirm with the user first. Call get_agent_access before a manage_* write.`;
|
|
4932
4938
|
|
|
4933
4939
|
// src/server.ts
|
|
4934
|
-
var PKG_VERSION = true ? "0.
|
|
4940
|
+
var PKG_VERSION = true ? "0.29.1" : "0.0.0-dev";
|
|
4935
4941
|
function createMcpServer(client) {
|
|
4936
4942
|
const server = new McpServer(
|
|
4937
4943
|
{
|
package/dist/index.cjs
CHANGED
|
@@ -2076,7 +2076,7 @@ function registerPageElementTools(server, client) {
|
|
|
2076
2076
|
"get_page_elements",
|
|
2077
2077
|
{
|
|
2078
2078
|
title: "Page elements Sentient found on your site",
|
|
2079
|
-
description: "The buttons, headlines, forms and other elements the latest site check found, each with an `id`, what kind it is, its label, its current text and the page it is on. Use an `id` as `targetId` for manage_generation open_pr, which writes the change into your site's code and sends it to your developers as a pull request (the project needs a connected GitHub repo first \u2014 that one step is done in the dashboard, because GitHub asks the repo owner to approve the app). open_pr body: { targetId, label, goalId, arms: [{ displayName, ops }] } with 2\u20134 arms, the first being the element as it is now (ops {}). ops may set: text (plain text), hidden (boolean), href and imageSrc (https URLs), imageAlt, and style with these properties only: color, background, fontSize, fontWeight, textAlign, padding, margin, borderRadius, width, height, maxWidth, border, boxShadow, opacity, lineHeight, letterSpacing, textTransform, gap, fontFamily. Pass `pageUrl` to keep one page. When the site has not been checked yet, ask for a check with manage_settings rescan_site; results land in a few minutes." + UNTRUSTED_FIELDS_NOTE,
|
|
2079
|
+
description: "The buttons, headlines, forms and other elements the latest site check found, each with an `id`, what kind it is, its label, its current text and the page it is on. Use an `id` as `targetId` for manage_generation open_pr, which writes the change into your site's code and sends it to your developers as a pull request (the project needs a connected GitHub repo first \u2014 that one step is done in the dashboard, Settings \u2192 GitHub, because GitHub asks the repo owner to approve the app). An element with no text (a whole form, an image with no id) cannot be found in the code and is refused for open_pr \u2014 offer the no-code path for it. open_pr body: { targetId, label, goalId, arms: [{ displayName, ops }] } with 2\u20134 arms, the first being the element as it is now (ops {}). ops may set: text (plain text), hidden (boolean), href and imageSrc (https URLs), imageAlt, and style with these properties only: color, background, fontSize, fontWeight, textAlign, padding, margin, borderRadius, width, height, maxWidth, border, boxShadow, opacity, lineHeight, letterSpacing, textTransform, gap, fontFamily. Pass `pageUrl` to keep one page. When the site has not been checked yet, ask for a check with manage_settings rescan_site; results land in a few minutes." + UNTRUSTED_FIELDS_NOTE,
|
|
2080
2080
|
inputSchema: {
|
|
2081
2081
|
projectId: projectIdSchema,
|
|
2082
2082
|
pageUrl: import_v312.z.string().max(500).optional().describe("Only elements on this page (a path like /pricing, or a full URL)")
|
|
@@ -3887,7 +3887,7 @@ function registerInternalTrafficTools(server, client) {
|
|
|
3887
3887
|
"get_internal_traffic_rules",
|
|
3888
3888
|
{
|
|
3889
3889
|
title: "Internal traffic rules",
|
|
3890
|
-
description: `Read how this project keeps its own team and test sites out of its numbers (dashboard Settings \u2192 Internal traffic): which allowed domains are internal sites, the team email domains and masked exact emails, whether a "mark this browser" link exists, and how many sessions each way marked internal in the last 7 days. Internal visits still see versions (QA works) but never count in any report or teach the optimizer; get_traffic_breakdown lists them as "${INTERNAL_TRAFFIC_LABEL}". Exact emails are stored only as a hash \u2014 this tool returns the masked form, never an address or the hash. Rules apply from when they are turned on
|
|
3890
|
+
description: `Read how this project keeps its own team and test sites out of its numbers (dashboard Settings \u2192 Internal traffic): which allowed domains are internal sites, the team email domains and masked exact emails, whether a "mark this browser" link exists, and how many sessions each way marked internal in the last 7 days. Internal visits still see versions (QA works) but never count in any report or teach the optimizer; get_traffic_breakdown lists them as "${INTERNAL_TRAFFIC_LABEL}". Exact emails are stored only as a hash \u2014 this tool returns the masked form, never an address or the hash. Rules apply from when they are turned on. To change them: manage_settings set_internal_sites, add_internal_email, remove_internal_email.`,
|
|
3891
3891
|
inputSchema: { projectId: projectIdSchema },
|
|
3892
3892
|
outputSchema: {
|
|
3893
3893
|
internalOrigins: import_v324.z.array(import_v324.z.string()).describe("Allowed domains whose every visit is marked internal"),
|
|
@@ -3962,9 +3962,9 @@ var personaOutput = import_v325.z.object({
|
|
|
3962
3962
|
)
|
|
3963
3963
|
});
|
|
3964
3964
|
var blockedOutput = import_v325.z.enum(["variant_history"]).nullable().optional().describe(
|
|
3965
|
-
"variant_history: the component's code still runs its own variants test, so versions written here are approved but NOT showing until it is migrated (dashboard Components \u2192 Migrate). Null when the column can serve."
|
|
3965
|
+
"variant_history: the component's code still runs its own variants test, so versions written here are approved but NOT showing until it is migrated (dashboard Components \u2192 Migrate; automatic once that test has assigned nobody a version for 14 days). Null when the column can serve."
|
|
3966
3966
|
);
|
|
3967
|
-
var BLOCKED_LINE = "Not showing yet \u2014 your code's own test still runs here. Versions written for this part of the page are approved but no visitor sees them until it is migrated (Components \u2192 this component \u2192 Migrate).";
|
|
3967
|
+
var BLOCKED_LINE = "Not showing yet \u2014 your code's own test still runs here. Versions written for this part of the page are approved but no visitor sees them until it is migrated (Components \u2192 this component \u2192 Migrate) \u2014 Sentient does it by itself once that test has shown nobody a version for 14 days.";
|
|
3968
3968
|
var NOT_DECLARED_LINE = "not declared yet \u2014 your site has not told us anyone is this persona in 14 days, so nobody sees versions written for them until your code sends it (the persona prop, init({ persona }) or window.sentient.persona)";
|
|
3969
3969
|
var cellOutput = import_v325.z.object({
|
|
3970
3970
|
slotId: import_v325.z.string(),
|
|
@@ -4807,7 +4807,13 @@ var ACTIONS = {
|
|
|
4807
4807
|
save_insight: a("POST", "structured-insights/:insightId/save", { body: "opt" }),
|
|
4808
4808
|
// Who counts as already past the main goal (spec 2026-11-17).
|
|
4809
4809
|
set_gate_settings: a("PUT", "gate-settings", { body: "req" }),
|
|
4810
|
-
import_known_people: a("POST", "known-people/import", { body: "req" })
|
|
4810
|
+
import_known_people: a("POST", "known-people/import", { body: "req" }),
|
|
4811
|
+
// Internal traffic (2026-11-19): read-only until now, but the API already
|
|
4812
|
+
// let agents change it under the Project settings switch — the MCP was
|
|
4813
|
+
// the only thing in the way of "keep our staging site out of the numbers".
|
|
4814
|
+
set_internal_sites: a("PUT", "internal-traffic/origins", { body: "req" }),
|
|
4815
|
+
add_internal_email: a("POST", "internal-traffic/emails", { body: "req" }),
|
|
4816
|
+
remove_internal_email: a("DELETE", "internal-traffic/emails", { body: "req" })
|
|
4811
4817
|
}
|
|
4812
4818
|
};
|
|
4813
4819
|
var REFUSAL_NOTE = " If this project has turned off agent access for this area, the call is refused with a sentence saying so \u2014 tell the user, don't retry.";
|
|
@@ -4840,7 +4846,7 @@ var TOOLS = {
|
|
|
4840
4846
|
manage_settings: {
|
|
4841
4847
|
title: "Manage project settings",
|
|
4842
4848
|
destructive: true,
|
|
4843
|
-
description:
|
|
4849
|
+
description: 'Change project settings: rename or edit the project, remove an allowed origin, add, remove or test a webhook, remove a captured style, rescan the site, set page meaning, create, refresh or remove a report share link, set previews and the layout and slot models, send a test event, and accept, dismiss or save a structured insight. Also who counts as already converted: set_gate_settings (body { identifiedIsConverted: boolean } \u2014 true only when reaching the main goal is what creates the account, i.e. the main goal is sign-up; not available on stores) and import_known_people (body { people: [{ userId, convertedAt?, converted?, orderCount?, totalSpent?, currency?, lastOrderAt?, customerSince?, tags? }] }, at most 2000 per call \u2014 the site\'s own user ids for people who already reached the main goal; never names, emails, phone numbers or addresses, which are refused). Who counts as your team or a test site (Settings \u2192 Internal traffic; read the rules first with get_internal_traffic_rules): set_internal_sites (body { origins: [...] } \u2014 the WHOLE list of internal sites, each one already an allowed origin; an origin left out stops being internal), add_internal_email (body { value } \u2014 a team email domain such as "@acme.com", or one exact address, which is stored only as a hash) and remove_internal_email (body { domain } or { hash } from get_internal_traffic_rules). Internal visits still see versions but never count or teach the optimizer, from the moment a rule is on; earlier visits are separated where the rule can tell. Confirm the list with the user first. Removals cannot be undone. The three insight actions (accept_insight, dismiss_insight, save_insight) are always allowed: the Project settings switch does not govern them. Pick one `action`; pass the ids it needs.' + REFUSAL_NOTE
|
|
4844
4850
|
}
|
|
4845
4851
|
};
|
|
4846
4852
|
var pathParams = (route) => [...route.matchAll(/:([A-Za-z]+)/g)].map((m) => m[1]);
|
|
@@ -4915,7 +4921,7 @@ Audiences, and what makes each one serve (precedence: declared > retargeting > d
|
|
|
4915
4921
|
- get_persona_breakdown personas counts the audience each visit was actually served as (the same number as the Matrix share in get_cell_matrix). Its behaviourGroups ("Behaviour group N") are visitors who behaved alike: not personas or audiences, they serve nothing \u2014 never report one as an audience's visitors.
|
|
4916
4922
|
- A version's name, or a code variants key, never targets an audience. To give one audience one version, pin it (manage_approvals pin); pinned visitors stop teaching the optimizer for that component.
|
|
4917
4923
|
|
|
4918
|
-
Components: an <Adaptive> with children and variants whose id already ran a variants test keeps serving that old test; dashboard-written or generated versions for it do not serve until it is migrated (dashboard Components -> Migrate..., or manage_tests migrate_component).
|
|
4924
|
+
Components: an <Adaptive> with children and variants whose id already ran a variants test keeps serving that old test; dashboard-written or generated versions for it do not serve until it is migrated (dashboard Components -> Migrate..., or manage_tests migrate_component). Sentient migrates it by itself once the code's test has assigned nobody a version for 14 days.
|
|
4919
4925
|
|
|
4920
4926
|
Funnels: every step must have something that sends it (a page-visit rule, a click or form goal, useGoal in the browser, or trackServerGoal from the server), or that step never fills.
|
|
4921
4927
|
|
|
@@ -4924,7 +4930,7 @@ Server goal, exact shape (server only, never the browser):
|
|
|
4924
4930
|
await trackServerGoal({ serverKey: process.env.SENTIENT_SECRET_KEY!, userId: user.id, name: 'subscribed', dedupeKey: user.id });
|
|
4925
4931
|
userId must be the id the site identifies the visitor with (<AdaptiveRoot userId={user.id}>); in the visitor's own request pass sessionId: readSessionCookie(cookies, publicKey) instead.
|
|
4926
4932
|
|
|
4927
|
-
Excluding the team and test sites (dashboard Settings -> Internal traffic): visits marked internal still see versions (QA works) but never count in any report and never teach the optimizer; get_traffic_breakdown lists them as "Your team / test sites". They are marked by internal sites (allowed domains such as staging or localhost), team emails and domains (they match visitors the site identifies with identify(userId, { email }); the SDK sends only a SHA-256 of the address and its domain, never the address), a browser link, or the code flag (the internal prop on <AdaptiveRoot>/<AdaptiveProvider>, init({ internal }), window.sentient.internal). There is no report filter or IP rule, and visits from before a rule was turned on cannot be separated. Read the rules with get_internal_traffic_rules;
|
|
4933
|
+
Excluding the team and test sites (dashboard Settings -> Internal traffic): visits marked internal still see versions (QA works) but never count in any report and never teach the optimizer; get_traffic_breakdown lists them as "Your team / test sites". They are marked by internal sites (allowed domains such as staging or localhost), team emails and domains (they match visitors the site identifies with identify(userId, { email }); the SDK sends only a SHA-256 of the address and its domain, never the address), a browser link, or the code flag (the internal prop on <AdaptiveRoot>/<AdaptiveProvider>, init({ internal }), window.sentient.internal). There is no report filter or IP rule, and visits from before a rule was turned on cannot be separated. Read the rules with get_internal_traffic_rules; change them with manage_settings set_internal_sites / add_internal_email / remove_internal_email (Agent access: Project settings), after confirming the list with the user.
|
|
4928
4934
|
|
|
4929
4935
|
The main funnel (get_main_funnel): "how is my funnel doing" is answered by the one journey that ends at the project's main goal \u2014 Arrived, the marketer's own steps, the main goal \u2014 counted in people, with those who had already converted left out. It is chosen with manage_goals set_main_funnel and must end at the main goal; with none chosen it is just Arrived -> main goal. Stores get their checkout journey as the main funnel on connect. Use get_funnel_report only for a side journey: it counts one funnel's goals inside a window and includes people who had already converted, so its numbers and the main funnel's do not add up.
|
|
4930
4936
|
|
|
@@ -4935,7 +4941,7 @@ Known people (get_known_people): a person is "known" once they have reached the
|
|
|
4935
4941
|
Write tools change what real visitors see: confirm with the user first. Call get_agent_access before a manage_* write.`;
|
|
4936
4942
|
|
|
4937
4943
|
// src/server.ts
|
|
4938
|
-
var PKG_VERSION = true ? "0.
|
|
4944
|
+
var PKG_VERSION = true ? "0.29.1" : "0.0.0-dev";
|
|
4939
4945
|
function createMcpServer(client) {
|
|
4940
4946
|
const server = new import_mcp.McpServer(
|
|
4941
4947
|
{
|
package/dist/index.js
CHANGED
package/dist/lib.cjs
CHANGED
|
@@ -2102,7 +2102,7 @@ function registerPageElementTools(server, client) {
|
|
|
2102
2102
|
"get_page_elements",
|
|
2103
2103
|
{
|
|
2104
2104
|
title: "Page elements Sentient found on your site",
|
|
2105
|
-
description: "The buttons, headlines, forms and other elements the latest site check found, each with an `id`, what kind it is, its label, its current text and the page it is on. Use an `id` as `targetId` for manage_generation open_pr, which writes the change into your site's code and sends it to your developers as a pull request (the project needs a connected GitHub repo first \u2014 that one step is done in the dashboard, because GitHub asks the repo owner to approve the app). open_pr body: { targetId, label, goalId, arms: [{ displayName, ops }] } with 2\u20134 arms, the first being the element as it is now (ops {}). ops may set: text (plain text), hidden (boolean), href and imageSrc (https URLs), imageAlt, and style with these properties only: color, background, fontSize, fontWeight, textAlign, padding, margin, borderRadius, width, height, maxWidth, border, boxShadow, opacity, lineHeight, letterSpacing, textTransform, gap, fontFamily. Pass `pageUrl` to keep one page. When the site has not been checked yet, ask for a check with manage_settings rescan_site; results land in a few minutes." + UNTRUSTED_FIELDS_NOTE,
|
|
2105
|
+
description: "The buttons, headlines, forms and other elements the latest site check found, each with an `id`, what kind it is, its label, its current text and the page it is on. Use an `id` as `targetId` for manage_generation open_pr, which writes the change into your site's code and sends it to your developers as a pull request (the project needs a connected GitHub repo first \u2014 that one step is done in the dashboard, Settings \u2192 GitHub, because GitHub asks the repo owner to approve the app). An element with no text (a whole form, an image with no id) cannot be found in the code and is refused for open_pr \u2014 offer the no-code path for it. open_pr body: { targetId, label, goalId, arms: [{ displayName, ops }] } with 2\u20134 arms, the first being the element as it is now (ops {}). ops may set: text (plain text), hidden (boolean), href and imageSrc (https URLs), imageAlt, and style with these properties only: color, background, fontSize, fontWeight, textAlign, padding, margin, borderRadius, width, height, maxWidth, border, boxShadow, opacity, lineHeight, letterSpacing, textTransform, gap, fontFamily. Pass `pageUrl` to keep one page. When the site has not been checked yet, ask for a check with manage_settings rescan_site; results land in a few minutes." + UNTRUSTED_FIELDS_NOTE,
|
|
2106
2106
|
inputSchema: {
|
|
2107
2107
|
projectId: projectIdSchema,
|
|
2108
2108
|
pageUrl: import_v312.z.string().max(500).optional().describe("Only elements on this page (a path like /pricing, or a full URL)")
|
|
@@ -3913,7 +3913,7 @@ function registerInternalTrafficTools(server, client) {
|
|
|
3913
3913
|
"get_internal_traffic_rules",
|
|
3914
3914
|
{
|
|
3915
3915
|
title: "Internal traffic rules",
|
|
3916
|
-
description: `Read how this project keeps its own team and test sites out of its numbers (dashboard Settings \u2192 Internal traffic): which allowed domains are internal sites, the team email domains and masked exact emails, whether a "mark this browser" link exists, and how many sessions each way marked internal in the last 7 days. Internal visits still see versions (QA works) but never count in any report or teach the optimizer; get_traffic_breakdown lists them as "${INTERNAL_TRAFFIC_LABEL}". Exact emails are stored only as a hash \u2014 this tool returns the masked form, never an address or the hash. Rules apply from when they are turned on
|
|
3916
|
+
description: `Read how this project keeps its own team and test sites out of its numbers (dashboard Settings \u2192 Internal traffic): which allowed domains are internal sites, the team email domains and masked exact emails, whether a "mark this browser" link exists, and how many sessions each way marked internal in the last 7 days. Internal visits still see versions (QA works) but never count in any report or teach the optimizer; get_traffic_breakdown lists them as "${INTERNAL_TRAFFIC_LABEL}". Exact emails are stored only as a hash \u2014 this tool returns the masked form, never an address or the hash. Rules apply from when they are turned on. To change them: manage_settings set_internal_sites, add_internal_email, remove_internal_email.`,
|
|
3917
3917
|
inputSchema: { projectId: projectIdSchema },
|
|
3918
3918
|
outputSchema: {
|
|
3919
3919
|
internalOrigins: import_v324.z.array(import_v324.z.string()).describe("Allowed domains whose every visit is marked internal"),
|
|
@@ -3988,9 +3988,9 @@ var personaOutput = import_v325.z.object({
|
|
|
3988
3988
|
)
|
|
3989
3989
|
});
|
|
3990
3990
|
var blockedOutput = import_v325.z.enum(["variant_history"]).nullable().optional().describe(
|
|
3991
|
-
"variant_history: the component's code still runs its own variants test, so versions written here are approved but NOT showing until it is migrated (dashboard Components \u2192 Migrate). Null when the column can serve."
|
|
3991
|
+
"variant_history: the component's code still runs its own variants test, so versions written here are approved but NOT showing until it is migrated (dashboard Components \u2192 Migrate; automatic once that test has assigned nobody a version for 14 days). Null when the column can serve."
|
|
3992
3992
|
);
|
|
3993
|
-
var BLOCKED_LINE = "Not showing yet \u2014 your code's own test still runs here. Versions written for this part of the page are approved but no visitor sees them until it is migrated (Components \u2192 this component \u2192 Migrate).";
|
|
3993
|
+
var BLOCKED_LINE = "Not showing yet \u2014 your code's own test still runs here. Versions written for this part of the page are approved but no visitor sees them until it is migrated (Components \u2192 this component \u2192 Migrate) \u2014 Sentient does it by itself once that test has shown nobody a version for 14 days.";
|
|
3994
3994
|
var NOT_DECLARED_LINE = "not declared yet \u2014 your site has not told us anyone is this persona in 14 days, so nobody sees versions written for them until your code sends it (the persona prop, init({ persona }) or window.sentient.persona)";
|
|
3995
3995
|
var cellOutput = import_v325.z.object({
|
|
3996
3996
|
slotId: import_v325.z.string(),
|
|
@@ -4833,7 +4833,13 @@ var ACTIONS = {
|
|
|
4833
4833
|
save_insight: a("POST", "structured-insights/:insightId/save", { body: "opt" }),
|
|
4834
4834
|
// Who counts as already past the main goal (spec 2026-11-17).
|
|
4835
4835
|
set_gate_settings: a("PUT", "gate-settings", { body: "req" }),
|
|
4836
|
-
import_known_people: a("POST", "known-people/import", { body: "req" })
|
|
4836
|
+
import_known_people: a("POST", "known-people/import", { body: "req" }),
|
|
4837
|
+
// Internal traffic (2026-11-19): read-only until now, but the API already
|
|
4838
|
+
// let agents change it under the Project settings switch — the MCP was
|
|
4839
|
+
// the only thing in the way of "keep our staging site out of the numbers".
|
|
4840
|
+
set_internal_sites: a("PUT", "internal-traffic/origins", { body: "req" }),
|
|
4841
|
+
add_internal_email: a("POST", "internal-traffic/emails", { body: "req" }),
|
|
4842
|
+
remove_internal_email: a("DELETE", "internal-traffic/emails", { body: "req" })
|
|
4837
4843
|
}
|
|
4838
4844
|
};
|
|
4839
4845
|
var REFUSAL_NOTE = " If this project has turned off agent access for this area, the call is refused with a sentence saying so \u2014 tell the user, don't retry.";
|
|
@@ -4866,7 +4872,7 @@ var TOOLS = {
|
|
|
4866
4872
|
manage_settings: {
|
|
4867
4873
|
title: "Manage project settings",
|
|
4868
4874
|
destructive: true,
|
|
4869
|
-
description:
|
|
4875
|
+
description: 'Change project settings: rename or edit the project, remove an allowed origin, add, remove or test a webhook, remove a captured style, rescan the site, set page meaning, create, refresh or remove a report share link, set previews and the layout and slot models, send a test event, and accept, dismiss or save a structured insight. Also who counts as already converted: set_gate_settings (body { identifiedIsConverted: boolean } \u2014 true only when reaching the main goal is what creates the account, i.e. the main goal is sign-up; not available on stores) and import_known_people (body { people: [{ userId, convertedAt?, converted?, orderCount?, totalSpent?, currency?, lastOrderAt?, customerSince?, tags? }] }, at most 2000 per call \u2014 the site\'s own user ids for people who already reached the main goal; never names, emails, phone numbers or addresses, which are refused). Who counts as your team or a test site (Settings \u2192 Internal traffic; read the rules first with get_internal_traffic_rules): set_internal_sites (body { origins: [...] } \u2014 the WHOLE list of internal sites, each one already an allowed origin; an origin left out stops being internal), add_internal_email (body { value } \u2014 a team email domain such as "@acme.com", or one exact address, which is stored only as a hash) and remove_internal_email (body { domain } or { hash } from get_internal_traffic_rules). Internal visits still see versions but never count or teach the optimizer, from the moment a rule is on; earlier visits are separated where the rule can tell. Confirm the list with the user first. Removals cannot be undone. The three insight actions (accept_insight, dismiss_insight, save_insight) are always allowed: the Project settings switch does not govern them. Pick one `action`; pass the ids it needs.' + REFUSAL_NOTE
|
|
4870
4876
|
}
|
|
4871
4877
|
};
|
|
4872
4878
|
var pathParams = (route) => [...route.matchAll(/:([A-Za-z]+)/g)].map((m) => m[1]);
|
|
@@ -4941,7 +4947,7 @@ Audiences, and what makes each one serve (precedence: declared > retargeting > d
|
|
|
4941
4947
|
- get_persona_breakdown personas counts the audience each visit was actually served as (the same number as the Matrix share in get_cell_matrix). Its behaviourGroups ("Behaviour group N") are visitors who behaved alike: not personas or audiences, they serve nothing \u2014 never report one as an audience's visitors.
|
|
4942
4948
|
- A version's name, or a code variants key, never targets an audience. To give one audience one version, pin it (manage_approvals pin); pinned visitors stop teaching the optimizer for that component.
|
|
4943
4949
|
|
|
4944
|
-
Components: an <Adaptive> with children and variants whose id already ran a variants test keeps serving that old test; dashboard-written or generated versions for it do not serve until it is migrated (dashboard Components -> Migrate..., or manage_tests migrate_component).
|
|
4950
|
+
Components: an <Adaptive> with children and variants whose id already ran a variants test keeps serving that old test; dashboard-written or generated versions for it do not serve until it is migrated (dashboard Components -> Migrate..., or manage_tests migrate_component). Sentient migrates it by itself once the code's test has assigned nobody a version for 14 days.
|
|
4945
4951
|
|
|
4946
4952
|
Funnels: every step must have something that sends it (a page-visit rule, a click or form goal, useGoal in the browser, or trackServerGoal from the server), or that step never fills.
|
|
4947
4953
|
|
|
@@ -4950,7 +4956,7 @@ Server goal, exact shape (server only, never the browser):
|
|
|
4950
4956
|
await trackServerGoal({ serverKey: process.env.SENTIENT_SECRET_KEY!, userId: user.id, name: 'subscribed', dedupeKey: user.id });
|
|
4951
4957
|
userId must be the id the site identifies the visitor with (<AdaptiveRoot userId={user.id}>); in the visitor's own request pass sessionId: readSessionCookie(cookies, publicKey) instead.
|
|
4952
4958
|
|
|
4953
|
-
Excluding the team and test sites (dashboard Settings -> Internal traffic): visits marked internal still see versions (QA works) but never count in any report and never teach the optimizer; get_traffic_breakdown lists them as "Your team / test sites". They are marked by internal sites (allowed domains such as staging or localhost), team emails and domains (they match visitors the site identifies with identify(userId, { email }); the SDK sends only a SHA-256 of the address and its domain, never the address), a browser link, or the code flag (the internal prop on <AdaptiveRoot>/<AdaptiveProvider>, init({ internal }), window.sentient.internal). There is no report filter or IP rule, and visits from before a rule was turned on cannot be separated. Read the rules with get_internal_traffic_rules;
|
|
4959
|
+
Excluding the team and test sites (dashboard Settings -> Internal traffic): visits marked internal still see versions (QA works) but never count in any report and never teach the optimizer; get_traffic_breakdown lists them as "Your team / test sites". They are marked by internal sites (allowed domains such as staging or localhost), team emails and domains (they match visitors the site identifies with identify(userId, { email }); the SDK sends only a SHA-256 of the address and its domain, never the address), a browser link, or the code flag (the internal prop on <AdaptiveRoot>/<AdaptiveProvider>, init({ internal }), window.sentient.internal). There is no report filter or IP rule, and visits from before a rule was turned on cannot be separated. Read the rules with get_internal_traffic_rules; change them with manage_settings set_internal_sites / add_internal_email / remove_internal_email (Agent access: Project settings), after confirming the list with the user.
|
|
4954
4960
|
|
|
4955
4961
|
The main funnel (get_main_funnel): "how is my funnel doing" is answered by the one journey that ends at the project's main goal \u2014 Arrived, the marketer's own steps, the main goal \u2014 counted in people, with those who had already converted left out. It is chosen with manage_goals set_main_funnel and must end at the main goal; with none chosen it is just Arrived -> main goal. Stores get their checkout journey as the main funnel on connect. Use get_funnel_report only for a side journey: it counts one funnel's goals inside a window and includes people who had already converted, so its numbers and the main funnel's do not add up.
|
|
4956
4962
|
|
|
@@ -4961,7 +4967,7 @@ Known people (get_known_people): a person is "known" once they have reached the
|
|
|
4961
4967
|
Write tools change what real visitors see: confirm with the user first. Call get_agent_access before a manage_* write.`;
|
|
4962
4968
|
|
|
4963
4969
|
// src/server.ts
|
|
4964
|
-
var PKG_VERSION = true ? "0.
|
|
4970
|
+
var PKG_VERSION = true ? "0.29.1" : "0.0.0-dev";
|
|
4965
4971
|
function createMcpServer(client) {
|
|
4966
4972
|
const server = new import_mcp.McpServer(
|
|
4967
4973
|
{
|
package/dist/lib.js
CHANGED