@apex-inc/mcp-server 0.12.0 → 0.14.0

package/dist/tools.js

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
 import { apiGet, apiPost, apiPatch, apiDelete, postWithIdempotency, setActiveWorkspace, getActiveWorkspace, setActiveOrg, getActiveOrg, getUserContext } from "./api-client.js";
 import { resolveExperimentHypothesis } from "./experiment-copy.js";
 const APEX = "∧ Apex";
@@ -62,6 +64,83 @@ function appUrl(path) {
 function journeyLink(id) {
     return appUrl(`/dashboard/communications/journeys/${id}`);
 }
+/**
+ * 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
+ * Capacitor/RN dependency. Returns null when there's no mobile signal (web is
+ * the safe default — a website repo carries no special marker). QA 2026-06-18.
+ */
+function detectSurfaceFromRepo() {
+    try {
+        let dir = process.cwd();
+        for (let i = 0; i < 4; i++) {
+            for (const f of [
+                "capacitor.config.ts",
+                "capacitor.config.js",
+                "capacitor.config.json",
+                "capacitor.config.mjs",
+            ]) {
+                if (existsSync(join(dir, f)))
+                    return "mobile";
+            }
+            const pkgPath = join(dir, "package.json");
+            if (existsSync(pkgPath)) {
+                try {
+                    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+                    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+                    if (deps["@apex-inc/capacitor-plugin"] ||
+                        deps["@capacitor/core"] ||
+                        deps["react-native"]) {
+                        return "mobile";
+                    }
+                }
+                catch {
+                    /* unreadable package.json — keep walking */
+                }
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    catch {
+        /* fs not available — fall through */
+    }
+    return null;
+}
+/**
+ * Resolve the experiment surface. Explicit wins; otherwise detect from repo
+ * signals, then the workspace's registered data sources. Returns an `ambiguous`
+ * error only when both web and mobile data sources exist and there's no repo
+ * signal — in that case the agent must choose. (QA: stop defaulting to web.)
+ */
+async function resolveCreateSurface(explicit) {
+    if (explicit)
+        return { surface: explicit };
+    const repo = detectSurfaceFromRepo();
+    if (repo)
+        return { surface: repo };
+    try {
+        const ws = getActiveWorkspace();
+        if (ws) {
+            const r = await apiGet(`/api/workspaces/${encodeURIComponent(ws)}/readiness`);
+            const sources = r.data?.sources ?? [];
+            const hasMobile = sources.some((s) => s.kind === "ios" || s.kind === "android");
+            const hasWeb = sources.some((s) => s.kind === "website");
+            if (hasMobile && !hasWeb)
+                return { surface: "mobile" };
+            if (hasWeb && !hasMobile)
+                return { surface: "web" };
+            if (hasMobile && hasWeb)
+                return { ambiguous: true };
+        }
+    }
+    catch {
+        /* readiness unavailable — fall back to web */
+    }
+    return { surface: "web" };
+}
 /**
  * Tenant echo (council CISO): never report a mutation as successful for a record
  * outside the active workspace (guards a leaked/cross-workspace key).
@@ -337,7 +416,7 @@ export const toolDefinitions = {
             guardrailThreshold: z.number().optional().describe("Harm margin for the guardrail, RELATIVE (0.25 = flag a >25% rise). Defaults to 0.25."),
             predictionMagnitude: z.string().optional().describe("Your committed prediction of the effect, e.g. '10% lift'. Recorded with 'agent' provenance and used for calibration. Required before the experiment can be ACTIVATED."),
             mode: z.enum(["sdk", "snippet"]).optional().describe("Experiment mode: 'sdk' for code-level (default via MCP), 'snippet' for runtime DOM"),
-            surface: z.enum(["web", "mobile"]).optional().describe("The PROPERTY the experiment runs in (not the SDK used): 'web' (default) for a website, 'mobile' for a native / Capacitor / React-Native app. If the repo is a mobile app (has capacitor.config.* or @apex-inc/capacitor-plugin), set 'mobile' for ALL its experiments — even ones resolved via useApexVariant in the web layer — so they group under the app, not a website. This sets the dashboard data-source label (Website vs Mobile app)."),
+            surface: z.enum(["web", "mobile"]).optional().describe("The PROPERTY the experiment runs in (not the SDK used): 'web' for a website, 'mobile' for a native / Capacitor / React-Native app. OPTIONAL — when omitted it is auto-detected from repo signals (capacitor.config.* / @apex-inc/capacitor-plugin → mobile) and the workspace's registered data sources; pass it explicitly only to override or when both web and mobile sources exist. Sets the dashboard data-source label (Website vs Mobile app)."),
             dataSourceId: z.string().optional().describe("Optional explicit Data Source (property) id this experiment runs in, e.g. 'ds_website' or 'ds_ios'. Usually inferred from surface; pass it to bind to a specific registered source. Tenant-validated server-side."),
             randomizationUnit: z.enum(["device", "visitor", "person", "account", "org"]).optional().describe("What to bucket on. Default 'visitor' (per-device). Use 'person' to give one stitched user the same variant across their devices, or 'account'/'org' for B2B account-level tests where everyone in an account should see the same variant."),
             preview: z.boolean().optional().describe("If true, returns a preview without creating. Default: true."),
@@ -345,7 +424,23 @@ export const toolDefinitions = {
         handler: async (args) => {
             const split = args.trafficSplit ?? 50;
             const mode = args.mode ?? "sdk";
-            const experimentSurface = args.surface ?? "web";
+            // Surface auto-detect (QA 2026-06-18): when the agent doesn't pass a
+            // surface, infer it from repo signals + registered data sources instead of
+            // silently defaulting to web (which mislabels mobile apps). Ambiguous →
+            // ask the agent to choose.
+            const surfaceResolution = await resolveCreateSurface(args.surface);
+            if ("ambiguous" in surfaceResolution) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} This workspace has both web and mobile data sources — pass surface ("web" or "mobile") explicitly so the experiment is labeled and grouped correctly.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const experimentSurface = surfaceResolution.surface;
             const isPreview = args.preview !== false;
             // p1-metric — resolve the primary metric. Defaults to the form_submit
             // conversion metric; an explicit primaryMetricEvent is validated against
@@ -2133,11 +2228,11 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     edit_communication: {
-        description: "Update a communication's subject, body, CTA, channels, or status. Pass the communication ID and the fields to update.",
+        description: "Update a communication's subject, body, CTA, channels, or status. Pass the communication ID and the fields to update. For blank/builder comms, the headline/body/ctaLabel/ctaUrl slots are synced into the rendered email body — verify with preview_communication.",
         schema: z.object({
             communicationId: z.string().describe("The communication ID to update"),
             subject: z.string().optional().describe("New email subject line"),
-            slots: z.record(z.string()).optional().describe("Content slot overrides (e.g. headline, body, ctaLabel, ctaUrl)"),
+            slots: z.record(z.string()).optional().describe("Content overrides: headline, body, ctaLabel, ctaUrl. These now sync into the rendered email body (not just metadata)."),
             channels: z.array(z.string()).optional().describe("Channels: email, in_app_push, mobile_push"),
             status: z.enum(["draft", "active", "paused"]).optional().describe("Communication status"),
         }),
@@ -2159,13 +2254,31 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     preview_communication: {
-        description: "See the rendered email with your brand applied. Returns HTML that can be displayed or sent as a test.",
+        description: "See the rendered communication with your brand applied. Returns the subject, the rendered plain-text body (so you can verify edits actually landed), and a browser preview link.",
         schema: z.object({
             communicationId: z.string().describe("The communication ID to preview"),
         }),
         handler: async (args) => {
             const data = await apiPost(`/api/communications/${args.communicationId}/preview`, {});
-            return { content: [{ type: "text", text: `Subject: ${data.subject}\n\nHTML preview generated (${data.html?.length || 0} chars). The email is ready to send.` }] };
+            // Strip tags from subject (preview may annotate it with a slot span).
+            const subject = (data.subject ?? "").replace(/<[^>]+>/g, "");
+            const text = (data.text ?? "").trim();
+            const link = appUrl(`/dashboard/communications/${args.communicationId}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `Subject: ${subject || "(none)"}`,
+                            ``,
+                            `Rendered body:`,
+                            text ? text : "(empty — add content via edit_communication)",
+                            ``,
+                            `Open in the browser to see the full styled email: ${link}`,
+                        ].join("\n"),
+                    },
+                ],
+            };
         },
     },
     send_test_communication: {
@@ -2706,14 +2819,52 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
             }
         },
     },
+    list_trigger_contracts: {
+        description: `${APEX} — List the workspace's trigger contracts (the event bindings you pass to set_journey_trigger / add_journey_exit). Returns each contract's id + the event it fires on. Call this before set_journey_trigger so you use a real id instead of guessing.`,
+        schema: z.object({}),
+        handler: async () => {
+            const data = await apiGet("/api/journeys/trigger-contracts");
+            const contracts = data.contracts ?? [];
+            if (contracts.length === 0) {
+                return { content: [{ type: "text", text: `${APEX} No trigger contracts registered yet. Creating a blank journey seeds the starter set.` }] };
+            }
+            const lines = contracts.map((c) => `  • ${c.id} → ${c.eventName ?? "?"}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [`${APEX} Trigger contracts (${contracts.length})`, ...lines, ``, `Pass one of these ids as triggerContractId to set_journey_trigger.`].join("\n"),
+                    },
+                ],
+            };
+        },
+    },
     set_journey_trigger: {
-        description: `${APEX} — Set the entry trigger (the event that enrolls subjects) on a draft journey's trigger step. Pass a triggerContractId (a blank journey seeds the starter contracts; get_journey shows the current value).`,
+        description: `${APEX} — Set the entry trigger (the event that enrolls subjects) on a draft journey's trigger step. Pass a triggerContractId — discover valid IDs with list_trigger_contracts (an invalid id is rejected with the list of options).`,
         schema: z.object({
             journeyId: z.string(),
-            triggerContractId: z.string().describe("The trigger contract id (event binding) to enroll on."),
+            triggerContractId: z.string().describe("The trigger contract id (event binding) to enroll on — see list_trigger_contracts."),
         }),
         handler: async ({ journeyId, triggerContractId }) => {
             try {
+                // Validate the contract id up front so a typo doesn't silently set a
+                // dead trigger that only fails at publish — enumerate valid options.
+                const cdata = await apiGet("/api/journeys/trigger-contracts");
+                const contracts = cdata.contracts ?? [];
+                if (contracts.length > 0 && !contracts.some((c) => c.id === triggerContractId)) {
+                    const opts = contracts
+                        .map((c) => `${c.id}${c.eventName ? ` (${c.eventName})` : ""}`)
+                        .join(", ");
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `${APEX} Unknown triggerContractId "${triggerContractId}". Valid options: ${opts}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
                 const j = await apiGet(`/api/journeys/${encodeURIComponent(journeyId)}`);
                 const steps = (j.steps ?? []).map((s) => s.type === "trigger" ? { ...s, trigger: { type: "event", triggerContractId } } : s);
                 const updated = await apiPatch(`/api/journeys/${encodeURIComponent(journeyId)}`, { steps });
@@ -2734,7 +2885,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
             durationIso: z.string().optional().describe("wait only: ISO-8601 duration, e.g. 'P1D' (1 day), 'PT2H' (2 hours)."),
             commId: z.string().optional().describe("send only: the communication id to fire (create_communication or an existing comm)."),
             commVersion: z.number().optional().describe("send only: pinned comm version (default 1)."),
-            channels: z.array(z.enum(["email", "in_app", "mobile_push", "web_push"])).optional().describe("send only: channels to fire (default ['email'])."),
+            channels: z.array(z.enum(["email", "in_app_push", "mobile_push", "web_push"])).optional().describe("send only: channels to fire (default ['email']). Use the SAME tokens as create_communication (email, in_app_push, mobile_push) so a comm's channels map cleanly onto the send step; web_push is send-only."),
         }),
         handler: async (args) => {
             try {
@@ -2767,6 +2918,98 @@ 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 (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"]),
+                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()
+                    .describe("attribute only."),
+                value: z
+                    .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)."),
+                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)."),
+            channels: z.array(z.enum(["email", "in_app_push", "mobile_push", "web_push"])).optional().describe("Channels for both send arms (default ['email'])."),
+        }),
+        handler: async (args) => {
+            try {
+                const c = args.condition;
+                // Build the predicate leaf (AudiencePredicate is a bare leaf here).
+                let predicate;
+                if (c.kind === "attribute") {
+                    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.field_path,
+                        operator: c.operator,
+                        ...(c.value !== undefined ? { value: c.value } : {}),
+                    };
+                }
+                else {
+                    if (!c.event_name) {
+                        return { content: [{ type: "text", text: `${APEX} An event condition needs event_name.` }], isError: true };
+                    }
+                    predicate = {
+                        kind: c.kind,
+                        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)}`);
+                const steps = [...(j.steps ?? [])];
+                const exit = steps.find((s) => s.type === "exit");
+                if (!exit) {
+                    return { content: [{ type: "text", text: `${APEX} Journey has no exit step; cannot insert a branch.` }], isError: true };
+                }
+                const exitId = exit.id;
+                const channels = args.channels ?? ["email"];
+                const mkId = () => `step_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+                const trueId = mkId();
+                const trueStep = { id: trueId, type: "send", label: "Send (match)", commId: args.whenTrueCommId, commVersion: 1, channels, next: exitId };
+                const newSteps = [trueStep];
+                let defaultNext = exitId;
+                if (args.whenFalseCommId) {
+                    const falseId = mkId();
+                    newSteps.push({ id: falseId, type: "send", label: "Send (no match)", commId: args.whenFalseCommId, commVersion: 1, channels, next: exitId });
+                    defaultNext = falseId;
+                }
+                const branchId = mkId();
+                const branchStep = {
+                    id: branchId,
+                    type: "branch",
+                    label: "Branch",
+                    mode: "condition",
+                    conditions: [{ predicate, next: trueId }],
+                    defaultNext,
+                };
+                // Insert the branch before the exit: rewire whatever currently points
+                // to the exit so the branch sits in the linear flow. (newSteps aren't in
+                // `steps` yet, so this only matches the existing pre-exit step.)
+                const pre = steps.find((s) => s.next === exitId);
+                if (pre)
+                    pre.next = branchId;
+                steps.push(branchStep, ...newSteps);
+                const updated = await apiPatch(`/api/journeys/${encodeURIComponent(args.journeyId)}`, { steps });
+                if (!tenantOk(updated.workspaceKey))
+                    return tenantMismatch();
+                return { content: [{ type: "text", text: `${APEX} Added a conditional branch to journey ${args.journeyId}. Watch it update in the browser: ${journeyLink(args.journeyId)}` }] };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: `${APEX} ${errMsg(err)}` }], isError: true };
+            }
+        },
+    },
     publish_journey: {
         description: `${APEX} — Publish a draft journey so it runs on live trigger events. SAFETY: defaults to a dry-run (validation only) — pass confirmLive:true to actually publish to real customers. Email sends require a verified sender domain or publish is blocked.`,
         schema: z.object({
@@ -2838,10 +3081,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({
-            journey_id: z.string().describe("Journey id returned from list_journeys"),
+            journeyId: z.string().describe("Journey id returned from list_journeys."),
         }),
-        handler: async ({ journey_id }) => {
-            const journey = await apiGet(`/api/journeys/${encodeURIComponent(journey_id)}`);
+        handler: async ({ journeyId }) => {
+            const journey = await apiGet(`/api/journeys/${encodeURIComponent(journeyId)}`);
             return {
                 content: [
                     {
@@ -2855,10 +3098,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({
-            journey_id: z.string(),
+            journeyId: z.string(),
         }),
-        handler: async ({ journey_id }) => {
-            const body = await apiGet(`/api/journeys/${encodeURIComponent(journey_id)}/exit-rules`);
+        handler: async ({ journeyId }) => {
+            const body = await apiGet(`/api/journeys/${encodeURIComponent(journeyId)}/exit-rules`);
             return {
                 content: [
                     {
@@ -2872,16 +3115,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({
-            journey_id: z.string(),
-            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 ({ journey_id, trigger_contract_id, label, enabled, }) => {
-            const body = await apiPost(`/api/journeys/${encodeURIComponent(journey_id)}/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,
             });
@@ -2898,16 +3141,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({
-            journey_id: z.string(),
-            rule_id: z.string(),
+            journeyId: z.string(),
+            ruleId: z.string(),
         }),
-        handler: async ({ journey_id, rule_id, }) => {
-            await apiDelete(`/api/journeys/${encodeURIComponent(journey_id)}/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 ${journey_id}.`,
+                        text: `Removed exit rule ${ruleId} from journey ${journeyId}.`,
                     },
                 ],
             };