@sentientui/mcp 0.10.0 → 0.12.0

package/README.md

@@ -93,6 +93,7 @@ A sandboxed demo token is provisioned automatically — 10 calls/month, read-onl
 | `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 |
+| `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 |
 | `get_integration_guide` | SentientUI adaptive-ladder setup guide (static — same for every project) |

package/dist/{chunk-ZH3EDKIT.js → chunk-BMOKDBGH.js}

@@ -734,12 +734,16 @@ function registerGoalTools(server, client) {
       inputSchema: { projectId: projectIdSchema },
       _meta: uiMeta("goal-funnel"),
       outputSchema: {
+        currency: z6.string().describe("Project display currency (ISO-4217) for the revenue fields"),
         goals: z6.array(
           z6.object({
             goalName: z6.string(),
             hits: z6.number(),
             uniqueSessions: z6.number(),
             conversionRate: z6.number().describe("Unique-session conversion rate (0-1)"),
+            revenue: z6.number().nullable().describe("Total revenue from valued conversions, in the project currency (null for valueless goals)"),
+            avgOrderValue: z6.number().nullable().describe("Average value per valued conversion (null for valueless goals)"),
+            revenuePerSession: z6.number().nullable().describe("Revenue divided by all project sessions (null for valueless goals)"),
             variants: z6.array(
               z6.object({
                 componentId: z6.string(),
@@ -757,20 +761,28 @@ function registerGoalTools(server, client) {
       }
     },
     withApiErrorGuidance(async ({ projectId }) => {
+      var _a, _b;
       const id = encodeURIComponent(projectId);
       const data = await client.get(`/projects/${id}/goals`);
       const structuredContent = {
-        goals: data.goals.map((g) => ({
-          goalName: g.goalName,
-          hits: g.hits,
-          uniqueSessions: g.uniqueSessions,
-          conversionRate: g.pct,
-          variants: g.variants.map((v) => ({
-            componentId: v.componentId,
-            variantId: v.variantId,
-            completionRate: v.completionRate
-          }))
-        }))
+        currency: (_a = data.currency) != null ? _a : "USD",
+        goals: data.goals.map((g) => {
+          var _a2, _b2, _c;
+          return {
+            goalName: g.goalName,
+            hits: g.hits,
+            uniqueSessions: g.uniqueSessions,
+            conversionRate: g.pct,
+            revenue: (_a2 = g.revenue) != null ? _a2 : null,
+            avgOrderValue: (_b2 = g.avgOrderValue) != null ? _b2 : null,
+            revenuePerSession: (_c = g.revenuePerSession) != null ? _c : null,
+            variants: g.variants.map((v) => ({
+              componentId: v.componentId,
+              variantId: v.variantId,
+              completionRate: v.completionRate
+            }))
+          };
+        })
       };
       if (!data.goals.length) {
         return {
@@ -779,14 +791,78 @@ function registerGoalTools(server, client) {
           _meta: uiMeta("goal-funnel")
         };
       }
-      const lines = data.goals.flatMap((g) => [
-        `${g.goalName}: ${g.hits} hits, ${g.uniqueSessions} unique sessions, ${(g.pct * 100).toFixed(1)}% conversion`,
-        ...g.variants.map((v) => `  ${v.componentId}/${v.variantId}: ${(v.completionRate * 100).toFixed(1)}% per assigned session`),
-        ""
-      ]);
+      const currency = (_b = data.currency) != null ? _b : "USD";
+      const lines = data.goals.flatMap((g) => {
+        var _a2;
+        return [
+          `${g.goalName}: ${g.hits} hits, ${g.uniqueSessions} unique sessions, ${(g.pct * 100).toFixed(1)}% conversion` + (g.revenue != null ? `, ${g.revenue.toFixed(2)} ${currency} revenue (${((_a2 = g.avgOrderValue) != null ? _a2 : 0).toFixed(2)} avg order)` : ""),
+          ...g.variants.map((v) => `  ${v.componentId}/${v.variantId}: ${(v.completionRate * 100).toFixed(1)}% per assigned session`),
+          ""
+        ];
+      });
       return { content: [{ type: "text", text: lines.join("\n").trim() }], structuredContent, _meta: uiMeta("goal-funnel") };
     })
   );
+  server.registerTool(
+    "list_goals",
+    {
+      title: "List goal definitions",
+      description: `List the project's defined goals \u2014 including ones with no conversions yet, which get_goal_funnel cannot see. Returns each goal's stable id, display name, role (primary/secondary/guardrail), event type, and status. Reference a goalId verbatim from code: client.goal('<goalId>') or <Adaptive goal="<goalId>">.`,
+      inputSchema: { projectId: projectIdSchema },
+      outputSchema: {
+        goals: z6.array(
+          z6.object({
+            goalId: z6.string().describe("Stable id \u2014 use this exact string when firing the goal from code"),
+            displayName: z6.string(),
+            role: z6.string().describe("primary | secondary | guardrail"),
+            event: z6.string().describe("click | form_submit | url_reached"),
+            urlPattern: z6.string().nullable().describe("Only for url_reached goals"),
+            status: z6.string().describe("active | archived"),
+            defaultValue: z6.number().nullable().describe("Fixed worth applied when a conversion carries no explicit value (project currency); null when unset")
+          })
+        ).describe("Defined goals (empty if none)")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    withApiErrorGuidance(async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/goal-definitions`);
+      const structuredContent = {
+        goals: data.goals.map((g) => {
+          var _a;
+          return {
+            goalId: g.goal_id,
+            displayName: g.display_name,
+            role: g.role,
+            event: g.event,
+            urlPattern: (_a = g.url_pattern) != null ? _a : null,
+            status: g.status,
+            // NUMERIC arrives serialized as a string; coerce and tolerate its
+            // absence from an older API deploy.
+            defaultValue: g.default_value != null ? Number(g.default_value) : null
+          };
+        })
+      };
+      if (!structuredContent.goals.length) {
+        return {
+          content: [{
+            type: "text",
+            text: "No goal definitions yet. Define one in the dashboard (Goals page or onboarding chat), or fire client.goal('<name>') from code and it will appear in get_goal_funnel once it converts."
+          }],
+          structuredContent
+        };
+      }
+      const lines = structuredContent.goals.map(
+        (g) => `${g.goalId} (${g.role}, ${g.event}${g.status === "archived" ? ", archived" : ""}) \u2014 ${g.displayName}`
+      );
+      lines.push("", `Reference a goalId verbatim from code: client.goal('<goalId>') or <Adaptive goal="<goalId>">.`);
+      return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
+    })
+  );
 }
 
 // src/tools/guardrails.ts
@@ -1520,7 +1596,7 @@ function registerAgentTrafficTools(server, client) {
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.10.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.12.0" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new McpServer(
     {

package/dist/index.cjs

@@ -738,12 +738,16 @@ function registerGoalTools(server, client) {
       inputSchema: { projectId: projectIdSchema },
       _meta: uiMeta("goal-funnel"),
       outputSchema: {
+        currency: import_zod6.z.string().describe("Project display currency (ISO-4217) for the revenue fields"),
         goals: import_zod6.z.array(
           import_zod6.z.object({
             goalName: import_zod6.z.string(),
             hits: import_zod6.z.number(),
             uniqueSessions: import_zod6.z.number(),
             conversionRate: import_zod6.z.number().describe("Unique-session conversion rate (0-1)"),
+            revenue: import_zod6.z.number().nullable().describe("Total revenue from valued conversions, in the project currency (null for valueless goals)"),
+            avgOrderValue: import_zod6.z.number().nullable().describe("Average value per valued conversion (null for valueless goals)"),
+            revenuePerSession: import_zod6.z.number().nullable().describe("Revenue divided by all project sessions (null for valueless goals)"),
             variants: import_zod6.z.array(
               import_zod6.z.object({
                 componentId: import_zod6.z.string(),
@@ -761,20 +765,28 @@ function registerGoalTools(server, client) {
       }
     },
     withApiErrorGuidance(async ({ projectId }) => {
+      var _a2, _b;
       const id = encodeURIComponent(projectId);
       const data = await client.get(`/projects/${id}/goals`);
       const structuredContent = {
-        goals: data.goals.map((g) => ({
-          goalName: g.goalName,
-          hits: g.hits,
-          uniqueSessions: g.uniqueSessions,
-          conversionRate: g.pct,
-          variants: g.variants.map((v) => ({
-            componentId: v.componentId,
-            variantId: v.variantId,
-            completionRate: v.completionRate
-          }))
-        }))
+        currency: (_a2 = data.currency) != null ? _a2 : "USD",
+        goals: data.goals.map((g) => {
+          var _a3, _b2, _c;
+          return {
+            goalName: g.goalName,
+            hits: g.hits,
+            uniqueSessions: g.uniqueSessions,
+            conversionRate: g.pct,
+            revenue: (_a3 = g.revenue) != null ? _a3 : null,
+            avgOrderValue: (_b2 = g.avgOrderValue) != null ? _b2 : null,
+            revenuePerSession: (_c = g.revenuePerSession) != null ? _c : null,
+            variants: g.variants.map((v) => ({
+              componentId: v.componentId,
+              variantId: v.variantId,
+              completionRate: v.completionRate
+            }))
+          };
+        })
       };
       if (!data.goals.length) {
         return {
@@ -783,14 +795,78 @@ function registerGoalTools(server, client) {
           _meta: uiMeta("goal-funnel")
         };
       }
-      const lines = data.goals.flatMap((g) => [
-        `${g.goalName}: ${g.hits} hits, ${g.uniqueSessions} unique sessions, ${(g.pct * 100).toFixed(1)}% conversion`,
-        ...g.variants.map((v) => `  ${v.componentId}/${v.variantId}: ${(v.completionRate * 100).toFixed(1)}% per assigned session`),
-        ""
-      ]);
+      const currency = (_b = data.currency) != null ? _b : "USD";
+      const lines = data.goals.flatMap((g) => {
+        var _a3;
+        return [
+          `${g.goalName}: ${g.hits} hits, ${g.uniqueSessions} unique sessions, ${(g.pct * 100).toFixed(1)}% conversion` + (g.revenue != null ? `, ${g.revenue.toFixed(2)} ${currency} revenue (${((_a3 = g.avgOrderValue) != null ? _a3 : 0).toFixed(2)} avg order)` : ""),
+          ...g.variants.map((v) => `  ${v.componentId}/${v.variantId}: ${(v.completionRate * 100).toFixed(1)}% per assigned session`),
+          ""
+        ];
+      });
       return { content: [{ type: "text", text: lines.join("\n").trim() }], structuredContent, _meta: uiMeta("goal-funnel") };
     })
   );
+  server.registerTool(
+    "list_goals",
+    {
+      title: "List goal definitions",
+      description: `List the project's defined goals \u2014 including ones with no conversions yet, which get_goal_funnel cannot see. Returns each goal's stable id, display name, role (primary/secondary/guardrail), event type, and status. Reference a goalId verbatim from code: client.goal('<goalId>') or <Adaptive goal="<goalId>">.`,
+      inputSchema: { projectId: projectIdSchema },
+      outputSchema: {
+        goals: import_zod6.z.array(
+          import_zod6.z.object({
+            goalId: import_zod6.z.string().describe("Stable id \u2014 use this exact string when firing the goal from code"),
+            displayName: import_zod6.z.string(),
+            role: import_zod6.z.string().describe("primary | secondary | guardrail"),
+            event: import_zod6.z.string().describe("click | form_submit | url_reached"),
+            urlPattern: import_zod6.z.string().nullable().describe("Only for url_reached goals"),
+            status: import_zod6.z.string().describe("active | archived"),
+            defaultValue: import_zod6.z.number().nullable().describe("Fixed worth applied when a conversion carries no explicit value (project currency); null when unset")
+          })
+        ).describe("Defined goals (empty if none)")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    withApiErrorGuidance(async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/goal-definitions`);
+      const structuredContent = {
+        goals: data.goals.map((g) => {
+          var _a2;
+          return {
+            goalId: g.goal_id,
+            displayName: g.display_name,
+            role: g.role,
+            event: g.event,
+            urlPattern: (_a2 = g.url_pattern) != null ? _a2 : null,
+            status: g.status,
+            // NUMERIC arrives serialized as a string; coerce and tolerate its
+            // absence from an older API deploy.
+            defaultValue: g.default_value != null ? Number(g.default_value) : null
+          };
+        })
+      };
+      if (!structuredContent.goals.length) {
+        return {
+          content: [{
+            type: "text",
+            text: "No goal definitions yet. Define one in the dashboard (Goals page or onboarding chat), or fire client.goal('<name>') from code and it will appear in get_goal_funnel once it converts."
+          }],
+          structuredContent
+        };
+      }
+      const lines = structuredContent.goals.map(
+        (g) => `${g.goalId} (${g.role}, ${g.event}${g.status === "archived" ? ", archived" : ""}) \u2014 ${g.displayName}`
+      );
+      lines.push("", `Reference a goalId verbatim from code: client.goal('<goalId>') or <Adaptive goal="<goalId>">.`);
+      return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
+    })
+  );
 }
 
 // src/tools/guardrails.ts
@@ -1524,7 +1600,7 @@ function registerAgentTrafficTools(server, client) {
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.10.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.12.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-ZH3EDKIT.js";
+} from "./chunk-BMOKDBGH.js";
 
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/lib.cjs

@@ -763,12 +763,16 @@ function registerGoalTools(server, client) {
       inputSchema: { projectId: projectIdSchema },
       _meta: uiMeta("goal-funnel"),
       outputSchema: {
+        currency: import_zod6.z.string().describe("Project display currency (ISO-4217) for the revenue fields"),
         goals: import_zod6.z.array(
           import_zod6.z.object({
             goalName: import_zod6.z.string(),
             hits: import_zod6.z.number(),
             uniqueSessions: import_zod6.z.number(),
             conversionRate: import_zod6.z.number().describe("Unique-session conversion rate (0-1)"),
+            revenue: import_zod6.z.number().nullable().describe("Total revenue from valued conversions, in the project currency (null for valueless goals)"),
+            avgOrderValue: import_zod6.z.number().nullable().describe("Average value per valued conversion (null for valueless goals)"),
+            revenuePerSession: import_zod6.z.number().nullable().describe("Revenue divided by all project sessions (null for valueless goals)"),
             variants: import_zod6.z.array(
               import_zod6.z.object({
                 componentId: import_zod6.z.string(),
@@ -786,20 +790,28 @@ function registerGoalTools(server, client) {
       }
     },
     withApiErrorGuidance(async ({ projectId }) => {
+      var _a, _b;
       const id = encodeURIComponent(projectId);
       const data = await client.get(`/projects/${id}/goals`);
       const structuredContent = {
-        goals: data.goals.map((g) => ({
-          goalName: g.goalName,
-          hits: g.hits,
-          uniqueSessions: g.uniqueSessions,
-          conversionRate: g.pct,
-          variants: g.variants.map((v) => ({
-            componentId: v.componentId,
-            variantId: v.variantId,
-            completionRate: v.completionRate
-          }))
-        }))
+        currency: (_a = data.currency) != null ? _a : "USD",
+        goals: data.goals.map((g) => {
+          var _a2, _b2, _c;
+          return {
+            goalName: g.goalName,
+            hits: g.hits,
+            uniqueSessions: g.uniqueSessions,
+            conversionRate: g.pct,
+            revenue: (_a2 = g.revenue) != null ? _a2 : null,
+            avgOrderValue: (_b2 = g.avgOrderValue) != null ? _b2 : null,
+            revenuePerSession: (_c = g.revenuePerSession) != null ? _c : null,
+            variants: g.variants.map((v) => ({
+              componentId: v.componentId,
+              variantId: v.variantId,
+              completionRate: v.completionRate
+            }))
+          };
+        })
       };
       if (!data.goals.length) {
         return {
@@ -808,14 +820,78 @@ function registerGoalTools(server, client) {
           _meta: uiMeta("goal-funnel")
         };
       }
-      const lines = data.goals.flatMap((g) => [
-        `${g.goalName}: ${g.hits} hits, ${g.uniqueSessions} unique sessions, ${(g.pct * 100).toFixed(1)}% conversion`,
-        ...g.variants.map((v) => `  ${v.componentId}/${v.variantId}: ${(v.completionRate * 100).toFixed(1)}% per assigned session`),
-        ""
-      ]);
+      const currency = (_b = data.currency) != null ? _b : "USD";
+      const lines = data.goals.flatMap((g) => {
+        var _a2;
+        return [
+          `${g.goalName}: ${g.hits} hits, ${g.uniqueSessions} unique sessions, ${(g.pct * 100).toFixed(1)}% conversion` + (g.revenue != null ? `, ${g.revenue.toFixed(2)} ${currency} revenue (${((_a2 = g.avgOrderValue) != null ? _a2 : 0).toFixed(2)} avg order)` : ""),
+          ...g.variants.map((v) => `  ${v.componentId}/${v.variantId}: ${(v.completionRate * 100).toFixed(1)}% per assigned session`),
+          ""
+        ];
+      });
       return { content: [{ type: "text", text: lines.join("\n").trim() }], structuredContent, _meta: uiMeta("goal-funnel") };
     })
   );
+  server.registerTool(
+    "list_goals",
+    {
+      title: "List goal definitions",
+      description: `List the project's defined goals \u2014 including ones with no conversions yet, which get_goal_funnel cannot see. Returns each goal's stable id, display name, role (primary/secondary/guardrail), event type, and status. Reference a goalId verbatim from code: client.goal('<goalId>') or <Adaptive goal="<goalId>">.`,
+      inputSchema: { projectId: projectIdSchema },
+      outputSchema: {
+        goals: import_zod6.z.array(
+          import_zod6.z.object({
+            goalId: import_zod6.z.string().describe("Stable id \u2014 use this exact string when firing the goal from code"),
+            displayName: import_zod6.z.string(),
+            role: import_zod6.z.string().describe("primary | secondary | guardrail"),
+            event: import_zod6.z.string().describe("click | form_submit | url_reached"),
+            urlPattern: import_zod6.z.string().nullable().describe("Only for url_reached goals"),
+            status: import_zod6.z.string().describe("active | archived"),
+            defaultValue: import_zod6.z.number().nullable().describe("Fixed worth applied when a conversion carries no explicit value (project currency); null when unset")
+          })
+        ).describe("Defined goals (empty if none)")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    withApiErrorGuidance(async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/goal-definitions`);
+      const structuredContent = {
+        goals: data.goals.map((g) => {
+          var _a;
+          return {
+            goalId: g.goal_id,
+            displayName: g.display_name,
+            role: g.role,
+            event: g.event,
+            urlPattern: (_a = g.url_pattern) != null ? _a : null,
+            status: g.status,
+            // NUMERIC arrives serialized as a string; coerce and tolerate its
+            // absence from an older API deploy.
+            defaultValue: g.default_value != null ? Number(g.default_value) : null
+          };
+        })
+      };
+      if (!structuredContent.goals.length) {
+        return {
+          content: [{
+            type: "text",
+            text: "No goal definitions yet. Define one in the dashboard (Goals page or onboarding chat), or fire client.goal('<name>') from code and it will appear in get_goal_funnel once it converts."
+          }],
+          structuredContent
+        };
+      }
+      const lines = structuredContent.goals.map(
+        (g) => `${g.goalId} (${g.role}, ${g.event}${g.status === "archived" ? ", archived" : ""}) \u2014 ${g.displayName}`
+      );
+      lines.push("", `Reference a goalId verbatim from code: client.goal('<goalId>') or <Adaptive goal="<goalId>">.`);
+      return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
+    })
+  );
 }
 
 // src/tools/guardrails.ts
@@ -1549,7 +1625,7 @@ function registerAgentTrafficTools(server, client) {
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.10.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.12.0" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new import_mcp.McpServer(
     {

package/dist/lib.js

@@ -3,7 +3,7 @@ import {
   ApiClient,
   ApiError,
   createMcpServer
-} from "./chunk-ZH3EDKIT.js";
+} from "./chunk-BMOKDBGH.js";
 export {
   ApiClient,
   ApiError,

package/package.json

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