@sentientui/mcp 0.20.0 → 0.21.0

package/AGENTS.md

@@ -51,6 +51,7 @@ Every write tool changes what real visitors see or what the project accepts —
 | `restore_variant` | write | Brings a retired variant back to active. Does not unpause it |
 | `get_goal_funnel` | read | Per-goal conversion summary (windowed) + descriptive per-variant all-time completion rates, each with its n and a low-sample flag (descriptive — no verdict). Not a step funnel; for drop-off use `get_funnel_report` |
 | `list_goals` | read | Defined goals, including ones with no conversions yet |
+| `define_goal` | write | Create a new goal. Create-only: an existing id (even archived) is refused, and it never sets or changes the primary goal — that stays a dashboard decision |
 | `list_funnels` | read | Defined multi-step funnels |
 | `get_funnel_report` | read | Step-by-step funnel drop-off |
 | `list_guardrail_events` | read | Every variant still paused by a guardrail; `days` narrows to recent pauses |
@@ -84,7 +85,7 @@ Every write tool changes what real visitors see or what the project accepts —
 4. Do **not** call `create_variant`. Commit, push, deploy — the variant auto-registers on the first assignment and goes live.
 5. Optional: enable shadow mode (project-level, in dashboard settings — it applies to the whole project, not a single component) first to validate before serving.
 
-The evidence state (from the brief) drives the change. It is keyed on the server's evidence tiers, never on a traffic count: only **DECIDED** (an arm reliably ahead of or behind the baseline, at the multiple-comparison-corrected strong bar) is a result to build on. **DIRECTIONAL** (early/moderate/inconclusive signals), **COLLECTING** (below the 100-visit floor per arm) and **EMPTY** all mean: apply the best-practice priors for the project's context type and make one conservative change. Never call an arm better or worse from its raw rate.
+The evidence state (from the brief) drives the change. It is keyed on the server's evidence tiers, never on a traffic count: only **DECIDED** (an arm reliably ahead of or behind the baseline, at the multiple-comparison-corrected strong bar) is a result to build on. **DIRECTIONAL** (early/moderate/likely-worse/inconclusive signals — likely-worse means probably behind the baseline, wrong about one time in five, so do not build on that arm but do not treat it as decided either), **COLLECTING** (below the 100-visit floor per arm) and **EMPTY** all mean: apply the best-practice priors for the project's context type and make one conservative change. Never call an arm better or worse from its raw rate.
 
 **Add a no-code managed text variant (fallback — text only, less powerful)**
 1. `list_components` — confirm the component ID

package/README.md

