@sentientui/mcp 0.24.2 → 0.25.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 +3 -2
- package/README.md +3 -2
- package/dist/{chunk-HLKZFTEV.js → chunk-QF2U745P.js} +268 -125
- package/dist/index.cjs +268 -125
- package/dist/index.js +1 -1
- package/dist/lib.cjs +270 -126
- package/dist/lib.js +3 -2
- package/package.json +1 -1
package/dist/index.cjs
CHANGED
|
@@ -405,12 +405,17 @@ function registerProjectTools(server, client) {
|
|
|
405
405
|
"get_project_stats",
|
|
406
406
|
{
|
|
407
407
|
title: "Project health stats",
|
|
408
|
-
description: "Get ingestion health for a project: status, events
|
|
408
|
+
description: "Get ingestion health for a project: status, events in the last 24 hours, the People count for the same window (visitors who ran the page, interacted and passed the bot check), how many visitors are still being analysed, how many are automated, the time of the last event, and the all-time count of calls to the SentientUI agent API (/v1/agent) \u2014 NOT MCP tool calls.",
|
|
409
409
|
inputSchema: { projectId: projectIdSchema },
|
|
410
410
|
outputSchema: {
|
|
411
411
|
status: import_v32.z.string().describe("Overall project health status"),
|
|
412
412
|
events24h: import_v32.z.number().describe("Events in the last 24 hours"),
|
|
413
|
-
|
|
413
|
+
// This field used to be raw sessions; it now carries People, so the old
|
|
414
|
+
// description told an agent bots and unverified visitors were in it.
|
|
415
|
+
sessions24h: import_v32.z.number().describe("Deprecated alias of people on a current API; the raw session count on an older one"),
|
|
416
|
+
people: import_v32.z.number().nullable().describe("People in the last 24 hours: visitors who ran the page, interacted and passed the bot check; null when the API predates the traffic classification"),
|
|
417
|
+
beingAnalysed: import_v32.z.number().nullable().describe("Visitors still being analysed \u2014 usually settled within 3 hours; null on an older API"),
|
|
418
|
+
automated: import_v32.z.number().nullable().describe("Automated visitors: AI assistants, search & AI crawlers and other automated; null on an older API"),
|
|
414
419
|
// Was "Total agent (MCP/API) calls" — but the count comes from
|
|
415
420
|
// agent_events, which only the /v1/agent endpoint writes. MCP tool calls
|
|
416
421
|
// are never in it, so an agent read its own activity as missing.
|
|
@@ -424,22 +429,30 @@ function registerProjectTools(server, client) {
|
|
|
424
429
|
}
|
|
425
430
|
},
|
|
426
431
|
withApiErrorGuidance(async ({ projectId }) => {
|
|
427
|
-
var _a2;
|
|
432
|
+
var _a2, _b, _c, _d, _e, _f, _g;
|
|
428
433
|
const id = encodeURIComponent(projectId);
|
|
429
434
|
const stats = await client.get(`/projects/${id}/health`);
|
|
435
|
+
const peopleCount = (_b = stats.people) != null ? _b : (_a2 = stats.traffic) == null ? void 0 : _a2.people;
|
|
436
|
+
const classified = peopleCount !== void 0;
|
|
437
|
+
const people = classified ? peopleCount : null;
|
|
438
|
+
const beingAnalysed = classified ? (_d = (_c = stats.traffic) == null ? void 0 : _c.beingAnalysed) != null ? _d : 0 : null;
|
|
439
|
+
const automated = classified ? (_f = (_e = stats.traffic) == null ? void 0 : _e.automated) != null ? _f : 0 : null;
|
|
430
440
|
const text = [
|
|
431
441
|
`Status: ${stats.status}`,
|
|
432
442
|
`Events (24h): ${stats.events24h}`,
|
|
433
|
-
`Sessions (24h): ${stats.sessions24h}
|
|
443
|
+
...classified ? [`People (24h): ${people}`, `Being analysed: ${beingAnalysed}`, `Automated: ${automated}`] : [`Sessions (24h): ${stats.sessions24h}`],
|
|
434
444
|
`Agent API calls (/v1/agent, all-time): ${stats.agentCalls}`,
|
|
435
|
-
`Last event: ${(
|
|
445
|
+
`Last event: ${(_g = stats.lastEventAt) != null ? _g : "never"}`
|
|
436
446
|
].join("\n");
|
|
437
447
|
return {
|
|
438
448
|
content: [{ type: "text", text }],
|
|
439
449
|
structuredContent: {
|
|
440
450
|
status: stats.status,
|
|
441
451
|
events24h: stats.events24h,
|
|
442
|
-
sessions24h: stats.sessions24h,
|
|
452
|
+
sessions24h: people != null ? people : stats.sessions24h,
|
|
453
|
+
people,
|
|
454
|
+
beingAnalysed,
|
|
455
|
+
automated,
|
|
443
456
|
agentCalls: stats.agentCalls,
|
|
444
457
|
lastEventAt: stats.lastEventAt
|
|
445
458
|
}
|
|
@@ -799,7 +812,7 @@ function registerComponentTools(server, client) {
|
|
|
799
812
|
"list_components",
|
|
800
813
|
{
|
|
801
814
|
title: "List components",
|
|
802
|
-
description: "List all adaptive components in a project with variant counts and impression totals. Counts cover all retained data by default; pass range or from/to for a window." + UNTRUSTED_FIELDS_NOTE,
|
|
815
|
+
description: "List all adaptive components in a project with variant counts and impression totals. Counts cover all retained data by default; pass range or from/to for a window. Impressions and conversions are People's; unconfirmedConversions is the API's count from visitors we couldn't confirm as people (not included in conversions)." + UNTRUSTED_FIELDS_NOTE,
|
|
803
816
|
inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("all")),
|
|
804
817
|
outputSchema: {
|
|
805
818
|
components: import_v33.z.array(
|
|
@@ -807,7 +820,8 @@ function registerComponentTools(server, client) {
|
|
|
807
820
|
componentId: import_v33.z.string(),
|
|
808
821
|
variantCount: import_v33.z.number(),
|
|
809
822
|
impressions: import_v33.z.number(),
|
|
810
|
-
conversions: import_v33.z.number()
|
|
823
|
+
conversions: import_v33.z.number(),
|
|
824
|
+
unconfirmedConversions: import_v33.z.number().nullable().describe("Conversions from visitors we couldn't confirm as people (not in conversions); null on an older API")
|
|
811
825
|
})
|
|
812
826
|
).describe("Adaptive components in the project (empty if none)"),
|
|
813
827
|
total: import_v33.z.number().describe("Total components in the project \u2014 larger than the list when truncated"),
|
|
@@ -823,12 +837,16 @@ function registerComponentTools(server, client) {
|
|
|
823
837
|
withApiErrorGuidance(async ({ projectId, range, from, to }) => {
|
|
824
838
|
const { components, total, window, truncated } = await fetchAllComponents(client, projectId, { rangeArgs: { range, from, to } });
|
|
825
839
|
const structuredContent = {
|
|
826
|
-
components: components.map((c) =>
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
840
|
+
components: components.map((c) => {
|
|
841
|
+
var _a2;
|
|
842
|
+
return {
|
|
843
|
+
componentId: c.component_id,
|
|
844
|
+
variantCount: c.variants.length,
|
|
845
|
+
impressions: c.total_impressions,
|
|
846
|
+
conversions: c.total_conversions,
|
|
847
|
+
unconfirmedConversions: (_a2 = c.total_unconfirmed_conversions) != null ? _a2 : null
|
|
848
|
+
};
|
|
849
|
+
}),
|
|
832
850
|
total,
|
|
833
851
|
truncated,
|
|
834
852
|
window
|
|
@@ -840,7 +858,7 @@ function registerComponentTools(server, client) {
|
|
|
840
858
|
};
|
|
841
859
|
}
|
|
842
860
|
const lines = components.map(
|
|
843
|
-
(c) => `- ${untrusted(c.component_id)}: ${c.variants.length} variants, ${c.total_impressions} impressions, ${c.total_conversions} conversions`
|
|
861
|
+
(c) => `- ${untrusted(c.component_id)}: ${c.variants.length} variants, ${c.total_impressions} impressions, ${c.total_conversions} conversions` + (c.total_unconfirmed_conversions ? ` (+${c.total_unconfirmed_conversions} conversions from visitors we couldn't confirm as people)` : "")
|
|
844
862
|
);
|
|
845
863
|
if (truncated) {
|
|
846
864
|
lines.push(`Showing ${components.length} of ${total} components \u2014 fetch cap reached; the rest exist but are not listed here.`);
|
|
@@ -852,7 +870,7 @@ function registerComponentTools(server, client) {
|
|
|
852
870
|
"get_variant_performance",
|
|
853
871
|
{
|
|
854
872
|
title: "Variant performance",
|
|
855
|
-
description: "Per-variant conversion over the selected window (default: last 7 calendar days), keyed by component AND variant, each rate with its sample (converting sessions / exposed sessions). Each non-baseline variant carries the server's evidence verdict against its component's baseline arm (100-visit floor on both arms, multiple-comparison-corrected bars): `verdict` judges the windowed rate this row prints when the server sends window evidence (`verdictBasis` = window), and falls back to the all-time verdict on older APIs (`verdictBasis` = all_time). The all-time verdict is also reported separately as reliability (`evidenceState`, `reliabilityVerdict`). Only ahead/behind is a comparative result; raw rates are not a ranking. The change vs the preceding window is an untested descriptor." + UNTRUSTED_FIELDS_NOTE,
|
|
873
|
+
description: "Per-variant conversion over the selected window (default: last 7 calendar days), as conversion rate among People (exposed and converting sessions are People's; conversions from visitors we couldn't confirm as people are reported beside them as unconfirmedConversions, never in the rate), keyed by component AND variant, each rate with its sample (converting sessions / exposed sessions). Each non-baseline variant carries the server's evidence verdict against its component's baseline arm (100-visit floor on both arms, multiple-comparison-corrected bars): `verdict` judges the windowed rate this row prints when the server sends window evidence (`verdictBasis` = window), and falls back to the all-time verdict on older APIs (`verdictBasis` = all_time). The all-time verdict is also reported separately as reliability (`evidenceState`, `reliabilityVerdict`) \u2014 that all-time reliability is the optimizer's own evidence, not a People-only figure. Only ahead/behind is a comparative result; raw rates are not a ranking. The change vs the preceding window is an untested descriptor." + UNTRUSTED_FIELDS_NOTE,
|
|
856
874
|
inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("7d")),
|
|
857
875
|
_meta: uiMeta("variant-performance"),
|
|
858
876
|
outputSchema: {
|
|
@@ -863,7 +881,8 @@ function registerComponentTools(server, client) {
|
|
|
863
881
|
isBaseline: import_v33.z.boolean().describe("The arm the server measures the others against"),
|
|
864
882
|
baselineExplicit: import_v33.z.boolean().describe("False when no arm is named 'control' and the baseline is just the alphabetically-first id"),
|
|
865
883
|
sessions: import_v33.z.number().describe("Exposed sessions in the window (the n of currentCvr)"),
|
|
866
|
-
conversions: import_v33.z.number().describe("Converting sessions in the window"),
|
|
884
|
+
conversions: import_v33.z.number().describe("Converting People (sessions) in the window"),
|
|
885
|
+
unconfirmedConversions: import_v33.z.number().nullable().describe("Converting sessions from visitors we couldn't confirm as people (the API's own remainder; not in conversions or currentCvr); null on an older API"),
|
|
867
886
|
currentCvr: import_v33.z.number().nullable().describe("conversions / sessions over the window (0-1); null at 0 sessions"),
|
|
868
887
|
lowSample: import_v33.z.boolean().describe(`True under ${MIN_EVIDENCE_SAMPLE} sessions \u2014 the rate is not interpretable on its own`),
|
|
869
888
|
evidenceState: import_v33.z.string().nullable().describe("Reliability (all time): the server's ALL-TIME evidence state vs the baseline on direct evidence \u2014 not_enough_data | early_signal | moderate_evidence | strong_evidence | likely_worse | inconclusive; null for the baseline or when not provided. Not a verdict on the windowed rate"),
|
|
@@ -890,7 +909,7 @@ function registerComponentTools(server, client) {
|
|
|
890
909
|
}
|
|
891
910
|
},
|
|
892
911
|
withApiErrorGuidance(async ({ projectId, range, from, to }) => {
|
|
893
|
-
var _a2, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k;
|
|
912
|
+
var _a2, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
|
|
894
913
|
const id = encodeURIComponent(projectId);
|
|
895
914
|
const [componentsRes, trendsRes] = await Promise.all([
|
|
896
915
|
settled(fetchAllComponents(client, projectId, { rangeArgs: { range, from, to } })),
|
|
@@ -971,13 +990,14 @@ function registerComponentTools(server, client) {
|
|
|
971
990
|
baselineExplicit: (_i = baseline == null ? void 0 : baseline.explicit) != null ? _i : false,
|
|
972
991
|
sessions: n,
|
|
973
992
|
conversions: conv,
|
|
993
|
+
unconfirmedConversions: (_j = v.unconfirmed_conversions) != null ? _j : null,
|
|
974
994
|
currentCvr: n > 0 ? conv / n : null,
|
|
975
995
|
lowSample: isLowSample(n),
|
|
976
996
|
evidenceState: state,
|
|
977
|
-
probBeatsBaseline: (
|
|
997
|
+
probBeatsBaseline: (_k = stats == null ? void 0 : stats.probBeatsControl) != null ? _k : null,
|
|
978
998
|
reliabilityVerdict,
|
|
979
999
|
windowEvidenceState: wState,
|
|
980
|
-
windowProbBeatsBaseline: (
|
|
1000
|
+
windowProbBeatsBaseline: (_l = wStats == null ? void 0 : wStats.probBeatsControl) != null ? _l : null,
|
|
981
1001
|
verdict,
|
|
982
1002
|
verdictBasis,
|
|
983
1003
|
priorCvr,
|
|
@@ -1007,6 +1027,7 @@ function registerComponentTools(server, client) {
|
|
|
1007
1027
|
`vs preceding window: ${(priorCvr * 100).toFixed(2)}%${pn}, ${deltaPp > 0 ? "+" : ""}${deltaPp.toFixed(1)} pp${momentum ? `, ${momentum}` : ""} (untested)`
|
|
1008
1028
|
);
|
|
1009
1029
|
}
|
|
1030
|
+
if (v.unconfirmed_conversions) parts.push(`${v.unconfirmed_conversions} conversions from visitors we couldn't confirm as people`);
|
|
1010
1031
|
block.push(parts.join(" \xB7 "));
|
|
1011
1032
|
}
|
|
1012
1033
|
textBlocks.push(block.join("\n"));
|
|
@@ -1021,7 +1042,7 @@ function registerComponentTools(server, client) {
|
|
|
1021
1042
|
}
|
|
1022
1043
|
const header = [
|
|
1023
1044
|
windowLine(window),
|
|
1024
|
-
`Rates: converting ${sessionUnit} \xF7 exposed ${sessionUnit} in the window. ` + (anyAllTimeBasis ? "Evidence: the server's ALL-TIME comparison of each arm against its component's baseline (this API sends no windowed verdict) \u2014 " : "Evidence (this window): the server's comparison of each arm's windowed rate against its component's baseline; reliability (all time): the all-time verdict on direct evidence, which can differ \u2014 ") + 'only "ahead"/"behind" is a result; do not rank arms by raw rate.'
|
|
1045
|
+
`Rates: conversion rate among People \u2014 converting ${sessionUnit} \xF7 exposed ${sessionUnit} in the window. ` + (anyAllTimeBasis ? "Evidence: the server's ALL-TIME comparison of each arm against its component's baseline (this API sends no windowed verdict) \u2014 " : "Evidence (this window): the server's comparison of each arm's windowed rate against its component's baseline; reliability (all time): the all-time verdict on direct evidence, which can differ \u2014 ") + 'only "ahead"/"behind" is a result; do not rank arms by raw rate.'
|
|
1025
1046
|
].filter(Boolean);
|
|
1026
1047
|
const footer = truncated ? ["", "Fetch cap reached \u2014 some components are not listed."] : [];
|
|
1027
1048
|
const text = [...header, "", textBlocks.join("\n\n"), ...footer].join("\n");
|
|
@@ -1036,7 +1057,7 @@ var DEFAULT_LIMIT = 10;
|
|
|
1036
1057
|
var MAX_LIMIT = 50;
|
|
1037
1058
|
var EMPTY_REASON_TEXT = {
|
|
1038
1059
|
no_events: "The snippet has not fired yet \u2014 nothing has reached us.",
|
|
1039
|
-
no_traffic_yet: "
|
|
1060
|
+
no_traffic_yet: "In the last 7 days we've only seen visitors we couldn't confirm as people. New visitors are usually confirmed within 3 hours, and this report fills in as they are.",
|
|
1040
1061
|
awaiting_profiles: "Still building visitor profiles before visitors can be grouped.",
|
|
1041
1062
|
no_variants: "Nothing to compare yet \u2014 no adaptive component is running.",
|
|
1042
1063
|
nothing_moved: "Enough data, and nothing moved this period. That is a result.",
|
|
@@ -1283,12 +1304,12 @@ function registerStageTools(server, client) {
|
|
|
1283
1304
|
// Mirrors GET /projects/:id/stage-report. Says OBSERVATIONAL in the
|
|
1284
1305
|
// description because nothing serves on stage yet: an agent must not
|
|
1285
1306
|
// read a per-context arm result as "stage-based serving would win".
|
|
1286
|
-
description: `E-commerce projects: where visitors are in buying (new, browsing, carted, customer, lapsed) \u2014 share of
|
|
1307
|
+
description: `E-commerce projects: where visitors are in buying (new, browsing, carted, customer, lapsed) \u2014 share of People per stage (each session counted once, at its latest recorded stage; hinted = set by a tagged campaign, not observed history), arrival channel x stage with conversion, how visitors moved between stages from one visit to the next, the TESTED holdout lift per first-visit context and per first-visit arrival channel (the same always-valid test as the headline lift, all-time, alpha split over all 23 possible series; "collecting" and "awaiting_conversions" are early, not results), and each region's versions per context judged against the original with the per-audience evidence rule. OBSERVATIONAL: nothing is served by stage yet; the per-context results are what stage-based serving would have to beat. Defaults to the last 30 days; pass range or from/to. Counts and conversion rates are among People (visitors who ran the page, interacted and passed the bot check); the holdout lift test is the one exception: it runs on the optimizer's own population, so its visitor counts will not add up to the People figures beside it. Returns enabled:false when the project does not record stages.` + UNTRUSTED_FIELDS_NOTE,
|
|
1287
1308
|
inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("30d")),
|
|
1288
1309
|
outputSchema: {
|
|
1289
1310
|
enabled: import_v36.z.boolean().describe("False when the project does not record funnel stages (settings.stage absent)"),
|
|
1290
1311
|
mode: import_v36.z.string().nullable().describe("'record' (reporting only) \u2014 serving by stage is not available yet"),
|
|
1291
|
-
sessions: import_v36.z.number().describe("
|
|
1312
|
+
sessions: import_v36.z.number().describe("People with a recorded stage in the window"),
|
|
1292
1313
|
hinted: import_v36.z.number().describe("Of those, sessions whose stage came from a campaign tag, not observed history"),
|
|
1293
1314
|
stages: import_v36.z.array(import_v36.z.object({ stage: import_v36.z.string(), sessions: import_v36.z.number(), share: import_v36.z.number().describe("0-1"), observed: import_v36.z.number(), hinted: import_v36.z.number() })),
|
|
1294
1315
|
channels: import_v36.z.array(import_v36.z.object({ channel: import_v36.z.string(), sessions: import_v36.z.number(), conversions: import_v36.z.number(), conversionRate: import_v36.z.number().nullable() })),
|
|
@@ -1417,7 +1438,7 @@ function registerGoalTools(server, client) {
|
|
|
1417
1438
|
// stages. The title and the first words of the description now say what
|
|
1418
1439
|
// it is, and point to the real funnel tool.
|
|
1419
1440
|
title: "Goal conversions (per goal \u2014 not a step funnel)",
|
|
1420
|
-
description: "Per-goal conversion summary \u2014 NOT a step funnel (for step-by-step drop-off use list_funnels + get_funnel_report). Gets goal hit counts and unique-session conversion rates for a window (default: last 30 calendar days), plus a per-variant breakdown. NOTE: the per-variant completionRate values are ALL-TIME (bounded only by plan retention), NOT windowed \u2014 a variant completion rate needs the full assignment history as its denominator, so it does not change when you narrow `range`, and retired components keep appearing in it. Only hits/uniqueSessions/conversionRate/revenue respect the window. Per-variant rates are descriptive, not joined to the evidence verdicts \u2014 for whether an arm is ahead, use get_variant_performance." + UNTRUSTED_FIELDS_NOTE,
|
|
1441
|
+
description: "Per-goal conversion summary \u2014 NOT a step funnel (for step-by-step drop-off use list_funnels + get_funnel_report). Gets goal hit counts and unique-session conversion rates for a window (counts and the rate are People's: conversion rate among People, meaning visitors who ran the page, interacted and passed the bot check; conversions by every other visitor are reported beside them as unconfirmedHits/unconfirmedSessions/unconfirmedRevenue, 'from visitors we couldn't confirm as people', never inside the rate) (default: last 30 calendar days), plus a per-variant breakdown. NOTE: the per-variant completionRate values are ALL-TIME (bounded only by plan retention), NOT windowed \u2014 a variant completion rate needs the full assignment history as its denominator, so it does not change when you narrow `range`, and retired components keep appearing in it. Only hits/uniqueSessions/conversionRate/revenue respect the window. Per-variant rates are descriptive, not joined to the evidence verdicts \u2014 for whether an arm is ahead, use get_variant_performance." + UNTRUSTED_FIELDS_NOTE,
|
|
1421
1442
|
inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("30d")),
|
|
1422
1443
|
_meta: uiMeta("goal-funnel"),
|
|
1423
1444
|
outputSchema: {
|
|
@@ -1427,7 +1448,10 @@ function registerGoalTools(server, client) {
|
|
|
1427
1448
|
goalName: import_v37.z.string(),
|
|
1428
1449
|
hits: import_v37.z.number(),
|
|
1429
1450
|
uniqueSessions: import_v37.z.number(),
|
|
1430
|
-
conversionRate: import_v37.z.number().describe("
|
|
1451
|
+
conversionRate: import_v37.z.number().describe("Conversion rate among People (0-1): People who converted \xF7 People in the window"),
|
|
1452
|
+
unconfirmedHits: import_v37.z.number().nullable().describe("Conversions from visitors we couldn't confirm as people (the API's own remainder; not in hits or the rate); null on an older API"),
|
|
1453
|
+
unconfirmedSessions: import_v37.z.number().nullable().describe("Converting sessions from visitors we couldn't confirm as people; null on an older API"),
|
|
1454
|
+
unconfirmedRevenue: import_v37.z.number().nullable().describe("Revenue from visitors we couldn't confirm as people (revenue is everyone's total); null when none or on an older API"),
|
|
1431
1455
|
revenue: import_v37.z.number().nullable().describe("Total revenue from valued conversions, in the project currency (null for valueless goals)"),
|
|
1432
1456
|
avgOrderValue: import_v37.z.number().nullable().describe("Average value per valued conversion (null for valueless goals)"),
|
|
1433
1457
|
revenuePerSession: import_v37.z.number().nullable().describe("Revenue divided by all project sessions (null for valueless goals)"),
|
|
@@ -1463,15 +1487,18 @@ function registerGoalTools(server, client) {
|
|
|
1463
1487
|
window: data.window,
|
|
1464
1488
|
currency: (_a2 = data.currency) != null ? _a2 : "USD",
|
|
1465
1489
|
goals: data.goals.map((g) => {
|
|
1466
|
-
var _a3, _b2, _c;
|
|
1490
|
+
var _a3, _b2, _c, _d, _e, _f;
|
|
1467
1491
|
return {
|
|
1468
1492
|
goalName: g.goalName,
|
|
1469
1493
|
hits: g.hits,
|
|
1470
1494
|
uniqueSessions: g.uniqueSessions,
|
|
1471
1495
|
conversionRate: g.pct,
|
|
1472
|
-
|
|
1473
|
-
|
|
1474
|
-
|
|
1496
|
+
unconfirmedHits: (_a3 = g.unconfirmedHits) != null ? _a3 : null,
|
|
1497
|
+
unconfirmedSessions: (_b2 = g.unconfirmedSessions) != null ? _b2 : null,
|
|
1498
|
+
unconfirmedRevenue: (_c = g.unconfirmedRevenue) != null ? _c : null,
|
|
1499
|
+
revenue: (_d = g.revenue) != null ? _d : null,
|
|
1500
|
+
avgOrderValue: (_e = g.avgOrderValue) != null ? _e : null,
|
|
1501
|
+
revenuePerSession: (_f = g.revenuePerSession) != null ? _f : null,
|
|
1475
1502
|
variants: g.variants.map((v) => {
|
|
1476
1503
|
var _a4, _b3;
|
|
1477
1504
|
return {
|
|
@@ -1496,9 +1523,13 @@ function registerGoalTools(server, client) {
|
|
|
1496
1523
|
const currency = (_b = data.currency) != null ? _b : "USD";
|
|
1497
1524
|
const win = windowLine(data.window);
|
|
1498
1525
|
const lines = data.goals.flatMap((g) => {
|
|
1499
|
-
var _a3;
|
|
1526
|
+
var _a3, _b2, _c;
|
|
1500
1527
|
return [
|
|
1501
|
-
`${untrusted(g.goalName)}: ${g.hits} hits, ${g.uniqueSessions} unique sessions, ${(g.pct * 100).toFixed(1)}% conversion` + (g.revenue != null ? `, ${g.revenue.toFixed(2)} ${currency} revenue (${((_a3 = g.avgOrderValue) != null ? _a3 : 0).toFixed(2)} avg order)` : ""),
|
|
1528
|
+
`${untrusted(g.goalName)}: ${g.hits} hits, ${g.uniqueSessions} unique sessions, ${(g.pct * 100).toFixed(1)}% conversion rate among People` + (g.revenue != null ? `, ${g.revenue.toFixed(2)} ${currency} revenue (${((_a3 = g.avgOrderValue) != null ? _a3 : 0).toFixed(2)} avg order)` : ""),
|
|
1529
|
+
// The remainder is the API's own (total − People); recomputing it here
|
|
1530
|
+
// would be a third definition that could drift from the dashboard's.
|
|
1531
|
+
...g.unconfirmedHits || g.unconfirmedSessions ? [` ${(_b2 = g.unconfirmedHits) != null ? _b2 : 0} hits (${(_c = g.unconfirmedSessions) != null ? _c : 0} sessions) from visitors we couldn't confirm as people`] : [],
|
|
1532
|
+
...g.unconfirmedRevenue != null && g.unconfirmedRevenue !== 0 ? [` ${g.unconfirmedRevenue.toFixed(2)} ${currency} revenue from visitors we couldn't confirm as people`] : [],
|
|
1502
1533
|
// The per-variant rates come from an all-time query (analytics.ts
|
|
1503
1534
|
// query 2, deliberately unwindowed so the denominator is the full
|
|
1504
1535
|
// assignment history). The dashboard labels them; this text had not,
|
|
@@ -1726,7 +1757,7 @@ function registerFunnelTools(server, client) {
|
|
|
1726
1757
|
"get_funnel_report",
|
|
1727
1758
|
{
|
|
1728
1759
|
title: "Funnel drop-off report",
|
|
1729
|
-
description:
|
|
1760
|
+
description: `Per-step reach and drop-off for one funnel over its conversion window (reach and drop-off are People: visitors who ran the page, interacted and passed the bot check; others who reached a step are in unconfirmedReached, from visitors we couldn't confirm as people, never inside a drop-off), with per-variant and audience splits per step, final-step revenue (the total, every visitor's orders, with unconfirmedRevenue beside it; avg order and per-entering-visitor are People's), and the holdout ("without optimization") comparison.` + UNTRUSTED_FIELDS_NOTE,
|
|
1730
1761
|
inputSchema: { projectId: projectIdSchema, funnelId: funnelIdSchema },
|
|
1731
1762
|
outputSchema: {
|
|
1732
1763
|
funnelId: import_v38.z.string(),
|
|
@@ -1739,7 +1770,8 @@ function registerFunnelTools(server, client) {
|
|
|
1739
1770
|
stepIndex: import_v38.z.number(),
|
|
1740
1771
|
goalId: import_v38.z.string(),
|
|
1741
1772
|
displayName: import_v38.z.string(),
|
|
1742
|
-
reached: import_v38.z.number().describe("Distinct
|
|
1773
|
+
reached: import_v38.z.number().describe("Distinct People reaching this step in-window"),
|
|
1774
|
+
unconfirmedReached: import_v38.z.number().nullable().describe("Visitors we couldn't confirm as people who reached this step (the API's own remainder; not in reached or any drop-off); null on an older API"),
|
|
1743
1775
|
dropOffFromPrevious: import_v38.z.number().nullable().describe("1 - reached/previousReached (null on the first step)"),
|
|
1744
1776
|
neverFired: import_v38.z.boolean().describe("True when the step goal has never been recorded anywhere \u2014 likely a typo"),
|
|
1745
1777
|
variants: import_v38.z.array(import_v38.z.object({
|
|
@@ -1751,20 +1783,21 @@ function registerFunnelTools(server, client) {
|
|
|
1751
1783
|
personas: import_v38.z.array(import_v38.z.object({ label: import_v38.z.string(), reached: import_v38.z.number() }))
|
|
1752
1784
|
})
|
|
1753
1785
|
),
|
|
1754
|
-
revenue: import_v38.z.number().nullable().describe("Final-step revenue in the project currency (null when no valued conversions)"),
|
|
1755
|
-
|
|
1756
|
-
|
|
1786
|
+
revenue: import_v38.z.number().nullable().describe("Final-step revenue in the project currency: the total, every visitor's orders plus orders with no visit (null when no valued conversions)"),
|
|
1787
|
+
unconfirmedRevenue: import_v38.z.number().nullable().describe("The part of revenue from visitors we couldn't confirm as people (the API's own remainder); null when none or on an older API"),
|
|
1788
|
+
avgOrderValue: import_v38.z.number().nullable().describe("People's revenue per People order"),
|
|
1789
|
+
revenuePerEnteringVisitor: import_v38.z.number().nullable().describe("People's revenue per People entering the funnel"),
|
|
1757
1790
|
holdoutCompletion: import_v38.z.object({ entered: import_v38.z.number(), reached: import_v38.z.number() }).nullable().describe('Holdout visitors entering vs finishing \u2014 the "without optimization" line')
|
|
1758
1791
|
},
|
|
1759
1792
|
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
|
|
1760
1793
|
},
|
|
1761
1794
|
withApiErrorGuidance(async ({ projectId, funnelId }) => {
|
|
1762
|
-
var _a2;
|
|
1795
|
+
var _a2, _b;
|
|
1763
1796
|
const data = await client.get(`/projects/${encodeURIComponent(projectId)}/funnels/${encodeURIComponent(funnelId)}/report`);
|
|
1764
1797
|
const lines = [`${untrusted(data.displayName)} \u2014 last ${data.windowDays} days`];
|
|
1765
1798
|
for (const s of data.steps) {
|
|
1766
1799
|
lines.push(
|
|
1767
|
-
`${s.stepIndex + 1}. ${untrusted(s.displayName)}: ${s.reached} reached` + stepChangeText(s.dropOffFromPrevious) + (s.neverFired ? " [never recorded \u2014 check the goal name]" : "")
|
|
1800
|
+
`${s.stepIndex + 1}. ${untrusted(s.displayName)}: ${s.reached} People reached` + (s.unconfirmedReached ? ` (${s.unconfirmedReached} more from visitors we couldn't confirm as people)` : "") + stepChangeText(s.dropOffFromPrevious) + (s.neverFired ? " [never recorded \u2014 check the goal name]" : "")
|
|
1768
1801
|
);
|
|
1769
1802
|
for (const v of s.variants) {
|
|
1770
1803
|
lines.push(` ${untrusted(v.componentId)}/${untrusted(v.variantId)}: ${v.reached}/${v.assigned} assigned sessions reached this step`);
|
|
@@ -1772,7 +1805,9 @@ function registerFunnelTools(server, client) {
|
|
|
1772
1805
|
}
|
|
1773
1806
|
if (data.revenue != null) {
|
|
1774
1807
|
lines.push(
|
|
1775
|
-
`Revenue: ${data.revenue.toFixed(2)} ${data.currency}` +
|
|
1808
|
+
`Revenue: ${data.revenue.toFixed(2)} ${data.currency}` + // The API's remainder, verbatim: no arithmetic here, or this line
|
|
1809
|
+
// would print a figure the dashboard does not.
|
|
1810
|
+
(data.unconfirmedRevenue != null && data.unconfirmedRevenue !== 0 ? ` (${data.unconfirmedRevenue.toFixed(2)} ${data.currency} from visitors we couldn't confirm as people)` : "") + (data.avgOrderValue != null ? ` (${data.avgOrderValue.toFixed(2)} ${data.currency} avg order)` : "") + (data.revenuePerEnteringVisitor != null ? `, ${data.revenuePerEnteringVisitor.toFixed(2)} ${data.currency} per entering visitor` : "")
|
|
1776
1811
|
);
|
|
1777
1812
|
}
|
|
1778
1813
|
if (data.holdoutCompletion && data.holdoutCompletion.entered > 0) {
|
|
@@ -1781,7 +1816,14 @@ function registerFunnelTools(server, client) {
|
|
|
1781
1816
|
return {
|
|
1782
1817
|
content: [{ type: "text", text: lines.join("\n") }],
|
|
1783
1818
|
// Tolerate an API deployed before strict funnels existed.
|
|
1784
|
-
structuredContent: __spreadProps(__spreadValues({}, data), {
|
|
1819
|
+
structuredContent: __spreadProps(__spreadValues({}, data), {
|
|
1820
|
+
strictOrder: (_a2 = data.strictOrder) != null ? _a2 : true,
|
|
1821
|
+
unconfirmedRevenue: (_b = data.unconfirmedRevenue) != null ? _b : null,
|
|
1822
|
+
steps: data.steps.map((s) => {
|
|
1823
|
+
var _a3;
|
|
1824
|
+
return __spreadProps(__spreadValues({}, s), { unconfirmedReached: (_a3 = s.unconfirmedReached) != null ? _a3 : null });
|
|
1825
|
+
})
|
|
1826
|
+
})
|
|
1785
1827
|
};
|
|
1786
1828
|
})
|
|
1787
1829
|
);
|
|
@@ -2590,11 +2632,12 @@ project has its own persona vocabulary (dashboard -> Settings -> Personas), and
|
|
|
2590
2632
|
EMPTY: every visitor is 'unknown' until a persona exists, and the optimizer learns across all
|
|
2591
2633
|
traffic pooled in the meantime. Personas are DISCOVERED from behavior \u2014 or, far faster,
|
|
2592
2634
|
DECLARED by the app when it already knows the visitor's role: init({ persona: 'admin' }) /
|
|
2593
|
-
<AdaptiveProvider persona=...> / window.sentient.persona. Declared beats
|
|
2635
|
+
<AdaptiveProvider persona=...> / window.sentient.persona. Declared beats discovered and serves
|
|
2594
2636
|
at full confidence; unrecognized values are ignored server-side and surfaced in the dashboard
|
|
2595
2637
|
so the operator can add them. Keep persona a low-cardinality role slug \u2014 never a user id.
|
|
2596
|
-
Decisions are locked per
|
|
2597
|
-
|
|
2638
|
+
Decisions are locked per visit: a first visit usually sees the original and the return visit adapts \u2014 the
|
|
2639
|
+
exception is a visitor arriving on a campaign link, whose first page can already show the campaign's version
|
|
2640
|
+
(see Campaigns). Integrate one rung at a time.
|
|
2598
2641
|
|
|
2599
2642
|
## Setup (60 seconds, no account)
|
|
2600
2643
|
|
|
@@ -2618,10 +2661,13 @@ time.
|
|
|
2618
2661
|
|
|
2619
2662
|
## Rung 1 \u2014 Style (CSS only)
|
|
2620
2663
|
|
|
2621
|
-
Persona attributes on <html> (zero declaration
|
|
2622
|
-
|
|
2664
|
+
Persona attributes on <html> (zero declaration). The attribute carries the key the visit is
|
|
2665
|
+
SERVED as: a declared key as-is ('admin'), a discovered group with its d- prefix
|
|
2666
|
+
('d-content'), a campaign ('c-spring') or retargeting group ('r-spring'), or 'unknown'. CSS for a discovered group must target the d- key \u2014 a rule
|
|
2667
|
+
written against a bare 'content' stops matching once the group carries its prefix:
|
|
2623
2668
|
|
|
2624
2669
|
html[data-sentient-persona='admin'] .admin-tools { display: block; }
|
|
2670
|
+
html[data-sentient-persona='d-content'] .reading-list { display: block; }
|
|
2625
2671
|
html[data-sentient-confidence='low'] .admin-tools { display: none; }
|
|
2626
2672
|
|
|
2627
2673
|
Learned style tokens (element-scoped, SSR-safe):
|
|
@@ -2711,6 +2757,44 @@ Consent: add consentFrom (same presets as above) to window.sentient when the sit
|
|
|
2711
2757
|
banner, or consent: false plus SentientSnippet.grantConsent() on accept. On Shopify, snippet 0.32
|
|
2712
2758
|
and later follows Shopify's Customer Privacy API automatically.
|
|
2713
2759
|
|
|
2760
|
+
## Campaigns \u2014 ad and email links
|
|
2761
|
+
|
|
2762
|
+
A campaign is named in the dashboard (Settings -> Campaigns -> Prepare a campaign): its name, the
|
|
2763
|
+
utm_campaign its links carry (optionally utm_source / utm_medium, or the ad platform), what the ad
|
|
2764
|
+
promises, any discount code, and its landing page. Visitors arriving on its links are served as the
|
|
2765
|
+
campaign \u2014 persona 'c-spring' for a campaign named "Spring" \u2014 with versions written for it, from the
|
|
2766
|
+
FIRST page of the visit; a visitor who comes back without a tagged link within 30 days is still the
|
|
2767
|
+
campaign's until it ends. A visitor the site already knows (a declared persona or a discovered group)
|
|
2768
|
+
keeps that audience; the click still counts on the campaign card, as "already known". After a
|
|
2769
|
+
campaign, its visitors who did not convert can be moved into a retargeting group ('r-spring') with
|
|
2770
|
+
its own versions and its own result.
|
|
2771
|
+
|
|
2772
|
+
What the integration must do is get the landing URL to the first decision:
|
|
2773
|
+
|
|
2774
|
+
- Tag every ad and email link: ?utm_campaign=spring&utm_source=newsletter&utm_medium=email.
|
|
2775
|
+
utm_campaign is required \u2014 it is what a campaign matches on; an untagged link is served like any
|
|
2776
|
+
other visit.
|
|
2777
|
+
- Snippet, Shopify theme embed, AdaptiveProvider, and AdaptiveRoot in app/layout.tsx with no server
|
|
2778
|
+
preload: nothing to add. The browser's first decision carries the page URL.
|
|
2779
|
+
- Next.js server preload (ANY of registrySlotIds, registrySlots, components, sections or slots on
|
|
2780
|
+
AdaptiveRoot): the server decides before the browser runs, and a Server Component cannot read
|
|
2781
|
+
the request URL. Next.js never passes searchParams to a layout, so preload in app/layout.tsx decides a campaign visitor's
|
|
2782
|
+
first page as everyone else's (the campaign starts on their next visit, and that first click is not
|
|
2783
|
+
on the campaign card). Where a page renders AdaptiveRoot itself, pass the page's own:
|
|
2784
|
+
|
|
2785
|
+
export default async function Page({ searchParams }: { searchParams: Promise<Record<string, string | string[] | undefined>> }) {
|
|
2786
|
+
return (
|
|
2787
|
+
<AdaptiveRoot apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY ?? ''}
|
|
2788
|
+
searchParams={await searchParams} pathname="/spring">
|
|
2789
|
+
\u2026
|
|
2790
|
+
</AdaptiveRoot>
|
|
2791
|
+
);
|
|
2792
|
+
}
|
|
2793
|
+
|
|
2794
|
+
- Verify with a tagged link in a fresh browser profile: once the page has decided, <html
|
|
2795
|
+
data-sentient-persona> reads the campaign's key ('c-spring'). The React SDK always sets it; the
|
|
2796
|
+
snippet only with personaAttributes: true in window.sentient.
|
|
2797
|
+
|
|
2714
2798
|
## Capture AI assistants (server-side, any framework)
|
|
2715
2799
|
|
|
2716
2800
|
AI assistants that fetch pages for their users (ChatGPT-User, Claude-User, Perplexity-User)
|
|
@@ -2774,7 +2858,7 @@ function registerAgentTrafficTools(server, client) {
|
|
|
2774
2858
|
"get_agent_traffic",
|
|
2775
2859
|
{
|
|
2776
2860
|
title: "Agent traffic",
|
|
2777
|
-
description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers,
|
|
2861
|
+
description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, automated browser sessions, agent API calls), engine breakdown, and the paths they fetch most. Defaults to the last 30 calendar days; pass range (7d/30d/90d/all) or from/to (YYYY-MM-DD) like every other windowed tool (agent logs are retained 30 days on Free/Starter, 90 on Growth+). Automated traffic is reported separately: conversion rate is among People only (see get_traffic_breakdown)." + UNTRUSTED_FIELDS_NOTE,
|
|
2778
2862
|
// This tool alone took ad-hoc ISO from/to with no range token and echoed
|
|
2779
2863
|
// no window, while every other windowed tool used rangeInputSchema — so
|
|
2780
2864
|
// agents passed range:'7d' here, it was silently dropped, and 30 days of
|
|
@@ -2817,7 +2901,7 @@ function registerAgentTrafficTools(server, client) {
|
|
|
2817
2901
|
}
|
|
2818
2902
|
const lines = [
|
|
2819
2903
|
...win ? [win] : [],
|
|
2820
|
-
`Agent traffic: ${s.totals.crawler} crawler fetches, ${s.totals.api} agent API calls, ${s.totals.browser}
|
|
2904
|
+
`Agent traffic: ${s.totals.crawler} crawler fetches, ${s.totals.api} agent API calls, ${s.totals.browser} automated browser sessions.`,
|
|
2821
2905
|
`Live user fetches: ${s.intents.user} \xB7 Search index: ${s.intents.search} \xB7 Training: ${s.intents.training}${s.intents.other ? ` \xB7 Other: ${s.intents.other}` : ""} (a "live user fetch" = an AI assistant reading your site to answer a real person).`,
|
|
2822
2906
|
"",
|
|
2823
2907
|
"Engines:",
|
|
@@ -2896,33 +2980,91 @@ function registerAgentTrafficTools(server, client) {
|
|
|
2896
2980
|
);
|
|
2897
2981
|
}
|
|
2898
2982
|
|
|
2899
|
-
// src/tools/
|
|
2983
|
+
// src/tools/traffic.ts
|
|
2900
2984
|
var import_v316 = require("zod/v3");
|
|
2901
|
-
var
|
|
2902
|
-
|
|
2903
|
-
|
|
2904
|
-
|
|
2905
|
-
|
|
2985
|
+
var NOTICE_TEXT = {
|
|
2986
|
+
no_interaction_evidence: "Your integration isn't reporting clicks or scrolls, so we can't confirm anyone as a person yet.",
|
|
2987
|
+
server_only: "We receive these visits from your server but never see a browser, so we can't confirm them as people or bots."
|
|
2988
|
+
};
|
|
2989
|
+
var trafficRangeSchema = import_v316.z.enum(["24h", "7d", "30d", "90d", "all"]).optional().describe("'24h' is the rolling last 24 hours; 7d/30d/90d/all are calendar windows in the project's reporting timezone (default 30d)");
|
|
2990
|
+
function registerTrafficTools(server, client) {
|
|
2991
|
+
server.registerTool(
|
|
2992
|
+
"get_traffic_breakdown",
|
|
2993
|
+
{
|
|
2994
|
+
title: "Traffic breakdown",
|
|
2995
|
+
description: "Where a project\u2019s traffic came from. Every visitor (one per browser or device) last seen in the window falls into exactly one of seven groups that add up to the total: People (ran the page, interacted (click, scroll, mouse, touch or key) and passed the bot check), Loaded but didn\u2019t interact, Not verified \u2014 no browser activity, Being analysed (usually settled within 3 hours), AI assistants, Search & AI crawlers and Other automated. Each group carries plain-English evidence counts; named AI assistants and crawlers, conversions (total and from People) and notices are included. Conversion rates elsewhere are conversion rate among People. Reporting only \u2014 it does not change what the optimizer learns from." + UNTRUSTED_FIELDS_NOTE,
|
|
2996
|
+
inputSchema: { projectId: projectIdSchema, range: trafficRangeSchema },
|
|
2997
|
+
outputSchema: {
|
|
2998
|
+
window: import_v316.z.object({ from: import_v316.z.string(), to: import_v316.z.string() }),
|
|
2999
|
+
total: import_v316.z.number().describe("Visitors in the window; the groups add up to this"),
|
|
3000
|
+
groups: import_v316.z.array(
|
|
3001
|
+
import_v316.z.object({
|
|
3002
|
+
group: import_v316.z.string().describe("people | loaded_no_interaction | not_verified | being_analysed | ai_assistant | crawler | other_automated"),
|
|
3003
|
+
label: import_v316.z.string(),
|
|
3004
|
+
count: import_v316.z.number(),
|
|
3005
|
+
evidence: import_v316.z.array(import_v316.z.object({ code: import_v316.z.string(), label: import_v316.z.string(), count: import_v316.z.number() }))
|
|
3006
|
+
})
|
|
3007
|
+
),
|
|
3008
|
+
agents: import_v316.z.array(import_v316.z.object({ name: import_v316.z.string(), group: import_v316.z.string(), count: import_v316.z.number() })),
|
|
3009
|
+
conversions: import_v316.z.object({
|
|
3010
|
+
total: import_v316.z.number().describe("Conversions from every visitor"),
|
|
3011
|
+
fromPeople: import_v316.z.number().describe("Conversions from People; the rest are from visitors we couldn\u2019t confirm as people")
|
|
3012
|
+
}),
|
|
3013
|
+
notices: import_v316.z.array(import_v316.z.string()).describe("no_interaction_evidence | server_only")
|
|
3014
|
+
},
|
|
3015
|
+
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
|
|
3016
|
+
},
|
|
3017
|
+
withApiErrorGuidance(async ({ projectId, range }) => {
|
|
3018
|
+
var _a2, _b, _c;
|
|
3019
|
+
const id = encodeURIComponent(projectId);
|
|
3020
|
+
const t = await client.get(`/projects/${id}/traffic${range ? `?range=${encodeURIComponent(range)}` : ""}`);
|
|
3021
|
+
const beingAnalysed = (_b = (_a2 = t.groups.find((g) => g.group === "being_analysed")) == null ? void 0 : _a2.count) != null ? _b : 0;
|
|
3022
|
+
const lines = [
|
|
3023
|
+
`Traffic from ${t.window.from.slice(0, 10)} to ${t.window.to.slice(0, 10)}: ${t.total} visitors.`,
|
|
3024
|
+
...t.groups.map((g) => `- ${g.label}: ${g.count}`)
|
|
3025
|
+
];
|
|
3026
|
+
if (beingAnalysed > 0) {
|
|
3027
|
+
lines.push("", `${beingAnalysed} visitors are being analysed \u2014 usually settled within 3 hours`);
|
|
3028
|
+
}
|
|
3029
|
+
if (t.agents.length > 0) {
|
|
3030
|
+
lines.push("", "Named agents:", ...t.agents.map((a) => `- ${untrusted(a.name)}: ${a.count}`));
|
|
3031
|
+
}
|
|
3032
|
+
lines.push("", `${t.conversions.total} conversions in total, ${t.conversions.fromPeople} from People.`);
|
|
3033
|
+
for (const n of t.notices) lines.push((_c = NOTICE_TEXT[n]) != null ? _c : n);
|
|
3034
|
+
return { content: [{ type: "text", text: lines.join("\n") }], structuredContent: t };
|
|
3035
|
+
}, {
|
|
3036
|
+
range_too_large: "That window has too much traffic to break down in one go. Ask for a shorter range (24h, 7d or 30d) and try again."
|
|
3037
|
+
})
|
|
3038
|
+
);
|
|
3039
|
+
}
|
|
3040
|
+
|
|
3041
|
+
// src/tools/cells.ts
|
|
3042
|
+
var import_v317 = require("zod/v3");
|
|
3043
|
+
var personaOutput = import_v317.z.object({
|
|
3044
|
+
key: import_v317.z.string(),
|
|
3045
|
+
displayName: import_v317.z.string(),
|
|
3046
|
+
description: import_v317.z.string().nullable(),
|
|
3047
|
+
share: import_v317.z.number().describe("Fraction of 30-day decided sessions")
|
|
2906
3048
|
});
|
|
2907
|
-
var cellOutput =
|
|
2908
|
-
slotId:
|
|
2909
|
-
persona:
|
|
2910
|
-
status:
|
|
2911
|
-
requestedBy:
|
|
2912
|
-
armId:
|
|
2913
|
-
rationale:
|
|
2914
|
-
error:
|
|
2915
|
-
updatedAt:
|
|
3049
|
+
var cellOutput = import_v317.z.object({
|
|
3050
|
+
slotId: import_v317.z.string(),
|
|
3051
|
+
persona: import_v317.z.string(),
|
|
3052
|
+
status: import_v317.z.string().describe("pending | generating | review (waiting for approval) | live | error | rejected"),
|
|
3053
|
+
requestedBy: import_v317.z.string(),
|
|
3054
|
+
armId: import_v317.z.string().nullable(),
|
|
3055
|
+
rationale: import_v317.z.string().nullable(),
|
|
3056
|
+
error: import_v317.z.string().nullable(),
|
|
3057
|
+
updatedAt: import_v317.z.string(),
|
|
2916
3058
|
// These ride the API response too; omitting them from the schema made zod
|
|
2917
3059
|
// STRIP them, so agents could never see refinement or retry state.
|
|
2918
|
-
refinedFrom:
|
|
2919
|
-
notBefore:
|
|
2920
|
-
attempts:
|
|
2921
|
-
performance:
|
|
2922
|
-
shown:
|
|
2923
|
-
conversions:
|
|
2924
|
-
deltaPct:
|
|
2925
|
-
tier:
|
|
3060
|
+
refinedFrom: import_v317.z.string().nullable().optional().describe("Incumbent arm this cell is improving on \u2014 a pending cell with this set still SERVES the incumbent"),
|
|
3061
|
+
notBefore: import_v317.z.string().nullable().optional().describe("ISO time the queue will next consider this cell (retry backoff / daily-cap deferral); null when due now"),
|
|
3062
|
+
attempts: import_v317.z.number().optional().describe("Generation attempts so far"),
|
|
3063
|
+
performance: import_v317.z.object({
|
|
3064
|
+
shown: import_v317.z.number(),
|
|
3065
|
+
conversions: import_v317.z.number(),
|
|
3066
|
+
deltaPct: import_v317.z.number().nullable().describe("Signed % vs the original conversion rate \u2014 a point estimate; only meaningful beside a winning/losing tier"),
|
|
3067
|
+
tier: import_v317.z.string().describe(
|
|
2926
3068
|
'early | no_baseline (under 100 views) | winning | losing (posterior separated from the original, corrected across the slot column) | flat (NOT separated yet \u2014 not "equal")'
|
|
2927
3069
|
)
|
|
2928
3070
|
}).optional().describe("Present on live cells (and, mid-refinement, the incumbent arm): the at-a-glance readout")
|
|
@@ -2935,28 +3077,28 @@ function registerCellTools(server, client) {
|
|
|
2935
3077
|
description: 'The "Who sees what" matrix: which visitor types (personas) have an AI-generated version live in each personalizable region (slot), with per-persona traffic share and the first-miss auto-fill setting. A cell with no row means that visitor type sees the original.' + UNTRUSTED_FIELDS_NOTE,
|
|
2936
3078
|
inputSchema: { projectId: projectIdSchema },
|
|
2937
3079
|
outputSchema: {
|
|
2938
|
-
slots:
|
|
2939
|
-
|
|
2940
|
-
slotId:
|
|
2941
|
-
displayName:
|
|
2942
|
-
supportsForms:
|
|
3080
|
+
slots: import_v317.z.array(
|
|
3081
|
+
import_v317.z.object({
|
|
3082
|
+
slotId: import_v317.z.string(),
|
|
3083
|
+
displayName: import_v317.z.string(),
|
|
3084
|
+
supportsForms: import_v317.z.boolean(),
|
|
2943
3085
|
// API sends this; without it zod stripped the draft-vs-live signal.
|
|
2944
|
-
live:
|
|
3086
|
+
live: import_v317.z.boolean().optional().describe("False for an sdk-registered draft column \u2014 nothing serves until its first generation publishes it")
|
|
2945
3087
|
})
|
|
2946
3088
|
),
|
|
2947
|
-
personas:
|
|
2948
|
-
cells:
|
|
2949
|
-
autoFill:
|
|
3089
|
+
personas: import_v317.z.array(personaOutput),
|
|
3090
|
+
cells: import_v317.z.array(cellOutput),
|
|
3091
|
+
autoFill: import_v317.z.boolean(),
|
|
2950
3092
|
// The API has always sent this; without it in the schema zod stripped
|
|
2951
3093
|
// it, and generate_cell had no way to know a version would wait for a
|
|
2952
3094
|
// human instead of publishing.
|
|
2953
|
-
reviewMode:
|
|
3095
|
+
reviewMode: import_v317.z.boolean().optional().describe("True when generated versions wait for approval (review_cell) instead of publishing automatically"),
|
|
2954
3096
|
// Nullable: a project with no persona set at all reports null, not a
|
|
2955
3097
|
// string. That is the NORMAL state since the default vocabulary was
|
|
2956
3098
|
// emptied, so a non-nullable schema failed output validation on most
|
|
2957
3099
|
// projects and the tool returned nothing but a zod error.
|
|
2958
|
-
personaSource:
|
|
2959
|
-
undecidedShare:
|
|
3100
|
+
personaSource: import_v317.z.string().nullable().describe('Active persona-set source: default | declared | discovered, or null when the project has no persona set (one "everyone" row)'),
|
|
3101
|
+
undecidedShare: import_v317.z.number()
|
|
2960
3102
|
},
|
|
2961
3103
|
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
|
|
2962
3104
|
},
|
|
@@ -2996,26 +3138,26 @@ function registerCellTools(server, client) {
|
|
|
2996
3138
|
description: "One cell's full story: the generated option a visitor type sees in a slot, why it was written (the stored generation rationale), and how it is performing vs the original (deterministic plain-language verdict)." + UNTRUSTED_FIELDS_NOTE,
|
|
2997
3139
|
inputSchema: {
|
|
2998
3140
|
projectId: projectIdSchema,
|
|
2999
|
-
slotId:
|
|
3000
|
-
persona:
|
|
3141
|
+
slotId: import_v317.z.string().min(1).max(128).describe("The slot id (a matrix column)"),
|
|
3142
|
+
persona: import_v317.z.string().min(1).max(64).describe("The persona key (a matrix row)")
|
|
3001
3143
|
},
|
|
3002
3144
|
outputSchema: {
|
|
3003
3145
|
cell: cellOutput.nullable(),
|
|
3004
|
-
arm:
|
|
3005
|
-
id:
|
|
3006
|
-
displayName:
|
|
3007
|
-
content:
|
|
3008
|
-
blocks:
|
|
3146
|
+
arm: import_v317.z.object({
|
|
3147
|
+
id: import_v317.z.string(),
|
|
3148
|
+
displayName: import_v317.z.string().nullable(),
|
|
3149
|
+
content: import_v317.z.string().nullable(),
|
|
3150
|
+
blocks: import_v317.z.unknown().nullable()
|
|
3009
3151
|
}).nullable(),
|
|
3010
|
-
performance:
|
|
3011
|
-
shown:
|
|
3012
|
-
conversions:
|
|
3013
|
-
conversionRate:
|
|
3014
|
-
baselineShown:
|
|
3015
|
-
baselineConversions:
|
|
3016
|
-
baselineConversionRate:
|
|
3152
|
+
performance: import_v317.z.object({
|
|
3153
|
+
shown: import_v317.z.number(),
|
|
3154
|
+
conversions: import_v317.z.number(),
|
|
3155
|
+
conversionRate: import_v317.z.number(),
|
|
3156
|
+
baselineShown: import_v317.z.number(),
|
|
3157
|
+
baselineConversions: import_v317.z.number(),
|
|
3158
|
+
baselineConversionRate: import_v317.z.number()
|
|
3017
3159
|
}).nullable(),
|
|
3018
|
-
verdict:
|
|
3160
|
+
verdict: import_v317.z.string()
|
|
3019
3161
|
},
|
|
3020
3162
|
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
|
|
3021
3163
|
},
|
|
@@ -3060,14 +3202,14 @@ function registerCellTools(server, client) {
|
|
|
3060
3202
|
description: "Queue AI generation of a version for one (persona, slot) cell; the worker writes it asynchronously, brand-locked. If the project has review mode on, the finished version WAITS for approval (list_cell_reviews / review_cell) and serves nobody until approved; otherwise it publishes automatically as a named option the optimizer explores. Also regenerates or retries a failed cell. Generation volume is capped per plan (Free included). Check get_cell_matrix for progress. Confirm with the user before calling \u2014 each generation is a model call against the plan quota.",
|
|
3061
3203
|
inputSchema: {
|
|
3062
3204
|
projectId: projectIdSchema,
|
|
3063
|
-
slotId:
|
|
3064
|
-
persona:
|
|
3205
|
+
slotId: import_v317.z.string().min(1).max(128).describe("The slot id (a matrix column)"),
|
|
3206
|
+
persona: import_v317.z.string().min(1).max(64).describe("The persona key (a matrix row)")
|
|
3065
3207
|
},
|
|
3066
3208
|
outputSchema: {
|
|
3067
|
-
slotId:
|
|
3068
|
-
persona:
|
|
3069
|
-
status:
|
|
3070
|
-
reviewMode:
|
|
3209
|
+
slotId: import_v317.z.string(),
|
|
3210
|
+
persona: import_v317.z.string(),
|
|
3211
|
+
status: import_v317.z.literal("pending").describe("Queued \u2014 check get_cell_matrix for progress"),
|
|
3212
|
+
reviewMode: import_v317.z.boolean().nullable().describe("True: the version will wait for review_cell approval. False: it publishes automatically. Null: could not be read.")
|
|
3071
3213
|
},
|
|
3072
3214
|
annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
|
|
3073
3215
|
},
|
|
@@ -3095,19 +3237,19 @@ function registerCellTools(server, client) {
|
|
|
3095
3237
|
description: "Generated versions waiting for approval (review mode): which slot and visitor type, the proposed text or layout, and why it was written. Approve or reject each with review_cell after the user decides." + UNTRUSTED_FIELDS_NOTE,
|
|
3096
3238
|
inputSchema: { projectId: projectIdSchema },
|
|
3097
3239
|
outputSchema: {
|
|
3098
|
-
reviews:
|
|
3099
|
-
|
|
3100
|
-
slotId:
|
|
3101
|
-
slotName:
|
|
3102
|
-
persona:
|
|
3103
|
-
personaDisplay:
|
|
3104
|
-
content:
|
|
3105
|
-
rationale:
|
|
3106
|
-
refinedFrom:
|
|
3107
|
-
updatedAt:
|
|
3240
|
+
reviews: import_v317.z.array(
|
|
3241
|
+
import_v317.z.object({
|
|
3242
|
+
slotId: import_v317.z.string(),
|
|
3243
|
+
slotName: import_v317.z.string(),
|
|
3244
|
+
persona: import_v317.z.string(),
|
|
3245
|
+
personaDisplay: import_v317.z.string(),
|
|
3246
|
+
content: import_v317.z.string().nullable().describe("Proposed text, when the version is text (null for a block/layout version)"),
|
|
3247
|
+
rationale: import_v317.z.string().nullable(),
|
|
3248
|
+
refinedFrom: import_v317.z.string().nullable().describe("Live version this one would replace; that version keeps serving until approval"),
|
|
3249
|
+
updatedAt: import_v317.z.string()
|
|
3108
3250
|
})
|
|
3109
3251
|
),
|
|
3110
|
-
total:
|
|
3252
|
+
total: import_v317.z.number().int().describe("How many versions are waiting in all. The list holds at most the oldest 200; decide those to see the rest.")
|
|
3111
3253
|
},
|
|
3112
3254
|
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
|
|
3113
3255
|
},
|
|
@@ -3157,17 +3299,17 @@ function registerCellTools(server, client) {
|
|
|
3157
3299
|
description: "Approve or reject ONE generated version waiting for review (see list_cell_reviews). 'approve' publishes it to live visitors of that type; 'reject' discards it (a rejected refinement leaves the current live version in place). This is the human decision review mode exists for \u2014 only call it with the user's explicit go-ahead.",
|
|
3158
3300
|
inputSchema: {
|
|
3159
3301
|
projectId: projectIdSchema,
|
|
3160
|
-
slotId:
|
|
3161
|
-
persona:
|
|
3162
|
-
action:
|
|
3163
|
-
feedback:
|
|
3302
|
+
slotId: import_v317.z.string().min(1).max(128).describe("The slot id of the version under review"),
|
|
3303
|
+
persona: import_v317.z.string().min(1).max(64).describe("The persona key of the version under review"),
|
|
3304
|
+
action: import_v317.z.enum(["approve", "reject"]),
|
|
3305
|
+
feedback: import_v317.z.string().max(2e3).optional().describe("Optional reviewer note, stored with a rejection")
|
|
3164
3306
|
},
|
|
3165
3307
|
outputSchema: {
|
|
3166
|
-
slotId:
|
|
3167
|
-
persona:
|
|
3168
|
-
action:
|
|
3169
|
-
status:
|
|
3170
|
-
armId:
|
|
3308
|
+
slotId: import_v317.z.string(),
|
|
3309
|
+
persona: import_v317.z.string(),
|
|
3310
|
+
action: import_v317.z.enum(["approve", "reject"]),
|
|
3311
|
+
status: import_v317.z.string().describe("live (approved, or a rejected refinement whose incumbent keeps serving) | rejected"),
|
|
3312
|
+
armId: import_v317.z.string().nullable().describe("The published option id, on approval")
|
|
3171
3313
|
},
|
|
3172
3314
|
annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }
|
|
3173
3315
|
},
|
|
@@ -3194,7 +3336,7 @@ function registerCellTools(server, client) {
|
|
|
3194
3336
|
}
|
|
3195
3337
|
|
|
3196
3338
|
// src/server.ts
|
|
3197
|
-
var PKG_VERSION = true ? "0.
|
|
3339
|
+
var PKG_VERSION = true ? "0.25.1" : "0.0.0-dev";
|
|
3198
3340
|
function createMcpServer(client) {
|
|
3199
3341
|
const server = new import_mcp.McpServer(
|
|
3200
3342
|
{
|
|
@@ -3230,6 +3372,7 @@ function createMcpServer(client) {
|
|
|
3230
3372
|
registerVariantWriteTools(server, client);
|
|
3231
3373
|
registerIntegrationGuideTools(server);
|
|
3232
3374
|
registerAgentTrafficTools(server, client);
|
|
3375
|
+
registerTrafficTools(server, client);
|
|
3233
3376
|
registerCellTools(server, client);
|
|
3234
3377
|
return server;
|
|
3235
3378
|
}
|