@sentientui/mcp 0.29.2 → 0.30.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 +1 -0
- package/README.md +1 -0
- package/dist/{chunk-HTKHEGTY.js → chunk-RXCALHF6.js} +219 -162
- package/dist/index.cjs +219 -162
- package/dist/index.js +1 -1
- package/dist/lib.cjs +220 -162
- package/dist/lib.js +2 -1
- package/package.json +1 -1
package/AGENTS.md
CHANGED
|
@@ -112,6 +112,7 @@ Every write tool changes what real visitors see or what the project accepts —
|
|
|
112
112
|
| `get_agent_traffic` | read | AI crawlers / automated browser sessions / agent API callers reading the site (windowed; paid plans) |
|
|
113
113
|
| `get_traffic_breakdown` | read | Where traffic came from: People vs visitors we couldn't confirm vs automated vs your team / test sites (windowed) |
|
|
114
114
|
| `get_internal_traffic_rules` | read | How the project keeps its team and test sites out of its numbers: internal sites, team email domains and masked emails, browser link, sessions marked internal (7 days) |
|
|
115
|
+
| `get_site_areas` | read | Which parts of the site are before sign-up (anonymous visitors to convert) and after (inside the product), with each site's signed-in share and a suggested side |
|
|
115
116
|
| `get_agent_legibility` | read | Whether agent-read pages are machine-legible, with fixes (paid plans) |
|
|
116
117
|
| `get_agent_access` | read | Which areas a person has allowed agents to change (read this before a write; only a person can change it) |
|
|
117
118
|
| `list_campaigns` | read | Named campaigns, retargeting groups and campaigns seen in traffic; with `campaignId`, one campaign card |
|
package/README.md
CHANGED
|
@@ -126,6 +126,7 @@ A demo token is provisioned automatically — 10 calls/month, read-only (write t
|
|
|
126
126
|
| `get_agent_traffic` | read | Which AI crawlers, automated browser sessions and agent API callers read the site (windowed; paid plans) |
|
|
127
127
|
| `get_traffic_breakdown` | read | Where traffic came from: People vs visitors we couldn't confirm vs automated vs your team / test sites (windowed) |
|
|
128
128
|
| `get_internal_traffic_rules` | read | How the project keeps its team and test sites out of its numbers: internal sites, team email domains and masked emails, browser link, sessions marked internal (7 days) |
|
|
129
|
+
| `get_site_areas` | read | Which parts of the site are before sign-up (anonymous visitors to convert) and after (inside the product), with each site's signed-in share and a suggested side |
|
|
129
130
|
| `get_agent_legibility` | read | Whether the pages agents read are machine-legible, with fixes (paid plans) |
|
|
130
131
|
| `get_agent_access` | read | Which areas a person has allowed agents to change (read this before a write; only a person can change it) |
|
|
131
132
|
| `list_campaigns` | read | Named campaigns, retargeting groups and campaigns seen in traffic; with `campaignId`, one campaign card |
|
|
@@ -3943,44 +3943,96 @@ function registerInternalTrafficTools(server, client) {
|
|
|
3943
3943
|
);
|
|
3944
3944
|
}
|
|
3945
3945
|
|
|
3946
|
-
// src/tools/
|
|
3946
|
+
// src/tools/site-areas.ts
|
|
3947
3947
|
import { z as z25 } from "zod/v3";
|
|
3948
|
-
var
|
|
3949
|
-
|
|
3950
|
-
|
|
3951
|
-
|
|
3952
|
-
|
|
3948
|
+
var SIDE_WORDS = { before: "before sign-up", after: "after sign-up" };
|
|
3949
|
+
function registerSiteAreasTools(server, client) {
|
|
3950
|
+
server.registerTool(
|
|
3951
|
+
"get_site_areas",
|
|
3952
|
+
{
|
|
3953
|
+
title: "Site areas (before and after sign-up)",
|
|
3954
|
+
description: "Read which parts of the site are before sign-up (anonymous visitors; the main goal is to convert them: a sign-up, a sale, a form) and which are after sign-up (inside the product, where the site knows who its users are) \u2014 dashboard Settings \u2192 Site areas. Each area is an allowed site, optionally narrowed to a path; a page no area covers is before sign-up. A component gets versions only for audiences of its own side: campaign, arrival and retargeting audiences are before sign-up, declared personas after (unless declared for before), discovered groups wherever their visits happen. An empty list means the site is not split and nothing is restricted. Also lists every allowed site with how many visitors were signed in (30 days) and a suggested side. To change: manage_settings set_site_areas; a declared persona's side: manage_campaigns update_audience with { side }.",
|
|
3955
|
+
inputSchema: { projectId: projectIdSchema },
|
|
3956
|
+
outputSchema: {
|
|
3957
|
+
split: z25.boolean().describe("True once the project has split its site into before and after sign-up"),
|
|
3958
|
+
areas: z25.array(z25.object({ origin: z25.string(), path: z25.string().nullable(), side: z25.enum(["before", "after"]) })).describe("The areas, as saved"),
|
|
3959
|
+
sites: z25.array(
|
|
3960
|
+
z25.object({
|
|
3961
|
+
origin: z25.string(),
|
|
3962
|
+
internal: z25.boolean().describe("Marked internal (Settings \u2192 Internal traffic): its visits never count"),
|
|
3963
|
+
visits30d: z25.number(),
|
|
3964
|
+
signedIn30d: z25.number().describe("Visits where the site passed a user id"),
|
|
3965
|
+
suggested: z25.enum(["before", "after"]).nullable().describe("After when most visitors were signed in; null with too few visits")
|
|
3966
|
+
})
|
|
3967
|
+
).describe("Every allowed site")
|
|
3968
|
+
},
|
|
3969
|
+
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
|
|
3970
|
+
},
|
|
3971
|
+
withApiErrorGuidance(async ({ projectId }) => {
|
|
3972
|
+
var _a, _b;
|
|
3973
|
+
const r = await client.get(`/projects/${encodeURIComponent(projectId)}/site-areas`);
|
|
3974
|
+
const areas = (_a = r.areas) != null ? _a : [];
|
|
3975
|
+
const sites = (_b = r.sites) != null ? _b : [];
|
|
3976
|
+
const lines = areas.length === 0 ? ["The site is not split into before and after sign-up: nothing is restricted."] : [
|
|
3977
|
+
"Site areas (a page no area covers is before sign-up):",
|
|
3978
|
+
...areas.map((a2) => {
|
|
3979
|
+
var _a2;
|
|
3980
|
+
return `- ${a2.origin}${(_a2 = a2.path) != null ? _a2 : ""}: ${SIDE_WORDS[a2.side]}`;
|
|
3981
|
+
})
|
|
3982
|
+
];
|
|
3983
|
+
const suggestions = sites.filter((s) => !s.internal && s.suggested !== null);
|
|
3984
|
+
if (suggestions.length > 0) {
|
|
3985
|
+
lines.push(
|
|
3986
|
+
"Signed-in share, last 30 days:",
|
|
3987
|
+
...suggestions.map((s) => `- ${s.origin}: ${s.signedIn30d} of ${s.visits30d} visits signed in \u2192 suggested ${SIDE_WORDS[s.suggested]}`)
|
|
3988
|
+
);
|
|
3989
|
+
}
|
|
3990
|
+
return {
|
|
3991
|
+
content: [{ type: "text", text: lines.join("\n") }],
|
|
3992
|
+
structuredContent: { split: areas.length > 0, areas, sites }
|
|
3993
|
+
};
|
|
3994
|
+
})
|
|
3995
|
+
);
|
|
3996
|
+
}
|
|
3997
|
+
|
|
3998
|
+
// src/tools/cells.ts
|
|
3999
|
+
import { z as z26 } from "zod/v3";
|
|
4000
|
+
var personaOutput = z26.object({
|
|
4001
|
+
key: z26.string(),
|
|
4002
|
+
displayName: z26.string(),
|
|
4003
|
+
description: z26.string().nullable(),
|
|
4004
|
+
share: z26.number().describe("Fraction of 30-day decided sessions"),
|
|
3953
4005
|
// Both ride the API response; without them zod stripped them and an agent
|
|
3954
4006
|
// reported a declared audience nothing declares as reachable.
|
|
3955
|
-
state:
|
|
3956
|
-
declaredVisits14d:
|
|
4007
|
+
state: z26.string().optional().describe("everyone | declared | unlocked | candidate | starter \u2014 why the row exists"),
|
|
4008
|
+
declaredVisits14d: z26.number().nullable().optional().describe(
|
|
3957
4009
|
"Declared rows only: visits in 14 days whose site declared this persona. 0 = not declared yet \u2014 nobody sees versions written for it until the site sends it."
|
|
3958
4010
|
)
|
|
3959
4011
|
});
|
|
3960
|
-
var blockedOutput =
|
|
4012
|
+
var blockedOutput = z26.enum(["variant_history"]).nullable().optional().describe(
|
|
3961
4013
|
"variant_history: the component's code still runs its own variants test, so versions written here are approved but NOT showing until it is migrated (dashboard Components \u2192 Migrate; automatic once that test has assigned nobody a version for 14 days). Null when the column can serve."
|
|
3962
4014
|
);
|
|
3963
4015
|
var BLOCKED_LINE = "Not showing yet \u2014 your code's own test still runs here. Versions written for this part of the page are approved but no visitor sees them until it is migrated (Components \u2192 this component \u2192 Migrate) \u2014 Sentient does it by itself once that test has shown nobody a version for 14 days.";
|
|
3964
4016
|
var NOT_DECLARED_LINE = "not declared yet \u2014 your site has not told us anyone is this persona in 14 days, so nobody sees versions written for them until your code sends it (the persona prop, init({ persona }) or window.sentient.persona)";
|
|
3965
|
-
var cellOutput =
|
|
3966
|
-
slotId:
|
|
3967
|
-
persona:
|
|
3968
|
-
status:
|
|
3969
|
-
requestedBy:
|
|
3970
|
-
armId:
|
|
3971
|
-
rationale:
|
|
3972
|
-
error:
|
|
3973
|
-
updatedAt:
|
|
4017
|
+
var cellOutput = z26.object({
|
|
4018
|
+
slotId: z26.string(),
|
|
4019
|
+
persona: z26.string(),
|
|
4020
|
+
status: z26.string().describe("pending | generating | review (waiting for approval) | live | error | rejected"),
|
|
4021
|
+
requestedBy: z26.string(),
|
|
4022
|
+
armId: z26.string().nullable(),
|
|
4023
|
+
rationale: z26.string().nullable(),
|
|
4024
|
+
error: z26.string().nullable(),
|
|
4025
|
+
updatedAt: z26.string(),
|
|
3974
4026
|
// These ride the API response too; omitting them from the schema made zod
|
|
3975
4027
|
// STRIP them, so agents could never see refinement or retry state.
|
|
3976
|
-
refinedFrom:
|
|
3977
|
-
notBefore:
|
|
3978
|
-
attempts:
|
|
3979
|
-
performance:
|
|
3980
|
-
shown:
|
|
3981
|
-
conversions:
|
|
3982
|
-
deltaPct:
|
|
3983
|
-
tier:
|
|
4028
|
+
refinedFrom: z26.string().nullable().optional().describe("Incumbent arm this cell is improving on \u2014 a pending cell with this set still SERVES the incumbent"),
|
|
4029
|
+
notBefore: z26.string().nullable().optional().describe("ISO time the queue will next consider this cell (retry backoff / daily-cap deferral); null when due now"),
|
|
4030
|
+
attempts: z26.number().optional().describe("Generation attempts so far"),
|
|
4031
|
+
performance: z26.object({
|
|
4032
|
+
shown: z26.number(),
|
|
4033
|
+
conversions: z26.number(),
|
|
4034
|
+
deltaPct: z26.number().nullable().describe("Signed % vs the original conversion rate \u2014 a point estimate; only meaningful beside a winning/losing tier"),
|
|
4035
|
+
tier: z26.string().describe(
|
|
3984
4036
|
'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")'
|
|
3985
4037
|
)
|
|
3986
4038
|
}).optional().describe("Present on live cells (and, mid-refinement, the incumbent arm): the at-a-glance readout")
|
|
@@ -3993,29 +4045,29 @@ function registerCellTools(server, client) {
|
|
|
3993
4045
|
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 nothing has been written for that visitor type in that region \u2014 not that it sees only the original: a region can still be testing shared versions (an editor or dashboard alternative) on everyone, which list_components lists with their numbers.' + UNTRUSTED_FIELDS_NOTE,
|
|
3994
4046
|
inputSchema: { projectId: projectIdSchema },
|
|
3995
4047
|
outputSchema: {
|
|
3996
|
-
slots:
|
|
3997
|
-
|
|
3998
|
-
slotId:
|
|
3999
|
-
displayName:
|
|
4000
|
-
supportsForms:
|
|
4048
|
+
slots: z26.array(
|
|
4049
|
+
z26.object({
|
|
4050
|
+
slotId: z26.string(),
|
|
4051
|
+
displayName: z26.string(),
|
|
4052
|
+
supportsForms: z26.boolean(),
|
|
4001
4053
|
// API sends this; without it zod stripped the draft-vs-live signal.
|
|
4002
|
-
live:
|
|
4054
|
+
live: z26.boolean().optional().describe("False for an sdk-registered draft column \u2014 nothing serves until its first generation publishes it"),
|
|
4003
4055
|
blocked: blockedOutput
|
|
4004
4056
|
})
|
|
4005
4057
|
),
|
|
4006
|
-
personas:
|
|
4007
|
-
cells:
|
|
4008
|
-
autoFill:
|
|
4058
|
+
personas: z26.array(personaOutput),
|
|
4059
|
+
cells: z26.array(cellOutput),
|
|
4060
|
+
autoFill: z26.boolean(),
|
|
4009
4061
|
// The API has always sent this; without it in the schema zod stripped
|
|
4010
4062
|
// it, and generate_cell had no way to know a version would wait for a
|
|
4011
4063
|
// human instead of publishing.
|
|
4012
|
-
reviewMode:
|
|
4064
|
+
reviewMode: z26.boolean().optional().describe("True when generated versions wait for approval (review_cell) instead of publishing automatically"),
|
|
4013
4065
|
// Nullable: a project with no persona set at all reports null, not a
|
|
4014
4066
|
// string. That is the NORMAL state since the default vocabulary was
|
|
4015
4067
|
// emptied, so a non-nullable schema failed output validation on most
|
|
4016
4068
|
// projects and the tool returned nothing but a zod error.
|
|
4017
|
-
personaSource:
|
|
4018
|
-
undecidedShare:
|
|
4069
|
+
personaSource: z26.string().nullable().describe('Active persona-set source: default | declared | discovered, or null when the project has no persona set (one "everyone" row)'),
|
|
4070
|
+
undecidedShare: z26.number()
|
|
4019
4071
|
},
|
|
4020
4072
|
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
|
|
4021
4073
|
},
|
|
@@ -4060,26 +4112,26 @@ function registerCellTools(server, client) {
|
|
|
4060
4112
|
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,
|
|
4061
4113
|
inputSchema: {
|
|
4062
4114
|
projectId: projectIdSchema,
|
|
4063
|
-
slotId:
|
|
4064
|
-
persona:
|
|
4115
|
+
slotId: z26.string().min(1).max(128).describe("The slot id (a matrix column)"),
|
|
4116
|
+
persona: z26.string().min(1).max(64).describe("The persona key (a matrix row)")
|
|
4065
4117
|
},
|
|
4066
4118
|
outputSchema: {
|
|
4067
4119
|
cell: cellOutput.nullable(),
|
|
4068
|
-
arm:
|
|
4069
|
-
id:
|
|
4070
|
-
displayName:
|
|
4071
|
-
content:
|
|
4072
|
-
blocks:
|
|
4120
|
+
arm: z26.object({
|
|
4121
|
+
id: z26.string(),
|
|
4122
|
+
displayName: z26.string().nullable(),
|
|
4123
|
+
content: z26.string().nullable(),
|
|
4124
|
+
blocks: z26.unknown().nullable()
|
|
4073
4125
|
}).nullable(),
|
|
4074
|
-
performance:
|
|
4075
|
-
shown:
|
|
4076
|
-
conversions:
|
|
4077
|
-
conversionRate:
|
|
4078
|
-
baselineShown:
|
|
4079
|
-
baselineConversions:
|
|
4080
|
-
baselineConversionRate:
|
|
4126
|
+
performance: z26.object({
|
|
4127
|
+
shown: z26.number(),
|
|
4128
|
+
conversions: z26.number(),
|
|
4129
|
+
conversionRate: z26.number(),
|
|
4130
|
+
baselineShown: z26.number(),
|
|
4131
|
+
baselineConversions: z26.number(),
|
|
4132
|
+
baselineConversionRate: z26.number()
|
|
4081
4133
|
}).nullable(),
|
|
4082
|
-
verdict:
|
|
4134
|
+
verdict: z26.string(),
|
|
4083
4135
|
blocked: blockedOutput
|
|
4084
4136
|
},
|
|
4085
4137
|
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
|
|
@@ -4130,14 +4182,14 @@ function registerCellTools(server, client) {
|
|
|
4130
4182
|
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.",
|
|
4131
4183
|
inputSchema: {
|
|
4132
4184
|
projectId: projectIdSchema,
|
|
4133
|
-
slotId:
|
|
4134
|
-
persona:
|
|
4185
|
+
slotId: z26.string().min(1).max(128).describe("The slot id (a matrix column)"),
|
|
4186
|
+
persona: z26.string().min(1).max(64).describe("The persona key (a matrix row)")
|
|
4135
4187
|
},
|
|
4136
4188
|
outputSchema: {
|
|
4137
|
-
slotId:
|
|
4138
|
-
persona:
|
|
4139
|
-
status:
|
|
4140
|
-
reviewMode:
|
|
4189
|
+
slotId: z26.string(),
|
|
4190
|
+
persona: z26.string(),
|
|
4191
|
+
status: z26.literal("pending").describe("Queued \u2014 check get_cell_matrix for progress"),
|
|
4192
|
+
reviewMode: z26.boolean().nullable().describe("True: the version will wait for review_cell approval. False: it publishes automatically. Null: could not be read.")
|
|
4141
4193
|
},
|
|
4142
4194
|
annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
|
|
4143
4195
|
},
|
|
@@ -4165,20 +4217,20 @@ function registerCellTools(server, client) {
|
|
|
4165
4217
|
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,
|
|
4166
4218
|
inputSchema: { projectId: projectIdSchema },
|
|
4167
4219
|
outputSchema: {
|
|
4168
|
-
reviews:
|
|
4169
|
-
|
|
4170
|
-
slotId:
|
|
4171
|
-
slotName:
|
|
4172
|
-
persona:
|
|
4173
|
-
personaDisplay:
|
|
4174
|
-
content:
|
|
4175
|
-
rationale:
|
|
4176
|
-
refinedFrom:
|
|
4177
|
-
updatedAt:
|
|
4220
|
+
reviews: z26.array(
|
|
4221
|
+
z26.object({
|
|
4222
|
+
slotId: z26.string(),
|
|
4223
|
+
slotName: z26.string(),
|
|
4224
|
+
persona: z26.string(),
|
|
4225
|
+
personaDisplay: z26.string(),
|
|
4226
|
+
content: z26.string().nullable().describe("Proposed text, when the version is text (null for a block/layout version)"),
|
|
4227
|
+
rationale: z26.string().nullable(),
|
|
4228
|
+
refinedFrom: z26.string().nullable().describe("Live version this one would replace; that version keeps serving until approval"),
|
|
4229
|
+
updatedAt: z26.string(),
|
|
4178
4230
|
blocked: blockedOutput
|
|
4179
4231
|
})
|
|
4180
4232
|
),
|
|
4181
|
-
total:
|
|
4233
|
+
total: z26.number().int().describe("How many versions are waiting in all. The list holds at most the oldest 200; decide those to see the rest.")
|
|
4182
4234
|
},
|
|
4183
4235
|
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
|
|
4184
4236
|
},
|
|
@@ -4230,17 +4282,17 @@ function registerCellTools(server, client) {
|
|
|
4230
4282
|
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.",
|
|
4231
4283
|
inputSchema: {
|
|
4232
4284
|
projectId: projectIdSchema,
|
|
4233
|
-
slotId:
|
|
4234
|
-
persona:
|
|
4235
|
-
action:
|
|
4236
|
-
feedback:
|
|
4285
|
+
slotId: z26.string().min(1).max(128).describe("The slot id of the version under review"),
|
|
4286
|
+
persona: z26.string().min(1).max(64).describe("The persona key of the version under review"),
|
|
4287
|
+
action: z26.enum(["approve", "reject"]),
|
|
4288
|
+
feedback: z26.string().max(2e3).optional().describe("On reject: what was wrong, in the user's words. The next version written for that square is told to address it.")
|
|
4237
4289
|
},
|
|
4238
4290
|
outputSchema: {
|
|
4239
|
-
slotId:
|
|
4240
|
-
persona:
|
|
4241
|
-
action:
|
|
4242
|
-
status:
|
|
4243
|
-
armId:
|
|
4291
|
+
slotId: z26.string(),
|
|
4292
|
+
persona: z26.string(),
|
|
4293
|
+
action: z26.enum(["approve", "reject"]),
|
|
4294
|
+
status: z26.string().describe("live (approved, or a rejected refinement whose incumbent keeps serving) | rejected"),
|
|
4295
|
+
armId: z26.string().nullable().describe("The published option id, on approval"),
|
|
4244
4296
|
blocked: blockedOutput
|
|
4245
4297
|
},
|
|
4246
4298
|
annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }
|
|
@@ -4269,7 +4321,7 @@ function registerCellTools(server, client) {
|
|
|
4269
4321
|
}
|
|
4270
4322
|
|
|
4271
4323
|
// src/tools/agent-reads.ts
|
|
4272
|
-
import { z as
|
|
4324
|
+
import { z as z27 } from "zod/v3";
|
|
4273
4325
|
var READ_ONLY = { readOnlyHint: true, idempotentHint: true, openWorldHint: false };
|
|
4274
4326
|
var AREA_NAMES = {
|
|
4275
4327
|
generate: "Generate",
|
|
@@ -4321,15 +4373,15 @@ function registerAgentReadTools(server, client) {
|
|
|
4321
4373
|
description: "See which areas of this project a person has allowed agents to change: Generate, Approve and publish, Run tests, Goals and funnels, Campaigns and audiences, Project settings. Reading is always allowed; this tells you what a write tool will be refused for before you try it. Agents cannot change these switches \u2014 only a person can, in Settings \u2192 Agent access.",
|
|
4322
4374
|
inputSchema: { projectId: projectIdSchema },
|
|
4323
4375
|
outputSchema: {
|
|
4324
|
-
areas:
|
|
4325
|
-
generate:
|
|
4326
|
-
approve:
|
|
4327
|
-
tests:
|
|
4328
|
-
goals:
|
|
4329
|
-
campaigns:
|
|
4330
|
-
settings:
|
|
4376
|
+
areas: z27.object({
|
|
4377
|
+
generate: z27.boolean(),
|
|
4378
|
+
approve: z27.boolean(),
|
|
4379
|
+
tests: z27.boolean(),
|
|
4380
|
+
goals: z27.boolean(),
|
|
4381
|
+
campaigns: z27.boolean(),
|
|
4382
|
+
settings: z27.boolean()
|
|
4331
4383
|
}).describe("true = agents may act in this area"),
|
|
4332
|
-
canEdit:
|
|
4384
|
+
canEdit: z27.boolean().describe("Whether THIS credential could change the switches (always false for an agent)")
|
|
4333
4385
|
},
|
|
4334
4386
|
annotations: READ_ONLY
|
|
4335
4387
|
},
|
|
@@ -4356,35 +4408,35 @@ function registerAgentReadTools(server, client) {
|
|
|
4356
4408
|
description: "List this project's named campaigns, their retargeting groups, and the campaigns seen in traffic. Pass campaignId to get one campaign's card instead: clicks, new people, how many came back, conversions per version, and the control group (visitors held back on the original site). Counts only \u2014 no lift is claimed." + UNTRUSTED_FIELDS_NOTE,
|
|
4357
4409
|
inputSchema: __spreadValues({
|
|
4358
4410
|
projectId: projectIdSchema,
|
|
4359
|
-
campaignId:
|
|
4411
|
+
campaignId: z27.string().optional().describe("A campaign id from this tool's list; returns that campaign's card")
|
|
4360
4412
|
}, rangeInputSchema("30d")),
|
|
4361
4413
|
outputSchema: {
|
|
4362
|
-
campaigns:
|
|
4363
|
-
id:
|
|
4364
|
-
name:
|
|
4365
|
-
status:
|
|
4366
|
-
arrivalType:
|
|
4367
|
-
landingPaths:
|
|
4414
|
+
campaigns: z27.array(z27.object({
|
|
4415
|
+
id: z27.string(),
|
|
4416
|
+
name: z27.string(),
|
|
4417
|
+
status: z27.string().nullable(),
|
|
4418
|
+
arrivalType: z27.string().nullable(),
|
|
4419
|
+
landingPaths: z27.array(z27.string())
|
|
4368
4420
|
})).optional(),
|
|
4369
|
-
retargeting:
|
|
4370
|
-
groupId:
|
|
4371
|
-
campaignId:
|
|
4372
|
-
name:
|
|
4373
|
-
status:
|
|
4374
|
-
endsAt:
|
|
4375
|
-
memberCount:
|
|
4421
|
+
retargeting: z27.array(z27.object({
|
|
4422
|
+
groupId: z27.string(),
|
|
4423
|
+
campaignId: z27.string().nullable(),
|
|
4424
|
+
name: z27.string(),
|
|
4425
|
+
status: z27.string().nullable(),
|
|
4426
|
+
endsAt: z27.string().nullable(),
|
|
4427
|
+
memberCount: z27.number()
|
|
4376
4428
|
})).optional(),
|
|
4377
|
-
observed:
|
|
4378
|
-
card:
|
|
4379
|
-
campaignId:
|
|
4380
|
-
name:
|
|
4381
|
-
status:
|
|
4382
|
-
clicks:
|
|
4383
|
-
people:
|
|
4384
|
-
cameBack:
|
|
4385
|
-
controlGroup:
|
|
4386
|
-
versions:
|
|
4387
|
-
retargetingGroupId:
|
|
4429
|
+
observed: z27.array(z27.object({ campaign: z27.string(), sessions: z27.number(), channel: z27.string().nullable() })).optional(),
|
|
4430
|
+
card: z27.object({
|
|
4431
|
+
campaignId: z27.string(),
|
|
4432
|
+
name: z27.string(),
|
|
4433
|
+
status: z27.string().nullable(),
|
|
4434
|
+
clicks: z27.number(),
|
|
4435
|
+
people: z27.number().describe("New people served as the campaign"),
|
|
4436
|
+
cameBack: z27.number(),
|
|
4437
|
+
controlGroup: z27.number().describe("Matched visits held back on the original site"),
|
|
4438
|
+
versions: z27.array(z27.object({ label: z27.string(), shown: z27.number(), conversions: z27.number() })).describe("Per section and version; one visitor can appear in several rows, so do not add them up"),
|
|
4439
|
+
retargetingGroupId: z27.string().nullable()
|
|
4388
4440
|
}).optional().describe("Only when campaignId was given")
|
|
4389
4441
|
},
|
|
4390
4442
|
annotations: READ_ONLY
|
|
@@ -4467,17 +4519,17 @@ function registerAgentReadTools(server, client) {
|
|
|
4467
4519
|
{
|
|
4468
4520
|
title: "Retargeting report",
|
|
4469
4521
|
description: "One retargeting group's numbers: how many people it started with, how many came back, clicks and conversions. These are counts, not lift. Get the group id from list_campaigns." + UNTRUSTED_FIELDS_NOTE,
|
|
4470
|
-
inputSchema: { projectId: projectIdSchema, groupId:
|
|
4522
|
+
inputSchema: { projectId: projectIdSchema, groupId: z27.string().describe("A retargeting group id from list_campaigns") },
|
|
4471
4523
|
outputSchema: {
|
|
4472
|
-
groupId:
|
|
4473
|
-
name:
|
|
4474
|
-
status:
|
|
4475
|
-
endsAt:
|
|
4476
|
-
members:
|
|
4477
|
-
cameBack:
|
|
4478
|
-
converted:
|
|
4479
|
-
clicks:
|
|
4480
|
-
versions:
|
|
4524
|
+
groupId: z27.string(),
|
|
4525
|
+
name: z27.string(),
|
|
4526
|
+
status: z27.string().nullable(),
|
|
4527
|
+
endsAt: z27.string().nullable(),
|
|
4528
|
+
members: z27.number(),
|
|
4529
|
+
cameBack: z27.number(),
|
|
4530
|
+
converted: z27.number(),
|
|
4531
|
+
clicks: z27.number(),
|
|
4532
|
+
versions: z27.array(z27.object({ label: z27.string(), shown: z27.number(), conversions: z27.number() }))
|
|
4481
4533
|
},
|
|
4482
4534
|
annotations: READ_ONLY
|
|
4483
4535
|
},
|
|
@@ -4514,20 +4566,20 @@ function registerAgentReadTools(server, client) {
|
|
|
4514
4566
|
description: "The audiences visitors are sorted into: the ones the site declares, the ones discovered from behaviour (with how many sessions, their share of traffic, and how much evidence there is), and whether the discovered set can be promoted to serving yet, with what is blocking it in plain words." + UNTRUSTED_FIELDS_NOTE,
|
|
4515
4567
|
inputSchema: { projectId: projectIdSchema },
|
|
4516
4568
|
outputSchema: {
|
|
4517
|
-
declared:
|
|
4518
|
-
source:
|
|
4519
|
-
members:
|
|
4569
|
+
declared: z27.object({
|
|
4570
|
+
source: z27.string().nullable(),
|
|
4571
|
+
members: z27.array(z27.object({ key: z27.string(), displayName: z27.string(), status: z27.string().nullable() }))
|
|
4520
4572
|
}).nullable(),
|
|
4521
|
-
discovered:
|
|
4522
|
-
members:
|
|
4523
|
-
key:
|
|
4524
|
-
displayName:
|
|
4525
|
-
sessions:
|
|
4526
|
-
share:
|
|
4527
|
-
evidence:
|
|
4573
|
+
discovered: z27.object({
|
|
4574
|
+
members: z27.array(z27.object({
|
|
4575
|
+
key: z27.string(),
|
|
4576
|
+
displayName: z27.string(),
|
|
4577
|
+
sessions: z27.number().nullable(),
|
|
4578
|
+
share: z27.number().nullable(),
|
|
4579
|
+
evidence: z27.string().describe("strong_evidence | moderate_evidence | no_clear_difference | not_enough_data | not_checked_yet")
|
|
4528
4580
|
}))
|
|
4529
4581
|
}).nullable().describe("null when no discovered set exists yet"),
|
|
4530
|
-
promotion:
|
|
4582
|
+
promotion: z27.object({ eligible: z27.boolean(), blockers: z27.array(z27.string()) }).nullable()
|
|
4531
4583
|
},
|
|
4532
4584
|
annotations: READ_ONLY
|
|
4533
4585
|
},
|
|
@@ -4593,18 +4645,18 @@ function registerAgentReadTools(server, client) {
|
|
|
4593
4645
|
description: "The styles captured from the site (what generated sections borrow), grouped by role, whether their colors were actually measured, when the scan last ran, and the site audit score. Without measured colors a style cannot be checked for readable contrast." + UNTRUSTED_FIELDS_NOTE,
|
|
4594
4646
|
inputSchema: { projectId: projectIdSchema },
|
|
4595
4647
|
outputSchema: {
|
|
4596
|
-
colorsMeasured:
|
|
4597
|
-
roles:
|
|
4598
|
-
role:
|
|
4599
|
-
count:
|
|
4600
|
-
measuredColors:
|
|
4648
|
+
colorsMeasured: z27.boolean().describe("false when no captured style has a measured text or background color"),
|
|
4649
|
+
roles: z27.array(z27.object({
|
|
4650
|
+
role: z27.string(),
|
|
4651
|
+
count: z27.number(),
|
|
4652
|
+
measuredColors: z27.number().describe("How many of these styles have a measured color")
|
|
4601
4653
|
})),
|
|
4602
|
-
lastScan:
|
|
4603
|
-
audit:
|
|
4604
|
-
status:
|
|
4605
|
-
score:
|
|
4606
|
-
auditedAt:
|
|
4607
|
-
checking:
|
|
4654
|
+
lastScan: z27.object({ editorAt: z27.string().nullable(), crawlAt: z27.string().nullable() }),
|
|
4655
|
+
audit: z27.object({
|
|
4656
|
+
status: z27.string().nullable(),
|
|
4657
|
+
score: z27.number().nullable(),
|
|
4658
|
+
auditedAt: z27.string().nullable(),
|
|
4659
|
+
checking: z27.boolean()
|
|
4608
4660
|
}).nullable().describe("null when the audit could not be read")
|
|
4609
4661
|
},
|
|
4610
4662
|
annotations: READ_ONLY
|
|
@@ -4660,13 +4712,13 @@ function registerAgentReadTools(server, client) {
|
|
|
4660
4712
|
{
|
|
4661
4713
|
title: "Region history",
|
|
4662
4714
|
description: "A region's published versions over time (newest first, which one is live) and whether the region is still found on the live page. Get the region id from list_components." + UNTRUSTED_FIELDS_NOTE,
|
|
4663
|
-
inputSchema: { projectId: projectIdSchema, regionId:
|
|
4715
|
+
inputSchema: { projectId: projectIdSchema, regionId: z27.string().describe("The region's id (the slot id shown by list_components)") },
|
|
4664
4716
|
outputSchema: {
|
|
4665
|
-
regionId:
|
|
4666
|
-
currentVersion:
|
|
4667
|
-
versions:
|
|
4668
|
-
recentDecisions:
|
|
4669
|
-
drift:
|
|
4717
|
+
regionId: z27.string(),
|
|
4718
|
+
currentVersion: z27.number(),
|
|
4719
|
+
versions: z27.array(z27.object({ version: z27.number(), publishedAt: z27.string().nullable(), isCurrent: z27.boolean() })),
|
|
4720
|
+
recentDecisions: z27.array(z27.object({ action: z27.string(), at: z27.string().nullable() })),
|
|
4721
|
+
drift: z27.object({ verdict: z27.string(), message: z27.string(), checkedUrl: z27.string().nullable() }).nullable().describe("Whether the region is still found on the live page; null when the check could not run")
|
|
4670
4722
|
},
|
|
4671
4723
|
annotations: READ_ONLY
|
|
4672
4724
|
},
|
|
@@ -4700,7 +4752,7 @@ function registerAgentReadTools(server, client) {
|
|
|
4700
4752
|
}
|
|
4701
4753
|
|
|
4702
4754
|
// src/tools/manage.ts
|
|
4703
|
-
import { z as
|
|
4755
|
+
import { z as z28 } from "zod/v3";
|
|
4704
4756
|
var a = (method, route, extra = {}) => __spreadValues({ method, route }, extra);
|
|
4705
4757
|
var ACTIONS = {
|
|
4706
4758
|
manage_generation: {
|
|
@@ -4809,7 +4861,9 @@ var ACTIONS = {
|
|
|
4809
4861
|
// the only thing in the way of "keep our staging site out of the numbers".
|
|
4810
4862
|
set_internal_sites: a("PUT", "internal-traffic/origins", { body: "req" }),
|
|
4811
4863
|
add_internal_email: a("POST", "internal-traffic/emails", { body: "req" }),
|
|
4812
|
-
remove_internal_email: a("DELETE", "internal-traffic/emails", { body: "req" })
|
|
4864
|
+
remove_internal_email: a("DELETE", "internal-traffic/emails", { body: "req" }),
|
|
4865
|
+
// Which parts of the site are before and after sign-up (2026-11-21).
|
|
4866
|
+
set_site_areas: a("PUT", "site-areas", { body: "req" })
|
|
4813
4867
|
}
|
|
4814
4868
|
};
|
|
4815
4869
|
var REFUSAL_NOTE = " If this project has turned off agent access for this area, the call is refused with a sentence saying so \u2014 tell the user, don't retry.";
|
|
@@ -4837,12 +4891,12 @@ var TOOLS = {
|
|
|
4837
4891
|
manage_campaigns: {
|
|
4838
4892
|
title: "Manage campaigns and audiences",
|
|
4839
4893
|
destructive: true,
|
|
4840
|
-
description:
|
|
4894
|
+
description: 'Manage campaigns, retargeting and audiences: create, update or tag campaigns, start retargeting and change its group, declare or edit audiences, promote or roll back the discovered audiences, promote labels, and set the shopping-stage settings, search categories and stage serving. Promote and roll back change who sees what. A declared audience carries a side of sign-up (declare_audiences / update_audience with side "before" or "after"; default after \u2014 see get_site_areas). Pick one `action`; pass the ids it needs.' + REFUSAL_NOTE
|
|
4841
4895
|
},
|
|
4842
4896
|
manage_settings: {
|
|
4843
4897
|
title: "Manage project settings",
|
|
4844
4898
|
destructive: true,
|
|
4845
|
-
description: 'Change project settings: rename or edit the project, remove an allowed origin, add, remove or test a webhook, remove a captured style, rescan the site, set page meaning, create, refresh or remove a report share link, set previews and the layout and slot models, send a test event, and accept, dismiss or save a structured insight. Also who counts as already converted: set_gate_settings (body { identifiedIsConverted: boolean } \u2014 true only when reaching the main goal is what creates the account, i.e. the main goal is sign-up; not available on stores) and import_known_people (body { people: [{ userId, convertedAt?, converted?, orderCount?, totalSpent?, currency?, lastOrderAt?, customerSince?, tags? }] }, at most 2000 per call \u2014 the site\'s own user ids for people who already reached the main goal; never names, emails, phone numbers or addresses, which are refused). Who counts as your team or a test site (Settings \u2192 Internal traffic; read the rules first with get_internal_traffic_rules): set_internal_sites (body { origins: [...] } \u2014 the WHOLE list of internal sites, each one already an allowed origin; an origin left out stops being internal), add_internal_email (body { value } \u2014 a team email domain such as "@acme.com", or one exact address, which is stored only as a hash) and remove_internal_email (body { domain } or { hash } from get_internal_traffic_rules). Internal visits still see versions but never count or teach the optimizer, from the moment a rule is on; earlier visits are separated where the rule can tell. Confirm the list with the user first. Removals cannot be undone. The three insight actions (accept_insight, dismiss_insight, save_insight) are always allowed: the Project settings switch does not govern them. Pick one `action`; pass the ids it needs.' + REFUSAL_NOTE
|
|
4899
|
+
description: 'Change project settings: rename or edit the project, remove an allowed origin, add, remove or test a webhook, remove a captured style, rescan the site, set page meaning, create, refresh or remove a report share link, set previews and the layout and slot models, send a test event, and accept, dismiss or save a structured insight. Also who counts as already converted: set_gate_settings (body { identifiedIsConverted: boolean } \u2014 true only when reaching the main goal is what creates the account, i.e. the main goal is sign-up; not available on stores) and import_known_people (body { people: [{ userId, convertedAt?, converted?, orderCount?, totalSpent?, currency?, lastOrderAt?, customerSince?, tags? }] }, at most 2000 per call \u2014 the site\'s own user ids for people who already reached the main goal; never names, emails, phone numbers or addresses, which are refused). Who counts as your team or a test site (Settings \u2192 Internal traffic; read the rules first with get_internal_traffic_rules): set_internal_sites (body { origins: [...] } \u2014 the WHOLE list of internal sites, each one already an allowed origin; an origin left out stops being internal), add_internal_email (body { value } \u2014 a team email domain such as "@acme.com", or one exact address, which is stored only as a hash) and remove_internal_email (body { domain } or { hash } from get_internal_traffic_rules). Internal visits still see versions but never count or teach the optimizer, from the moment a rule is on; earlier visits are separated where the rule can tell. Confirm the list with the user first. Removals cannot be undone. Which parts of the site are before and after sign-up (read first with get_site_areas): set_site_areas (body { areas: [{ origin, path?, side: "before" | "after" }] } \u2014 the WHOLE list, each origin an allowed site; [] removes the split). Components then get versions only for audiences of their own side; confirm with the user first. The three insight actions (accept_insight, dismiss_insight, save_insight) are always allowed: the Project settings switch does not govern them. Pick one `action`; pass the ids it needs.' + REFUSAL_NOTE
|
|
4846
4900
|
}
|
|
4847
4901
|
};
|
|
4848
4902
|
var pathParams = (route) => [...route.matchAll(/:([A-Za-z]+)/g)].map((m) => m[1]);
|
|
@@ -4860,13 +4914,13 @@ function registerManageTools(server, client) {
|
|
|
4860
4914
|
const meta = TOOLS[tool];
|
|
4861
4915
|
const shape = {
|
|
4862
4916
|
projectId: projectIdSchema,
|
|
4863
|
-
action:
|
|
4864
|
-
enabled:
|
|
4865
|
-
body:
|
|
4917
|
+
action: z28.enum(names).describe("What to do. Each action needs only the fields noted below."),
|
|
4918
|
+
enabled: z28.boolean().optional().describe("For set_auto_fill, set_require_approval, set_observation_mode: on (true) or off (false)"),
|
|
4919
|
+
body: z28.record(z28.unknown()).optional().describe("The fields to send, for actions that change several things at once; the API checks them and says what's wrong")
|
|
4866
4920
|
};
|
|
4867
|
-
if (tool === "manage_generation") shape.depth =
|
|
4868
|
-
if (tool === "manage_settings") shape.origin =
|
|
4869
|
-
for (const p of paramNames(tool)) shape[p] =
|
|
4921
|
+
if (tool === "manage_generation") shape.depth = z28.enum(["auto", "rewrite", "redesign"]).optional().describe("For set_depth: how far a rewrite may go");
|
|
4922
|
+
if (tool === "manage_settings") shape.origin = z28.string().optional().describe("For remove_origin: the origin to stop allowing, e.g. https://example.com");
|
|
4923
|
+
for (const p of paramNames(tool)) shape[p] = z28.string().optional().describe(`Required by the actions whose route has :${p}`);
|
|
4870
4924
|
server.registerTool(
|
|
4871
4925
|
tool,
|
|
4872
4926
|
{
|
|
@@ -4928,6 +4982,8 @@ userId must be the id the site identifies the visitor with (<AdaptiveRoot userId
|
|
|
4928
4982
|
|
|
4929
4983
|
Excluding the team and test sites (dashboard Settings -> Internal traffic): visits marked internal still see versions (QA works) but never count in any report and never teach the optimizer; get_traffic_breakdown lists them as "Your team / test sites". They are marked by internal sites (allowed domains such as staging or localhost), team emails and domains (they match visitors the site identifies with identify(userId, { email }); the SDK sends only a SHA-256 of the address and its domain, never the address), a browser link, or the code flag (the internal prop on <AdaptiveRoot>/<AdaptiveProvider>, init({ internal }), window.sentient.internal). There is no report filter or IP rule, and visits from before a rule was turned on cannot be separated. Read the rules with get_internal_traffic_rules; change them with manage_settings set_internal_sites / add_internal_email / remove_internal_email (Agent access: Project settings), after confirming the list with the user.
|
|
4930
4984
|
|
|
4985
|
+
Two sides of sign-up (dashboard Settings -> Site areas; read with get_site_areas): before sign-up the visitor is anonymous and the goal is to convert them; after sign-up the visitor is inside the product and known. Once a project splits its site, a component gets versions only for audiences of its own side: campaign, arrival and retargeting audiences are before sign-up, declared personas after (unless declared for before), discovered groups wherever their visits happen. A version, pin or approval across the line is refused (error other_side) \u2014 pick an audience of the component's side instead of retrying.
|
|
4986
|
+
|
|
4931
4987
|
The main funnel (get_main_funnel): "how is my funnel doing" is answered by the one journey that ends at the project's main goal \u2014 Arrived, the marketer's own steps, the main goal \u2014 counted in people, with those who had already converted left out. It is chosen with manage_goals set_main_funnel and must end at the main goal; with none chosen it is just Arrived -> main goal. Stores get their checkout journey as the main funnel on connect. Use get_funnel_report only for a side journey: it counts one funnel's goals inside a window and includes people who had already converted, so its numbers and the main funnel's do not add up.
|
|
4932
4988
|
|
|
4933
4989
|
Page groups (get_page_groups): "what runs where" is answered by page groups \u2014 the site's pages under names a marketer uses (Home, Product pages, Pricing), each placed on the main funnel, with the people who viewed them and the components and layouts that ran there. A component's place is where it was actually shown; a header shown everywhere is site-wide. A group's placement only organises the view: where a PERSON is in the funnel comes from get_main_funnel. Until a list is saved (manage_goals set_page_groups) the tool returns a suggestion.
|
|
@@ -4937,7 +4993,7 @@ Known people (get_known_people): a person is "known" once they have reached the
|
|
|
4937
4993
|
Write tools change what real visitors see: confirm with the user first. Call get_agent_access before a manage_* write.`;
|
|
4938
4994
|
|
|
4939
4995
|
// src/server.ts
|
|
4940
|
-
var PKG_VERSION = true ? "0.
|
|
4996
|
+
var PKG_VERSION = true ? "0.30.0" : "0.0.0-dev";
|
|
4941
4997
|
function createMcpServer(client) {
|
|
4942
4998
|
const server = new McpServer(
|
|
4943
4999
|
{
|
|
@@ -4985,6 +5041,7 @@ function createMcpServer(client) {
|
|
|
4985
5041
|
registerAgentTrafficTools(server, client);
|
|
4986
5042
|
registerTrafficTools(server, client);
|
|
4987
5043
|
registerInternalTrafficTools(server, client);
|
|
5044
|
+
registerSiteAreasTools(server, client);
|
|
4988
5045
|
registerCellTools(server, client);
|
|
4989
5046
|
registerAgentReadTools(server, client);
|
|
4990
5047
|
registerManageTools(server, client);
|