@apex-inc/mcp-server 0.17.0 → 0.19.0

package/package.json

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

package/skills/apex-adoption/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: apex-adoption
+description: Help users set up and run Apex's Adoption Engine — per-feature adoption milestones defined over their own events/traits, automatic nudges to users who haven't adopted, and lift-vs-holdout measurement. Use whenever the user mentions product adoption, activation nudges, "users who haven't tried X", feature adoption, onboarding nudges, or wants to drive users to a feature. A milestone is NOT a goal.
+---
+
+# Apex Adoption (MCP)
+
+The Adoption Engine tracks whether each end-user has adopted each feature, nudges the ones who haven't (one next-best nudge per user), and measures the lift against a holdout.
+
+## Core idea
+
+- A **milestone** = "has this end-user adopted feature X?" — defined by an event they fire (`report_run`) or a trait (`plan = pro`). It is per-user and per-feature. It is **not** a goal (goals are workspace/experiment/journey success).
+- Apex ranks a user's unmet milestones by priority and sends the single top nudge per cadence — so nobody gets spammed.
+- A ~10% deterministic holdout is kept automatically; the report shows lift vs that holdout, not last-touch attribution. Users in an active experiment are never nudged.
+
+## When to Activate
+
+- "Nudge users who signed up but never ran their first report."
+- "Which features are people not adopting?"
+- "Set up an activation program / onboarding nudges."
+
+## Tool Map
+
+| Tool | When to use |
+|---|---|
+| `list_adoption_milestones` | See the workspace's current milestones |
+| `get_adoption_milestone` | Inspect one milestone |
+| `create_adoption_milestone` | Define a new "adopted feature" milestone |
+| `update_adoption_milestone` | Change priority / gap window / turn on/off |
+| `delete_adoption_milestone` | Remove a milestone |
+| `get_adoption_metrics` | Per-milestone funnel + lift-vs-holdout + workspace health |
+| `list_adoption_features` / `create_adoption_feature` | Tenant-owned feature groupings (group your own events) |
+| `list_segments` / `get_segment` / `create_segment` | Saved groups of customers — same grammar as milestones |
+| `define_event` | Register an event's NAME before it fires (define ≠ fire) |
+
+Read-only summary resource: `apex://adoption`.
+
+## One grammar: define → wire → verify
+
+Milestones and segments both describe "people who…" over the workspace's own
+events + traits. The methodology is the same everywhere (dashboard, SDK, MCP):
+
+1. **Define** — name the signal. If the event doesn't exist yet, `define_event`
+   registers it. Defining does NOT make it fire.
+2. **Wire** — a developer calls `apex.track("your_event")` from the app (or
+   sends the trait via `apex.identify`). Until then it shows a "not seen yet"
+   dot.
+3. **Verify** — once real events arrive, milestone lift / segment counts fill in.
+
+### Segments — `create_segment`
+
+Author with the friendly `conditions` grammar (snake_case sub-keys), or pass a
+raw `predicate`:
+
+```json
+{
+  "name": "Power users who haven't upgraded",
+  "conditions": {
+    "match": "all",
+    "groups": [
+      { "match": "all", "conditions": [
+        { "verb": "has", "event": "report_run", "window_days": 30 },
+        { "attribute": "plan", "op": "is_not", "value": "pro" }
+      ] }
+    ]
+  }
+}
+```
+
+## Tool Invocation Order
+
+### "Nudge users who haven't run their first report"
+1. `list_adoption_milestones` → check it doesn't already exist.
+2. `create_adoption_milestone` with `name: "Ran first report"`, `featureKey: "reporting"`, `adoptedWhenKind: "event"`, `eventName: "report_run"`, `gapDays: 3`. Leave `active` off first.
+3. Tell the user it's created as a draft, and that turning it on (`update_adoption_milestone` with `active: true`) starts nudging through their journeys (opt-out + caps respected).
+4. Later: `get_adoption_metrics` → report the lift-vs-holdout so they know whether it worked.
+
+## Guardrails
+
+- Milestones start OFF. Only set `active: true` when the user confirms they want to start sending.
+- Never call it a "goal" in user-facing text.
+- The `eventName`/`traitPath` must be an event/trait the workspace actually sends — confirm with the user if unsure.

package/skills/apex-experimentation/SKILL.md

@@ -72,7 +72,7 @@ Interactive flows: MCP prompts `new-experiment` and `experiment-review` orchestr
 - **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 })`.
 - **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`: both arms must be producing `experiment_exposure` events first, or it refuses (pass `force: true` to override). Run `verify_experiment_wiring({ experimentId })` after deploying the variant code to confirm both arms are live before launch.
+- **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") and starts them automatically at the first `experiment_exposure`. 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)