dtc-mcp 0.2.0 → 1.0.0

package/README.md

@@ -1,484 +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`
+**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.
 
-Recent events for a metric (e.g., Placed Order, Opened Email).
+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.
 
+### Fallback: in-process `node:vm`
 
-| 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 |
+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."
 
+Every `execute_code` result includes `"sandbox": "sidecar"` or `"sandbox": "vm"` so you (and the LLM) can see which mode ran.
 
-> "Show me the last 10 orders placed"
+### Stateful sessions
 
-### Shopify Tools
+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.
 
-#### `shopify_sales_summary`
+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.
 
-Revenue (gross + net), orders, AOV for a period with comparison.
+### Output discipline
 
+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.
 
-| Parameter          | Type    | Default | Description                        |
-| ------------------ | ------- | ------- | ---------------------------------- |
-| `days`             | 1-90    | 30      | Lookback period                    |
-| `compare_previous` | boolean | true    | Include previous period comparison |
+### Docs delivery
 
+`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.
 
-> "What were my sales last month compared to the month before?"
+---
 
-#### `shopify_sales_timeseries`
+## Install
 
-Revenue and orders broken down by day, week, or month.
+### Option A — Claude Desktop one-click
 
+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`.
 
-| Parameter     | Type                                 | Default   | Description     |
-| ------------- | ------------------------------------ | --------- | --------------- |
-| `days`        | 1-365                                | 30        | Lookback period |
-| `granularity` | `"daily"` | `"weekly"` | `"monthly"` | `"daily"` | Bucket size     |
+### Option B — manual config (`claude_desktop_config.json`, Cursor, etc.)
 
+```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"
+      }
+    }
+  }
+}
+```
 
-> "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.
+Klaviyo-only mode: omit the `SHOPIFY_*` variables. `shopify.*` calls throw a configuration error; `klaviyo.*` calls work normally.
 
+### Option C — npm global install
 
-| 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)           |
+```bash
+npm install -g dtc-mcp
+dtc-mcp           # runs the MCP server on stdio
+```
 
+---
 
-> "What's my return rate?" or "Which products get returned the most?"
+## Getting credentials
 
-#### `shopify_recent_orders`
+### Klaviyo
 
-Most recent orders. Quick snapshot of store activity.
+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
 
-| Parameter | Type | Default | Description |
-| --------- | ---- | ------- | ----------- |
-| `limit`   | 1-25 | 10      | Max results |
+Two auth modes. Use whichever matches your app type.
 
+**Dev Dashboard app (recommended, required for apps created after Jan 2026):**
 
-> "Show me the last 10 orders"
+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`.
 
-### Cross-Platform Tools
+Env vars:
 
-#### `dtc_email_revenue_attribution`
+```
+SHOPIFY_STORE=your-store.myshopify.com
+SHOPIFY_CLIENT_ID=your_client_id
+SHOPIFY_CLIENT_SECRET=shpss_your_secret
+```
 
-Email/SMS revenue vs total Shopify revenue. Shows email marketing contribution.
+**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_...`).
 
-| Parameter | Type  | Default | Description     |
-| --------- | ----- | ------- | --------------- |
-| `days`    | 1-365 | 30      | Lookback period |
+Env vars:
 
+```
+SHOPIFY_STORE=your-store.myshopify.com
+SHOPIFY_ACCESS_TOKEN=shpat_your_token_here
+```
 
-> "What percentage of my revenue came from email?"
+Do not set both auth modes at once; the server logs a warning and uses Client Credentials if both are present.
 
-#### `dtc_dashboard`
+---
 
-Complete DTC health dashboard: sales + email + subscriber metrics in one call.
+## 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`) |
 
-| Parameter | Type | Default | Description     |
-| --------- | ---- | ------- | --------------- |
-| `days`    | 7-90 | 30      | Lookback period |
+---
 
+## Development
 
-> "Give me the full business dashboard for last month"
+```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
+```
 
-## Example Queries
+### Building the .mcpb bundle
 
-Here are questions you can ask Claude once dtc-mcp is connected:
+```bash
+tools/build-mcpb.sh           # → dtc-mcp-v<version>.mcpb in repo root
+```
 
-- "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?"
+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 (44 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`.