@apex-inc/mcp-server 0.26.0 → 0.27.1

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.26.0",
+  "version": "0.27.1",
   "description": "MCP server for Apex \u2014 currently in private beta.",
   "type": "module",
   "main": "dist/index.js",

package/skills/apex-communications/SKILL.md

@@ -45,30 +45,32 @@ 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
 
-- **`intent: "compete"`** — *Add as a variant.* Your edit runs as an experiment
-  against the current content. Nothing changes for recipients yet; Apex measures
-  which one is better and tells you.
-- **`intent: "replace"`** — *Update for everyone.* Your edit becomes what
-  everyone receives. Any prior win is superseded.
+- **`intent: "compete"`** — *Start an experiment.* What's sending now stays
+  live. Publish creates a filled-in draft. Then `activate_experiment` after
+  the user confirms.
+- **`intent: "replace"`** — *Replace what's sending.* Everyone gets this
+  version on the next send. No experiment row.
 
 ### When in doubt, compete
 
 This is the default, and it isn't a coin flip. The two mistakes are not
 symmetric:
 
-- Guessing `compete` when the user wanted `replace` costs **time** — they see
-  an experiment start and can promote the winner immediately.
+- Guessing `compete` when the user wanted `replace` costs **time** — they have
+  a draft to activate, or they can publish again with replace.
 - Guessing `replace` when the user wanted `compete` **destroys a measured
   result permanently**. There's no undo for evidence.
 
@@ -76,9 +78,9 @@ So: if the user explicitly said "just change it for everyone" / "replace the
 copy" / "roll this out," send `replace`. Otherwise send `compete`, and say what
 you did:
 
-> "That comm's control won an experiment, so I added your new copy as a variant
-> and started an experiment against it rather than overwriting the winner. Want
-> me to make it the control for everyone instead?"
+> "That comm's control won an experiment, so I published your copy as a
+> competing version and opened a filled-in draft. Want me to activate it, or
+> make this the letter everyone gets instead?"
 
 ### Don't force through a running experiment
 
@@ -97,9 +99,10 @@ re-issue. Do not retry the identical call.
 ### Running experiments
 
 1. **`list_communications`** — find the communication to test.
-2. **`create_comm_experiment`** — set up the A/B test with variants.
-3. The experiment runs automatically via Thompson Sampling.
-4. Check results via `list_communications` or the dashboard.
+2. **`edit_communication` / `add_communication_variant`** — write the versions.
+3. **`publish_communication`** with `intent: "compete"` — creates a prefilled draft. Does not start the test.
+4. **`activate_experiment`** — begins the test on the next send.
+5. Check results via `get_results` / `list_experiments`.
 
 ### Manual sends
 
@@ -157,15 +160,16 @@ hard-block**. For those journeys, filter to `pipeline="marketing"`.
 ```
 1. recommend_communications → look for retention/winback entries
 2. generate_communications for churn-related comms
-3. create_comm_experiment to A/B test the messaging
+3. add_communication_variant, publish_communication (compete), then activate_experiment
 4. get_event_taxonomy to see what churn signals to track
 ```
 
 ### "How do I A/B test my emails?"
 ```
 1. list_communications → find the target
-2. create_comm_experiment with subject or body split
-3. Explain Thompson Sampling: traffic shifts automatically toward the winner
+2. add_communication_variant (or edit the second column)
+3. publish_communication intent=compete → filled-in draft
+4. activate_experiment after the user confirms
 ```
 
 ### "Set up cart abandonment recovery"

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 **live customer** exposure — not merge, not activate, not TestFlight. Testers can still get an arm while waiting. 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)
 
@@ -95,18 +97,28 @@ Do NOT describe this as champion versus challenger, and do not try to run "the o
 
 ### Starting an experiment from the communication side
 
-`publish_communication` is the other way an experiment starts. Publishing a communication that has variants starts the experiment measuring them against the control, on the published journey that sends it. Preconditions, each reported rather than guessed:
+Write the letter with `edit_communication` / `add_communication_variant`. Then:
+
+1. `publish_communication` with `intent: "compete"` (or when variants already exist). This creates a **prefilled draft** on the same experiment page as web tests. It does **not** start the test.
+2. Show the user the draft. They can edit window, hypothesis, belief.
+3. `activate_experiment` starts it. People on that journey get control or the variant on the next send. Screenshots are captured on activate — do not call `attach_experiment_asset` for a letter unless capture failed.
+
+`intent: "replace"` publishes the letter for everyone. Leftover variant columns leave. No experiment row.
+
+Preconditions for a draft, each reported rather than guessed:
 
 - **A host** — some published journey must send the communication. `no_host` means there is no traffic to measure.
 - **A goal** — the host step's own goal event, or the journey's. `no_goal` means there is nothing to optimize toward; set the journey's goal event first.
 - **One host** — 409 `ambiguous_experiment_host` lists the candidates when several journeys send it. Ask the user which, then re-issue with `host_journey_id`.
 