@@ -102,6 +102,7 @@ A demo token is provisioned automatically — 10 calls/month, read-only (write t
 | `restore_variant` | write | Bring a retired variant back to active (does not unpause it) |
 | `get_goal_funnel` | read | Per-goal conversion summary (windowed; default 30d) with descriptive all-time per-variant rates — not a step funnel (use `get_funnel_report` for drop-off); the id is kept for compatibility |
 | `list_goals` | read | Defined goals (id, role, event, status), including ones with no conversions yet |
+| `define_goal` | write | Create a new goal (secondary or guardrail). Create-only: refuses an existing goal id and never sets or changes the primary goal |
 | `list_funnels` | read | Defined multi-step funnels |
 | `get_funnel_report` | read | Step-by-step funnel drop-off |
 | `list_guardrail_events` | read | Every variant currently paused by a guardrail (pass `days` to see only pauses from the last N days) |

package/dist/{chunk-35I5EJTS.js → chunk-K7JN3LOH.js}

@@ -720,6 +720,10 @@ var EVIDENCE_LABEL = {
   early_signal: "Early signal (still moving \u2014 not a result)",
   moderate_evidence: "Moderate evidence (about one call in five of this strength is wrong \u2014 not decided)",
   strong_evidence: "Strong evidence",
+  // The mirror of moderate_evidence. Before the server had it, an arm clearly
+  // behind its baseline read "Inconclusive (… without separating)" — it HAD
+  // separated, downward.
+  likely_worse: "Likely worse than the baseline (about one call in five of this strength is wrong \u2014 not decided)",
   inconclusive: "Inconclusive (ran a full period without separating from the baseline)"
 };
 var STATES = new Set(Object.keys(EVIDENCE_LABEL));
@@ -770,7 +774,9 @@ function verdictOf(state, stats, isBaseline) {
 var VERDICT_TEXT = {
   ahead: "reliably AHEAD of the baseline",
   behind: "reliably BEHIND the baseline",
-  unclear: "not separated from the baseline",
+  // "not RELIABLY": this is printed beside moderate_evidence and likely_worse
+  // labels too, and a bare "not separated" contradicted the label next to it.
+  unclear: "not reliably separated from the baseline",
   no_evidence: "no evidence available from the server"
 };
 function rateWithN(conversions, n, unit = "sessions") {
@@ -856,7 +862,7 @@ function registerComponentTools(server, client) {
             conversions: z3.number().describe("Converting sessions in the window"),
             currentCvr: z3.number().nullable().describe("conversions / sessions over the window (0-1); null at 0 sessions"),
             lowSample: z3.boolean().describe(`True under ${MIN_EVIDENCE_SAMPLE} sessions \u2014 the rate is not interpretable on its own`),
-            evidenceState: z3.string().nullable().describe("Reliability (all time): the server's ALL-TIME evidence state vs the baseline on direct evidence \u2014 not_enough_data | early_signal | moderate_evidence | strong_evidence | inconclusive; null for the baseline or when not provided. Not a verdict on the windowed rate"),
+            evidenceState: z3.string().nullable().describe("Reliability (all time): the server's ALL-TIME evidence state vs the baseline on direct evidence \u2014 not_enough_data | early_signal | moderate_evidence | strong_evidence | likely_worse | inconclusive; null for the baseline or when not provided. Not a verdict on the windowed rate"),
             probBeatsBaseline: z3.number().nullable().describe("P(this arm > baseline), all-time, from the server; null when not provided"),
             reliabilityVerdict: z3.enum(["baseline", "ahead", "behind", "unclear", "no_evidence"]).describe("The all-time verdict read from evidenceState \u2014 reliability (all time), which can differ from `verdict` on the window"),
             windowEvidenceState: z3.string().nullable().describe("The server's evidence state on the WINDOWED session conversion rate vs the baseline; null for the baseline, when the arm was not scored in the window, or on older APIs"),
@@ -1425,6 +1431,51 @@ function registerGoalTools(server, client) {
       return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
     })
   );
+  server.registerTool(
+    "define_goal",
+    {
+      title: "Define a new goal",
+      description: "Create a NEW goal (conversion signal) for a project. Create-only: it never changes an existing goal \u2014 an id that already exists, including an archived one, is refused (goal_exists); call list_goals first. It never sets or changes the PRIMARY goal (what experiments optimize): the goal is created as 'secondary' (default) or 'guardrail'; choosing the primary stays a dashboard decision. A guardrail goal can pause variants that hurt it \u2014 say so when proposing one. Event types: url_reached (needs urlPattern, e.g. /thank-you), click / form_submit (need a locator, usually easier to pick in the dashboard on-site editor, or fire from code with client.goal('<goalId>') instead), scroll_depth (needs threshold in (0, 1]). Needs an editor/admin login or the project's sk_ server key. Confirm the goal id, event and pattern with the user before calling.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        goalId: z6.string().min(1).max(128).refine((s) => !s.startsWith("funnel:"), "'funnel:' is reserved for funnel bindings").describe("Stable id code will reference, e.g. 'signup' or 'checkout-complete'. Must not exist yet."),
+        event: z6.enum(["url_reached", "click", "form_submit", "scroll_depth"]).describe("What counts as a conversion"),
+        urlPattern: z6.string().min(1).max(512).optional().describe("url_reached only: the path pattern, e.g. '/thank-you' or '/orders/*'"),
+        locator: z6.record(z6.unknown()).optional().describe('click / form_submit only: the element locator (e.g. { "id": "signup-button" })'),
+        threshold: z6.number().gt(0).max(1).optional().describe("scroll_depth only: how far down the page counts, in (0, 1]"),
+        displayName: z6.string().min(1).max(128).optional().describe("Human-readable name shown in the dashboard"),
+        role: z6.enum(["secondary", "guardrail"]).optional().describe("secondary (default) is tracked and reported; guardrail can also pause variants that hurt it. Never 'primary'."),
+        defaultValue: z6.number().positive().max(1e9).optional().describe("Fixed worth of one conversion in the project currency (revenue goals)")
+      },
+      outputSchema: {
+        goalId: z6.string(),
+        role: z6.enum(["secondary", "guardrail"]).describe("Never primary \u2014 this tool cannot change the primary goal")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, goalId, event, urlPattern, locator, threshold, displayName, role, defaultValue }) => {
+      var _a, _b, _c;
+      const id = encodeURIComponent(projectId);
+      const res = await client.post(`/projects/${id}/goal-definitions`, __spreadValues(__spreadValues(__spreadValues(__spreadValues(__spreadValues(__spreadValues({
+        goalId,
+        event
+      }, urlPattern !== void 0 ? { urlPattern } : {}), locator !== void 0 ? { locator } : {}), threshold !== void 0 ? { threshold } : {}), displayName !== void 0 ? { displayName } : {}), role !== void 0 ? { role } : {}), defaultValue !== void 0 ? { defaultValue } : {}));
+      const structuredContent = { goalId: (_a = res.goalId) != null ? _a : goalId, role: (_c = (_b = res.role) != null ? _b : role) != null ? _c : "secondary" };
+      return {
+        content: [{
+          type: "text",
+          text: `Created goal ${untrusted(structuredContent.goalId)} (${structuredContent.role}, ${event}). It is active now. The primary goal was not changed \u2014 if this should be what experiments optimize, the owner can make it primary in the dashboard. Reference the goalId verbatim from code (client.goal('<goalId>')) if the event is not tracked automatically.`
+        }],
+        structuredContent
+      };
+    }, {
+      goal_exists: "A goal with this id already exists (it may be archived). define_goal never changes an existing goal \u2014 pick a new id (see list_goals), or edit that goal in the dashboard.",
+      primary_not_allowed: "define_goal never sets the primary goal. Create it as secondary; the owner can make it primary in the dashboard.",
+      invalid_goal_id: "That goal id is not allowed: use 1-128 characters, and not the reserved 'funnel:' prefix.",
+      invalid_goal: "The goal definition is incomplete for its event type: url_reached needs urlPattern, click/form_submit need a locator, scroll_depth needs threshold.",
+      "Not Found": "This SentientUI API does not support creating goals from MCP yet (it predates create-only goals). Define the goal in the dashboard instead."
+    })
+  );
 }
 
 // src/tools/funnels.ts
