dtc-mcp 0.2.1 → 1.0.1

package/README.md

@@ -1,488 +1,251 @@
 # dtc-mcp
 
-Context-optimized MCP server for DTC e-commerce brands. Connect Claude (or any MCP client) to your Klaviyo and Shopify data with 22 pre-built analytics tools.
+**A code-execution MCP server for Klaviyo + Shopify analytics.**
 
-Unlike raw API wrappers, dtc-mcp pre-aggregates data server-side and returns only actionable fields — using ~80% less context than dumping raw API responses into your conversation.
+Three tools. Typed SDKs. A V8 sandbox that keeps state across calls so iterative analyses don't re-fetch. Works inside Claude Desktop, Cursor, or any MCP client.
 
-## Features
-
-- **8 Klaviyo tools** — campaign performance, flow breakdowns, subscriber health, profile search, event activity
-- **12 Shopify tools** — sales summaries, time series, product performance, inventory alerts, customer cohorts & segments, sales breakdowns by country/channel/vendor, traffic sources, returns analysis, order search
-- **2 cross-platform tools** — email revenue attribution, full DTC health dashboard
-- **Dual revenue metrics** — both gross and net revenue on every sales query
-- **ShopifyQL-powered analytics** — fast aggregated queries for sales, customers, and sessions
-- **Aggressive caching** — respects Klaviyo's strict rate limits (1 req/s on reporting)
-
-## Quick Start
-
-```bash
-npm install -g dtc-mcp
 ```
-
-Or run directly:
-
-```bash
-npx dtc-mcp
+LLM asks → execute_code → V8 sandbox ─→ host bridge ─→ Klaviyo / Shopify
+                              ↑                             ↓
+                         globalThis state            rate limit + cache
+                         persists across calls
 ```
 
