@sentientui/mcp 0.24.2 → 0.25.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +3 -2
- package/README.md +3 -2
- package/dist/{chunk-HLKZFTEV.js → chunk-U54H74Y7.js} +221 -120
- package/dist/index.cjs +221 -120
- package/dist/index.js +1 -1
- package/dist/lib.cjs +223 -121
- package/dist/lib.js +3 -2
- package/package.json +1 -1
package/dist/lib.cjs
CHANGED
|
@@ -431,12 +431,17 @@ function registerProjectTools(server, client) {
|
|
|
431
431
|
"get_project_stats",
|
|
432
432
|
{
|
|
433
433
|
title: "Project health stats",
|
|
434
|
-
description: "Get ingestion health for a project: status, events
|
|
434
|
+
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.",
|
|
435
435
|
inputSchema: { projectId: projectIdSchema },
|
|
436
436
|
outputSchema: {
|
|
437
437
|
status: import_v32.z.string().describe("Overall project health status"),
|
|
438
438
|
events24h: import_v32.z.number().describe("Events in the last 24 hours"),
|
|
439
|
-
|
|
439
|
+
// This field used to be raw sessions; it now carries People, so the old
|
|
440
|
+
// description told an agent bots and unverified visitors were in it.
|
|
441
|
+
sessions24h: import_v32.z.number().describe("Deprecated alias of people on a current API; the raw session count on an older one"),
|
|
442
|
+
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"),
|
|
443
|
+
beingAnalysed: import_v32.z.number().nullable().describe("Visitors still being analysed \u2014 usually settled within 3 hours; null on an older API"),
|
|
444
|
+
automated: import_v32.z.number().nullable().describe("Automated visitors: AI assistants, search & AI crawlers and other automated; null on an older API"),
|
|
440
445
|
// Was "Total agent (MCP/API) calls" — but the count comes from
|
|
441
446
|
// agent_events, which only the /v1/agent endpoint writes. MCP tool calls
|
|
442
447
|
// are never in it, so an agent read its own activity as missing.
|
|
@@ -450,22 +455,30 @@ function registerProjectTools(server, client) {
|
|
|
450
455
|
}
|
|
451
456
|
},
|
|
452
457
|
withApiErrorGuidance(async ({ projectId }) => {
|
|
453
|
-
var _a;
|
|
458
|
+
var _a, _b, _c, _d, _e, _f, _g;
|
|
454
459
|
const id = encodeURIComponent(projectId);
|
|
455
460
|
const stats = await client.get(`/projects/${id}/health`);
|
|
461
|
+
const peopleCount = (_b = stats.people) != null ? _b : (_a = stats.traffic) == null ? void 0 : _a.people;
|
|
462
|
+
const classified = peopleCount !== void 0;
|
|
463
|
+
const people = classified ? peopleCount : null;
|
|
464
|
+
const beingAnalysed = classified ? (_d = (_c = stats.traffic) == null ? void 0 : _c.beingAnalysed) != null ? _d : 0 : null;
|
|
465
|
+
const automated = classified ? (_f = (_e = stats.traffic) == null ? void 0 : _e.automated) != null ? _f : 0 : null;
|
|
456
466
|
const text = [
|
|
457
467
|
`Status: ${stats.status}`,
|
|
458
468
|
`Events (24h): ${stats.events24h}`,
|
|
459
|
-
`Sessions (24h): ${stats.sessions24h}
|
|
469
|
+
...classified ? [`People (24h): ${people}`, `Being analysed: ${beingAnalysed}`, `Automated: ${automated}`] : [`Sessions (24h): ${stats.sessions24h}`],
|
|
460
470
|
`Agent API calls (/v1/agent, all-time): ${stats.agentCalls}`,
|
|
461
|
-
`Last event: ${(
|
|
471
|
+
`Last event: ${(_g = stats.lastEventAt) != null ? _g : "never"}`
|
|
462
472
|
].join("\n");
|
|
463
473
|
return {
|
|
464
474
|
content: [{ type: "text", text }],
|
|
465
475
|
structuredContent: {
|
|
466
476
|
status: stats.status,
|
|
467
477
|
events24h: stats.events24h,
|
|
468
|
-
sessions24h: stats.sessions24h,
|
|
478
|
+
sessions24h: people != null ? people : stats.sessions24h,
|
|
479
|
+
people,
|
|
480
|
+
beingAnalysed,
|
|
481
|
+
automated,
|
|
469
482
|
agentCalls: stats.agentCalls,
|
|
470
483
|
lastEventAt: stats.lastEventAt
|
|
471
484
|
}
|
|
@@ -825,7 +838,7 @@ function registerComponentTools(server, client) {
|
|
|
825
838
|
"list_components",
|
|
826
839
|
{
|
|
827
840
|
title: "List components",
|
|
828
|
-
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,
|
|
841
|
+
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,
|
|
829
842
|
inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("all")),
|
|
830
843
|
outputSchema: {
|
|
831
844
|
components: import_v33.z.array(
|
|
@@ -833,7 +846,8 @@ function registerComponentTools(server, client) {
|
|
|
833
846
|
componentId: import_v33.z.string(),
|
|
834
847
|
variantCount: import_v33.z.number(),
|
|
835
848
|
impressions: import_v33.z.number(),
|
|
836
|
-
conversions: import_v33.z.number()
|
|
849
|
+
conversions: import_v33.z.number(),
|
|
850
|
+
unconfirmedConversions: import_v33.z.number().nullable().describe("Conversions from visitors we couldn't confirm as people (not in conversions); null on an older API")
|
|
837
851
|
})
|
|
838
852
|
).describe("Adaptive components in the project (empty if none)"),
|
|
839
853
|
total: import_v33.z.number().describe("Total components in the project \u2014 larger than the list when truncated"),
|
|
@@ -849,12 +863,16 @@ function registerComponentTools(server, client) {
|
|
|
849
863
|
withApiErrorGuidance(async ({ projectId, range, from, to }) => {
|
|
850
864
|
const { components, total, window, truncated } = await fetchAllComponents(client, projectId, { rangeArgs: { range, from, to } });
|
|
851
865
|
const structuredContent = {
|
|
852
|
-
components: components.map((c) =>
|
|
853
|
-
|
|
854
|
-
|
|
855
|
-
|
|
856
|
-
|
|
857
|
-
|
|
866
|
+
components: components.map((c) => {
|
|
867
|
+
var _a;
|
|
868
|
+
return {
|
|
869
|
+
componentId: c.component_id,
|
|
870
|
+
variantCount: c.variants.length,
|
|
871
|
+
impressions: c.total_impressions,
|
|
872
|
+
conversions: c.total_conversions,
|
|
873
|
+
unconfirmedConversions: (_a = c.total_unconfirmed_conversions) != null ? _a : null
|
|
874
|
+
};
|
|
875
|
+
}),
|
|
858
876
|
total,
|
|
859
877
|
truncated,
|
|
860
878
|
window
|
|
@@ -866,7 +884,7 @@ function registerComponentTools(server, client) {
|
|
|
866
884
|
};
|
|
867
885
|
}
|
|
868
886
|
const lines = components.map(
|
|
869
|
-
(c) => `- ${untrusted(c.component_id)}: ${c.variants.length} variants, ${c.total_impressions} impressions, ${c.total_conversions} conversions`
|
|
887
|
+
(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)` : "")
|
|
870
888
|
);
|
|
871
889
|
if (truncated) {
|
|
872
890
|
lines.push(`Showing ${components.length} of ${total} components \u2014 fetch cap reached; the rest exist but are not listed here.`);
|
|
@@ -878,7 +896,7 @@ function registerComponentTools(server, client) {
|
|
|
878
896
|
"get_variant_performance",
|
|
879
897
|
{
|
|
880
898
|
title: "Variant performance",
|
|
881
|
-
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,
|
|
899
|
+
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,
|
|
882
900
|
inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("7d")),
|
|
883
901
|
_meta: uiMeta("variant-performance"),
|
|
884
902
|
outputSchema: {
|
|
@@ -889,7 +907,8 @@ function registerComponentTools(server, client) {
|
|
|
889
907
|
isBaseline: import_v33.z.boolean().describe("The arm the server measures the others against"),
|
|
890
908
|
baselineExplicit: import_v33.z.boolean().describe("False when no arm is named 'control' and the baseline is just the alphabetically-first id"),
|
|
891
909
|
sessions: import_v33.z.number().describe("Exposed sessions in the window (the n of currentCvr)"),
|
|
892
|
-
conversions: import_v33.z.number().describe("Converting sessions in the window"),
|
|
910
|
+
conversions: import_v33.z.number().describe("Converting People (sessions) in the window"),
|
|
911
|
+
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"),
|
|
893
912
|
currentCvr: import_v33.z.number().nullable().describe("conversions / sessions over the window (0-1); null at 0 sessions"),
|
|
894
913
|
lowSample: import_v33.z.boolean().describe(`True under ${MIN_EVIDENCE_SAMPLE} sessions \u2014 the rate is not interpretable on its own`),
|
|
895
914
|
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"),
|
|
@@ -916,7 +935,7 @@ function registerComponentTools(server, client) {
|
|
|
916
935
|
}
|
|
917
936
|
},
|
|
918
937
|
withApiErrorGuidance(async ({ projectId, range, from, to }) => {
|
|
919
|
-
var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k;
|
|
938
|
+
var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
|
|
920
939
|
const id = encodeURIComponent(projectId);
|
|
921
940
|
const [componentsRes, trendsRes] = await Promise.all([
|
|
922
941
|
settled(fetchAllComponents(client, projectId, { rangeArgs: { range, from, to } })),
|
|
@@ -997,13 +1016,14 @@ function registerComponentTools(server, client) {
|
|
|
997
1016
|
baselineExplicit: (_i = baseline == null ? void 0 : baseline.explicit) != null ? _i : false,
|
|
998
1017
|
sessions: n,
|
|
999
1018
|
conversions: conv,
|
|
1019
|
+
unconfirmedConversions: (_j = v.unconfirmed_conversions) != null ? _j : null,
|
|
1000
1020
|
currentCvr: n > 0 ? conv / n : null,
|
|
1001
1021
|
lowSample: isLowSample(n),
|
|
1002
1022
|
evidenceState: state,
|
|
1003
|
-
probBeatsBaseline: (
|
|
1023
|
+
probBeatsBaseline: (_k = stats == null ? void 0 : stats.probBeatsControl) != null ? _k : null,
|
|
1004
1024
|
reliabilityVerdict,
|
|
1005
1025
|
windowEvidenceState: wState,
|
|
1006
|
-
windowProbBeatsBaseline: (
|
|
1026
|
+
windowProbBeatsBaseline: (_l = wStats == null ? void 0 : wStats.probBeatsControl) != null ? _l : null,
|
|
1007
1027
|
verdict,
|
|
1008
1028
|
verdictBasis,
|
|
1009
1029
|
priorCvr,
|
|
@@ -1033,6 +1053,7 @@ function registerComponentTools(server, client) {
|
|
|
1033
1053
|
`vs preceding window: ${(priorCvr * 100).toFixed(2)}%${pn}, ${deltaPp > 0 ? "+" : ""}${deltaPp.toFixed(1)} pp${momentum ? `, ${momentum}` : ""} (untested)`
|
|
1034
1054
|
);
|
|
1035
1055
|
}
|
|
1056
|
+
if (v.unconfirmed_conversions) parts.push(`${v.unconfirmed_conversions} conversions from visitors we couldn't confirm as people`);
|
|
1036
1057
|
block.push(parts.join(" \xB7 "));
|
|
1037
1058
|
}
|
|
1038
1059
|
textBlocks.push(block.join("\n"));
|
|
@@ -1047,7 +1068,7 @@ function registerComponentTools(server, client) {
|
|
|
1047
1068
|
}
|
|
1048
1069
|
const header = [
|
|
1049
1070
|
windowLine(window),
|
|
1050
|
-
`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.'
|
|
1071
|
+
`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.'
|
|
1051
1072
|
].filter(Boolean);
|
|
1052
1073
|
const footer = truncated ? ["", "Fetch cap reached \u2014 some components are not listed."] : [];
|
|
1053
1074
|
const text = [...header, "", textBlocks.join("\n\n"), ...footer].join("\n");
|
|
@@ -1062,7 +1083,7 @@ var DEFAULT_LIMIT = 10;
|
|
|
1062
1083
|
var MAX_LIMIT = 50;
|
|
1063
1084
|
var EMPTY_REASON_TEXT = {
|
|
1064
1085
|
no_events: "The snippet has not fired yet \u2014 nothing has reached us.",
|
|
1065
|
-
no_traffic_yet: "
|
|
1086
|
+
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.",
|
|
1066
1087
|
awaiting_profiles: "Still building visitor profiles before visitors can be grouped.",
|
|
1067
1088
|
no_variants: "Nothing to compare yet \u2014 no adaptive component is running.",
|
|
1068
1089
|
nothing_moved: "Enough data, and nothing moved this period. That is a result.",
|
|
@@ -1309,12 +1330,12 @@ function registerStageTools(server, client) {
|
|
|
1309
1330
|
// Mirrors GET /projects/:id/stage-report. Says OBSERVATIONAL in the
|
|
1310
1331
|
// description because nothing serves on stage yet: an agent must not
|
|
1311
1332
|
// read a per-context arm result as "stage-based serving would win".
|
|
1312
|
-
description: `E-commerce projects: where visitors are in buying (new, browsing, carted, customer, lapsed) \u2014 share of
|
|
1333
|
+
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,
|
|
1313
1334
|
inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("30d")),
|
|
1314
1335
|
outputSchema: {
|
|
1315
1336
|
enabled: import_v36.z.boolean().describe("False when the project does not record funnel stages (settings.stage absent)"),
|
|
1316
1337
|
mode: import_v36.z.string().nullable().describe("'record' (reporting only) \u2014 serving by stage is not available yet"),
|
|
1317
|
-
sessions: import_v36.z.number().describe("
|
|
1338
|
+
sessions: import_v36.z.number().describe("People with a recorded stage in the window"),
|
|
1318
1339
|
hinted: import_v36.z.number().describe("Of those, sessions whose stage came from a campaign tag, not observed history"),
|
|
1319
1340
|
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() })),
|
|
1320
1341
|
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() })),
|
|
@@ -1443,7 +1464,7 @@ function registerGoalTools(server, client) {
|
|
|
1443
1464
|
// stages. The title and the first words of the description now say what
|
|
1444
1465
|
// it is, and point to the real funnel tool.
|
|
1445
1466
|
title: "Goal conversions (per goal \u2014 not a step funnel)",
|
|
1446
|
-
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,
|
|
1467
|
+
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,
|
|
1447
1468
|
inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("30d")),
|
|
1448
1469
|
_meta: uiMeta("goal-funnel"),
|
|
1449
1470
|
outputSchema: {
|
|
@@ -1453,7 +1474,10 @@ function registerGoalTools(server, client) {
|
|
|
1453
1474
|
goalName: import_v37.z.string(),
|
|
1454
1475
|
hits: import_v37.z.number(),
|
|
1455
1476
|
uniqueSessions: import_v37.z.number(),
|
|
1456
|
-
conversionRate: import_v37.z.number().describe("
|
|
1477
|
+
conversionRate: import_v37.z.number().describe("Conversion rate among People (0-1): People who converted \xF7 People in the window"),
|
|
1478
|
+
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"),
|
|
1479
|
+
unconfirmedSessions: import_v37.z.number().nullable().describe("Converting sessions from visitors we couldn't confirm as people; null on an older API"),
|
|
1480
|
+
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"),
|
|
1457
1481
|
revenue: import_v37.z.number().nullable().describe("Total revenue from valued conversions, in the project currency (null for valueless goals)"),
|
|
1458
1482
|
avgOrderValue: import_v37.z.number().nullable().describe("Average value per valued conversion (null for valueless goals)"),
|
|
1459
1483
|
revenuePerSession: import_v37.z.number().nullable().describe("Revenue divided by all project sessions (null for valueless goals)"),
|
|
@@ -1489,15 +1513,18 @@ function registerGoalTools(server, client) {
|
|
|
1489
1513
|
window: data.window,
|
|
1490
1514
|
currency: (_a = data.currency) != null ? _a : "USD",
|
|
1491
1515
|
goals: data.goals.map((g) => {
|
|
1492
|
-
var _a2, _b2, _c;
|
|
1516
|
+
var _a2, _b2, _c, _d, _e, _f;
|
|
1493
1517
|
return {
|
|
1494
1518
|
goalName: g.goalName,
|
|
1495
1519
|
hits: g.hits,
|
|
1496
1520
|
uniqueSessions: g.uniqueSessions,
|
|
1497
1521
|
conversionRate: g.pct,
|
|
1498
|
-
|
|
1499
|
-
|
|
1500
|
-
|
|
1522
|
+
unconfirmedHits: (_a2 = g.unconfirmedHits) != null ? _a2 : null,
|
|
1523
|
+
unconfirmedSessions: (_b2 = g.unconfirmedSessions) != null ? _b2 : null,
|
|
1524
|
+
unconfirmedRevenue: (_c = g.unconfirmedRevenue) != null ? _c : null,
|
|
1525
|
+
revenue: (_d = g.revenue) != null ? _d : null,
|
|
1526
|
+
avgOrderValue: (_e = g.avgOrderValue) != null ? _e : null,
|
|
1527
|
+
revenuePerSession: (_f = g.revenuePerSession) != null ? _f : null,
|
|
1501
1528
|
variants: g.variants.map((v) => {
|
|
1502
1529
|
var _a3, _b3;
|
|
1503
1530
|
return {
|
|
@@ -1522,9 +1549,13 @@ function registerGoalTools(server, client) {
|
|
|
1522
1549
|
const currency = (_b = data.currency) != null ? _b : "USD";
|
|
1523
1550
|
const win = windowLine(data.window);
|
|
1524
1551
|
const lines = data.goals.flatMap((g) => {
|
|
1525
|
-
var _a2;
|
|
1552
|
+
var _a2, _b2, _c;
|
|
1526
1553
|
return [
|
|
1527
|
-
`${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 (${((_a2 = g.avgOrderValue) != null ? _a2 : 0).toFixed(2)} avg order)` : ""),
|
|
1554
|
+
`${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 (${((_a2 = g.avgOrderValue) != null ? _a2 : 0).toFixed(2)} avg order)` : ""),
|
|
1555
|
+
// The remainder is the API's own (total − People); recomputing it here
|
|
1556
|
+
// would be a third definition that could drift from the dashboard's.
|
|
1557
|
+
...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`] : [],
|
|
1558
|
+
...g.unconfirmedRevenue != null && g.unconfirmedRevenue !== 0 ? [` ${g.unconfirmedRevenue.toFixed(2)} ${currency} revenue from visitors we couldn't confirm as people`] : [],
|
|
1528
1559
|
// The per-variant rates come from an all-time query (analytics.ts
|
|
1529
1560
|
// query 2, deliberately unwindowed so the denominator is the full
|
|
1530
1561
|
// assignment history). The dashboard labels them; this text had not,
|
|
@@ -1752,7 +1783,7 @@ function registerFunnelTools(server, client) {
|
|
|
1752
1783
|
"get_funnel_report",
|
|
1753
1784
|
{
|
|
1754
1785
|
title: "Funnel drop-off report",
|
|
1755
|
-
description:
|
|
1786
|
+
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,
|
|
1756
1787
|
inputSchema: { projectId: projectIdSchema, funnelId: funnelIdSchema },
|
|
1757
1788
|
outputSchema: {
|
|
1758
1789
|
funnelId: import_v38.z.string(),
|
|
@@ -1765,7 +1796,8 @@ function registerFunnelTools(server, client) {
|
|
|
1765
1796
|
stepIndex: import_v38.z.number(),
|
|
1766
1797
|
goalId: import_v38.z.string(),
|
|
1767
1798
|
displayName: import_v38.z.string(),
|
|
1768
|
-
reached: import_v38.z.number().describe("Distinct
|
|
1799
|
+
reached: import_v38.z.number().describe("Distinct People reaching this step in-window"),
|
|
1800
|
+
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"),
|
|
1769
1801
|
dropOffFromPrevious: import_v38.z.number().nullable().describe("1 - reached/previousReached (null on the first step)"),
|
|
1770
1802
|
neverFired: import_v38.z.boolean().describe("True when the step goal has never been recorded anywhere \u2014 likely a typo"),
|
|
1771
1803
|
variants: import_v38.z.array(import_v38.z.object({
|
|
@@ -1777,20 +1809,21 @@ function registerFunnelTools(server, client) {
|
|
|
1777
1809
|
personas: import_v38.z.array(import_v38.z.object({ label: import_v38.z.string(), reached: import_v38.z.number() }))
|
|
1778
1810
|
})
|
|
1779
1811
|
),
|
|
1780
|
-
revenue: import_v38.z.number().nullable().describe("Final-step revenue in the project currency (null when no valued conversions)"),
|
|
1781
|
-
|
|
1782
|
-
|
|
1812
|
+
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)"),
|
|
1813
|
+
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"),
|
|
1814
|
+
avgOrderValue: import_v38.z.number().nullable().describe("People's revenue per People order"),
|
|
1815
|
+
revenuePerEnteringVisitor: import_v38.z.number().nullable().describe("People's revenue per People entering the funnel"),
|
|
1783
1816
|
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')
|
|
1784
1817
|
},
|
|
1785
1818
|
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
|
|
1786
1819
|
},
|
|
1787
1820
|
withApiErrorGuidance(async ({ projectId, funnelId }) => {
|
|
1788
|
-
var _a;
|
|
1821
|
+
var _a, _b;
|
|
1789
1822
|
const data = await client.get(`/projects/${encodeURIComponent(projectId)}/funnels/${encodeURIComponent(funnelId)}/report`);
|
|
1790
1823
|
const lines = [`${untrusted(data.displayName)} \u2014 last ${data.windowDays} days`];
|
|
1791
1824
|
for (const s of data.steps) {
|
|
1792
1825
|
lines.push(
|
|
1793
|
-
`${s.stepIndex + 1}. ${untrusted(s.displayName)}: ${s.reached} reached` + stepChangeText(s.dropOffFromPrevious) + (s.neverFired ? " [never recorded \u2014 check the goal name]" : "")
|
|
1826
|
+
`${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]" : "")
|
|
1794
1827
|
);
|
|
1795
1828
|
for (const v of s.variants) {
|
|
1796
1829
|
lines.push(` ${untrusted(v.componentId)}/${untrusted(v.variantId)}: ${v.reached}/${v.assigned} assigned sessions reached this step`);
|
|
@@ -1798,7 +1831,9 @@ function registerFunnelTools(server, client) {
|
|
|
1798
1831
|
}
|
|
1799
1832
|
if (data.revenue != null) {
|
|
1800
1833
|
lines.push(
|
|
1801
|
-
`Revenue: ${data.revenue.toFixed(2)} ${data.currency}` +
|
|
1834
|
+
`Revenue: ${data.revenue.toFixed(2)} ${data.currency}` + // The API's remainder, verbatim: no arithmetic here, or this line
|
|
1835
|
+
// would print a figure the dashboard does not.
|
|
1836
|
+
(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` : "")
|
|
1802
1837
|
);
|
|
1803
1838
|
}
|
|
1804
1839
|
if (data.holdoutCompletion && data.holdoutCompletion.entered > 0) {
|
|
@@ -1807,7 +1842,14 @@ function registerFunnelTools(server, client) {
|
|
|
1807
1842
|
return {
|
|
1808
1843
|
content: [{ type: "text", text: lines.join("\n") }],
|
|
1809
1844
|
// Tolerate an API deployed before strict funnels existed.
|
|
1810
|
-
structuredContent: __spreadProps(__spreadValues({}, data), {
|
|
1845
|
+
structuredContent: __spreadProps(__spreadValues({}, data), {
|
|
1846
|
+
strictOrder: (_a = data.strictOrder) != null ? _a : true,
|
|
1847
|
+
unconfirmedRevenue: (_b = data.unconfirmedRevenue) != null ? _b : null,
|
|
1848
|
+
steps: data.steps.map((s) => {
|
|
1849
|
+
var _a2;
|
|
1850
|
+
return __spreadProps(__spreadValues({}, s), { unconfirmedReached: (_a2 = s.unconfirmedReached) != null ? _a2 : null });
|
|
1851
|
+
})
|
|
1852
|
+
})
|
|
1811
1853
|
};
|
|
1812
1854
|
})
|
|
1813
1855
|
);
|
|
@@ -2800,7 +2842,7 @@ function registerAgentTrafficTools(server, client) {
|
|
|
2800
2842
|
"get_agent_traffic",
|
|
2801
2843
|
{
|
|
2802
2844
|
title: "Agent traffic",
|
|
2803
|
-
description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers,
|
|
2845
|
+
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,
|
|
2804
2846
|
// This tool alone took ad-hoc ISO from/to with no range token and echoed
|
|
2805
2847
|
// no window, while every other windowed tool used rangeInputSchema — so
|
|
2806
2848
|
// agents passed range:'7d' here, it was silently dropped, and 30 days of
|
|
@@ -2843,7 +2885,7 @@ function registerAgentTrafficTools(server, client) {
|
|
|
2843
2885
|
}
|
|
2844
2886
|
const lines = [
|
|
2845
2887
|
...win ? [win] : [],
|
|
2846
|
-
`Agent traffic: ${s.totals.crawler} crawler fetches, ${s.totals.api} agent API calls, ${s.totals.browser}
|
|
2888
|
+
`Agent traffic: ${s.totals.crawler} crawler fetches, ${s.totals.api} agent API calls, ${s.totals.browser} automated browser sessions.`,
|
|
2847
2889
|
`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).`,
|
|
2848
2890
|
"",
|
|
2849
2891
|
"Engines:",
|
|
@@ -2922,33 +2964,91 @@ function registerAgentTrafficTools(server, client) {
|
|
|
2922
2964
|
);
|
|
2923
2965
|
}
|
|
2924
2966
|
|
|
2925
|
-
// src/tools/
|
|
2967
|
+
// src/tools/traffic.ts
|
|
2926
2968
|
var import_v316 = require("zod/v3");
|
|
2927
|
-
var
|
|
2928
|
-
|
|
2929
|
-
|
|
2930
|
-
|
|
2931
|
-
|
|
2969
|
+
var NOTICE_TEXT = {
|
|
2970
|
+
no_interaction_evidence: "Your integration isn't reporting clicks or scrolls, so we can't confirm anyone as a person yet.",
|
|
2971
|
+
server_only: "We receive these visits from your server but never see a browser, so we can't confirm them as people or bots."
|
|
2972
|
+
};
|
|
2973
|
+
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)");
|
|
2974
|
+
function registerTrafficTools(server, client) {
|
|
2975
|
+
server.registerTool(
|
|
2976
|
+
"get_traffic_breakdown",
|
|
2977
|
+
{
|
|
2978
|
+
title: "Traffic breakdown",
|
|
2979
|
+
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,
|
|
2980
|
+
inputSchema: { projectId: projectIdSchema, range: trafficRangeSchema },
|
|
2981
|
+
outputSchema: {
|
|
2982
|
+
window: import_v316.z.object({ from: import_v316.z.string(), to: import_v316.z.string() }),
|
|
2983
|
+
total: import_v316.z.number().describe("Visitors in the window; the groups add up to this"),
|
|
2984
|
+
groups: import_v316.z.array(
|
|
2985
|
+
import_v316.z.object({
|
|
2986
|
+
group: import_v316.z.string().describe("people | loaded_no_interaction | not_verified | being_analysed | ai_assistant | crawler | other_automated"),
|
|
2987
|
+
label: import_v316.z.string(),
|
|
2988
|
+
count: import_v316.z.number(),
|
|
2989
|
+
evidence: import_v316.z.array(import_v316.z.object({ code: import_v316.z.string(), label: import_v316.z.string(), count: import_v316.z.number() }))
|
|
2990
|
+
})
|
|
2991
|
+
),
|
|
2992
|
+
agents: import_v316.z.array(import_v316.z.object({ name: import_v316.z.string(), group: import_v316.z.string(), count: import_v316.z.number() })),
|
|
2993
|
+
conversions: import_v316.z.object({
|
|
2994
|
+
total: import_v316.z.number().describe("Conversions from every visitor"),
|
|
2995
|
+
fromPeople: import_v316.z.number().describe("Conversions from People; the rest are from visitors we couldn\u2019t confirm as people")
|
|
2996
|
+
}),
|
|
2997
|
+
notices: import_v316.z.array(import_v316.z.string()).describe("no_interaction_evidence | server_only")
|
|
2998
|
+
},
|
|
2999
|
+
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
|
|
3000
|
+
},
|
|
3001
|
+
withApiErrorGuidance(async ({ projectId, range }) => {
|
|
3002
|
+
var _a, _b, _c;
|
|
3003
|
+
const id = encodeURIComponent(projectId);
|
|
3004
|
+
const t = await client.get(`/projects/${id}/traffic${range ? `?range=${encodeURIComponent(range)}` : ""}`);
|
|
3005
|
+
const beingAnalysed = (_b = (_a = t.groups.find((g) => g.group === "being_analysed")) == null ? void 0 : _a.count) != null ? _b : 0;
|
|
3006
|
+
const lines = [
|
|
3007
|
+
`Traffic from ${t.window.from.slice(0, 10)} to ${t.window.to.slice(0, 10)}: ${t.total} visitors.`,
|
|
3008
|
+
...t.groups.map((g) => `- ${g.label}: ${g.count}`)
|
|
3009
|
+
];
|
|
3010
|
+
if (beingAnalysed > 0) {
|
|
3011
|
+
lines.push("", `${beingAnalysed} visitors are being analysed \u2014 usually settled within 3 hours`);
|
|
3012
|
+
}
|
|
3013
|
+
if (t.agents.length > 0) {
|
|
3014
|
+
lines.push("", "Named agents:", ...t.agents.map((a) => `- ${untrusted(a.name)}: ${a.count}`));
|
|
3015
|
+
}
|
|
3016
|
+
lines.push("", `${t.conversions.total} conversions in total, ${t.conversions.fromPeople} from People.`);
|
|
3017
|
+
for (const n of t.notices) lines.push((_c = NOTICE_TEXT[n]) != null ? _c : n);
|
|
3018
|
+
return { content: [{ type: "text", text: lines.join("\n") }], structuredContent: t };
|
|
3019
|
+
}, {
|
|
3020
|
+
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."
|
|
3021
|
+
})
|
|
3022
|
+
);
|
|
3023
|
+
}
|
|
3024
|
+
|
|
3025
|
+
// src/tools/cells.ts
|
|
3026
|
+
var import_v317 = require("zod/v3");
|
|
3027
|
+
var personaOutput = import_v317.z.object({
|
|
3028
|
+
key: import_v317.z.string(),
|
|
3029
|
+
displayName: import_v317.z.string(),
|
|
3030
|
+
description: import_v317.z.string().nullable(),
|
|
3031
|
+
share: import_v317.z.number().describe("Fraction of 30-day decided sessions")
|
|
2932
3032
|
});
|
|
2933
|
-
var cellOutput =
|
|
2934
|
-
slotId:
|
|
2935
|
-
persona:
|
|
2936
|
-
status:
|
|
2937
|
-
requestedBy:
|
|
2938
|
-
armId:
|
|
2939
|
-
rationale:
|
|
2940
|
-
error:
|
|
2941
|
-
updatedAt:
|
|
3033
|
+
var cellOutput = import_v317.z.object({
|
|
3034
|
+
slotId: import_v317.z.string(),
|
|
3035
|
+
persona: import_v317.z.string(),
|
|
3036
|
+
status: import_v317.z.string().describe("pending | generating | review (waiting for approval) | live | error | rejected"),
|
|
3037
|
+
requestedBy: import_v317.z.string(),
|
|
3038
|
+
armId: import_v317.z.string().nullable(),
|
|
3039
|
+
rationale: import_v317.z.string().nullable(),
|
|
3040
|
+
error: import_v317.z.string().nullable(),
|
|
3041
|
+
updatedAt: import_v317.z.string(),
|
|
2942
3042
|
// These ride the API response too; omitting them from the schema made zod
|
|
2943
3043
|
// STRIP them, so agents could never see refinement or retry state.
|
|
2944
|
-
refinedFrom:
|
|
2945
|
-
notBefore:
|
|
2946
|
-
attempts:
|
|
2947
|
-
performance:
|
|
2948
|
-
shown:
|
|
2949
|
-
conversions:
|
|
2950
|
-
deltaPct:
|
|
2951
|
-
tier:
|
|
3044
|
+
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"),
|
|
3045
|
+
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"),
|
|
3046
|
+
attempts: import_v317.z.number().optional().describe("Generation attempts so far"),
|
|
3047
|
+
performance: import_v317.z.object({
|
|
3048
|
+
shown: import_v317.z.number(),
|
|
3049
|
+
conversions: import_v317.z.number(),
|
|
3050
|
+
deltaPct: import_v317.z.number().nullable().describe("Signed % vs the original conversion rate \u2014 a point estimate; only meaningful beside a winning/losing tier"),
|
|
3051
|
+
tier: import_v317.z.string().describe(
|
|
2952
3052
|
'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")'
|
|
2953
3053
|
)
|
|
2954
3054
|
}).optional().describe("Present on live cells (and, mid-refinement, the incumbent arm): the at-a-glance readout")
|
|
@@ -2961,28 +3061,28 @@ function registerCellTools(server, client) {
|
|
|
2961
3061
|
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,
|
|
2962
3062
|
inputSchema: { projectId: projectIdSchema },
|
|
2963
3063
|
outputSchema: {
|
|
2964
|
-
slots:
|
|
2965
|
-
|
|
2966
|
-
slotId:
|
|
2967
|
-
displayName:
|
|
2968
|
-
supportsForms:
|
|
3064
|
+
slots: import_v317.z.array(
|
|
3065
|
+
import_v317.z.object({
|
|
3066
|
+
slotId: import_v317.z.string(),
|
|
3067
|
+
displayName: import_v317.z.string(),
|
|
3068
|
+
supportsForms: import_v317.z.boolean(),
|
|
2969
3069
|
// API sends this; without it zod stripped the draft-vs-live signal.
|
|
2970
|
-
live:
|
|
3070
|
+
live: import_v317.z.boolean().optional().describe("False for an sdk-registered draft column \u2014 nothing serves until its first generation publishes it")
|
|
2971
3071
|
})
|
|
2972
3072
|
),
|
|
2973
|
-
personas:
|
|
2974
|
-
cells:
|
|
2975
|
-
autoFill:
|
|
3073
|
+
personas: import_v317.z.array(personaOutput),
|
|
3074
|
+
cells: import_v317.z.array(cellOutput),
|
|
3075
|
+
autoFill: import_v317.z.boolean(),
|
|
2976
3076
|
// The API has always sent this; without it in the schema zod stripped
|
|
2977
3077
|
// it, and generate_cell had no way to know a version would wait for a
|
|
2978
3078
|
// human instead of publishing.
|
|
2979
|
-
reviewMode:
|
|
3079
|
+
reviewMode: import_v317.z.boolean().optional().describe("True when generated versions wait for approval (review_cell) instead of publishing automatically"),
|
|
2980
3080
|
// Nullable: a project with no persona set at all reports null, not a
|
|
2981
3081
|
// string. That is the NORMAL state since the default vocabulary was
|
|
2982
3082
|
// emptied, so a non-nullable schema failed output validation on most
|
|
2983
3083
|
// projects and the tool returned nothing but a zod error.
|
|
2984
|
-
personaSource:
|
|
2985
|
-
undecidedShare:
|
|
3084
|
+
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)'),
|
|
3085
|
+
undecidedShare: import_v317.z.number()
|
|
2986
3086
|
},
|
|
2987
3087
|
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
|
|
2988
3088
|
},
|
|
@@ -3022,26 +3122,26 @@ function registerCellTools(server, client) {
|
|
|
3022
3122
|
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,
|
|
3023
3123
|
inputSchema: {
|
|
3024
3124
|
projectId: projectIdSchema,
|
|
3025
|
-
slotId:
|
|
3026
|
-
persona:
|
|
3125
|
+
slotId: import_v317.z.string().min(1).max(128).describe("The slot id (a matrix column)"),
|
|
3126
|
+
persona: import_v317.z.string().min(1).max(64).describe("The persona key (a matrix row)")
|
|
3027
3127
|
},
|
|
3028
3128
|
outputSchema: {
|
|
3029
3129
|
cell: cellOutput.nullable(),
|
|
3030
|
-
arm:
|
|
3031
|
-
id:
|
|
3032
|
-
displayName:
|
|
3033
|
-
content:
|
|
3034
|
-
blocks:
|
|
3130
|
+
arm: import_v317.z.object({
|
|
3131
|
+
id: import_v317.z.string(),
|
|
3132
|
+
displayName: import_v317.z.string().nullable(),
|
|
3133
|
+
content: import_v317.z.string().nullable(),
|
|
3134
|
+
blocks: import_v317.z.unknown().nullable()
|
|
3035
3135
|
}).nullable(),
|
|
3036
|
-
performance:
|
|
3037
|
-
shown:
|
|
3038
|
-
conversions:
|
|
3039
|
-
conversionRate:
|
|
3040
|
-
baselineShown:
|
|
3041
|
-
baselineConversions:
|
|
3042
|
-
baselineConversionRate:
|
|
3136
|
+
performance: import_v317.z.object({
|
|
3137
|
+
shown: import_v317.z.number(),
|
|
3138
|
+
conversions: import_v317.z.number(),
|
|
3139
|
+
conversionRate: import_v317.z.number(),
|
|
3140
|
+
baselineShown: import_v317.z.number(),
|
|
3141
|
+
baselineConversions: import_v317.z.number(),
|
|
3142
|
+
baselineConversionRate: import_v317.z.number()
|
|
3043
3143
|
}).nullable(),
|
|
3044
|
-
verdict:
|
|
3144
|
+
verdict: import_v317.z.string()
|
|
3045
3145
|
},
|
|
3046
3146
|
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
|
|
3047
3147
|
},
|
|
@@ -3086,14 +3186,14 @@ function registerCellTools(server, client) {
|
|
|
3086
3186
|
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.",
|
|
3087
3187
|
inputSchema: {
|
|
3088
3188
|
projectId: projectIdSchema,
|
|
3089
|
-
slotId:
|
|
3090
|
-
persona:
|
|
3189
|
+
slotId: import_v317.z.string().min(1).max(128).describe("The slot id (a matrix column)"),
|
|
3190
|
+
persona: import_v317.z.string().min(1).max(64).describe("The persona key (a matrix row)")
|
|
3091
3191
|
},
|
|
3092
3192
|
outputSchema: {
|
|
3093
|
-
slotId:
|
|
3094
|
-
persona:
|
|
3095
|
-
status:
|
|
3096
|
-
reviewMode:
|
|
3193
|
+
slotId: import_v317.z.string(),
|
|
3194
|
+
persona: import_v317.z.string(),
|
|
3195
|
+
status: import_v317.z.literal("pending").describe("Queued \u2014 check get_cell_matrix for progress"),
|
|
3196
|
+
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.")
|
|
3097
3197
|
},
|
|
3098
3198
|
annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
|
|
3099
3199
|
},
|
|
@@ -3121,19 +3221,19 @@ function registerCellTools(server, client) {
|
|
|
3121
3221
|
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,
|
|
3122
3222
|
inputSchema: { projectId: projectIdSchema },
|
|
3123
3223
|
outputSchema: {
|
|
3124
|
-
reviews:
|
|
3125
|
-
|
|
3126
|
-
slotId:
|
|
3127
|
-
slotName:
|
|
3128
|
-
persona:
|
|
3129
|
-
personaDisplay:
|
|
3130
|
-
content:
|
|
3131
|
-
rationale:
|
|
3132
|
-
refinedFrom:
|
|
3133
|
-
updatedAt:
|
|
3224
|
+
reviews: import_v317.z.array(
|
|
3225
|
+
import_v317.z.object({
|
|
3226
|
+
slotId: import_v317.z.string(),
|
|
3227
|
+
slotName: import_v317.z.string(),
|
|
3228
|
+
persona: import_v317.z.string(),
|
|
3229
|
+
personaDisplay: import_v317.z.string(),
|
|
3230
|
+
content: import_v317.z.string().nullable().describe("Proposed text, when the version is text (null for a block/layout version)"),
|
|
3231
|
+
rationale: import_v317.z.string().nullable(),
|
|
3232
|
+
refinedFrom: import_v317.z.string().nullable().describe("Live version this one would replace; that version keeps serving until approval"),
|
|
3233
|
+
updatedAt: import_v317.z.string()
|
|
3134
3234
|
})
|
|
3135
3235
|
),
|
|
3136
|
-
total:
|
|
3236
|
+
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.")
|
|
3137
3237
|
},
|
|
3138
3238
|
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
|
|
3139
3239
|
},
|
|
@@ -3183,17 +3283,17 @@ function registerCellTools(server, client) {
|
|
|
3183
3283
|
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.",
|
|
3184
3284
|
inputSchema: {
|
|
3185
3285
|
projectId: projectIdSchema,
|
|
3186
|
-
slotId:
|
|
3187
|
-
persona:
|
|
3188
|
-
action:
|
|
3189
|
-
feedback:
|
|
3286
|
+
slotId: import_v317.z.string().min(1).max(128).describe("The slot id of the version under review"),
|
|
3287
|
+
persona: import_v317.z.string().min(1).max(64).describe("The persona key of the version under review"),
|
|
3288
|
+
action: import_v317.z.enum(["approve", "reject"]),
|
|
3289
|
+
feedback: import_v317.z.string().max(2e3).optional().describe("Optional reviewer note, stored with a rejection")
|
|
3190
3290
|
},
|
|
3191
3291
|
outputSchema: {
|
|
3192
|
-
slotId:
|
|
3193
|
-
persona:
|
|
3194
|
-
action:
|
|
3195
|
-
status:
|
|
3196
|
-
armId:
|
|
3292
|
+
slotId: import_v317.z.string(),
|
|
3293
|
+
persona: import_v317.z.string(),
|
|
3294
|
+
action: import_v317.z.enum(["approve", "reject"]),
|
|
3295
|
+
status: import_v317.z.string().describe("live (approved, or a rejected refinement whose incumbent keeps serving) | rejected"),
|
|
3296
|
+
armId: import_v317.z.string().nullable().describe("The published option id, on approval")
|
|
3197
3297
|
},
|
|
3198
3298
|
annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }
|
|
3199
3299
|
},
|
|
@@ -3220,7 +3320,7 @@ function registerCellTools(server, client) {
|
|
|
3220
3320
|
}
|
|
3221
3321
|
|
|
3222
3322
|
// src/server.ts
|
|
3223
|
-
var PKG_VERSION = true ? "0.
|
|
3323
|
+
var PKG_VERSION = true ? "0.25.0" : "0.0.0-dev";
|
|
3224
3324
|
function createMcpServer(client) {
|
|
3225
3325
|
const server = new import_mcp.McpServer(
|
|
3226
3326
|
{
|
|
@@ -3256,6 +3356,7 @@ function createMcpServer(client) {
|
|
|
3256
3356
|
registerVariantWriteTools(server, client);
|
|
3257
3357
|
registerIntegrationGuideTools(server);
|
|
3258
3358
|
registerAgentTrafficTools(server, client);
|
|
3359
|
+
registerTrafficTools(server, client);
|
|
3259
3360
|
registerCellTools(server, client);
|
|
3260
3361
|
return server;
|
|
3261
3362
|
}
|
|
@@ -3300,7 +3401,8 @@ var TOOL_CATALOG = [
|
|
|
3300
3401
|
{ name: "list_cell_reviews", access: "read", summary: "Generated versions waiting for approval (review mode)" },
|
|
3301
3402
|
{ name: "review_cell", access: "write", summary: "Approve (publish) or reject one generated version waiting for review" },
|
|
3302
3403
|
// Agent traffic
|
|
3303
|
-
{ name: "get_agent_traffic", access: "read", summary: "Which AI crawlers,
|
|
3404
|
+
{ name: "get_agent_traffic", access: "read", summary: "Which AI crawlers, automated browser sessions and agent API callers read the site (windowed)" },
|
|
3405
|
+
{ name: "get_traffic_breakdown", access: "read", summary: "Where traffic came from: People vs visitors we could not confirm vs automated (7 groups, windowed)" },
|
|
3304
3406
|
{ name: "get_agent_legibility", access: "read", summary: "Whether the pages agents read are machine-legible, with fixes" },
|
|
3305
3407
|
// Setup
|
|
3306
3408
|
{ name: "get_integration_guide", access: "read", summary: "SDK setup guide (static \u2014 same for every project)" }
|