@apex-inc/mcp-server 0.13.0 → 0.15.0

package/dist/tools.js

@@ -64,6 +64,28 @@ function appUrl(path) {
 function journeyLink(id) {
     return appUrl(`/dashboard/communications/journeys/${id}`);
 }
+/**
+ * Render the author-time conflict guard advisory (non-blocking). `selfId` is the
+ * candidate experiment's id when known (so the set_experiment_mutex suggestion
+ * is copy-pasteable); omitted during pre-create previews.
+ */
+function renderConflictAdvisory(data, selfId) {
+    const lines = [];
+    for (const h of data.differentMetric) {
+        const soft = h.confidence === "low" ? " (same data source — only a real conflict if it targets the same screen)" : "";
+        lines.push(`⚠ Overlaps "${h.name}" (${h.experimentId}) on ${h.location}${soft}. It measures ${h.primaryMetricLabel}; this measures a different goal — running both at once contaminates both results.`);
+        lines.push(selfId
+            ? `   → Run both safely in parallel: set_experiment_mutex({ experimentId: "${selfId}", withExperimentId: "${h.experimentId}" }). Or sequence: activate this only after "${h.name}" concludes.`
+            : `   → After creating it, run both safely in parallel: set_experiment_mutex({ experimentId: "<new id>", withExperimentId: "${h.experimentId}" }). Or sequence after "${h.name}" concludes.`);
+    }
+    for (const h of data.sameMetric) {
+        const soft = h.confidence === "low" ? " (same data source — only a real conflict if it targets the same screen)" : "";
+        lines.push(`↔ "${h.name}" (${h.experimentId}) already tests ${h.location} for ${h.primaryMetricLabel} — the SAME metric${soft}. These look like two arms of one question: consider adding your change as a variant of "${h.name}" rather than a separate experiment.`);
+    }
+    if (lines.length === 0)
+        return "✓ No overlap with live experiments on this surface.";
+    return `Conflict guard:\n${lines.join("\n")}`;
+}
 /**
  * Detect a MOBILE experiment surface from repo signals (the MCP runs in the
  * merchant's repo). Walks up a few dirs looking for capacitor.config.* or a
@@ -495,6 +517,25 @@ export const toolDefinitions = {
                 };
             }
             if (isPreview) {
+                // Author-time conflict guard (best-effort, non-blocking): warn if this
+                // overlaps a LIVE experiment on the same surface before it's created.
+                let conflictAdvisory;
+                try {
+                    const cc = await apiPost("/api/experiments/check-conflicts", {
+                        surface: experimentSurface,
+                        target_component: args.targetComponent,
+                        target_url: args.targetUrl,
+                        target_anchor: args.targetAnchor,
+                        data_source_id: args.dataSourceId,
+                        primary_metric_event: primaryMetric.source.eventType,
+                    });
+                    if (cc.data.sameMetric.length || cc.data.differentMetric.length) {
+                        conflictAdvisory = renderConflictAdvisory(cc.data);
+                    }
+                }
+                catch {
+                    /* conflict check is advisory; never block the preview */
+                }
                 const recipe = {
                     _apex: true,
                     _type: "experiment_preview",
@@ -511,7 +552,8 @@ export const toolDefinitions = {
                     beliefId: args.beliefId || null,
                     beliefStatement: args.beliefStatement || null,
                     predictionId: args.predictionId || null,
-                    _instructions: "Before proposing variant copy, ground every factual claim in .apex/brand-truth.md (read it; cite the line each claim traces to; if a claim isn't backed there, ask the user instead of inventing it). Then present this as a summary and ask the user to confirm (1), adjust (2), or cancel (3). Do NOT create the experiment until confirmed.",
+                    ...(conflictAdvisory ? { _conflict_advisory: conflictAdvisory } : {}),
+                    _instructions: `Before proposing variant copy, ground every factual claim in .apex/brand-truth.md (read it; cite the line each claim traces to; if a claim isn't backed there, ask the user instead of inventing it).${conflictAdvisory ? " IMPORTANT: _conflict_advisory is set — show it to the user and resolve the overlap (mutex / variant / sequence) before creating." : ""} Then present this as a summary and ask the user to confirm (1), adjust (2), or cancel (3). Do NOT create the experiment until confirmed.`,
                 };
                 return { content: [{ type: "text", text: JSON.stringify(recipe, null, 2) }] };
             }