@@ -2052,7 +2103,10 @@ function guidanceFor(dataState, contextType, arms) {
     }
     case "directional": {
       const inconclusive = arms.some((a) => a.state === "inconclusive");
-      return 'No comparison on this component is decided. Early and moderate signals are hypotheses, not results (moderate evidence is wrong about one time in five), so do not target an arm as "under-" or "out-performing". ' + (inconclusive ? "At least one arm ran a full period without separating from the baseline \u2014 the existing versions do not differ meaningfully, so make a clearly different change rather than a tweak. " : "") + "Lean on the best-practice priors below and make one focused change.";
+      const likelyWorse = arms.filter((a) => !a.isBaseline && a.state === "likely_worse").map((a) => untrusted(a.variantId));
+      return 'No comparison on this component is decided. Early, moderate and likely-worse signals are hypotheses, not results (each is wrong about one time in five), so do not target an arm as "under-" or "out-performing". ' + (likelyWorse.length ? `Probably behind the baseline (not decided): ${likelyWorse.join(", ")} \u2014 do not build on ${likelyWorse.length === 1 ? "it" : "them"}. ` : "") + // "did not separate" is not "do not differ": the old wording asserted
+      // an equality the evidence never measured.
+      (inconclusive ? "At least one arm ran a full period without separating from the baseline \u2014 any difference between the existing versions is too small to detect, so make a clearly different change rather than a tweak. " : "") + "Lean on the best-practice priors below and make one focused change.";
     }
     case "collecting":
       if (!arms.some((a) => !a.isBaseline)) {
@@ -2965,7 +3019,7 @@ function registerCellTools(server, client) {
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.20.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.21.0" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new McpServer(
     {

package/dist/index.cjs

@@ -724,6 +724,10 @@ var EVIDENCE_LABEL = {
   early_signal: "Early signal (still moving \u2014 not a result)",
   moderate_evidence: "Moderate evidence (about one call in five of this strength is wrong \u2014 not decided)",
   strong_evidence: "Strong evidence",
+  // The mirror of moderate_evidence. Before the server had it, an arm clearly
+  // behind its baseline read "Inconclusive (… without separating)" — it HAD
+  // separated, downward.
+  likely_worse: "Likely worse than the baseline (about one call in five of this strength is wrong \u2014 not decided)",
   inconclusive: "Inconclusive (ran a full period without separating from the baseline)"
 };
 var STATES = new Set(Object.keys(EVIDENCE_LABEL));
@@ -774,7 +778,9 @@ function verdictOf(state, stats, isBaseline) {
 var VERDICT_TEXT = {
   ahead: "reliably AHEAD of the baseline",
   behind: "reliably BEHIND the baseline",
-  unclear: "not separated from the baseline",
+  // "not RELIABLY": this is printed beside moderate_evidence and likely_worse
+  // labels too, and a bare "not separated" contradicted the label next to it.
+  unclear: "not reliably separated from the baseline",
   no_evidence: "no evidence available from the server"
 };
 function rateWithN(conversions, n, unit = "sessions") {
@@ -860,7 +866,7 @@ function registerComponentTools(server, client) {
             conversions: import_zod3.z.number().describe("Converting sessions in the window"),
             currentCvr: import_zod3.z.number().nullable().describe("conversions / sessions over the window (0-1); null at 0 sessions"),
             lowSample: import_zod3.z.boolean().describe(`True under ${MIN_EVIDENCE_SAMPLE} sessions \u2014 the rate is not interpretable on its own`),
-            evidenceState: import_zod3.z.string().nullable().describe("Reliability (all time): the server's ALL-TIME evidence state vs the baseline on direct evidence \u2014 not_enough_data | early_signal | moderate_evidence | strong_evidence | inconclusive; null for the baseline or when not provided. Not a verdict on the windowed rate"),
+            evidenceState: import_zod3.z.string().nullable().describe("Reliability (all time): the server's ALL-TIME evidence state vs the baseline on direct evidence \u2014 not_enough_data | early_signal | moderate_evidence | strong_evidence | likely_worse | inconclusive; null for the baseline or when not provided. Not a verdict on the windowed rate"),
             probBeatsBaseline: import_zod3.z.number().nullable().describe("P(this arm > baseline), all-time, from the server; null when not provided"),
             reliabilityVerdict: import_zod3.z.enum(["baseline", "ahead", "behind", "unclear", "no_evidence"]).describe("The all-time verdict read from evidenceState \u2014 reliability (all time), which can differ from `verdict` on the window"),
             windowEvidenceState: import_zod3.z.string().nullable().describe("The server's evidence state on the WINDOWED session conversion rate vs the baseline; null for the baseline, when the arm was not scored in the window, or on older APIs"),
@@ -1429,6 +1435,51 @@ function registerGoalTools(server, client) {
       return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
     })
   );
+  server.registerTool(
+    "define_goal",
+    {
+      title: "Define a new goal",
+      description: "Create a NEW goal (conversion signal) for a project. Create-only: it never changes an existing goal \u2014 an id that already exists, including an archived one, is refused (goal_exists); call list_goals first. It never sets or changes the PRIMARY goal (what experiments optimize): the goal is created as 'secondary' (default) or 'guardrail'; choosing the primary stays a dashboard decision. A guardrail goal can pause variants that hurt it \u2014 say so when proposing one. Event types: url_reached (needs urlPattern, e.g. /thank-you), click / form_submit (need a locator, usually easier to pick in the dashboard on-site editor, or fire from code with client.goal('<goalId>') instead), scroll_depth (needs threshold in (0, 1]). Needs an editor/admin login or the project's sk_ server key. Confirm the goal id, event and pattern with the user before calling.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        goalId: import_zod6.z.string().min(1).max(128).refine((s) => !s.startsWith("funnel:"), "'funnel:' is reserved for funnel bindings").describe("Stable id code will reference, e.g. 'signup' or 'checkout-complete'. Must not exist yet."),
+        event: import_zod6.z.enum(["url_reached", "click", "form_submit", "scroll_depth"]).describe("What counts as a conversion"),
+        urlPattern: import_zod6.z.string().min(1).max(512).optional().describe("url_reached only: the path pattern, e.g. '/thank-you' or '/orders/*'"),
+        locator: import_zod6.z.record(import_zod6.z.unknown()).optional().describe('click / form_submit only: the element locator (e.g. { "id": "signup-button" })'),
+        threshold: import_zod6.z.number().gt(0).max(1).optional().describe("scroll_depth only: how far down the page counts, in (0, 1]"),
+        displayName: import_zod6.z.string().min(1).max(128).optional().describe("Human-readable name shown in the dashboard"),
+        role: import_zod6.z.enum(["secondary", "guardrail"]).optional().describe("secondary (default) is tracked and reported; guardrail can also pause variants that hurt it. Never 'primary'."),
+        defaultValue: import_zod6.z.number().positive().max(1e9).optional().describe("Fixed worth of one conversion in the project currency (revenue goals)")
+      },
+      outputSchema: {
+        goalId: import_zod6.z.string(),
+        role: import_zod6.z.enum(["secondary", "guardrail"]).describe("Never primary \u2014 this tool cannot change the primary goal")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, goalId, event, urlPattern, locator, threshold, displayName, role, defaultValue }) => {
+      var _a2, _b, _c;
+      const id = encodeURIComponent(projectId);
+      const res = await client.post(`/projects/${id}/goal-definitions`, __spreadValues(__spreadValues(__spreadValues(__spreadValues(__spreadValues(__spreadValues({
+        goalId,
+        event
+      }, urlPattern !== void 0 ? { urlPattern } : {}), locator !== void 0 ? { locator } : {}), threshold !== void 0 ? { threshold } : {}), displayName !== void 0 ? { displayName } : {}), role !== void 0 ? { role } : {}), defaultValue !== void 0 ? { defaultValue } : {}));
+      const structuredContent = { goalId: (_a2 = res.goalId) != null ? _a2 : goalId, role: (_c = (_b = res.role) != null ? _b : role) != null ? _c : "secondary" };
+      return {
+        content: [{
+          type: "text",
+          text: `Created goal ${untrusted(structuredContent.goalId)} (${structuredContent.role}, ${event}). It is active now. The primary goal was not changed \u2014 if this should be what experiments optimize, the owner can make it primary in the dashboard. Reference the goalId verbatim from code (client.goal('<goalId>')) if the event is not tracked automatically.`
+        }],
+        structuredContent
+      };
+    }, {
+      goal_exists: "A goal with this id already exists (it may be archived). define_goal never changes an existing goal \u2014 pick a new id (see list_goals), or edit that goal in the dashboard.",
+      primary_not_allowed: "define_goal never sets the primary goal. Create it as secondary; the owner can make it primary in the dashboard.",
+      invalid_goal_id: "That goal id is not allowed: use 1-128 characters, and not the reserved 'funnel:' prefix.",
+      invalid_goal: "The goal definition is incomplete for its event type: url_reached needs urlPattern, click/form_submit need a locator, scroll_depth needs threshold.",
+      "Not Found": "This SentientUI API does not support creating goals from MCP yet (it predates create-only goals). Define the goal in the dashboard instead."
+    })
+  );
 }
 
 // src/tools/funnels.ts
@@ -2056,7 +2107,10 @@ function guidanceFor(dataState, contextType, arms) {
     }
     case "directional": {
       const inconclusive = arms.some((a) => a.state === "inconclusive");
-      return 'No comparison on this component is decided. Early and moderate signals are hypotheses, not results (moderate evidence is wrong about one time in five), so do not target an arm as "under-" or "out-performing". ' + (inconclusive ? "At least one arm ran a full period without separating from the baseline \u2014 the existing versions do not differ meaningfully, so make a clearly different change rather than a tweak. " : "") + "Lean on the best-practice priors below and make one focused change.";
+      const likelyWorse = arms.filter((a) => !a.isBaseline && a.state === "likely_worse").map((a) => untrusted(a.variantId));
+      return 'No comparison on this component is decided. Early, moderate and likely-worse signals are hypotheses, not results (each is wrong about one time in five), so do not target an arm as "under-" or "out-performing". ' + (likelyWorse.length ? `Probably behind the baseline (not decided): ${likelyWorse.join(", ")} \u2014 do not build on ${likelyWorse.length === 1 ? "it" : "them"}. ` : "") + // "did not separate" is not "do not differ": the old wording asserted
+      // an equality the evidence never measured.
+      (inconclusive ? "At least one arm ran a full period without separating from the baseline \u2014 any difference between the existing versions is too small to detect, so make a clearly different change rather than a tweak. " : "") + "Lean on the best-practice priors below and make one focused change.";
     }
     case "collecting":
       if (!arms.some((a) => !a.isBaseline)) {
@@ -2969,7 +3023,7 @@ function registerCellTools(server, client) {
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.20.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.21.0" : "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-35I5EJTS.js";
+} from "./chunk-K7JN3LOH.js";
 
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/lib.cjs

@@ -750,6 +750,10 @@ var EVIDENCE_LABEL = {
   early_signal: "Early signal (still moving \u2014 not a result)",
   moderate_evidence: "Moderate evidence (about one call in five of this strength is wrong \u2014 not decided)",
   strong_evidence: "Strong evidence",
+  // The mirror of moderate_evidence. Before the server had it, an arm clearly
+  // behind its baseline read "Inconclusive (… without separating)" — it HAD
+  // separated, downward.
+  likely_worse: "Likely worse than the baseline (about one call in five of this strength is wrong \u2014 not decided)",
   inconclusive: "Inconclusive (ran a full period without separating from the baseline)"
 };
 var STATES = new Set(Object.keys(EVIDENCE_LABEL));
@@ -800,7 +804,9 @@ function verdictOf(state, stats, isBaseline) {
 var VERDICT_TEXT = {
   ahead: "reliably AHEAD of the baseline",
   behind: "reliably BEHIND the baseline",
-  unclear: "not separated from the baseline",
+  // "not RELIABLY": this is printed beside moderate_evidence and likely_worse
+  // labels too, and a bare "not separated" contradicted the label next to it.
+  unclear: "not reliably separated from the baseline",
   no_evidence: "no evidence available from the server"
 };
 function rateWithN(conversions, n, unit = "sessions") {
@@ -886,7 +892,7 @@ function registerComponentTools(server, client) {
             conversions: import_zod3.z.number().describe("Converting sessions in the window"),
             currentCvr: import_zod3.z.number().nullable().describe("conversions / sessions over the window (0-1); null at 0 sessions"),
             lowSample: import_zod3.z.boolean().describe(`True under ${MIN_EVIDENCE_SAMPLE} sessions \u2014 the rate is not interpretable on its own`),
-            evidenceState: import_zod3.z.string().nullable().describe("Reliability (all time): the server's ALL-TIME evidence state vs the baseline on direct evidence \u2014 not_enough_data | early_signal | moderate_evidence | strong_evidence | inconclusive; null for the baseline or when not provided. Not a verdict on the windowed rate"),
+            evidenceState: import_zod3.z.string().nullable().describe("Reliability (all time): the server's ALL-TIME evidence state vs the baseline on direct evidence \u2014 not_enough_data | early_signal | moderate_evidence | strong_evidence | likely_worse | inconclusive; null for the baseline or when not provided. Not a verdict on the windowed rate"),
             probBeatsBaseline: import_zod3.z.number().nullable().describe("P(this arm > baseline), all-time, from the server; null when not provided"),
             reliabilityVerdict: import_zod3.z.enum(["baseline", "ahead", "behind", "unclear", "no_evidence"]).describe("The all-time verdict read from evidenceState \u2014 reliability (all time), which can differ from `verdict` on the window"),
             windowEvidenceState: import_zod3.z.string().nullable().describe("The server's evidence state on the WINDOWED session conversion rate vs the baseline; null for the baseline, when the arm was not scored in the window, or on older APIs"),
@@ -1455,6 +1461,51 @@ function registerGoalTools(server, client) {
       return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
     })
   );
+  server.registerTool(
+    "define_goal",
+    {
+      title: "Define a new goal",
+      description: "Create a NEW goal (conversion signal) for a project. Create-only: it never changes an existing goal \u2014 an id that already exists, including an archived one, is refused (goal_exists); call list_goals first. It never sets or changes the PRIMARY goal (what experiments optimize): the goal is created as 'secondary' (default) or 'guardrail'; choosing the primary stays a dashboard decision. A guardrail goal can pause variants that hurt it \u2014 say so when proposing one. Event types: url_reached (needs urlPattern, e.g. /thank-you), click / form_submit (need a locator, usually easier to pick in the dashboard on-site editor, or fire from code with client.goal('<goalId>') instead), scroll_depth (needs threshold in (0, 1]). Needs an editor/admin login or the project's sk_ server key. Confirm the goal id, event and pattern with the user before calling.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        goalId: import_zod6.z.string().min(1).max(128).refine((s) => !s.startsWith("funnel:"), "'funnel:' is reserved for funnel bindings").describe("Stable id code will reference, e.g. 'signup' or 'checkout-complete'. Must not exist yet."),
+        event: import_zod6.z.enum(["url_reached", "click", "form_submit", "scroll_depth"]).describe("What counts as a conversion"),
+        urlPattern: import_zod6.z.string().min(1).max(512).optional().describe("url_reached only: the path pattern, e.g. '/thank-you' or '/orders/*'"),
+        locator: import_zod6.z.record(import_zod6.z.unknown()).optional().describe('click / form_submit only: the element locator (e.g. { "id": "signup-button" })'),
+        threshold: import_zod6.z.number().gt(0).max(1).optional().describe("scroll_depth only: how far down the page counts, in (0, 1]"),
+        displayName: import_zod6.z.string().min(1).max(128).optional().describe("Human-readable name shown in the dashboard"),
+        role: import_zod6.z.enum(["secondary", "guardrail"]).optional().describe("secondary (default) is tracked and reported; guardrail can also pause variants that hurt it. Never 'primary'."),
+        defaultValue: import_zod6.z.number().positive().max(1e9).optional().describe("Fixed worth of one conversion in the project currency (revenue goals)")
+      },
+      outputSchema: {
+        goalId: import_zod6.z.string(),
+        role: import_zod6.z.enum(["secondary", "guardrail"]).describe("Never primary \u2014 this tool cannot change the primary goal")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, goalId, event, urlPattern, locator, threshold, displayName, role, defaultValue }) => {
+      var _a, _b, _c;
+      const id = encodeURIComponent(projectId);
+      const res = await client.post(`/projects/${id}/goal-definitions`, __spreadValues(__spreadValues(__spreadValues(__spreadValues(__spreadValues(__spreadValues({
+        goalId,
+        event
+      }, urlPattern !== void 0 ? { urlPattern } : {}), locator !== void 0 ? { locator } : {}), threshold !== void 0 ? { threshold } : {}), displayName !== void 0 ? { displayName } : {}), role !== void 0 ? { role } : {}), defaultValue !== void 0 ? { defaultValue } : {}));
+      const structuredContent = { goalId: (_a = res.goalId) != null ? _a : goalId, role: (_c = (_b = res.role) != null ? _b : role) != null ? _c : "secondary" };
+      return {
+        content: [{
+          type: "text",
+          text: `Created goal ${untrusted(structuredContent.goalId)} (${structuredContent.role}, ${event}). It is active now. The primary goal was not changed \u2014 if this should be what experiments optimize, the owner can make it primary in the dashboard. Reference the goalId verbatim from code (client.goal('<goalId>')) if the event is not tracked automatically.`
+        }],
+        structuredContent
+      };
+    }, {
+      goal_exists: "A goal with this id already exists (it may be archived). define_goal never changes an existing goal \u2014 pick a new id (see list_goals), or edit that goal in the dashboard.",
+      primary_not_allowed: "define_goal never sets the primary goal. Create it as secondary; the owner can make it primary in the dashboard.",
+      invalid_goal_id: "That goal id is not allowed: use 1-128 characters, and not the reserved 'funnel:' prefix.",
+      invalid_goal: "The goal definition is incomplete for its event type: url_reached needs urlPattern, click/form_submit need a locator, scroll_depth needs threshold.",
+      "Not Found": "This SentientUI API does not support creating goals from MCP yet (it predates create-only goals). Define the goal in the dashboard instead."
+    })
+  );
 }
 
 // src/tools/funnels.ts