+When in doubt, compete. The cheap mistake is now "they have a draft to activate," not "they already have a live test."
+
 ### Editing a control that won
 
 `edit_communication` and `publish_communication` both take `intent` when the control is protected (it won an experiment, or a published journey is sending it):
 
-- `"compete"` — the current content keeps sending and your change runs against it as an experiment. **This is the default when the user hasn't said otherwise**; it is recoverable.
-- `"replace"` — your change becomes what everyone receives, superseding the prior win. This permanently discards a measured result.
+- `"compete"` — the current content keeps sending. Publish opens a filled-in draft. Then `activate_experiment`. **This is the default when the user hasn't said otherwise**; it is recoverable.
+- `"replace"` — your change becomes what everyone receives, superseding the prior win. No experiment row.
 
 Omitting `intent` when it's required returns 409 `intent_required` naming both. Do not pick `replace` to clear the error.
 
@@ -136,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).
@@ -160,7 +174,7 @@ Editability is gated by lifecycle, keyed to DATA:
 
 - **Draft, no exposures yet:** fully editable. Use `update_experiment({ experimentId, ... })` to fix a mislabeled surface, rename, or correct the hypothesis/metric/guardrail. This is where typo and surface fixes belong.
 - **Running, or any exposures recorded:** the pre-registration (hypothesis, metric, guardrails) and bucketing (surface, variants) FREEZE. `update_experiment` returns `experiment_locked` with the reason — that's intentional, so results stay valid. Do not fight it.
-- **After freeze:** call `fork_experiment({ experimentId })`. It duplicates the design into a fresh draft (no data carries over, lineage recorded), which you then edit and activate.
+- **After freeze:** call `fork_experiment({ experimentId })`. It duplicates the design into a fresh draft (no data carries over, lineage recorded). A copy gets a new id — replace `useApexVariant("<old id>")` with the new id, deploy, then activate. Preview still works via `_apex_exp`; a normal visit shows control until the new id is shipped.
 
 Surface specifically: `create_experiment` auto-detects mobile vs web from repo signals (capacitor.config.* / @apex-inc/capacitor-plugin) and the workspace's registered data sources when you omit `surface`; if a Capacitor app got mislabeled `web`, fix it on the draft with `update_experiment({ experiment_id, surface: "mobile" })` before the first exposure, or fork if it's already running.
 

package/skills/apex-growth-tracking/SKILL.md

@@ -20,7 +20,7 @@ Apex ingests **events** and **identities** so experiments, attribution, and inte
 ## Event naming
 
 - Use **snake_case** or **dot-separated** consistent verbs: `page_viewed`, `signup_started`, `trial_started`, `notification_clicked`.
-- Include **context** in properties, not in the event name explosion: `track("button_clicked", { surface: "pricing", label: "start_trial" })` vs dozens of `pricing_start_trial_clicked` events.
+- Include **context** in properties, not in the event name explosion: `track("ui_action", { action: "click", name: "Start trial", location: "pricing" })` vs dozens of `pricing_start_trial_clicked` events.
 - For experiments, include **`experimentId`** and **`variant`** when the event is relevant to that exposure.
 
 ## Canonical attributes (the Schema)

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

@@ -118,7 +118,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`
-- Context in **properties**: `track("button_clicked", { surface: "pricing", label: "start_trial" })`
+- 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
 

package/skills/apex-spec/SKILL.md

@@ -94,6 +94,12 @@ find where each business truth already lives and instrument it there.
 - Revenue events MUST carry `value` + `currency`, and a stable
   external id when one exists (order id, invoice id) — dedupe depends
   on it.
+- Do **not** invent one event per button. In-product chrome (named
+  buttons, widget close/minimize/move, nav picks) is `ui_action` with
+  `action` + `name` + optional `location`. Outcomes stay semantic:
+  `integration_selected`, `setup_step_continued`, `integration_connected`.
+  `click` is the snippet's outbound-link auto-event; do not use it for
+  dashboard buttons.
 
 ## Vertical event sets (Vertical Widget Packs, 2026-07)