@apex-inc/mcp-server 0.27.0 → 0.27.2

package/dist/workspace-target-url.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Bind experiment target_url to hosts the ACTIVE workspace actually owns.
+ *
+ * A merchant with two workspaces (e.g. apex-staging vs the stealth apex.inc
+ * property) must not silently land a draft on the sibling's site. Agents
+ * guess brand domains; the catalog is the source of truth.
+ */
+export declare function hostnameOf(raw: string): string | null;
+export declare function collectHosts(input: {
+    analyticsHosts?: Array<{
+        hostname?: string;
+    } | string>;
+    namedSites?: string[];
+    workspaceUrl?: string | null;
+    apexUrl?: string | null;
+}): string[];
+export declare function evaluateTargetUrl(targetUrl: string, allowedHosts: string[]): {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+//# sourceMappingURL=workspace-target-url.d.ts.map

package/dist/workspace-target-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-target-url.d.ts","sourceRoot":"","sources":["../src/workspace-target-url.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOrD;AAUD,wBAAgB,YAAY,CAAC,KAAK,EAAE;IAClC,cAAc,CAAC,EAAE,KAAK,CAAC;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,CAAC;IACvD,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,GAAG,MAAM,EAAE,CASX;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EAAE,GACrB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAwB/C"}

package/dist/workspace-target-url.js

@@ -0,0 +1,62 @@
+/**
+ * Bind experiment target_url to hosts the ACTIVE workspace actually owns.
+ *
+ * A merchant with two workspaces (e.g. apex-staging vs the stealth apex.inc
+ * property) must not silently land a draft on the sibling's site. Agents
+ * guess brand domains; the catalog is the source of truth.
+ */
+export function hostnameOf(raw) {
+    try {
+        const withScheme = /:\/\//.test(raw) ? raw : `https://${raw}`;
+        return new URL(withScheme).hostname.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+function addHost(hosts, raw) {
+    if (!raw)
+        return;
+    const host = hostnameOf(raw);
+    if (!host)
+        return;
+    if (host === "localhost" || host === "127.0.0.1")
+        return;
+    hosts.add(host);
+}
+export function collectHosts(input) {
+    const hosts = new Set();
+    for (const item of input.analyticsHosts ?? []) {
+        addHost(hosts, typeof item === "string" ? item : item.hostname);
+    }
+    for (const site of input.namedSites ?? [])
+        addHost(hosts, site);
+    addHost(hosts, input.workspaceUrl);
+    addHost(hosts, input.apexUrl);
+    return [...hosts];
+}
+export function evaluateTargetUrl(targetUrl, allowedHosts) {
+    const host = hostnameOf(targetUrl);
+    if (!host) {
+        return { ok: false, message: `target_url is not a valid URL: ${targetUrl}` };
+    }
+    if (host === "localhost" || host === "127.0.0.1") {
+        return {
+            ok: false,
+            message: "target_url must be a named site on the active workspace, not localhost. Capture localhost screenshots with attach_experiment_asset; the experiment itself runs on a hosted site.",
+        };
+    }
+    if (allowedHosts.length === 0) {
+        return {
+            ok: false,
+            message: "No sites are named on the active workspace yet. Call list_workspace_environments, then set_workspace_environments with the real host (or use the workspace's own site). Do not guess a brand domain or a sibling workspace's site.",
+        };
+    }
+    if (allowedHosts.includes(host))
+        return { ok: true };
+    return {
+        ok: false,
+        message: `target_url host "${host}" is not a site on the active workspace. Known hosts: ${allowedHosts.join(", ")}. Do not guess a brand domain or a sibling workspace's site.`,
+    };
+}
+//# sourceMappingURL=workspace-target-url.js.map

package/dist/workspace-target-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-target-url.js","sourceRoot":"","sources":["../src/workspace-target-url.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,GAAG,EAAE,CAAC;QAC9D,OAAO,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,OAAO,CAAC,KAAkB,EAAE,GAAmB;IACtD,IAAI,CAAC,GAAG;QAAE,OAAO;IACjB,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,CAAC,IAAI;QAAE,OAAO;IAClB,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,WAAW;QAAE,OAAO;IACzD,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAK5B;IACC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,cAAc,IAAI,EAAE,EAAE,CAAC;QAC9C,OAAO,CAAC,KAAK,EAAE,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAClE,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,UAAU,IAAI,EAAE;QAAE,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAChE,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;IACnC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAC9B,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,SAAiB,EACjB,YAAsB;IAEtB,MAAM,IAAI,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;IACnC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,kCAAkC,SAAS,EAAE,EAAE,CAAC;IAC/E,CAAC;IACD,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;QACjD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EACL,kLAAkL;SACrL,CAAC;IACJ,CAAC;IACD,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EACL,oOAAoO;SACvO,CAAC;IACJ,CAAC;IACD,IAAI,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACrD,OAAO;QACL,EAAE,EAAE,KAAK;QACT,OAAO,EAAE,oBAAoB,IAAI,yDAAyD,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,8DAA8D;KAChL,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-inc/mcp-server",
-  "version": "0.27.0",
+  "version": "0.27.2",
   "description": "MCP server for Apex \u2014 currently in private beta.",
   "type": "module",
   "main": "dist/index.js",

package/skills/apex-communications/SKILL.md

@@ -45,14 +45,16 @@ experience, so Apex won't let you do it by accident.
 
 | `controlState` | What it means | Editing it |
 |---|---|---|
-| `none` | Never experimented on | Edit freely |
-| `no_winner` | An experiment ran and settled without a winner | Edit freely; worth re-testing |
-| `winner` | Won an experiment, unchanged since | Needs `intent` |
-| `winner_edited` | Won, then was changed | Needs `intent` |
+| `none` | Never experimented on | Editable. If a journey is sending it, Publish still asks replace vs compete |
+| `no_winner` | An experiment ran and settled without a winner | Editable. Same publish question if it's sending |
+| `winner` | Won an experiment, unchanged since | Champion. Control is read-only. Add a variant to compete; Replace overwrites |
+| `winner_edited` | Won, then was changed | Still a champion. Same as winner |
 | `in_experiment` | Frozen — an experiment is measuring it right now | Blocked; see below |
 
 A comm that's live in a published journey also needs `intent`, whatever its
-`controlState`.
+`controlState`. Do not rewrite a champion to start a test. Use
+`add_communication_variant`, then `publish_communication` with `intent: "compete"`.
+Rewriting what's sending is `replace`.
 
 ### The two intents
 
@@ -135,7 +137,7 @@ Read these resources before suggesting communications-related actions to underst
 1. list_communications(pipeline="transactional", channel="email")
    → narrow to the pipeline + channel the step needs. 'transactional'
      bypasses opt-out and is ONLY valid after a recipient-initiated trigger
-     (user_signup, password_reset_requested). 'marketing' is consent-gated.
+     (user_signed_up, password_reset_requested). 'marketing' is consent-gated.
 2. Read each row's subject + one-line body preview to disambiguate similar
    titles — you do NOT need to preview_communication every candidate.
 3. Pick by `id` (+ its version) and attach it to the send step.
@@ -151,7 +153,7 @@ hard-block**. For those journeys, filter to `pipeline="marketing"`.
 2. generate_communications with the welcome entry ID
 3. edit_communication to customize copy
 4. send_test_communication to preview
-5. Show user the apex.track("user_signup") call to add
+5. Show user the apex.track("user_signed_up") call to add
 ```
 
 ### "My churn rate is high"

package/skills/apex-experimentation/SKILL.md

@@ -69,10 +69,12 @@ Interactive flows: MCP prompts `new-experiment` and `experiment-review` orchestr
 
 ## Screenshots, exposure & the wiring gate
 
-- **Screenshots are first-class.** For public web URLs, `create_experiment` auto-captures control + variant screenshots and shows them on the dashboard experiment card + detail gallery. For localhost / auth-gated / mobile screens, capture the image yourself and call `attach_experiment_asset({ experimentId, variantKey, imageBase64 })`.
+- **Screenshots are first-class.** SDK / Cursor experiments author the variant in local code. Apex does **not** auto-capture a public URL on create — that page does not have the unpublished variant, and a guessed host (a sibling workspace's brand domain) shows the wrong site on both arms. Capture both arms on localhost with `?_apex_preview=control|variant_a&_apex_exp=<id>`, then `attach_experiment_asset({ experimentId, variantKey, imageBase64 })`. After deploy, `recapture_experiment_screenshots` refreshes the live host. Snippet/DOM experiments created in the dashboard still auto-capture a public URL whose variant already lives there.
+- **Target URL is this workspace.** `target_url` must be a host named on the **active** workspace (`list_workspace_environments` + the workspace site). If the merchant already named a workspace, switch to it — do not ask which workspace again. If they have multiple hosts on that workspace, ask which URL. Never guess `apex.inc` or any other workspace's domain.
 - **Mobile/Capacitor experiments capture on-device.** When the experiment runs on an authed in-app screen (servers can't reach it), tell the dev to call `Apex.captureVariantScreenshot({ experimentId, variantKey })` on the variant's screen, keyed to the resolved variant in a `useEffect`, in a debug build (`Apex.initialize({ ..., debug: true })`). It no-ops in production and lands the shot on the dashboard card + gallery like web/agent captures.
 - **Exposure auto-fires.** When a variant resolves via `useApexVariant` (web) or `Apex.getVariant()` (mobile), the SDK fires the canonical `experiment_exposure` event — the denominator for results. You don't fire it manually.
-- **Don't launch a dead experiment.** `activate_experiment` is gated on `verify_experiment_wiring`. Code-wired (SDK-hook) web experiments are safe to activate before their code ships: the server holds them in `pending_deployment` ("Waiting on deploy"). The 14-day clock starts at the first **recorded** visit (a tester on a named Beta site, or a live visit) — not merge, not activate, not localhost. Testers on a named Beta site count in the winner. Localhost does not. Assign with no Origin is Unclassified (no enrollment). Backend assign must send `environment` or `x-apex-web-environment`. Non-SDK experiments with unwired arms are refused (pass `force: true` to override). Run `verify_experiment_wiring({ experimentId })` after the deploy lands to confirm both arms are live.
+- **Preview on Next.js.** `useApexVariant` cannot read `window` during SSR. Pass the request search string (`useApexVariant(id, { search })` from `searchParams`, or `<ApexProvider search>`) so the first HTML matches `_apex_preview`. Without it the server renders control and the arm only appears after hydrate.
+- **Don't launch a dead experiment.** `activate_experiment` is gated on `verify_experiment_wiring`. Code-wired (SDK-hook) web experiments are safe to activate before their code ships: the server holds them in `pending_deployment` ("Waiting on deploy"). The 14-day clock starts at the first **recorded** visit (a tester on a named Beta site, or a live visit) — not merge, not activate. Testers on a named Beta site count in the winner. Localhost/dev is recorded as Dev and does not start the window or decide the winner. Assign with no Origin is Unclassified (no enrollment). Backend assign must send `environment` or `x-apex-web-environment`. Non-SDK experiments with unwired arms are refused (pass `force: true` to override). Run `verify_experiment_wiring({ experimentId })` after the deploy lands to confirm both arms are live.
 
 ### Journey-arm experiments (any surface)
 
@@ -146,6 +148,8 @@ Match Apex UI terminology in user-facing copy: e.g. **Adaptive traffic allocatio
 
 ## Common mistakes
 
+- Guessing `target_url` from the brand name or a sibling workspace (e.g. `apex.inc` while the active workspace is `apex-staging`). Use `list_workspace_environments` + the workspace site.
+- Declaring an SDK / Cursor draft ready from hosted screenshots of a public URL. The variant is local until deploy — attach localhost shots with `attach_experiment_asset`.
 - Starting an experiment without a **clear primary metric** tied to the belief.
 - Using different visitor ids for the same user across channels (breaks consistent assignment).
 - Changing variant implementation mid-flight without versioning (invalidates analysis).

package/skills/apex-integration-cookbook/SKILL.md

@@ -27,7 +27,7 @@ Events are batched and sent to `POST /api/events` automatically. Call `flush()`
 
 ```typescript
 // On signup
-track("signup_completed", { method: "email", plan: "free" });
+track("user_signed_up", { method: "email", plan: "free" });
 identify(user.id, {
   email: user.email,
   name: user.name,
@@ -117,7 +117,7 @@ For agent-driven testing through MCP, use the **`send_server_event`** tool — s
 
 ## Event naming conventions
 
-- **snake_case**: `signup_completed`, `feature_used`, `invoice_paid`
+- **snake_case**: `user_signed_up`, `feature_used`, `invoice_paid`
 - Context in **properties**: `track("ui_action", { action: "click", name: "Start trial", location: "pricing" })`
 - For experiments, include `experimentId` and `variant` in properties
 - One primary metric per experiment; secondary metrics as properties