@apex-inc/mcp-server 0.18.0 → 0.20.0

package/package.json

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

package/skills/apex-adoption/SKILL.md

@@ -29,9 +29,44 @@ The Adoption Engine tracks whether each end-user has adopted each feature, nudge
 | `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"

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

@@ -39,6 +39,33 @@ When a user was anonymous and then becomes known (signup, login, checkout email)
 - Call **`identify`** with a stable `userId` and pass **`traits.email`** when applicable.
 - **Server-side** `identify` (webhooks, API routes): pass **`traits.visitorId`** = value of the browser **`apex_vid`** cookie so the stitch links to the real marketing session. Without it, Apex may create a synthetic visitor disconnected from prior events.
 
+## B2B accounts + groups (model the company, not just the seat)
+
+For B2B, revenue belongs to the **account** (company), not the individual. Add a nested `account` object to the SAME `identify` you already call at login/signup:
+
+```ts
+identify(user.id, {
+  email: user.email,
+  account: { id: "acct_acme", name: "Acme Inc", plan: "enterprise", seat_count: 25 },
+});
+```
+
+Apex upserts the Account, links the user as a member, and rolls every member's revenue into one account LTV (no double counting). `account.id` is required — Apex never infers the company from a shared email domain.
+
+If your product has an intermediate org-unit layer (workspaces / teams / projects), assert it with `groups[]` on the same identify — the "model a team/workspace layer" recipe:
+
+```ts
+identify(user.id, {
+  account: { id: "acct_acme", name: "Acme Inc" },
+  groups: [
+    { id: "ws_prod", name: "Production", kind: "workspace", role: "admin" },
+    { id: "team_growth", name: "Growth Team", kind: "team", parent_id: "acct_acme" },
+  ],
+});
+```
+
+Each group becomes a sub-account of `parent_id` (defaults to `account.id`) and the user is linked to it. Read it back with `apex.accounts.list()` / `.subaccounts(id)` / `.people(id)` / `.contactGroups(contactId)` (SDK) or `list_accounts` / `list_sub_accounts` / `get_contact_groups` (MCP). Revenue lands on the billed account; a parent's LTV is its own counters, not the sum of children.
+
 ## What to measure by loop phase
 
 - **Acquisition**: landing views, campaign params (UTM already captured by snippet where configured), signup started.

package/skills/apex-spec/SKILL.md

@@ -105,6 +105,16 @@ 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).
+  For account-level rollup (B2B): send a nested `account` object on
+  `identify` — `identify(user.id, { account: { id, name, plan,
+  seat_count } })` — so revenue rolls up to the company, not the seat.
+  For an intermediate org-unit layer (workspaces / teams / projects),
+  add `groups[]` on the SAME identify: `groups: [{ id, name, kind,
+  parent_id?, role? }]`. Each group becomes a sub-account of `parent_id`
+  (defaults to `account.id`) and the user is linked to it. snake_case
+  sub-keys; a group only attaches under an account the user is already
+  anchored to. Read back via MCP `list_accounts` / `list_sub_accounts`
+  / `get_contact_groups`.
 - **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.