@@ -602,6 +644,9 @@ export const toolDefinitions = {
                 name: args.name,
                 targetUrl: args.targetUrl,
                 targetAnchor: args.targetAnchor,
+                // Persist the component (e.g. "ProductCard") as a precise location
+                // signal for the author-time conflict guard — esp. mobile/SDK arms.
+                ...(args.targetComponent ? { targetComponent: args.targetComponent } : {}),
                 createdFrom: "cursor",
                 status: "draft",
                 ...(args.dataSourceId ? { dataSourceId: args.dataSourceId } : {}),
@@ -978,6 +1023,17 @@ export const toolDefinitions = {
             else if (wiring && !wiring.bothArmsLive && force === true) {
                 notes.push(`  ⚠ Launched with force: true despite an incomplete wiring check`, `    (verdict: ${wiring.verdict}, ${wiring.armsLive}/${wiring.totalArms} arm(s) live).`, `    Some arm(s) may not be collecting data yet.`, ``);
             }
+            // Author-time conflict guard (advisory): if this now-running experiment
+            // overlaps another live one on the same surface, surface the fix.
+            try {
+                const cc = await apiPost("/api/experiments/check-conflicts", { experiment_id: experimentId });
+                if (cc.data.sameMetric.length || cc.data.differentMetric.length) {
+                    notes.push(`  ${renderConflictAdvisory(cc.data, experimentId).split("\n").join("\n  ")}`, ``);
+                }
+            }
+            catch {
+                /* advisory only — never affect the launch result */
+            }
             return {
                 content: [
                     {
@@ -1445,6 +1501,53 @@ export const toolDefinitions = {
             }
         },
     },
+    check_experiment_conflicts: {
+        description: `${APEX} — Before you create or activate an experiment, check whether it overlaps a LIVE experiment on the same surface. Same location + DIFFERENT metric → they'll contaminate each other (make them mutually exclusive with set_experiment_mutex, or sequence). Same location + SAME metric → add a variant to the existing experiment instead. Pass either experimentId (an existing draft) OR the candidate's location + primaryMetricEvent. Advisory only — nothing is blocked.`,
+        schema: z.object({
+            experimentId: z.string().optional().describe("Check an existing experiment by id (loads its location + metric)."),
+            surface: z.enum(["web", "mobile"]).optional(),
+            targetComponent: z.string().optional().describe("Component/file the experiment changes, e.g. 'ProductCard'."),
+            targetUrl: z.string().optional(),
+            targetAnchor: z.string().optional(),
+            dataSourceId: z.string().optional(),
+            primaryMetricEvent: z.string().optional().describe("Canonical primary-metric event, e.g. 'add_to_cart'."),
+        }),
+        handler: async (args) => {
+            try {
+                const res = await apiPost("/api/experiments/check-conflicts", {
+                    ...(args.experimentId ? { experiment_id: args.experimentId } : {}),
+                    surface: args.surface,
+                    target_component: args.targetComponent,
+                    target_url: args.targetUrl,
+                    target_anchor: args.targetAnchor,
+                    data_source_id: args.dataSourceId,
+                    primary_metric_event: args.primaryMetricEvent,
+                });
+                return { content: [{ type: "text", text: `${APEX} ${renderConflictAdvisory(res.data, args.experimentId)}` }] };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: `${APEX} ${errMsg(err)}` }], isError: true };
+            }
+        },
+    },
+    set_experiment_mutex: {
+        description: `${APEX} — Put two experiments in a mutual-exclusion group: no visitor is ever assigned to both, so they run concurrently with partitioned traffic (the scientifically clean way to run two experiments that touch the same surface). Bidirectional. Pass mode:"remove" to unlink. Safe on running experiments — only affects future assignments.`,
+        schema: z.object({
+            experimentId: z.string(),
+            withExperimentId: z.string().describe("The other experiment to make mutually exclusive with."),
+            mode: z.enum(["add", "remove"]).optional().describe("'add' (default) links; 'remove' unlinks."),
+        }),
+        handler: async ({ experimentId, withExperimentId, mode }) => {
+            try {
+                await apiPost(`/api/experiments/${encodeURIComponent(experimentId)}/mutex`, { withExperimentId, mode });
+                const verb = mode === "remove" ? "are no longer" : "are now";
+                return { content: [{ type: "text", text: `${APEX} ${experimentId} and ${withExperimentId} ${verb} mutually exclusive — no visitor will be assigned to both.` }] };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: `${APEX} ${errMsg(err)}` }], isError: true };
+            }
+        },
+    },
     get_growth_reality: {
         description: `${APEX} — "Is our growth real?" Per goal, the cumulative lift of everything Apex did (journeys + experiments) vs a persistent do-nothing global holdout, with a 95% CI. The honest, holdout-gated answer to "would this have happened anyway?" Forward-only; goals still collecting are flagged, not faked.`,
         schema: z.object({
@@ -2919,12 +3022,12 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     add_journey_branch: {
-        description: `${APEX} — Insert a CONDITIONAL content branch before the exit: evaluate one condition and send a different communication to each side. Use this for true content branching (e.g. "cart value > $100 → VIP email, else standard email"). For the simpler "skip the next send if they already converted" case, use add_journey_exit instead. The condition is an attribute test (fieldPath + operator + value) or an event test (event_fired / event_not_fired within a window).`,
+        description: `${APEX} — Insert a CONDITIONAL content branch before the exit: evaluate one condition and send a different communication to each side. Use this for true content branching (e.g. "cart value > $100 → VIP email, else standard email"). For the simpler "skip the next send if they already converted" case, use add_journey_exit instead. The condition is an attribute test (field_path + operator + value) or an event test (event_fired / event_not_fired within a window).`,
         schema: z.object({
             journeyId: z.string(),
             condition: z.object({
                 kind: z.enum(["attribute", "event_fired", "event_not_fired"]),
-                fieldPath: z.string().optional().describe("attribute only: dotted path, e.g. 'cart.valueCents' or 'plan'."),
+                field_path: z.string().optional().describe("attribute only: dotted path, e.g. 'cart.valueCents' or 'plan'."),
                 operator: z
                     .enum(["equals", "not_equals", "greater_than", "less_than", "in", "exists", "not_exists"])
                     .optional()
@@ -2933,8 +3036,8 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                     .union([z.string(), z.number(), z.boolean(), z.array(z.union([z.string(), z.number(), z.boolean()]))])
                     .optional()
                     .describe("attribute only: the comparison value (omit for exists/not_exists)."),
-                eventName: z.string().optional().describe("event only: the canonical event, e.g. 'purchase'."),
-                windowDays: z.number().optional().describe("event only: look-back window in days (omit = ever)."),
+                event_name: z.string().optional().describe("event only: the canonical event, e.g. 'purchase'."),
+                window_days: z.number().optional().describe("event only: look-back window in days (omit = ever)."),
             }),
             whenTrueCommId: z.string().describe("Communication to send when the condition matches."),
             whenFalseCommId: z.string().optional().describe("Communication to send when it doesn't match (omit to just continue to exit)."),
@@ -2946,24 +3049,24 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                 // Build the predicate leaf (AudiencePredicate is a bare leaf here).
                 let predicate;
                 if (c.kind === "attribute") {
-                    if (!c.fieldPath || !c.operator) {
-                        return { content: [{ type: "text", text: `${APEX} An attribute condition needs fieldPath and operator.` }], isError: true };
+                    if (!c.field_path || !c.operator) {
+                        return { content: [{ type: "text", text: `${APEX} An attribute condition needs field_path and operator.` }], isError: true };
                     }
                     predicate = {
                         kind: "attribute",
-                        fieldPath: c.fieldPath,
+                        fieldPath: c.field_path,
                         operator: c.operator,
                         ...(c.value !== undefined ? { value: c.value } : {}),
                     };
                 }
                 else {
-                    if (!c.eventName) {
-                        return { content: [{ type: "text", text: `${APEX} An event condition needs eventName.` }], isError: true };
+                    if (!c.event_name) {
+                        return { content: [{ type: "text", text: `${APEX} An event condition needs event_name.` }], isError: true };
                     }
                     predicate = {
                         kind: c.kind,
-                        eventName: c.eventName,
-                        window: c.windowDays ? { type: "last_n_days", days: c.windowDays } : { type: "ever" },
+                        eventName: c.event_name,
+                        window: c.window_days ? { type: "last_n_days", days: c.window_days } : { type: "ever" },
                     };
                 }
                 const j = await apiGet(`/api/journeys/${encodeURIComponent(args.journeyId)}`);
@@ -3081,15 +3184,10 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
     get_journey: {
         description: `${APEX} — Read the full configuration for a single journey, including steps, goal event, attribution window, and exit rules. Use after list_journeys to inspect a journey's wiring before recommending edits.`,
         schema: z.object({
-            journeyId: z.string().optional().describe("Journey id returned from list_journeys."),
-            journey_id: z.string().optional().describe("Deprecated alias for journeyId."),
+            journeyId: z.string().describe("Journey id returned from list_journeys."),
         }),
-        handler: async ({ journeyId, journey_id }) => {
-            const jid = journeyId ?? journey_id;
-            if (!jid) {
-                return { content: [{ type: "text", text: `${APEX} journeyId is required.` }], isError: true };
-            }
-            const journey = await apiGet(`/api/journeys/${encodeURIComponent(jid)}`);
+        handler: async ({ journeyId }) => {
+            const journey = await apiGet(`/api/journeys/${encodeURIComponent(journeyId)}`);
             return {
                 content: [
                     {
@@ -3103,15 +3201,10 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
     list_journey_exits: {
         description: `${APEX} — Just the exit-rules block of one journey. Cheaper than get_journey for audit loops that only need to know "does this journey suppress purchase / unsubscribe?".`,
         schema: z.object({
-            journeyId: z.string().optional(),
-            journey_id: z.string().optional().describe("Deprecated alias for journeyId."),
+            journeyId: z.string(),
         }),
-        handler: async ({ journeyId, journey_id }) => {
-            const jid = journeyId ?? journey_id;
-            if (!jid) {
-                return { content: [{ type: "text", text: `${APEX} journeyId is required.` }], isError: true };
-            }
-            const body = await apiGet(`/api/journeys/${encodeURIComponent(jid)}/exit-rules`);
+        handler: async ({ journeyId }) => {
+            const body = await apiGet(`/api/journeys/${encodeURIComponent(journeyId)}/exit-rules`);
             return {
                 content: [
                     {
@@ -3125,21 +3218,16 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
     add_journey_exit: {
         description: `${APEX} — Append a new exit rule to a journey's draft. Rule fires when the chosen trigger contract's event lands on a contact with an in-flight execution — Apex stops the execution and skips any pending sends. Re-publish required for the rule to take effect on live runs.`,
         schema: z.object({
-            journeyId: z.string().optional(),
-            journey_id: z.string().optional().describe("Deprecated alias for journeyId."),
-            trigger_contract_id: z
+            journeyId: z.string(),
+            triggerContractId: z
                 .string()
                 .describe("Trigger-contract id, e.g. trig-in-app-purchase"),
             label: z.string().optional(),
             enabled: z.boolean().optional().default(true),
         }),
-        handler: async ({ journeyId, journey_id, trigger_contract_id, label, enabled, }) => {
-            const jid = journeyId ?? journey_id;
-            if (!jid) {
-                return { content: [{ type: "text", text: `${APEX} journeyId is required.` }], isError: true };
-            }
-            const body = await apiPost(`/api/journeys/${encodeURIComponent(jid)}/exit-rules`, {
-                triggerContractId: trigger_contract_id,
+        handler: async ({ journeyId, triggerContractId, label, enabled, }) => {
+            const body = await apiPost(`/api/journeys/${encodeURIComponent(journeyId)}/exit-rules`, {
+                triggerContractId,
                 ...(label !== undefined && { label }),
                 enabled: enabled !== false,
             });
@@ -3156,21 +3244,16 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
     remove_journey_exit: {
         description: `${APEX} — Remove an exit rule from a journey's draft. Re-publish required for the change to apply to live runs.`,
         schema: z.object({
-            journeyId: z.string().optional(),
-            journey_id: z.string().optional().describe("Deprecated alias for journeyId."),
-            rule_id: z.string(),
+            journeyId: z.string(),
+            ruleId: z.string(),
         }),
-        handler: async ({ journeyId, journey_id, rule_id, }) => {
-            const jid = journeyId ?? journey_id;
-            if (!jid) {
-                return { content: [{ type: "text", text: `${APEX} journeyId is required.` }], isError: true };
-            }
-            await apiDelete(`/api/journeys/${encodeURIComponent(jid)}/exit-rules/${encodeURIComponent(rule_id)}`);
+        handler: async ({ journeyId, ruleId, }) => {
+            await apiDelete(`/api/journeys/${encodeURIComponent(journeyId)}/exit-rules/${encodeURIComponent(ruleId)}`);
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Removed exit rule ${rule_id} from journey ${jid}.`,
+                        text: `Removed exit rule ${ruleId} from journey ${journeyId}.`,
                     },
                 ],
             };