@apex-inc/mcp-server 0.16.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-inc/mcp-server",
-  "version": "0.16.0",
+  "version": "0.18.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,47 @@
+---
+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 |
+
+Read-only summary resource: `apex://adoption`.
+
+## 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)
 

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

@@ -160,8 +160,8 @@ just report the number.
 | Concentration: top 10% sellers > ~60% GMV | Long-tail seller enablement; the platform is one churn away from a revenue cliff |
 | NRR < 100% (`get_saas_recurring_revenue`) | Expansion journey + contraction interviews; churned-MRR column names the cohort |
 | Contraction MRR spike (`get_saas_expansion`) | Downgrade-reason capture (`subscription_event` action="downgrade" with reason) → pricing/packaging belief |
-| Rising return rate on one SKU (`get_dtc_returns` + `get_dtc_merchandising`) | Fix the PDP (size guide, photos) — reasons name the fix; returns are goods-back, refunds are money-back |
-| High views, low add-to-cart on a top SKU | Merchandising experiment (price anchor, social proof) on that product page |
+| Rising return rate on one SKU (`get_ecommerce_returns` + `get_ecommerce_product_sales`) | Fix the PDP (size guide, photos) — reasons name the fix; returns are goods-back, refunds are money-back |
+| High views, low add-to-cart on a top SKU | Product-page experiment (price anchor, social proof) on that product |
 
 Honesty rules baked into every tool: metrics with unwired inputs come
 back as unwired hints (never zeros), rates follow small-n rules, low-

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

@@ -256,6 +256,11 @@ Each launch vertical has a canonical event set that unlocks its
 industry-specific dashboard pack. Wire the vertical's set and the
 matching widgets + read APIs light up automatically.
 
+Every pack read API accepts a relative window (`days` for event-based
+reports, `months` for month-grain MRR reports) OR an explicit
+`start` + `end` (YYYY-MM-DD, both together — explicit bounds win).
+Month-grain reports map the range to the UTC calendar months it covers.
+
 ### B2B SaaS — recurring revenue
 
 ```typescript
@@ -278,7 +283,7 @@ Unlocks: MRR waterfall, NRR/GRR, expansion & seats
 `get_saas_recurring_revenue` / `get_saas_expansion` via MCP).
 Connecting Stripe replaces manual events per account (Stripe wins).
 
-### E-commerce / DTC — merchandising + returns
+### E-commerce — product sales + returns
 
 ```typescript
 track("product_view", { product_id: "sku_a", product_name: "Trail Runner", category: "footwear", value: 129.99 });
@@ -292,7 +297,9 @@ track("purchase_refunded", { order_id: "o_1", value: 129.99, currency: "USD", re
 ```
 
 Unlocks: per-product funnel, returns & reasons, AOV/repeat
-(`GET /api/dtc/merchandising`, `/api/dtc/returns`).
+(`GET /api/ecommerce/product-sales`, `/api/ecommerce/returns` —
+`getEcommerceProductSales()` / `getEcommerceReturns()` in the SDK,
+`get_ecommerce_product_sales` / `get_ecommerce_returns` via MCP).
 
 ### Marketplace — two-sided lifecycle
 

package/skills/apex-spec/SKILL.md

@@ -105,7 +105,7 @@ Scan-first additions per vertical — wire where the truth lives:
   (monthly|annual|quarterly|weekly) — quarantined for MRR otherwise.
   `seat_count` unlocks seat growth. Account traits: `account_id`,
   `plan`, `mrr`, `arr`, `seat_count` (typed via ApexAccountTraits).
-- **DTC**: returns pipeline → `return_requested` / `return_completed`
+- **E-commerce**: returns pipeline → `return_requested` / `return_completed`
   (goods back) alongside `purchase_refunded` (money back — now carries
   optional `product_id` for per-SKU attribution). Never conflate the two.
 - **Marketplace**: supply (`seller_signup`, `listing_created`,