@sentientui/mcp 0.16.0 → 0.17.1

package/AGENTS.md

@@ -33,7 +33,7 @@ Server keys start with `sk_` — required for the management API. Public keys (`
 | `create_project` | Onboard a new user: creates a project + returns its `pk_` key. Needs an account login (OAuth) — refuses `sk_` project keys and demo tokens. Follow with `get_integration_guide` |
 | `get_project_stats` | Health status + 24h event/session volume |
 | `list_components` | Components + variant counts + impression totals |
-| `get_variant_performance` | CVR 7d vs prior 7d + momentum direction |
+| `get_variant_performance` | CVR current vs prior window + momentum (range/from/to params; default 7d) |
 | `get_persona_breakdown` | Cluster distribution + avg reliability per cluster |
 | `get_goal_funnel` | Goal hit counts + per-variant completion rates |
 | `list_guardrail_events` | Auto-paused variants (last 24h) |

package/README.md

@@ -88,11 +88,11 @@ A sandboxed demo token is provisioned automatically — 10 calls/month, read-onl
 | `create_project` | Create a new project and return its `pk_` public key (account login required — not usable with an `sk_` project key or demo token) |
 | `get_project_stats` | Events, sessions, agent calls, and health status |
 | `list_components` | All adaptive components with variant counts |
-| `get_variant_performance` | CVR, momentum, and impressions per variant (7d vs prior 7d) |
+| `get_variant_performance` | CVR, momentum, and impressions per variant (windowed: range 7d/30d/90d/all or from/to; default 7d vs prior 7d) |
 | `get_insights` | AI-generated narrator observations and advisor recommendations |
 | `refresh_insights` | Trigger fresh AI insight generation |
 | `get_persona_breakdown` | Visitor cluster distribution with reliability scores |
-| `get_goal_funnel` | Goal hit counts and conversion rates per variant |
+| `get_goal_funnel` | Goal hit counts and conversion rates per variant (windowed; default 30d) |
 | `list_goals` | Defined goals (id, role, event, status) — includes goals with no conversions yet, so agents can wire a dashboard-defined goal into code |
 | `list_guardrail_events` | Variants auto-paused by the guardrail (last 24h) |
 | `get_layout_stats` | Per-persona section layout rankings and reward weights |

package/dist/{chunk-SUMKFRQP.js → chunk-KT2ZKW7I.js}

@@ -199,7 +199,11 @@ var RENDER_JS = {
   "variant-performance": `
     window.__render = function(data){
       var variants = (data && data.variants) || [];
-      el('sub').textContent = variants.length + ' variant' + (variants.length === 1 ? '' : 's') + ' \xB7 conversion, last 7 days vs prior 7';
+      var winText = 'current vs prior period';
+      if (data && data.window && data.window.start && data.window.end) {
+        winText = String(data.window.start).slice(0, 10) + ' to ' + String(data.window.end).slice(0, 10) + ' vs prior period';
+      }
+      el('sub').textContent = variants.length + ' variant' + (variants.length === 1 ? '' : 's') + ' \xB7 conversion, ' + winText;
       if (!variants.length) { showEmpty('No variant data available yet.'); return; }
       var max = variants.reduce(function(m,v){ return Math.max(m, v.currentCvr || 0); }, 0) || 1;
       var sorted = variants.slice().sort(function(a,b){ return (b.currentCvr||0) - (a.currentCvr||0); });
@@ -331,6 +335,44 @@ import { z as z2 } from "zod";
 // src/tools/common.ts
 import { z } from "zod";
 var projectIdSchema = z.string().uuid().describe("The project UUID");
+function rangeInputSchema(defaultRange) {
+  return {
+    range: z.enum(["7d", "30d", "90d", "all"]).optional().describe(
+      `Calendar window in the project's reporting timezone (default ${defaultRange}). 'all' means all retained data \u2014 the plan's retention window bounds every lookback.`
+    ),
+    from: z.string().optional().describe(
+      "Custom window start (YYYY-MM-DD; overrides range). Must be within the plan retention window."
+    ),
+    to: z.string().optional().describe("Custom window end (YYYY-MM-DD, inclusive; default today).")
+  };
+}
+function rangeQuery(args) {
+  const p = new URLSearchParams();
+  if (args.from) {
+    p.set("from", args.from);
+    if (args.to) p.set("to", args.to);
+  } else if (args.range) {
+    p.set("range", args.range);
+  }
+  const s = p.toString();
+  return s ? `?${s}` : "";
+}
+var windowOutputSchema = z.object({
+  range: z.string(),
+  start: z.string().nullable(),
+  end: z.string().nullable(),
+  timezone: z.string(),
+  bucketUnit: z.string(),
+  retentionDays: z.number().describe("The plan's effective data retention in days"),
+  earliestAvailable: z.string().describe("First date retention still holds data for (YYYY-MM-DD)")
+}).optional().describe("The window the server actually used for every count in this response");
+function windowLine(window) {
+  if (!window) return "";
+  if (window.start && window.end) {
+    return `Window: ${window.start.slice(0, 10)} to ${window.end.slice(0, 10)} (${window.timezone}, exclusive end)`;
+  }
+  return `Window: all retained data (${window.retentionDays}-day retention)`;
+}
 function apiErrorGuidance(err, extra) {
   if (extra && Object.prototype.hasOwnProperty.call(extra, err.message)) {
     return extra[err.message];
@@ -345,6 +387,12 @@ function apiErrorGuidance(err, extra) {
     default:
       break;
   }
+  if (err.message === "range_out_of_retention") {
+    return "The requested window starts before this plan retains data \u2014 older events have been deleted by the retention purge and cannot be recovered. Ask for a more recent window, or upgrade the SentientUI plan for longer history (Growth keeps 180 days, Scale 365).";
+  }
+  if (err.message === "invalid_range") {
+    return "Invalid time window. Use range '7d', '30d', '90d' or 'all', or from/to as YYYY-MM-DD dates.";
+  }
   if (err.status === 402) {
     return `This feature requires a higher plan (${err.message}). Upgrade your SentientUI plan, then try again.`;
   }
@@ -516,8 +564,8 @@ function registerComponentTools(server, client) {
     "list_components",
     {
       title: "List components",
-      description: "List all adaptive components in a project with variant counts and impression totals.",
-      inputSchema: { projectId: projectIdSchema },
+      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.",
+      inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("all")),
       outputSchema: {
         components: z3.array(
           z3.object({
@@ -526,7 +574,8 @@ function registerComponentTools(server, client) {
             impressions: z3.number(),
             conversions: z3.number()
           })
-        ).describe("Adaptive components in the project (empty if none)")
+        ).describe("Adaptive components in the project (empty if none)"),
+        window: windowOutputSchema
       },
       annotations: {
         readOnlyHint: true,
@@ -534,16 +583,17 @@ function registerComponentTools(server, client) {
         openWorldHint: false
       }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, range, from, to }) => {
       const id = encodeURIComponent(projectId);
-      const { components } = await client.get(`/projects/${id}/components`);
+      const { components, window } = await client.get(`/projects/${id}/components${rangeQuery({ range, from, to })}`);
       const structuredContent = {
         components: components.map((c) => ({
           componentId: c.component_id,
           variantCount: c.variants.length,
           impressions: c.total_impressions,
           conversions: c.total_conversions
-        }))
+        })),
+        window
       };
       if (!components.length) {
         return {
@@ -561,19 +611,20 @@ function registerComponentTools(server, client) {
     "get_variant_performance",
     {
       title: "Variant performance",
-      description: "Get CVR and momentum for all variants in a project over the last 7 days vs prior 7 days.",
-      inputSchema: { projectId: projectIdSchema },
+      description: "Get CVR and momentum for all variants in a project over the selected window vs the immediately-preceding window of equal length (default: last 7 calendar days vs prior 7).",
+      inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("7d")),
       _meta: uiMeta("variant-performance"),
       outputSchema: {
         variants: z3.array(
           z3.object({
             variantId: z3.string(),
-            currentCvr: z3.number().describe("Conversion rate over the last 7 days (0-1)"),
-            priorCvr: z3.number().describe("Conversion rate over the prior 7 days (0-1)"),
+            currentCvr: z3.number().describe("Conversion rate over the selected window (0-1)"),
+            priorCvr: z3.number().describe("Conversion rate over the preceding window (0-1)"),
             deltaPp: z3.number().describe("Change in percentage points"),
             momentum: z3.string().describe("Momentum direction: gaining, losing, or stable")
           })
-        ).describe("Per-variant performance (empty if no data yet)")
+        ).describe("Per-variant performance (empty if no data yet)"),
+        window: windowOutputSchema
       },
       annotations: {
         readOnlyHint: true,
@@ -581,10 +632,10 @@ function registerComponentTools(server, client) {
         openWorldHint: false
       }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, range, from, to }) => {
       var _a, _b, _c;
       const id = encodeURIComponent(projectId);
-      const data = await client.get(`/projects/${id}/trends`);
+      const data = await client.get(`/projects/${id}/trends${rangeQuery({ range, from, to })}`);
       const momentumMap = new Map(((_a = data.momentum) != null ? _a : []).map((m) => [m.variantId, m.direction]));
       const structuredContent = {
         variants: ((_b = data.cvr) != null ? _b : []).map((v) => {
@@ -596,7 +647,8 @@ function registerComponentTools(server, client) {
             deltaPp: v.deltaPp,
             momentum: (_a2 = momentumMap.get(v.variantId)) != null ? _a2 : "stable"
           };
-        })
+        }),
+        window: data.window
       };
       if (!((_c = data.cvr) == null ? void 0 : _c.length)) {
         return {
@@ -605,12 +657,14 @@ function registerComponentTools(server, client) {
           _meta: uiMeta("variant-performance")
         };
       }
-      const text = data.cvr.map(
+      const lines = data.cvr.map(
         (v) => {
           var _a2;
           return `- ${v.variantId}: CVR ${(v.currentCvr * 100).toFixed(2)}% (prior ${(v.priorCvr * 100).toFixed(2)}%, ${v.deltaPp > 0 ? "+" : ""}${v.deltaPp.toFixed(1)} pp, ${(_a2 = momentumMap.get(v.variantId)) != null ? _a2 : "stable"})`;
         }
-      ).join("\n");
+      );
+      const win = windowLine(data.window);
+      const text = (win ? [win, ...lines] : lines).join("\n");
       return { content: [{ type: "text", text }], structuredContent, _meta: uiMeta("variant-performance") };
     })
   );
