dtc-mcp 0.1.3 → 0.2.0

package/README.md

@@ -1,16 +1,16 @@
 # dtc-mcp
 
-Context-optimized MCP server for DTC e-commerce brands. Connect Claude (or any MCP client) to your Klaviyo and Shopify data with 16 pre-built analytics tools.
+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.
 
 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.
 
 ## Features
 
 - **8 Klaviyo tools** — campaign performance, flow breakdowns, subscriber health, profile search, event activity
-- **7 Shopify tools** — sales summaries, daily/weekly/monthly trends, product performance, inventory alerts, customer cohorts, order search
+- **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
-- **Smart fallbacks** — ShopifyQL when available, GraphQL pagination when not
+- **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
@@ -32,7 +32,7 @@ npx dtc-mcp
 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 16 tools will appear in the hammer menu automatically
+4. The 22 tools will appear in the hammer menu automatically
 
 ### Option B: Manual Configuration
 
@@ -57,8 +57,8 @@ npx dtc-mcp
 }
 ```
 
-4. Restart Claude Desktop
-5. Look for the hammer icon in the chat input — that confirms the MCP tools are loaded
+1. Restart Claude Desktop
+2. Look for the hammer icon in the chat input — that confirms the MCP tools are loaded
 
 ### Klaviyo-only mode
 
@@ -78,13 +78,13 @@ ChatGPT supports MCP servers via remote connections. Since dtc-mcp uses stdio tr
 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`
+  - `campaigns:read`
+  - `flows:read`
+  - `lists:read`
+  - `segments:read`
+  - `profiles:read`
+  - `metrics:read`
+  - `events:read`
 7. Copy the key (starts with `pk_`)
 
 ### Shopify Credentials
@@ -101,13 +101,14 @@ For apps created in the [Shopify Partners Dashboard](https://partners.shopify.co
 4. Your store URL is your `*.myshopify.com` domain
 
 Set these environment variables:
+
 ```
 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`
+**Required scopes:** `read_orders`, `read_products`, `read_customers`, `read_inventory`, `read_reports`
 
 #### Option B: Legacy Custom App
 
@@ -118,6 +119,7 @@ For custom apps created directly in Shopify Admin (apps created before January 2
 3. Go to **API credentials** and copy the **Admin API access token**
 
 Set these environment variables:
+
 ```
 SHOPIFY_STORE=your-store.myshopify.com
 SHOPIFY_ACCESS_TOKEN=shpat_your_token_here
@@ -127,194 +129,318 @@ SHOPIFY_ACCESS_TOKEN=shpat_your_token_here
 
 ## 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`) |
+
+| 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 |
+
+| 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 |
-|-----------|------|---------|-------------|
+
+| 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 |
+
+| 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 |
-|-----------|------|---------|-------------|
+
+| Parameter | Type   | Default  | Description     |
+| --------- | ------ | -------- | --------------- |
 | `flow_id` | string | required | Klaviyo flow ID |
-| `days` | 1-365 | 30 | Lookback period |
+| `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 |
-|-----------|------|---------|-------------|
+
+| 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 |
+
+| 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"
+| 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).
 
-| 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 |
+
+| 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 |
+
 
 > "Show me the last 10 orders placed"
 
 ### Shopify Tools
 
 #### `shopify_sales_summary`
+
 Revenue (gross + net), orders, AOV for a period with comparison.
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `days` | 1-90 | 30 | Lookback period |
-| `compare_previous` | boolean | true | Include previous period comparison |
+
+| Parameter          | Type    | Default | Description                        |
+| ------------------ | ------- | ------- | ---------------------------------- |
+| `days`             | 1-90    | 30      | Lookback period                    |
+| `compare_previous` | boolean | true    | Include previous period comparison |
+
 
 > "What were my sales last month compared to the month before?"
 
 #### `shopify_sales_timeseries`
+
 Revenue and orders broken down by day, week, or month.
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `days` | 1-365 | 30 | Lookback period |
-| `granularity` | `"daily"` \| `"weekly"` \| `"monthly"` | `"daily"` | Bucket size |
+
+| Parameter     | Type                                 | Default   | Description     |
+| ------------- | ------------------------------------ | --------- | --------------- |
+| `days`        | 1-365                                | 30        | Lookback period |
+| `granularity` | `"daily"` | `"weekly"` | `"monthly"` | `"daily"` | Bucket size     |
+
 
 > "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 |
+
+| 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 |
+
+| 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 |
+
+| 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_cohort`
-New vs returning buyers. First-time vs repeat split.
+#### `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 | 90 | Lookback period |
-| `limit` | 1-500 | 250 | Max customers to analyze |
 
-> "What percentage of orders this quarter came from new customers?"
+| 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.
+
+
+| 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)           |
+
+
+> "What's my return rate?" or "Which products get returned the most?"
 
 #### `shopify_recent_orders`