-## Setup with Claude Desktop
-
-### Option A: Desktop Extension (one-click install)
-
-1. Download the latest `dtc-mcp.mcpb` from [GitHub Releases](https://github.com/rafaelsztutman/dtc-mcp/releases)
-2. Double-click the `.mcpb` file — Claude Desktop will open an install dialog
-3. Enter your API credentials when prompted (Klaviyo key required, Shopify optional)
-4. The 22 tools will appear in the hammer menu automatically
-
-### Option B: Manual Configuration
-
-1. Open Claude Desktop
-2. Go to **Settings** (gear icon) > **Developer** > **Edit Config**
-3. Add the following to your `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "dtc-mcp": {
-      "command": "npx",
-      "args": ["-y", "dtc-mcp"],
-      "env": {
-        "KLAVIYO_API_KEY": "pk_your_private_key_here",
-        "SHOPIFY_STORE": "your-store.myshopify.com",
-        "SHOPIFY_CLIENT_ID": "your_client_id",
-        "SHOPIFY_CLIENT_SECRET": "shpss_your_secret"
-      }
-    }
-  }
-}
+```bash
+npm install -g dtc-mcp
 ```
 
-1. Restart Claude Desktop
-2. Look for the hammer icon in the chat input — that confirms the MCP tools are loaded
-
-### Klaviyo-only mode
+Or get the one-click [Claude Desktop extension](#install).
 
-If you only use Klaviyo (no Shopify), just omit the Shopify variables. The 8 Klaviyo tools and subscriber analytics will work standalone. Shopify tools will return a helpful "not configured" message.
+---
 
-## Setup with ChatGPT
+## The three tools
 
-ChatGPT supports MCP servers via remote connections. Since dtc-mcp uses stdio transport (runs locally), you would need an MCP-to-HTTP bridge to expose it as a remote server. See [OpenAI's MCP documentation](https://platform.openai.com/docs/guides/tools-remote-mcp) for details on connecting remote MCP servers.
+### `execute_code(code)`
 
-## Getting Your API Credentials
+Runs JavaScript (TypeScript syntax accepted — type annotations are stripped before execution) inside a constrained V8 sandbox. The sandbox exposes typed Klaviyo and Shopify clients; the host handles auth, rate limiting, and caching invisibly.
 
-### Klaviyo API Key
+**Globals available inside the sandbox:**
 
-1. Log into [Klaviyo](https://www.klaviyo.com/login)
-2. Go to **Settings** (bottom-left) > **Account** > **Settings**
-3. Click **API Keys** in the left sidebar
-4. Click **Create Private API Key**
-5. Give it a name (e.g., "dtc-mcp")
-6. Select **Read-only** access for these scopes:
-  - `campaigns:read`
-  - `flows:read`
-  - `lists:read`
-  - `segments:read`
-  - `profiles:read`
-  - `metrics:read`
-  - `events:read`
-7. Copy the key (starts with `pk_`)
+| | |
+|---|---|
+| `klaviyo` | `get`, `post`, `paginate`, plus typed namespaces: `campaigns`, `flows`, `lists`, `segments`, `profiles`, `events`, `metrics`, and `reporting.{campaignValues,flowValues}` |
+| `shopify` | `gql`, `ql` (ShopifyQL), `timezone` |
+| `console` | `log` / `error` / `warn` / `info` — captured and returned as `stdout` |
+| `pick(v, schema)` | Deep projection over objects / arrays |
+| `topN(arr, n, by)` | Top-N by numeric key, descending |
+| `summarize(arr, opts)` | Auto-aggregate (count, total, min/max/avg, optional topN) |
+| `globalThis.*` | Assignments persist across `execute_code` calls within the same MCP session |
 
-### Shopify Credentials
+**Not exposed:** `fetch`, `process`, `require`, `import`, `setTimeout`, the filesystem, or any env var. The only path out of the sandbox is the typed SDK methods, which route through the host's rate limiter and cache.
 
-There are two authentication methods. Use whichever matches your app type.
+Defaults: 30s wall-clock per call, 128 MB heap (sidecar), 256 MB total per session. Opt-in `// @timeout 2m` at the top of the code extends the wall-clock up to 5 min.
 
-#### Option A: Dev Dashboard App (Recommended)
+### `search_docs(query, platform?, limit?)`
 
-For apps created in the [Shopify Partners Dashboard](https://partners.shopify.com/) or Shopify CLI (required for new apps since January 2026):
+Full-text BM25 search over the bundled SDK reference. Returns ranked markdown chunks with signatures and runnable examples. Use this when you're discovering methods by intent ("how do I list flows with their actions?").
 
-1. Go to your app in the Partners Dashboard
-2. Navigate to **Configuration** > **Client credentials**
-3. Copy the **Client ID** and **Client Secret**
-4. Your store URL is your `*.myshopify.com` domain
+### `read_doc(path?, platform?)`
 
-Set these environment variables:
+Direct fetch of a chunk by exact path, or a full listing when called with no args. Cheaper than `search_docs` once the LLM knows what it wants. Calling `read_doc({})` once at the start of a session is the recommended way to map the whole SDK surface in one shot.
 
+```js
+read_doc({})                                            // list all 332 paths
+read_doc({ path: "klaviyo.reporting.campaignValues" })  // one chunk verbatim
+read_doc({ platform: "shopify" })                       // Shopify only
 ```
-SHOPIFY_STORE=your-store.myshopify.com
-SHOPIFY_CLIENT_ID=your_client_id
-SHOPIFY_CLIENT_SECRET=shpss_your_secret
-```
-
-**Required scopes:** `read_orders`, `read_products`, `read_customers`, `read_inventory`, `read_reports`
 
-#### Option B: Legacy Custom App
+---
 
-For custom apps created directly in Shopify Admin (apps created before January 2026):
+## Architecture
 
-1. Go to **Shopify Admin** > **Settings** > **Apps and sales channels**
-2. Click **Develop apps** > select your app
-3. Go to **API credentials** and copy the **Admin API access token**
+The sandbox runs in one of two modes, chosen automatically at startup.
 
-Set these environment variables:
+### Preferred: sidecar with isolated-vm
 
 ```
-SHOPIFY_STORE=your-store.myshopify.com
-SHOPIFY_ACCESS_TOKEN=shpat_your_token_here
+┌─ Claude Desktop (Electron, hardened runtime) ────────────────┐
+│                                                               │
+│  MCP server (Electron's bundled Node)                         │
+│   ├ execute_code      proxies to ↓                            │
+│   ├ search_docs       MiniSearch BM25 over data/docs.json     │
+│   ├ read_doc          direct fetch by chunk ID                │
+│   ├ host SDK          Klaviyo + Shopify (rate limit / cache)  │
+│   └ sidecar manager   spawn / lifecycle / NDJSON over stdio   │
+│                                                               │
+└─────────────────────────────│─────────────────────────────────┘
+                              │ newline-delimited JSON-RPC
+┌─ Sidecar process (system Node, outside Electron) ────────────┐
+│                                                               │
+│  isolated-vm loads here (no Library Validation restriction)   │
+│                                                               │
+│  One long-lived V8 isolate per MCP connection:                │
+│   • 256 MB heap, 30 min idle TTL                              │
+│   • klaviyo/shopify/pick/topN/summarize injected once         │
+│   • globalThis state preserved across execute_code calls      │
+│   • host-bridge calls round-trip back to the main process     │
+│                                                               │
+└───────────────────────────────────────────────────────────────┘
 ```
 
-> Do not set both `SHOPIFY_ACCESS_TOKEN` and `SHOPIFY_CLIENT_ID`/`SHOPIFY_CLIENT_SECRET` at the same time. The server will error if both are present.
-
-## Environment Variables
-
-
-| Variable                       | Required                    | Description                                           |
-| ------------------------------ | --------------------------- | ----------------------------------------------------- |
-| `KLAVIYO_API_KEY`              | Yes                         | Klaviyo private API key (starts with `pk_`)           |
-| `SHOPIFY_STORE`                | For Shopify                 | Your `*.myshopify.com` domain                         |
-| `SHOPIFY_CLIENT_ID`            | For Shopify (Dev Dashboard) | App client ID                                         |
-| `SHOPIFY_CLIENT_SECRET`        | For Shopify (Dev Dashboard) | App client secret (starts with `shpss_`)              |
-| `SHOPIFY_ACCESS_TOKEN`         | For Shopify (Legacy)        | Admin API access token (starts with `shpat_`)         |
-| `SHOPIFY_API_VERSION`          | No                          | Shopify API version (default: `2026-01`)              |
-| `KLAVIYO_CONVERSION_METRIC_ID` | No                          | Override auto-discovered "Placed Order" metric ID     |
-| `LOG_LEVEL`                    | No                          | `debug` | `info` | `warn` | `error` (default: `info`) |
-
-
-## Tool Reference
-
-### Klaviyo Tools
-
-#### `klaviyo_campaign_summary`
-
-Top campaigns ranked by metric. Returns name, send date, opens, clicks, revenue.
-
-
-| Parameter | Type                                                          | Default     | Description     |
-| --------- | ------------------------------------------------------------- | ----------- | --------------- |
-| `channel` | `"email"` | `"sms"`                                           | required    | Channel filter  |
-| `metric`  | `"revenue"` | `"open_rate"` | `"click_rate"` | `"recipients"` | `"revenue"` | Rank by         |
-| `days`    | 1-365                                                         | 30          | Lookback period |
-| `limit`   | 1-25                                                          | 10          | Max results     |
-
-
-> "Show me my top email campaigns by revenue this month"
-
-#### `klaviyo_campaign_detail`
-
-Deep dive on one campaign: full metrics, subject line, audiences, send time.
-
-
-| Parameter     | Type   | Default  | Description         |
-| ------------- | ------ | -------- | ------------------- |
-| `campaign_id` | string | required | Klaviyo campaign ID |
-
-
-> "Give me the full breakdown on my Black Friday campaign"
-
-#### `klaviyo_flow_summary`
-
-Top flows by metric. Returns name, status, trigger, message count, revenue.
-
-
-| Parameter | Type                                                                | Default     | Description      |
-| --------- | ------------------------------------------------------------------- | ----------- | ---------------- |
-| `metric`  | `"revenue"` | `"click_rate"` | `"conversion_rate"` | `"recipients"` | `"revenue"` | Rank by          |
-| `days`    | 1-365                                                               | 30          | Lookback period  |
-| `status`  | `"live"` | `"draft"` | `"manual"` | `"all"`                         | `"live"`    | Filter by status |
-| `limit`   | 1-25                                                                | 10          | Max results      |
-
-
-> "Which of my flows generates the most revenue?"
-
-#### `klaviyo_flow_detail`
-
-Deep dive on one flow: per-message performance breakdown.
-
-
-| Parameter | Type   | Default  | Description     |
-| --------- | ------ | -------- | --------------- |
-| `flow_id` | string | required | Klaviyo flow ID |
-| `days`    | 1-365  | 30       | Lookback period |
-
-
-> "Show me the per-email breakdown of my welcome flow"
-
-#### `klaviyo_subscriber_health`
-
-List growth and engagement tier breakdown.
-
-
-| Parameter | Type   | Default  | Description                 |
-| --------- | ------ | -------- | --------------------------- |
-| `list_id` | string | optional | Specific list, or all lists |
-
-
-> "What's the health of my email list?"
-
-#### `klaviyo_list_segments`
-
-All lists and segments with sizes.
-
-
-| Parameter | Type                               | Default  | Description       |
-| --------- | ---------------------------------- | -------- | ----------------- |
-| `type`    | `"lists"` | `"segments"` | `"all"` | `"all"`  | Filter by type    |
-| `cursor`  | string                             | optional | Pagination cursor |
-
-
-> "List all my Klaviyo segments and their sizes"
-
-#### `klaviyo_search_profiles`
-
-Find profiles by email, phone, or name.
-
-
-| Parameter | Type   | Default  | Description           |
-| --------- | ------ | -------- | --------------------- |
-| `query`   | string | required | Email, phone, or name |
-| `limit`   | 1-10   | 5        | Max results           |
-
-
-> "Look up the profile for [john@example.com](mailto:john@example.com)"
-
-#### `klaviyo_recent_activity`
-
-Recent events for a metric (e.g., Placed Order, Opened Email).
+**Why a sidecar:** Claude Desktop is an Electron app with macOS hardened runtime + Library Validation. Native modules loaded into the Claude Desktop process must share Anthropic's Team ID — which we can't sign with. Spawning the user's `/usr/local/bin/node` as a child process sidesteps the restriction; the child has its own hardened-runtime status, so `isolated-vm` loads cleanly.
 
+Node discovery walks: `DTC_MCP_NODE_PATH` env var → `which node` / `where node` → Homebrew (Intel + Apple Silicon) → standard system paths → nvm → Volta → fnm → asdf. Requires Node ≥ 20.
 
-| Parameter       | Type   | Default          | Description           |
-| --------------- | ------ | ---------------- | --------------------- |
-| `metric_name`   | string | `"Placed Order"` | Metric name           |
-| `days`          | 1-90   | 7                | Lookback period       |
-| `limit`         | 1-25   | 10               | Max events            |
-| `profile_email` | string | optional         | Filter to one profile |
+### Fallback: in-process `node:vm`
 
+If no system Node ≥ 20 is found, or the sidecar fails to start, the server falls back to a `node:vm` runner in the main process. Sandbox surface is identical (same `globalThis`, same helpers, same state semantics), but isolation is weaker — `node:vm` is a mistake fence, not a security boundary, and can be escaped via prototype-chain tricks. Acceptable because the threat model is "the user's own LLM might write buggy code," not "an attacker is trying to escape."
 
-> "Show me the last 10 orders placed"
+Every `execute_code` result includes `"sandbox": "sidecar"` or `"sandbox": "vm"` so you (and the LLM) can see which mode ran.
 
-### Shopify Tools
+### Stateful sessions
 
-#### `shopify_sales_summary`
+A single sandbox context lives for the lifetime of the MCP connection. `globalThis.x = ...` in one `execute_code` call is visible in every later call. `const`/`let` declared at the top of a script are scoped to that call only — use `globalThis` for anything you want to carry forward.
 
-Revenue (gross + net), orders, AOV for a period with comparison.
+The context is recreated on: connection close, 30 min idle, isolate OOM, or first call after a long gap. When that happens the next result includes `"sessionReset": true` so the LLM knows prior state is gone.
 
+### Output discipline
 
-| Parameter          | Type    | Default | Description                        |
-| ------------------ | ------- | ------- | ---------------------------------- |
-| `days`             | 1-90    | 30      | Lookback period                    |
-| `compare_previous` | boolean | true    | Include previous period comparison |
+Klaviyo and Shopify endpoints return verbose JSON. The host caps any `execute_code` return value at 100 KB (configurable via `DTC_MCP_MAX_RESPONSE_KB`); oversized returns are replaced with `{ truncated: true, preview, instructions }`. The sandbox-side `pick` / `topN` / `summarize` helpers exist so the LLM can stay under the cap by design — see the `guide.output-discipline` doc chunk for examples.
 
+### Docs delivery
 
-> "What were my sales last month compared to the month before?"
+`search_docs` and `read_doc` query an in-memory MiniSearch index built from `data/docs.json`. The bundled copy ships with ~330 chunks (hand-authored guides + recipes + auto-generated reference for every Klaviyo OpenAPI endpoint). A background fetch on startup pulls a fresher copy from `https://cdn.jsdelivr.net/gh/rafaelsztutman/dtc-mcp-docs@latest/docs.json` (ETag-cached at `~/.cache/dtc-mcp/docs.json`), so new API endpoints land without a new MCP release. Set `DTC_MCP_DOCS_REFRESH=0` for fully offline use.
 
-#### `shopify_sales_timeseries`
+---
 
-Revenue and orders broken down by day, week, or month.
+## Install
 
+### Option A — Claude Desktop one-click
 
-| Parameter     | Type                                 | Default   | Description     |
-| ------------- | ------------------------------------ | --------- | --------------- |
-| `days`        | 1-365                                | 30        | Lookback period |
-| `granularity` | `"daily"` | `"weekly"` | `"monthly"` | `"daily"` | Bucket size     |
+1. Download `dtc-mcp.mcpb` from the latest [GitHub release](https://github.com/rafaelsztutman/dtc-mcp/releases).
+2. Double-click the file. Claude Desktop opens an install dialog.
+3. Paste your Klaviyo API key (required) and Shopify credentials (optional).
+4. Restart Claude Desktop. Three tools appear in the hammer menu: `execute_code`, `search_docs`, `read_doc`.
 
+### Option B — manual config (`claude_desktop_config.json`, Cursor, etc.)
 
-> "Show me daily revenue for this month"
-
-#### `shopify_product_performance`
-
-Top products by revenue or units sold.
-
-
-| Parameter | Type                    | Default     | Description     |
-| --------- | ----------------------- | ----------- | --------------- |
-| `days`    | 1-90                    | 7           | Lookback period |
-| `metric`  | `"revenue"` | `"units"` | `"revenue"` | Rank by         |
-| `limit`   | 1-25                    | 10          | Max results     |
-
-
-> "Which products sold the most units this week?"
-
-#### `shopify_order_search`
-
-Find orders by number, email, or status.
-
-
-| Parameter | Type   | Default  | Description                                     |
-| --------- | ------ | -------- | ----------------------------------------------- |
-| `query`   | string | required | Order number, email, or `financial_status:paid` |
-| `limit`   | 1-25   | 10       | Max results                                     |
-
-
-> "Find order #1234"
-
-#### `shopify_inventory_alerts`
-
-Products with low or zero stock, sorted by most urgent.
-
-
-| Parameter   | Type   | Default | Description                     |
-| ----------- | ------ | ------- | ------------------------------- |
-| `threshold` | number | 10      | Alert at or below this quantity |
-| `limit`     | 1-50   | 20      | Max results                     |
-
-
-> "Which products are running low on stock?"
-
-#### `shopify_customer_cohorts`
-
-Monthly or quarterly acquisition cohorts with LTV and retention signals.
-
-
-| Parameter     | Type                        | Default     | Description     |
-| ------------- | --------------------------- | ----------- | --------------- |
-| `granularity` | `"monthly"` | `"quarterly"` | `"monthly"` | Cohort grouping |
-| `months`      | 1-24                        | 12          | Lookback period |
-
-
-> "Show me customer cohorts by month — which cohort has the best LTV?"
-
-#### `shopify_customer_segments`
-
-Customer distribution by RFM group, spend tier, country, or tags.
-
-
-| Parameter   | Type                                                                                                                                                                                               | Default  | Description            |
-| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------- |
-| `dimension` | `"rfm_group"` | `"predicted_spend_tier"` | `"customer_email_subscription_status"` | `"customer_sms_subscription_status"` | `"customer_country"` | `"customer_tag"` | `"customer_number_of_orders"` | required | Segmentation dimension |
-| `months`    | 1-24                                                                                                                                                                                               | 12       | Lookback period        |
-| `limit`     | 1-50                                                                                                                                                                                               | 20       | Max segments           |
-
-
-> "Break down my customers by RFM group — who are my champions vs at-risk?"
-
-#### `shopify_sales_breakdown`
-
-Revenue and orders broken down by country, channel, vendor, or traffic source.
-
-
-| Parameter   | Type                                                                                                                                                                                              | Default       | Description         |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------- |
-| `dimension` | `"billing_country"` | `"billing_region"` | `"channel_name"` | `"product_vendor"` | `"referrer_source"` | `"referring_channel"` | `"referring_platform"` | `"traffic_type"` | `"shipping_country"` | required      | Breakdown dimension |
-| `days`      | 1-365                                                                                                                                                                                             | 30            | Lookback period     |
-| `metric`    | `"total_sales"` | `"net_sales"` | `"orders"` | `"average_order_value"` | `"gross_profit"`                                                                                                         | `"net_sales"` | Metric to rank by   |
-| `limit`     | 1-50                                                                                                                                                                                              | 10            | Max results         |
-
-
-> "What are my top countries by revenue?" or "Break down sales by channel"
-
-#### `shopify_product_analytics`
-
-Product performance with margins, returns, and quantities via ShopifyQL.
-
-
-| Parameter | Type                                                            | Default       | Description      |
-| --------- | --------------------------------------------------------------- | ------------- | ---------------- |
-| `days`    | 1-365                                                           | 30            | Lookback period  |
-| `metric`  | `"net_sales"` | `"gross_sales"` | `"orders"` | `"gross_profit"` | `"net_sales"` | Sort products by |
-| `limit`   | 1-50                                                            | 10            | Max results      |
-
-
-> "Which products have the best margins?" or "Show product performance with return rates"
-
-#### `shopify_traffic_sources`
-
-Session analytics by source, landing page, or daily trend.
-
-
-| Parameter | Type                                        | Default     | Description     |
-| --------- | ------------------------------------------- | ----------- | --------------- |
-| `mode`    | `"sources"` | `"landing_pages"` | `"trend"` | `"sources"` | Analysis mode   |
-| `days`    | 1-365                                       | 30          | Lookback period |
-| `limit`   | 1-50                                        | 10          | Max results     |
-
-
-> "Where is my traffic coming from?" or "What are my top landing pages?"
-
-#### `shopify_returns_analysis`
-
-Return rates, costs, and most-returned products.
-
+```json
+{
+  "mcpServers": {
+    "dtc-mcp": {
+      "command": "npx",
+      "args": ["-y", "dtc-mcp"],
+      "env": {
+        "KLAVIYO_API_KEY": "pk_your_private_key_here",
+        "SHOPIFY_STORE": "your-store.myshopify.com",
+        "SHOPIFY_CLIENT_ID": "your_client_id",
+        "SHOPIFY_CLIENT_SECRET": "shpss_your_secret"
+      }
+    }
+  }
+}
+```
 
-| Parameter | Type                         | Default     | Description                             |
-| --------- | ---------------------------- | ----------- | --------------------------------------- |
-| `mode`    | `"summary"` | `"by_product"` | `"summary"` | Summary totals or per-product breakdown |
-| `days`    | 1-365                        | 30          | Lookback period                         |
-| `limit`   | 1-50                         | 10          | Max results (by_product mode)           |
+Klaviyo-only mode: omit the `SHOPIFY_*` variables. `shopify.*` calls throw a configuration error; `klaviyo.*` calls work normally.
 
+### Option C — npm global install
 
-> "What's my return rate?" or "Which products get returned the most?"
+```bash
+npm install -g dtc-mcp
+dtc-mcp           # runs the MCP server on stdio
+```
 
-#### `shopify_recent_orders`
+---
 
-Most recent orders. Quick snapshot of store activity.
+## Getting credentials
 
+### Klaviyo
 
-| Parameter | Type | Default | Description |
-| --------- | ---- | ------- | ----------- |
-| `limit`   | 1-25 | 10      | Max results |
+1. Log into Klaviyo. **Settings → Account → API Keys** (left sidebar).
+2. **Create Private API Key**. Name it `dtc-mcp`.
+3. Grant read-only scopes: `campaigns:read`, `flows:read`, `lists:read`, `segments:read`, `profiles:read`, `metrics:read`, `events:read`.
+4. Copy the `pk_...` key.
 
+### Shopify
 
-> "Show me the last 10 orders"
+Two auth modes. Use whichever matches your app type.
 
-### Cross-Platform Tools
+**Dev Dashboard app (recommended, required for apps created after Jan 2026):**
 
-#### `dtc_email_revenue_attribution`
+1. Open your app in the [Shopify Partners Dashboard](https://partners.shopify.com).
+2. **Configuration → Client credentials.** Copy the Client ID and Client Secret.
+3. Required scopes: `read_orders`, `read_products`, `read_customers`, `read_inventory`, `read_reports`.
 
-Email/SMS revenue vs total Shopify revenue. Shows email marketing contribution.
+Env vars:
 
+```
+SHOPIFY_STORE=your-store.myshopify.com
+SHOPIFY_CLIENT_ID=your_client_id
+SHOPIFY_CLIENT_SECRET=shpss_your_secret
+```
 
-| Parameter | Type  | Default | Description     |
-| --------- | ----- | ------- | --------------- |
-| `days`    | 1-365 | 30      | Lookback period |
+**Legacy custom app (apps created before Jan 2026):**
 
+1. Shopify Admin → **Settings → Apps and sales channels → Develop apps**, open your app.
+2. **API credentials** → copy the Admin API access token (`shpat_...`).
 
-> "What percentage of my revenue came from email?"
+Env vars:
 
-#### `dtc_dashboard`
+```
+SHOPIFY_STORE=your-store.myshopify.com
+SHOPIFY_ACCESS_TOKEN=shpat_your_token_here
+```
 
-Complete DTC health dashboard: sales + email + subscriber metrics in one call.
+Do not set both auth modes at once; the server logs a warning and uses Client Credentials if both are present.
 
+---
 
-| Parameter | Type | Default | Description     |
-| --------- | ---- | ------- | --------------- |
-| `days`    | 7-90 | 30      | Lookback period |
+## Environment
 
+| Variable | Required | Description |
+|---|---|---|
+| `KLAVIYO_API_KEY` | Yes | Klaviyo private API key (`pk_...`) |
+| `SHOPIFY_STORE` | For Shopify | `*.myshopify.com` domain |
+| `SHOPIFY_CLIENT_ID` | Dev Dashboard auth | App Client ID |
+| `SHOPIFY_CLIENT_SECRET` | Dev Dashboard auth | App Client Secret (`shpss_...`) |
+| `SHOPIFY_ACCESS_TOKEN` | Legacy custom app | Admin API token (`shpat_...`) |
+| `SHOPIFY_API_VERSION` | No | Default `2026-01` |
+| `KLAVIYO_CONVERSION_METRIC_ID` | No | Override auto-discovered "Placed Order" metric ID |
+| `DTC_MCP_SANDBOX` | No | `auto` (default) \| `sidecar` (require isolated-vm) \| `vm` (force `node:vm`) |
+| `DTC_MCP_NODE_PATH` | No | Absolute path to the Node binary used by the sidecar. Skips discovery. |
+| `DTC_MCP_MAX_RESPONSE_KB` | No | Cap on bytes of `execute_code` return values (default `100`). |
+| `DTC_MCP_DOCS_URL` | No | Override docs source. Default: jsDelivr → `dtc-mcp-docs@latest`. |
+| `DTC_MCP_DOCS_REFRESH` | No | Set to `0` to disable the background docs refresh (offline mode). |
+| `LOG_LEVEL` | No | `debug` \| `info` \| `warn` \| `error` (default `info`) |
 
-> "Give me the full business dashboard for last month"
+---
 
-## Example Queries
+## Development
 
-Here are questions you can ask Claude once dtc-mcp is connected:
+```bash
+npm install        # installs deps, builds isolated-vm via node-gyp
+npm run build      # tsc → dist/
+npm run dev        # tsc --watch
+npm test           # vitest (53 tests)
+npm run inspect    # MCP Inspector — connect any client to dist/index.js
+```
 
-- "How did my email campaigns perform this month?"
-- "Which flow is generating the most revenue? Drill into the top one."
-- "Show me daily revenue for this month so I can compare against my Shopify dashboard"
-- "What's my gross vs net revenue for the past 30 days?"
-- "Which products are my best sellers this week?"
-- "Are any products running low on stock?"
-- "What percentage of my revenue comes from email marketing?"
-- "How many new vs returning customers did I have this quarter?"
-- "Show me customer cohorts by month — which has the best LTV?"
-- "Break down my customers by RFM group"
-- "What are my top countries by revenue?"
-- "Where is my traffic coming from?"
-- "What's my return rate? Which products get returned the most?"
-- "Which products have the best margins?"
-- "Give me a complete health dashboard for my business"
-- "Compare this month's sales to last month"
-- "What are my top SMS campaigns by click rate?"
+### Building the .mcpb bundle
 
-## Privacy Policy
+```bash
+tools/build-mcpb.sh           # → dtc-mcp-v<version>.mcpb in repo root
+```
 
-dtc-mcp runs locally on your machine. It does not collect, store, or transmit any user data. API credentials are stored in your local MCP client configuration and used only to authenticate directly with Klaviyo and Shopify. No analytics, telemetry, or third-party data sharing. See [PRIVACY.md](PRIVACY.md) for full details.
+Stages prod-only dependencies, ad-hoc code-signs native `.node` binaries (macOS requirement), and zips into a `.mcpb` ready for one-click install.
 
-## Development
+### Regenerating bundled docs
 
 ```bash
-git clone https://github.com/rafaelsztutman/dtc-mcp.git
-cd dtc-mcp
-npm install
-cp .env.example .env    # Fill in your API credentials
-npm run build           # Compile TypeScript
-npm test                # Run tests (46 tests)
-npm run dev             # Watch mode
-npm run inspect         # Open MCP Inspector for interactive testing
+npm run codegen:klaviyo   # download Klaviyo OpenAPI, emit chunk JSON
+npm run codegen:shopify   # introspect Shopify GraphQL (needs SHOPIFY_* env), emit chunks
+npm run codegen:docs      # merge guides + chunks into data/docs.json
 ```
 
+In production this runs daily on a GitHub Action in [dtc-mcp-docs](https://github.com/rafaelsztutman/dtc-mcp-docs); the MCP fetches the freshest copy on the next boot.
+
+---
+
 ## License
 
-MIT
+MIT. See `LICENSE`.