@@ -796,8 +850,8 @@ function registerGoalTools(server, client) {
     "get_goal_funnel",
     {
       title: "Goal funnel",
-      description: "Get goal hit counts, unique-session conversion rates, and per-variant breakdown. This is a flat per-goal list \u2014 for multi-step funnel drop-off, use get_funnel_report.",
-      inputSchema: { projectId: projectIdSchema },
+      description: "Get goal hit counts, unique-session conversion rates, and per-variant breakdown (default window: last 30 calendar days). This is a flat per-goal list \u2014 for multi-step funnel drop-off, use get_funnel_report.",
+      inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("30d")),
       _meta: uiMeta("goal-funnel"),
       outputSchema: {
         currency: z6.string().describe("Project display currency (ISO-4217) for the revenue fields"),
@@ -818,7 +872,8 @@ function registerGoalTools(server, client) {
               })
             ).describe("Per-variant breakdown")
           })
-        ).describe("Configured goals (empty if none)")
+        ).describe("Configured goals (empty if none)"),
+        window: windowOutputSchema
       },
       annotations: {
         readOnlyHint: true,
@@ -826,11 +881,12 @@ function registerGoalTools(server, client) {
         openWorldHint: false
       }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, range, from, to }) => {
       var _a, _b;
       const id = encodeURIComponent(projectId);
-      const data = await client.get(`/projects/${id}/goals`);
+      const data = await client.get(`/projects/${id}/goals${rangeQuery({ range, from, to })}`);
       const structuredContent = {
+        window: data.window,
         currency: (_a = data.currency) != null ? _a : "USD",
         goals: data.goals.map((g) => {
           var _a2, _b2, _c;
@@ -858,6 +914,7 @@ function registerGoalTools(server, client) {
         };
       }
       const currency = (_b = data.currency) != null ? _b : "USD";
+      const win = windowLine(data.window);
       const lines = data.goals.flatMap((g) => {
         var _a2;
         return [
@@ -866,7 +923,8 @@ function registerGoalTools(server, client) {
           ""
         ];
       });
-      return { content: [{ type: "text", text: lines.join("\n").trim() }], structuredContent, _meta: uiMeta("goal-funnel") };
+      const text = (win ? [win, "", ...lines] : lines).join("\n").trim();
+      return { content: [{ type: "text", text }], structuredContent, _meta: uiMeta("goal-funnel") };
     })
   );
   server.registerTool(
@@ -1613,9 +1671,15 @@ function registerTestBriefTools(server, client) {
 import { z as z13 } from "zod";
 var GUIDE = `# SentientUI integration guide \u2014 the adaptive ladder
 
-SentientUI adapts a site per visitor type (personas: buyer, researcher, deal_seeker, browser,
-unknown), learning from real conversions. Decisions are locked per session: Visit 1 learns,
-Visit 2 converts. Integrate one rung at a time.
+SentientUI adapts a site per visitor type (personas), learning from real conversions. Each
+project has its own persona vocabulary (dashboard -> Settings -> Personas; the default is
+buyer, researcher, deal_seeker, browser + unknown). Personas are inferred from behavior \u2014 or
+DECLARED by the app when it already knows the visitor's role: init({ persona: 'admin' }) /
+<AdaptiveProvider persona=...> / window.sentient.persona. Declared beats inferred and serves
+at full confidence; unrecognized values are ignored server-side and surfaced in the dashboard
+so the operator can add them. Keep persona a low-cardinality role slug \u2014 never a user id.
+Decisions are locked per session: Visit 1 learns, Visit 2 converts. Integrate one rung at a
+time.
 
 ## Setup (60 seconds, no account)
 
@@ -1633,7 +1697,8 @@ Visit 2 converts. Integrate one rung at a time.
 
 ## Rung 1 \u2014 Style (CSS only)
 
-Persona attributes on <html> (zero declaration):
+Persona attributes on <html> (zero declaration; the attribute carries the project's own
+vocabulary keys \u2014 declared or inferred):
 
     html[data-sentient-persona='deal_seeker'] .discount-banner { display: block; }
     html[data-sentient-confidence='low'] .discount-banner { display: none; }
@@ -1710,8 +1775,12 @@ function registerAgentTrafficTools(server, client) {
     "get_agent_traffic",
     {
       title: "Agent traffic",
-      description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, agentic browsers, agent API calls), engine breakdown, and the paths they fetch most. Agent traffic is tracked separately and never counted in conversion rate.",
-      inputSchema: { projectId: projectIdSchema },
+      description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, agentic browsers, agent API calls), engine breakdown, and the paths they fetch most. Defaults to the last 30 days; pass from/to for a custom period (agent logs are retained 30 days on Free/Starter, 90 on Growth+). Agent traffic is tracked separately and never counted in conversion rate.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        from: z14.string().optional().describe("Period start (ISO 8601 date or timestamp). Defaults to 30 days ago."),
+        to: z14.string().optional().describe("Period end (ISO 8601 date or timestamp). Defaults to now.")
+      },
       outputSchema: {
         totals: z14.object({ crawler: z14.number(), api: z14.number(), browser: z14.number() }),
         engines: z14.array(
@@ -1729,9 +1798,14 @@ function registerAgentTrafficTools(server, client) {
       },
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, from, to }) => {
       const id = encodeURIComponent(projectId);
-      const s = await client.get(`/projects/${id}/agent-activity/summary`);
+      const qs = new URLSearchParams();
+      if (from) qs.set("from", from);
+      if (to) qs.set("to", to);
+      const s = await client.get(
+        `/projects/${id}/agent-activity/summary${qs.size > 0 ? `?${qs.toString()}` : ""}`
+      );
       const structuredContent = { totals: s.totals, engines: s.engines, intents: s.intents, topPaths: s.topPaths };
       const total = s.totals.crawler + s.totals.api + s.totals.browser;
       if (total === 0) {
@@ -1819,7 +1893,7 @@ function registerAgentTrafficTools(server, client) {
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.16.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.17.1" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new McpServer(
     {

package/dist/index.cjs

@@ -78,6 +78,44 @@ var import_zod2 = require("zod");
 // src/tools/common.ts
 var import_zod = require("zod");
 var projectIdSchema = import_zod.z.string().uuid().describe("The project UUID");
+function rangeInputSchema(defaultRange) {
+  return {
+    range: import_zod.z.enum(["7d", "30d", "90d", "all"]).optional().describe(
+      `Calendar window in the project's reporting timezone (default ${defaultRange}). 'all' means all retained data \u2014 the plan's retention window bounds every lookback.`
+    ),
+    from: import_zod.z.string().optional().describe(
+      "Custom window start (YYYY-MM-DD; overrides range). Must be within the plan retention window."
+    ),
+    to: import_zod.z.string().optional().describe("Custom window end (YYYY-MM-DD, inclusive; default today).")
+  };
+}
+function rangeQuery(args) {
+  const p = new URLSearchParams();
+  if (args.from) {
+    p.set("from", args.from);
+    if (args.to) p.set("to", args.to);
+  } else if (args.range) {
+    p.set("range", args.range);
+  }
+  const s = p.toString();
+  return s ? `?${s}` : "";
+}
+var windowOutputSchema = import_zod.z.object({
+  range: import_zod.z.string(),
+  start: import_zod.z.string().nullable(),
+  end: import_zod.z.string().nullable(),
+  timezone: import_zod.z.string(),
+  bucketUnit: import_zod.z.string(),
+  retentionDays: import_zod.z.number().describe("The plan's effective data retention in days"),
+  earliestAvailable: import_zod.z.string().describe("First date retention still holds data for (YYYY-MM-DD)")
+}).optional().describe("The window the server actually used for every count in this response");
+function windowLine(window) {
+  if (!window) return "";
+  if (window.start && window.end) {
+    return `Window: ${window.start.slice(0, 10)} to ${window.end.slice(0, 10)} (${window.timezone}, exclusive end)`;
+  }
+  return `Window: all retained data (${window.retentionDays}-day retention)`;
+}
 function apiErrorGuidance(err, extra) {
   if (extra && Object.prototype.hasOwnProperty.call(extra, err.message)) {
     return extra[err.message];
@@ -92,6 +130,12 @@ function apiErrorGuidance(err, extra) {
     default:
       break;
   }
+  if (err.message === "range_out_of_retention") {
+    return "The requested window starts before this plan retains data \u2014 older events have been deleted by the retention purge and cannot be recovered. Ask for a more recent window, or upgrade the SentientUI plan for longer history (Growth keeps 180 days, Scale 365).";
+  }
+  if (err.message === "invalid_range") {
+    return "Invalid time window. Use range '7d', '30d', '90d' or 'all', or from/to as YYYY-MM-DD dates.";
+  }
   if (err.status === 402) {
     return `This feature requires a higher plan (${err.message}). Upgrade your SentientUI plan, then try again.`;
   }
@@ -393,7 +437,11 @@ var RENDER_JS = {
   "variant-performance": `
     window.__render = function(data){
       var variants = (data && data.variants) || [];
-      el('sub').textContent = variants.length + ' variant' + (variants.length === 1 ? '' : 's') + ' \xB7 conversion, last 7 days vs prior 7';
+      var winText = 'current vs prior period';
+      if (data && data.window && data.window.start && data.window.end) {
+        winText = String(data.window.start).slice(0, 10) + ' to ' + String(data.window.end).slice(0, 10) + ' vs prior period';
+      }
+      el('sub').textContent = variants.length + ' variant' + (variants.length === 1 ? '' : 's') + ' \xB7 conversion, ' + winText;
       if (!variants.length) { showEmpty('No variant data available yet.'); return; }
       var max = variants.reduce(function(m,v){ return Math.max(m, v.currentCvr || 0); }, 0) || 1;
       var sorted = variants.slice().sort(function(a,b){ return (b.currentCvr||0) - (a.currentCvr||0); });
@@ -522,8 +570,8 @@ function registerComponentTools(server, client) {
     "list_components",
     {
       title: "List components",
-      description: "List all adaptive components in a project with variant counts and impression totals.",
-      inputSchema: { projectId: projectIdSchema },
+      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.",
+      inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("all")),
       outputSchema: {
         components: import_zod3.z.array(
           import_zod3.z.object({
@@ -532,7 +580,8 @@ function registerComponentTools(server, client) {
             impressions: import_zod3.z.number(),
             conversions: import_zod3.z.number()
           })
-        ).describe("Adaptive components in the project (empty if none)")
+        ).describe("Adaptive components in the project (empty if none)"),
+        window: windowOutputSchema
       },
       annotations: {
         readOnlyHint: true,
@@ -540,16 +589,17 @@ function registerComponentTools(server, client) {
         openWorldHint: false
       }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, range, from, to }) => {
       const id = encodeURIComponent(projectId);
-      const { components } = await client.get(`/projects/${id}/components`);
+      const { components, window } = await client.get(`/projects/${id}/components${rangeQuery({ range, from, to })}`);
       const structuredContent = {
         components: components.map((c) => ({
           componentId: c.component_id,
           variantCount: c.variants.length,
           impressions: c.total_impressions,
           conversions: c.total_conversions
-        }))
+        })),
+        window
       };
       if (!components.length) {
         return {
@@ -567,19 +617,20 @@ function registerComponentTools(server, client) {
     "get_variant_performance",
     {
       title: "Variant performance",
-      description: "Get CVR and momentum for all variants in a project over the last 7 days vs prior 7 days.",
-      inputSchema: { projectId: projectIdSchema },
+      description: "Get CVR and momentum for all variants in a project over the selected window vs the immediately-preceding window of equal length (default: last 7 calendar days vs prior 7).",
+      inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("7d")),
       _meta: uiMeta("variant-performance"),
       outputSchema: {
         variants: import_zod3.z.array(
           import_zod3.z.object({
             variantId: import_zod3.z.string(),
-            currentCvr: import_zod3.z.number().describe("Conversion rate over the last 7 days (0-1)"),
-            priorCvr: import_zod3.z.number().describe("Conversion rate over the prior 7 days (0-1)"),
+            currentCvr: import_zod3.z.number().describe("Conversion rate over the selected window (0-1)"),
+            priorCvr: import_zod3.z.number().describe("Conversion rate over the preceding window (0-1)"),
             deltaPp: import_zod3.z.number().describe("Change in percentage points"),
             momentum: import_zod3.z.string().describe("Momentum direction: gaining, losing, or stable")
           })
-        ).describe("Per-variant performance (empty if no data yet)")
+        ).describe("Per-variant performance (empty if no data yet)"),
+        window: windowOutputSchema
       },
       annotations: {
         readOnlyHint: true,
@@ -587,10 +638,10 @@ function registerComponentTools(server, client) {
         openWorldHint: false
       }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, range, from, to }) => {
       var _a2, _b, _c;
       const id = encodeURIComponent(projectId);
-      const data = await client.get(`/projects/${id}/trends`);
+      const data = await client.get(`/projects/${id}/trends${rangeQuery({ range, from, to })}`);
       const momentumMap = new Map(((_a2 = data.momentum) != null ? _a2 : []).map((m) => [m.variantId, m.direction]));
       const structuredContent = {
         variants: ((_b = data.cvr) != null ? _b : []).map((v) => {
@@ -602,7 +653,8 @@ function registerComponentTools(server, client) {
             deltaPp: v.deltaPp,
             momentum: (_a3 = momentumMap.get(v.variantId)) != null ? _a3 : "stable"
           };
-        })
+        }),
+        window: data.window
       };
       if (!((_c = data.cvr) == null ? void 0 : _c.length)) {
         return {
@@ -611,12 +663,14 @@ function registerComponentTools(server, client) {
           _meta: uiMeta("variant-performance")
         };
       }
-      const text = data.cvr.map(
+      const lines = data.cvr.map(
         (v) => {
           var _a3;
           return `- ${v.variantId}: CVR ${(v.currentCvr * 100).toFixed(2)}% (prior ${(v.priorCvr * 100).toFixed(2)}%, ${v.deltaPp > 0 ? "+" : ""}${v.deltaPp.toFixed(1)} pp, ${(_a3 = momentumMap.get(v.variantId)) != null ? _a3 : "stable"})`;
         }
-      ).join("\n");
+      );
+      const win = windowLine(data.window);
+      const text = (win ? [win, ...lines] : lines).join("\n");
       return { content: [{ type: "text", text }], structuredContent, _meta: uiMeta("variant-performance") };
     })
   );