+
 Most recent orders. Quick snapshot of store activity.
 
+
 | Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `limit` | 1-25 | 10 | Max results |
+| --------- | ---- | ------- | ----------- |
+| `limit`   | 1-25 | 10      | Max results |
+
 
 > "Show me the last 10 orders"
 
 ### Cross-Platform Tools
 
 #### `dtc_email_revenue_attribution`
+
 Email/SMS revenue vs total Shopify revenue. Shows email marketing contribution.
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `days` | 1-365 | 30 | Lookback period |
+
+| Parameter | Type  | Default | Description     |
+| --------- | ----- | ------- | --------------- |
+| `days`    | 1-365 | 30      | Lookback period |
+
 
 > "What percentage of my revenue came from email?"
 
 #### `dtc_dashboard`
+
 Complete DTC health dashboard: sales + email + subscriber metrics in one call.
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `days` | 7-90 | 30 | Lookback period |
+
+| Parameter | Type | Default | Description     |
+| --------- | ---- | ------- | --------------- |
+| `days`    | 7-90 | 30      | Lookback period |
+
 
 > "Give me the full business dashboard for last month"
 
@@ -330,7 +456,12 @@ Here are questions you can ask Claude once dtc-mcp is connected:
 - "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?"
-- "Look up the customer profile for sarah@example.com"
+- "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?"
@@ -343,11 +474,11 @@ cd dtc-mcp
 npm install
 cp .env.example .env    # Fill in your API credentials
 npm run build           # Compile TypeScript