@@ -2082,7 +2133,10 @@ function guidanceFor(dataState, contextType, arms) {
     }
     case "directional": {
       const inconclusive = arms.some((a) => a.state === "inconclusive");
-      return 'No comparison on this component is decided. Early and moderate signals are hypotheses, not results (moderate evidence is wrong about one time in five), so do not target an arm as "under-" or "out-performing". ' + (inconclusive ? "At least one arm ran a full period without separating from the baseline \u2014 the existing versions do not differ meaningfully, so make a clearly different change rather than a tweak. " : "") + "Lean on the best-practice priors below and make one focused change.";
+      const likelyWorse = arms.filter((a) => !a.isBaseline && a.state === "likely_worse").map((a) => untrusted(a.variantId));
+      return 'No comparison on this component is decided. Early, moderate and likely-worse signals are hypotheses, not results (each is wrong about one time in five), so do not target an arm as "under-" or "out-performing". ' + (likelyWorse.length ? `Probably behind the baseline (not decided): ${likelyWorse.join(", ")} \u2014 do not build on ${likelyWorse.length === 1 ? "it" : "them"}. ` : "") + // "did not separate" is not "do not differ": the old wording asserted
+      // an equality the evidence never measured.
+      (inconclusive ? "At least one arm ran a full period without separating from the baseline \u2014 any difference between the existing versions is too small to detect, so make a clearly different change rather than a tweak. " : "") + "Lean on the best-practice priors below and make one focused change.";
     }
     case "collecting":
       if (!arms.some((a) => !a.isBaseline)) {
@@ -2995,7 +3049,7 @@ function registerCellTools(server, client) {
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.20.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.21.0" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new import_mcp.McpServer(
     {
@@ -3056,6 +3110,7 @@ var TOOL_CATALOG = [
   // Goals, funnels, guardrails
   { name: "get_goal_funnel", access: "read", summary: "Per-goal conversion summary (windowed) with descriptive all-time per-variant rates \u2014 not a step funnel (see get_funnel_report)" },
   { name: "list_goals", access: "read", summary: "Defined goals (id, role, event, status), including ones with no conversions yet" },
+  { name: "define_goal", access: "write", summary: "Create a new goal \u2014 never overwrites an existing goal and never changes the primary goal" },
   { name: "list_funnels", access: "read", summary: "Defined multi-step funnels" },
   { name: "get_funnel_report", access: "read", summary: "Step-by-step funnel drop-off" },
   { name: "list_guardrail_events", access: "read", summary: "Every variant currently paused by a guardrail (optionally only pauses from the last N days)" },

package/dist/lib.js

@@ -4,7 +4,7 @@ import {
   ApiError,
   PUBLIC_UI_RESOURCE_URIS,
   createMcpServer
-} from "./chunk-35I5EJTS.js";
+} from "./chunk-K7JN3LOH.js";
 
 // src/tool-catalog.ts
 var TOOL_CATALOG = [
@@ -28,6 +28,7 @@ var TOOL_CATALOG = [
   // Goals, funnels, guardrails
   { name: "get_goal_funnel", access: "read", summary: "Per-goal conversion summary (windowed) with descriptive all-time per-variant rates \u2014 not a step funnel (see get_funnel_report)" },
   { name: "list_goals", access: "read", summary: "Defined goals (id, role, event, status), including ones with no conversions yet" },
+  { name: "define_goal", access: "write", summary: "Create a new goal \u2014 never overwrites an existing goal and never changes the primary goal" },
   { name: "list_funnels", access: "read", summary: "Defined multi-step funnels" },
   { name: "get_funnel_report", access: "read", summary: "Step-by-step funnel drop-off" },
   { name: "list_guardrail_events", access: "read", summary: "Every variant currently paused by a guardrail (optionally only pauses from the last N days)" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentientui/mcp",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "MCP server for SentientUI — exposes project data and actions to AI agents",
   "license": "MIT",
   "homepage": "https://sentient-ui.com",
@@ -35,7 +35,8 @@
       "types": "./dist/lib.d.ts",
       "import": "./dist/lib.js",
       "require": "./dist/lib.cjs"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",