@@ -802,8 +856,8 @@ function registerGoalTools(server, client) {
     "get_goal_funnel",
     {
       title: "Goal funnel",
-      description: "Get goal hit counts, unique-session conversion rates, and per-variant breakdown. This is a flat per-goal list \u2014 for multi-step funnel drop-off, use get_funnel_report.",
-      inputSchema: { projectId: projectIdSchema },
+      description: "Get goal hit counts, unique-session conversion rates, and per-variant breakdown (default window: last 30 calendar days). This is a flat per-goal list \u2014 for multi-step funnel drop-off, use get_funnel_report.",
+      inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("30d")),
       _meta: uiMeta("goal-funnel"),
       outputSchema: {
         currency: import_zod6.z.string().describe("Project display currency (ISO-4217) for the revenue fields"),
@@ -824,7 +878,8 @@ function registerGoalTools(server, client) {
               })
             ).describe("Per-variant breakdown")
           })
-        ).describe("Configured goals (empty if none)")
+        ).describe("Configured goals (empty if none)"),
+        window: windowOutputSchema
       },
       annotations: {
         readOnlyHint: true,
@@ -832,11 +887,12 @@ function registerGoalTools(server, client) {
         openWorldHint: false
       }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, range, from, to }) => {
       var _a2, _b;
       const id = encodeURIComponent(projectId);
-      const data = await client.get(`/projects/${id}/goals`);
+      const data = await client.get(`/projects/${id}/goals${rangeQuery({ range, from, to })}`);
       const structuredContent = {
+        window: data.window,
         currency: (_a2 = data.currency) != null ? _a2 : "USD",
         goals: data.goals.map((g) => {
           var _a3, _b2, _c;
@@ -864,6 +920,7 @@ function registerGoalTools(server, client) {
         };
       }
       const currency = (_b = data.currency) != null ? _b : "USD";
+      const win = windowLine(data.window);
       const lines = data.goals.flatMap((g) => {
         var _a3;
         return [
@@ -872,7 +929,8 @@ function registerGoalTools(server, client) {
           ""
         ];
       });
-      return { content: [{ type: "text", text: lines.join("\n").trim() }], structuredContent, _meta: uiMeta("goal-funnel") };
+      const text = (win ? [win, "", ...lines] : lines).join("\n").trim();
+      return { content: [{ type: "text", text }], structuredContent, _meta: uiMeta("goal-funnel") };
     })
   );
   server.registerTool(
@@ -1619,9 +1677,15 @@ function registerTestBriefTools(server, client) {
 var import_zod13 = require("zod");
 var GUIDE = `# SentientUI integration guide \u2014 the adaptive ladder
 
-SentientUI adapts a site per visitor type (personas: buyer, researcher, deal_seeker, browser,
-unknown), learning from real conversions. Decisions are locked per session: Visit 1 learns,
-Visit 2 converts. Integrate one rung at a time.
+SentientUI adapts a site per visitor type (personas), learning from real conversions. Each
+project has its own persona vocabulary (dashboard -> Settings -> Personas; the default is
+buyer, researcher, deal_seeker, browser + unknown). Personas are inferred from behavior \u2014 or
+DECLARED by the app when it already knows the visitor's role: init({ persona: 'admin' }) /
+<AdaptiveProvider persona=...> / window.sentient.persona. Declared beats inferred and serves
+at full confidence; unrecognized values are ignored server-side and surfaced in the dashboard
+so the operator can add them. Keep persona a low-cardinality role slug \u2014 never a user id.
+Decisions are locked per session: Visit 1 learns, Visit 2 converts. Integrate one rung at a
+time.
 
 ## Setup (60 seconds, no account)
 
@@ -1639,7 +1703,8 @@ Visit 2 converts. Integrate one rung at a time.
 
 ## Rung 1 \u2014 Style (CSS only)
 
-Persona attributes on <html> (zero declaration):
+Persona attributes on <html> (zero declaration; the attribute carries the project's own
+vocabulary keys \u2014 declared or inferred):
 
     html[data-sentient-persona='deal_seeker'] .discount-banner { display: block; }
     html[data-sentient-confidence='low'] .discount-banner { display: none; }
@@ -1716,8 +1781,12 @@ function registerAgentTrafficTools(server, client) {
     "get_agent_traffic",
     {
       title: "Agent traffic",
-      description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, agentic browsers, agent API calls), engine breakdown, and the paths they fetch most. Agent traffic is tracked separately and never counted in conversion rate.",
-      inputSchema: { projectId: projectIdSchema },
+      description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, agentic browsers, agent API calls), engine breakdown, and the paths they fetch most. Defaults to the last 30 days; pass from/to for a custom period (agent logs are retained 30 days on Free/Starter, 90 on Growth+). Agent traffic is tracked separately and never counted in conversion rate.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        from: import_zod14.z.string().optional().describe("Period start (ISO 8601 date or timestamp). Defaults to 30 days ago."),
+        to: import_zod14.z.string().optional().describe("Period end (ISO 8601 date or timestamp). Defaults to now.")
+      },
       outputSchema: {
         totals: import_zod14.z.object({ crawler: import_zod14.z.number(), api: import_zod14.z.number(), browser: import_zod14.z.number() }),
         engines: import_zod14.z.array(
@@ -1735,9 +1804,14 @@ function registerAgentTrafficTools(server, client) {
       },
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, from, to }) => {
       const id = encodeURIComponent(projectId);
-      const s = await client.get(`/projects/${id}/agent-activity/summary`);
+      const qs = new URLSearchParams();
+      if (from) qs.set("from", from);
+      if (to) qs.set("to", to);
+      const s = await client.get(
+        `/projects/${id}/agent-activity/summary${qs.size > 0 ? `?${qs.toString()}` : ""}`
+      );
       const structuredContent = { totals: s.totals, engines: s.engines, intents: s.intents, topPaths: s.topPaths };
       const total = s.totals.crawler + s.totals.api + s.totals.browser;
       if (total === 0) {
@@ -1825,7 +1899,7 @@ function registerAgentTrafficTools(server, client) {
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.16.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.17.1" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new import_mcp.McpServer(
     {

package/dist/index.js

@@ -2,7 +2,7 @@
 import {
   ApiClient,
   createMcpServer
-} from "./chunk-SUMKFRQP.js";
+} from "./chunk-KT2ZKW7I.js";
 
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/lib.cjs

@@ -102,6 +102,44 @@ var ApiClient = class {
 
 // src/tools/common.ts
 var projectIdSchema = import_zod.z.string().uuid().describe("The project UUID");
+function rangeInputSchema(defaultRange) {
+  return {
+    range: import_zod.z.enum(["7d", "30d", "90d", "all"]).optional().describe(
+      `Calendar window in the project's reporting timezone (default ${defaultRange}). 'all' means all retained data \u2014 the plan's retention window bounds every lookback.`
+    ),
+    from: import_zod.z.string().optional().describe(
+      "Custom window start (YYYY-MM-DD; overrides range). Must be within the plan retention window."
+    ),
+    to: import_zod.z.string().optional().describe("Custom window end (YYYY-MM-DD, inclusive; default today).")
+  };
+}
+function rangeQuery(args) {
+  const p = new URLSearchParams();
+  if (args.from) {
+    p.set("from", args.from);
+    if (args.to) p.set("to", args.to);
+  } else if (args.range) {
+    p.set("range", args.range);
+  }
+  const s = p.toString();
+  return s ? `?${s}` : "";
+}
+var windowOutputSchema = import_zod.z.object({
+  range: import_zod.z.string(),
+  start: import_zod.z.string().nullable(),
+  end: import_zod.z.string().nullable(),
+  timezone: import_zod.z.string(),
+  bucketUnit: import_zod.z.string(),
+  retentionDays: import_zod.z.number().describe("The plan's effective data retention in days"),
+  earliestAvailable: import_zod.z.string().describe("First date retention still holds data for (YYYY-MM-DD)")
+}).optional().describe("The window the server actually used for every count in this response");
+function windowLine(window) {
+  if (!window) return "";
+  if (window.start && window.end) {
+    return `Window: ${window.start.slice(0, 10)} to ${window.end.slice(0, 10)} (${window.timezone}, exclusive end)`;
+  }
+  return `Window: all retained data (${window.retentionDays}-day retention)`;
+}
 function apiErrorGuidance(err, extra) {
   if (extra && Object.prototype.hasOwnProperty.call(extra, err.message)) {
     return extra[err.message];
@@ -116,6 +154,12 @@ function apiErrorGuidance(err, extra) {
     default:
       break;
   }
+  if (err.message === "range_out_of_retention") {
+    return "The requested window starts before this plan retains data \u2014 older events have been deleted by the retention purge and cannot be recovered. Ask for a more recent window, or upgrade the SentientUI plan for longer history (Growth keeps 180 days, Scale 365).";
+  }
+  if (err.message === "invalid_range") {
+    return "Invalid time window. Use range '7d', '30d', '90d' or 'all', or from/to as YYYY-MM-DD dates.";
+  }
   if (err.status === 402) {
     return `This feature requires a higher plan (${err.message}). Upgrade your SentientUI plan, then try again.`;
   }
@@ -417,7 +461,11 @@ var RENDER_JS = {
   "variant-performance": `
     window.__render = function(data){
       var variants = (data && data.variants) || [];
-      el('sub').textContent = variants.length + ' variant' + (variants.length === 1 ? '' : 's') + ' \xB7 conversion, last 7 days vs prior 7';
+      var winText = 'current vs prior period';
+      if (data && data.window && data.window.start && data.window.end) {
+        winText = String(data.window.start).slice(0, 10) + ' to ' + String(data.window.end).slice(0, 10) + ' vs prior period';
+      }
+      el('sub').textContent = variants.length + ' variant' + (variants.length === 1 ? '' : 's') + ' \xB7 conversion, ' + winText;
       if (!variants.length) { showEmpty('No variant data available yet.'); return; }
       var max = variants.reduce(function(m,v){ return Math.max(m, v.currentCvr || 0); }, 0) || 1;
       var sorted = variants.slice().sort(function(a,b){ return (b.currentCvr||0) - (a.currentCvr||0); });
@@ -546,8 +594,8 @@ function registerComponentTools(server, client) {
     "list_components",
     {
       title: "List components",
-      description: "List all adaptive components in a project with variant counts and impression totals.",
-      inputSchema: { projectId: projectIdSchema },
+      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.",
+      inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("all")),
       outputSchema: {
         components: import_zod3.z.array(
           import_zod3.z.object({
@@ -556,7 +604,8 @@ function registerComponentTools(server, client) {
             impressions: import_zod3.z.number(),
             conversions: import_zod3.z.number()
           })
-        ).describe("Adaptive components in the project (empty if none)")
+        ).describe("Adaptive components in the project (empty if none)"),
+        window: windowOutputSchema
       },
       annotations: {
         readOnlyHint: true,
@@ -564,16 +613,17 @@ function registerComponentTools(server, client) {
         openWorldHint: false
       }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, range, from, to }) => {
       const id = encodeURIComponent(projectId);
-      const { components } = await client.get(`/projects/${id}/components`);
+      const { components, window } = await client.get(`/projects/${id}/components${rangeQuery({ range, from, to })}`);
       const structuredContent = {
         components: components.map((c) => ({
           componentId: c.component_id,
           variantCount: c.variants.length,
           impressions: c.total_impressions,
           conversions: c.total_conversions
-        }))
+        })),
+        window
       };
       if (!components.length) {
         return {
@@ -591,19 +641,20 @@ function registerComponentTools(server, client) {
     "get_variant_performance",
     {
       title: "Variant performance",
-      description: "Get CVR and momentum for all variants in a project over the last 7 days vs prior 7 days.",
-      inputSchema: { projectId: projectIdSchema },
+      description: "Get CVR and momentum for all variants in a project over the selected window vs the immediately-preceding window of equal length (default: last 7 calendar days vs prior 7).",
+      inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("7d")),
       _meta: uiMeta("variant-performance"),
       outputSchema: {
         variants: import_zod3.z.array(
           import_zod3.z.object({
             variantId: import_zod3.z.string(),
-            currentCvr: import_zod3.z.number().describe("Conversion rate over the last 7 days (0-1)"),
-            priorCvr: import_zod3.z.number().describe("Conversion rate over the prior 7 days (0-1)"),
+            currentCvr: import_zod3.z.number().describe("Conversion rate over the selected window (0-1)"),
+            priorCvr: import_zod3.z.number().describe("Conversion rate over the preceding window (0-1)"),
             deltaPp: import_zod3.z.number().describe("Change in percentage points"),
             momentum: import_zod3.z.string().describe("Momentum direction: gaining, losing, or stable")
           })
-        ).describe("Per-variant performance (empty if no data yet)")
+        ).describe("Per-variant performance (empty if no data yet)"),
+        window: windowOutputSchema
       },
       annotations: {
         readOnlyHint: true,
@@ -611,10 +662,10 @@ function registerComponentTools(server, client) {
         openWorldHint: false
       }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, range, from, to }) => {
       var _a, _b, _c;
       const id = encodeURIComponent(projectId);
-      const data = await client.get(`/projects/${id}/trends`);
+      const data = await client.get(`/projects/${id}/trends${rangeQuery({ range, from, to })}`);
       const momentumMap = new Map(((_a = data.momentum) != null ? _a : []).map((m) => [m.variantId, m.direction]));
       const structuredContent = {
         variants: ((_b = data.cvr) != null ? _b : []).map((v) => {
@@ -626,7 +677,8 @@ function registerComponentTools(server, client) {
             deltaPp: v.deltaPp,
             momentum: (_a2 = momentumMap.get(v.variantId)) != null ? _a2 : "stable"
           };
-        })
+        }),
+        window: data.window
       };
       if (!((_c = data.cvr) == null ? void 0 : _c.length)) {
         return {
@@ -635,12 +687,14 @@ function registerComponentTools(server, client) {
           _meta: uiMeta("variant-performance")
         };
       }
-      const text = data.cvr.map(
+      const lines = data.cvr.map(
         (v) => {
           var _a2;
           return `- ${v.variantId}: CVR ${(v.currentCvr * 100).toFixed(2)}% (prior ${(v.priorCvr * 100).toFixed(2)}%, ${v.deltaPp > 0 ? "+" : ""}${v.deltaPp.toFixed(1)} pp, ${(_a2 = momentumMap.get(v.variantId)) != null ? _a2 : "stable"})`;
         }
-      ).join("\n");
+      );
+      const win = windowLine(data.window);
+      const text = (win ? [win, ...lines] : lines).join("\n");
       return { content: [{ type: "text", text }], structuredContent, _meta: uiMeta("variant-performance") };
     })
   );