-npm test                # Run tests (31 tests)
+npm test                # Run tests (44 tests)
 npm run dev             # Watch mode
 npm run inspect         # Open MCP Inspector for interactive testing
 ```
 
 ## License
 
-MIT
+MIT

package/dist/bootstrap.cjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+"use strict";
+// CommonJS bootstrap — runs BEFORE any ESM module evaluation.
+// Catches errors during ESM module loading and writes to a debug log file.
+// This exists because Claude Desktop's built-in Node.js does not capture stderr.
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const LOG = path.join(os.tmpdir(), "dtc-mcp-debug.log");
+function debugLog(msg) {
+    try {
+        fs.appendFileSync(LOG, `${new Date().toISOString()} ${msg}\n`);
+    }
+    catch {
+        // can't write to log file
+    }
+}
+try {
+    fs.writeFileSync(LOG, "");
+}
+catch {
+    // ignore
+}
+debugLog("=== dtc-mcp bootstrap ===");
+debugLog(`node: ${process.version}`);
+debugLog(`platform: ${process.platform} ${process.arch}`);
+debugLog(`argv: ${JSON.stringify(process.argv)}`);
+debugLog(`cwd: ${process.cwd()}`);
+debugLog(`env KLAVIYO_API_KEY set: ${!!process.env.KLAVIYO_API_KEY} (length: ${process.env.KLAVIYO_API_KEY?.length ?? 0})`);
+debugLog(`env SHOPIFY_STORE set: ${!!process.env.SHOPIFY_STORE}`);
+debugLog(`env SHOPIFY_CLIENT_ID set: ${!!process.env.SHOPIFY_CLIENT_ID}`);
+debugLog(`env SHOPIFY_CLIENT_SECRET set: ${!!process.env.SHOPIFY_CLIENT_SECRET}`);
+debugLog(`env SHOPIFY_ACCESS_TOKEN set: ${!!process.env.SHOPIFY_ACCESS_TOKEN}`);
+process.on("uncaughtException", (err) => {
+    debugLog(`uncaughtException: ${err?.stack || err}`);
+});
+process.on("unhandledRejection", (err) => {
+    debugLog(`unhandledRejection: ${err instanceof Error ? err.stack : String(err)}`);
+});
+process.on("exit", (code) => {
+    debugLog(`process exit: code=${code}`);
+});
+debugLog("loading ESM module...");
+import("./index.js")
+    .then(() => {
+    debugLog("ESM module loaded OK");
+})
+    .catch((err) => {
+    debugLog(`ESM module load FAILED: ${err?.stack || err}`);
+    process.exit(1);
+});
+//# sourceMappingURL=bootstrap.cjs.map

package/dist/bootstrap.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.cjs","sourceRoot":"","sources":["../src/bootstrap.cts"],"names":[],"mappings":";;AAEA,8DAA8D;AAC9D,2EAA2E;AAC3E,iFAAiF;;AAEjF,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AACzB,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AACzB,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE7B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,mBAAmB,CAAC,CAAC;AAExD,SAAS,QAAQ,CAAC,GAAW;IAC3B,IAAI,CAAC;QACH,EAAE,CAAC,cAAc,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,0BAA0B;IAC5B,CAAC;AACH,CAAC;AAED,IAAI,CAAC;IACH,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAC5B,CAAC;AAAC,MAAM,CAAC;IACP,SAAS;AACX,CAAC;AAED,QAAQ,CAAC,2BAA2B,CAAC,CAAC;AACtC,QAAQ,CAAC,SAAS,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;AACrC,QAAQ,CAAC,aAAa,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;AAC1D,QAAQ,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAClD,QAAQ,CAAC,QAAQ,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAClC,QAAQ,CACN,4BAA4B,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,aAAa,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,MAAM,IAAI,CAAC,GAAG,CAClH,CAAC;AACF,QAAQ,CAAC,0BAA0B,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC,CAAC;AAClE,QAAQ,CAAC,8BAA8B,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,CAAC,CAAC;AAC1E,QAAQ,CACN,kCAAkC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,EAAE,CACxE,CAAC;AACF,QAAQ,CACN,iCAAiC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,CACtE,CAAC;AAEF,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,GAAU,EAAE,EAAE;IAC7C,QAAQ,CAAC,sBAAsB,GAAG,EAAE,KAAK,IAAI,GAAG,EAAE,CAAC,CAAC;AACtD,CAAC,CAAC,CAAC;AACH,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,GAAY,EAAE,EAAE;IAChD,QAAQ,CACN,uBAAuB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACxE,CAAC;AACJ,CAAC,CAAC,CAAC;AACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;IAClC,QAAQ,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC;AACzC,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,uBAAuB,CAAC,CAAC;AAClC,MAAM,CAAC,YAAY,CAAC;KACjB,IAAI,CAAC,GAAG,EAAE;IACT,QAAQ,CAAC,sBAAsB,CAAC,CAAC;AACnC,CAAC,CAAC;KACD,KAAK,CAAC,CAAC,GAAU,EAAE,EAAE;IACpB,QAAQ,CAAC,2BAA2B,GAAG,EAAE,KAAK,IAAI,GAAG,EAAE,CAAC,CAAC;IACzD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/bootstrap.d.cts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/config.js

@@ -10,7 +10,14 @@ function getRequired(name) {
     return value;
 }
 function getOptional(name) {
-    return process.env[name] || null;
+    const raw = process.env[name];
+    if (!raw)
+        return null;
+    // Claude Desktop may pass placeholder values for unfilled optional fields
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed === "undefined" || trimmed === "null")
+        return null;
+    return trimmed;
 }
 function loadConfig() {
     const klaviyoApiKey = getRequired("KLAVIYO_API_KEY");
@@ -21,36 +28,41 @@ function loadConfig() {
     // Determine auth mode
     const hasLegacy = shopifyAccessToken !== null;
     const hasClientCredentials = shopifyClientId !== null && shopifyClientSecret !== null;
+    let shopifyAuthMode = null;
     if (hasLegacy && hasClientCredentials) {
-        throw new Error("Ambiguous Shopify config: both SHOPIFY_ACCESS_TOKEN and SHOPIFY_CLIENT_ID/SHOPIFY_CLIENT_SECRET are set. Use one auth mode, not both.");
+        // Both set — prefer client_credentials (recommended), ignore legacy token
+        console.error("[dtc-mcp] warn: Both SHOPIFY_ACCESS_TOKEN and SHOPIFY_CLIENT_ID/SECRET are set. Using Client Credentials (recommended). Remove ACCESS_TOKEN to silence this warning.");
+        shopifyAuthMode = "client_credentials";
     }
-    let shopifyAuthMode = null;
-    if (hasClientCredentials) {
+    else if (hasClientCredentials) {
         shopifyAuthMode = "client_credentials";
     }
     else if (hasLegacy) {
         shopifyAuthMode = "legacy";
     }
-    // Validate that store is set when any auth is configured
+    // Warn (don't throw) if store is missing when auth is configured
     if (shopifyAuthMode && !shopifyStore) {
-        throw new Error("SHOPIFY_STORE is required when Shopify credentials are configured.");
+        console.error("[dtc-mcp] warn: Shopify credentials are set but SHOPIFY_STORE is missing. Shopify tools will be disabled.");
+        shopifyAuthMode = null;
     }
-    // Validate partial client credentials
+    // Warn (don't throw) for partial client credentials
     if ((shopifyClientId && !shopifyClientSecret) ||
         (!shopifyClientId && shopifyClientSecret)) {
-        throw new Error("Both SHOPIFY_CLIENT_ID and SHOPIFY_CLIENT_SECRET must be set together.");
+        console.error("[dtc-mcp] warn: Only one of SHOPIFY_CLIENT_ID/SHOPIFY_CLIENT_SECRET is set. Both are required. Shopify client credentials auth will be disabled.");
     }
-    const logLevel = (process.env.LOG_LEVEL || "info");
-    if (!["debug", "info", "warn", "error"].includes(logLevel)) {
-        throw new Error(`Invalid LOG_LEVEL: ${logLevel}. Must be one of: debug, info, warn, error`);
+    const rawLogLevel = (process.env.LOG_LEVEL || "info");
+    const validLevels = ["debug", "info", "warn", "error"];
+    const logLevel = validLevels.includes(rawLogLevel) ? rawLogLevel : "info";
+    if (!validLevels.includes(rawLogLevel)) {
+        console.error(`[dtc-mcp] warn: Invalid LOG_LEVEL "${rawLogLevel}", defaulting to "info".`);
     }
     return Object.freeze({
         klaviyoApiKey,
         klaviyoRevision: "2026-01-15",
         shopifyStore,
-        shopifyAccessToken,
-        shopifyClientId,
-        shopifyClientSecret,
+        shopifyAccessToken: shopifyAuthMode === "legacy" ? shopifyAccessToken : null,
+        shopifyClientId: shopifyAuthMode === "client_credentials" ? shopifyClientId : null,
+        shopifyClientSecret: shopifyAuthMode === "client_credentials" ? shopifyClientSecret : null,
         shopifyAuthMode,
         shopifyApiVersion: process.env.SHOPIFY_API_VERSION || "2026-01",
         klaviyoConversionMetricId: getOptional("KLAVIYO_CONVERSION_METRIC_ID"),