@@ -826,8 +880,8 @@ function registerGoalTools(server, client) {
     "get_goal_funnel",
     {
       title: "Goal funnel",
-      description: "Get goal hit counts, unique-session conversion rates, and per-variant breakdown. This is a flat per-goal list \u2014 for multi-step funnel drop-off, use get_funnel_report.",
-      inputSchema: { projectId: projectIdSchema },
+      description: "Get goal hit counts, unique-session conversion rates, and per-variant breakdown (default window: last 30 calendar days). This is a flat per-goal list \u2014 for multi-step funnel drop-off, use get_funnel_report.",
+      inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("30d")),
       _meta: uiMeta("goal-funnel"),
       outputSchema: {
         currency: import_zod6.z.string().describe("Project display currency (ISO-4217) for the revenue fields"),
@@ -848,7 +902,8 @@ function registerGoalTools(server, client) {
               })
             ).describe("Per-variant breakdown")
           })
-        ).describe("Configured goals (empty if none)")
+        ).describe("Configured goals (empty if none)"),
+        window: windowOutputSchema
       },
       annotations: {
         readOnlyHint: true,
@@ -856,11 +911,12 @@ function registerGoalTools(server, client) {
         openWorldHint: false
       }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, range, from, to }) => {
       var _a, _b;
       const id = encodeURIComponent(projectId);
-      const data = await client.get(`/projects/${id}/goals`);
+      const data = await client.get(`/projects/${id}/goals${rangeQuery({ range, from, to })}`);
       const structuredContent = {
+        window: data.window,
         currency: (_a = data.currency) != null ? _a : "USD",
         goals: data.goals.map((g) => {
           var _a2, _b2, _c;
@@ -888,6 +944,7 @@ function registerGoalTools(server, client) {
         };
       }
       const currency = (_b = data.currency) != null ? _b : "USD";
+      const win = windowLine(data.window);
       const lines = data.goals.flatMap((g) => {
         var _a2;
         return [
@@ -896,7 +953,8 @@ function registerGoalTools(server, client) {
           ""
         ];
       });
-      return { content: [{ type: "text", text: lines.join("\n").trim() }], structuredContent, _meta: uiMeta("goal-funnel") };
+      const text = (win ? [win, "", ...lines] : lines).join("\n").trim();
+      return { content: [{ type: "text", text }], structuredContent, _meta: uiMeta("goal-funnel") };
     })
   );
   server.registerTool(
@@ -1643,9 +1701,15 @@ function registerTestBriefTools(server, client) {
 var import_zod13 = require("zod");
 var GUIDE = `# SentientUI integration guide \u2014 the adaptive ladder
 
-SentientUI adapts a site per visitor type (personas: buyer, researcher, deal_seeker, browser,
-unknown), learning from real conversions. Decisions are locked per session: Visit 1 learns,
-Visit 2 converts. Integrate one rung at a time.
+SentientUI adapts a site per visitor type (personas), learning from real conversions. Each
+project has its own persona vocabulary (dashboard -> Settings -> Personas; the default is
+buyer, researcher, deal_seeker, browser + unknown). Personas are inferred from behavior \u2014 or
+DECLARED by the app when it already knows the visitor's role: init({ persona: 'admin' }) /
+<AdaptiveProvider persona=...> / window.sentient.persona. Declared beats inferred and serves
+at full confidence; unrecognized values are ignored server-side and surfaced in the dashboard
+so the operator can add them. Keep persona a low-cardinality role slug \u2014 never a user id.
+Decisions are locked per session: Visit 1 learns, Visit 2 converts. Integrate one rung at a
+time.
 
 ## Setup (60 seconds, no account)
 
@@ -1663,7 +1727,8 @@ Visit 2 converts. Integrate one rung at a time.
 
 ## Rung 1 \u2014 Style (CSS only)
 
-Persona attributes on <html> (zero declaration):
+Persona attributes on <html> (zero declaration; the attribute carries the project's own
+vocabulary keys \u2014 declared or inferred):
 
     html[data-sentient-persona='deal_seeker'] .discount-banner { display: block; }
     html[data-sentient-confidence='low'] .discount-banner { display: none; }
@@ -1740,8 +1805,12 @@ function registerAgentTrafficTools(server, client) {
     "get_agent_traffic",
     {
       title: "Agent traffic",
-      description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, agentic browsers, agent API calls), engine breakdown, and the paths they fetch most. Agent traffic is tracked separately and never counted in conversion rate.",
-      inputSchema: { projectId: projectIdSchema },
+      description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, agentic browsers, agent API calls), engine breakdown, and the paths they fetch most. Defaults to the last 30 days; pass from/to for a custom period (agent logs are retained 30 days on Free/Starter, 90 on Growth+). Agent traffic is tracked separately and never counted in conversion rate.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        from: import_zod14.z.string().optional().describe("Period start (ISO 8601 date or timestamp). Defaults to 30 days ago."),
+        to: import_zod14.z.string().optional().describe("Period end (ISO 8601 date or timestamp). Defaults to now.")
+      },
       outputSchema: {
         totals: import_zod14.z.object({ crawler: import_zod14.z.number(), api: import_zod14.z.number(), browser: import_zod14.z.number() }),
         engines: import_zod14.z.array(
@@ -1759,9 +1828,14 @@ function registerAgentTrafficTools(server, client) {
       },
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, from, to }) => {
       const id = encodeURIComponent(projectId);
-      const s = await client.get(`/projects/${id}/agent-activity/summary`);
+      const qs = new URLSearchParams();
+      if (from) qs.set("from", from);
+      if (to) qs.set("to", to);
+      const s = await client.get(
+        `/projects/${id}/agent-activity/summary${qs.size > 0 ? `?${qs.toString()}` : ""}`
+      );
       const structuredContent = { totals: s.totals, engines: s.engines, intents: s.intents, topPaths: s.topPaths };
       const total = s.totals.crawler + s.totals.api + s.totals.browser;
       if (total === 0) {
@@ -1849,7 +1923,7 @@ function registerAgentTrafficTools(server, client) {
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.16.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.17.1" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new import_mcp.McpServer(
     {

package/dist/lib.js

@@ -4,7 +4,7 @@ import {
   ApiError,
   PUBLIC_UI_RESOURCE_URIS,
   createMcpServer
-} from "./chunk-SUMKFRQP.js";
+} from "./chunk-KT2ZKW7I.js";
 export {
   ApiClient,
   ApiError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentientui/mcp",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "MCP server for SentientUI — exposes project data and actions to AI agents",
   "license": "MIT",
   "homepage": "https://sentient-ui.com",