dtc-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rafael Sztutman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,344 @@
+# 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.
+
+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
+- **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
+- **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
+```
+
+## Setup with Claude Desktop
+
+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"
+      }
+    }
+  }
+}
+```
+
+4. Restart Claude Desktop
+5. Look for the hammer icon in the chat input — that confirms the MCP tools are loaded
+
+### Klaviyo-only mode
+
+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
+
+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.
+
+## Getting Your API Credentials
+
+### Klaviyo API Key
+
+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_`)
+
+### Shopify Credentials
+
+There are two authentication methods. Use whichever matches your app type.
+
+#### Option A: Dev Dashboard App (Recommended)
+
+For apps created in the [Shopify Partners Dashboard](https://partners.shopify.com/) or Shopify CLI (required for new apps since January 2026):
+
+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
+
+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`
+
+#### Option B: Legacy Custom App
+
+For custom apps created directly in Shopify Admin (apps created before January 2026):
+
+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**
+
+Set these environment variables:
+```
+SHOPIFY_STORE=your-store.myshopify.com
+SHOPIFY_ACCESS_TOKEN=shpat_your_token_here
+```
+
+> 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"
+
+#### `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 |
+
+> "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 |
+
+> "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 |
+
+> "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_cohort`
+New vs returning buyers. First-time vs repeat split.
+
+| 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?"
+
+#### `shopify_recent_orders`
+Most recent orders. Quick snapshot of store activity.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `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 |
+
+> "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 |
+
+> "Give me the full business dashboard for last month"
+
+## Example Queries
+
+Here are questions you can ask Claude once dtc-mcp is connected:
+
+- "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?"
+- "Look up the customer profile for sarah@example.com"
+- "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?"
+
+## Development
+
+```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 (31 tests)
+npm run dev             # Watch mode
+npm run inspect         # Open MCP Inspector for interactive testing
+```
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,17 @@
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export type ShopifyAuthMode = "client_credentials" | "legacy" | null;
+export interface Config {
+    readonly klaviyoApiKey: string;
+    readonly klaviyoRevision: string;
+    readonly shopifyStore: string | null;
+    readonly shopifyAccessToken: string | null;
+    readonly shopifyClientId: string | null;
+    readonly shopifyClientSecret: string | null;
+    readonly shopifyAuthMode: ShopifyAuthMode;
+    readonly shopifyApiVersion: string;
+    readonly klaviyoConversionMetricId: string | null;
+    readonly logLevel: LogLevel;
+}
+export declare const config: Config;
+export declare function isShopifyConfigured(): boolean;
+export declare function log(level: LogLevel, message: string, data?: Record<string, unknown>): void;

package/dist/config.js

@@ -0,0 +1,71 @@
+function getRequired(name) {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`Missing required environment variable: ${name}. ` +
+            `Set it in your environment: export ${name}=your_value_here`);
+    }
+    return value;
+}
+function getOptional(name) {
+    return process.env[name] || null;
+}
+function loadConfig() {
+    const klaviyoApiKey = getRequired("KLAVIYO_API_KEY");
+    const shopifyStore = getOptional("SHOPIFY_STORE");
+    const shopifyAccessToken = getOptional("SHOPIFY_ACCESS_TOKEN");
+    const shopifyClientId = getOptional("SHOPIFY_CLIENT_ID");
+    const shopifyClientSecret = getOptional("SHOPIFY_CLIENT_SECRET");
+    // Determine auth mode
+    const hasLegacy = shopifyAccessToken !== null;
+    const hasClientCredentials = shopifyClientId !== null && shopifyClientSecret !== 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.");
+    }
+    let shopifyAuthMode = null;
+    if (hasClientCredentials) {
+        shopifyAuthMode = "client_credentials";
+    }
+    else if (hasLegacy) {
+        shopifyAuthMode = "legacy";
+    }
+    // Validate that store is set when any auth is configured
+    if (shopifyAuthMode && !shopifyStore) {
+        throw new Error("SHOPIFY_STORE is required when Shopify credentials are configured.");
+    }
+    // Validate partial client credentials
+    if ((shopifyClientId && !shopifyClientSecret) ||
+        (!shopifyClientId && shopifyClientSecret)) {
+        throw new Error("Both SHOPIFY_CLIENT_ID and SHOPIFY_CLIENT_SECRET must be set together.");
+    }
+    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`);
+    }
+    return Object.freeze({
+        klaviyoApiKey,
+        klaviyoRevision: "2026-01-15",
+        shopifyStore,
+        shopifyAccessToken,
+        shopifyClientId,
+        shopifyClientSecret,
+        shopifyAuthMode,
+        shopifyApiVersion: process.env.SHOPIFY_API_VERSION || "2026-01",
+        klaviyoConversionMetricId: getOptional("KLAVIYO_CONVERSION_METRIC_ID"),
+        logLevel,
+    });
+}
+export const config = loadConfig();
+export function isShopifyConfigured() {
+    return config.shopifyStore !== null && config.shopifyAuthMode !== null;
+}
+export function log(level, message, data) {
+    const levels = ["debug", "info", "warn", "error"];
+    if (levels.indexOf(level) < levels.indexOf(config.logLevel))
+        return;
+    const entry = data
+        ? `[dtc-mcp] ${level}: ${message} ${JSON.stringify(data)}`
+        : `[dtc-mcp] ${level}: ${message}`;
+    // Always log to stderr — stdout is the MCP transport channel
+    console.error(entry);
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/cross-platform/correlator.d.ts

@@ -0,0 +1,10 @@
+import type { RevenueAttribution, Dashboard } from "../shared/types.js";
+/**
+ * Compare Klaviyo attributed revenue vs Shopify total revenue.
+ */
+export declare function computeRevenueAttribution(days: number): Promise<RevenueAttribution>;
+/**
+ * Orchestrate a complete DTC health dashboard.
+ * Uses cached results from sub-queries to minimize API calls.
+ */
+export declare function computeDashboard(days: number): Promise<Dashboard>;

package/dist/cross-platform/correlator.js

@@ -0,0 +1,166 @@
+import { isShopifyConfigured } from "../config.js";
+import { getCampaignReport, getFlowReport } from "../platforms/klaviyo/client.js";
+import { getAggregatedSales } from "../platforms/shopify/client.js";
+/**
+ * Compare Klaviyo attributed revenue vs Shopify total revenue.
+ */
+export async function computeRevenueAttribution(days) {
+    // Fetch Klaviyo campaign + flow revenue (uses cached reporting data)
+    const [campaignRows, flowRows] = await Promise.all([
+        getCampaignReport(days),
+        getFlowReport(days),
+    ]);
+    // Sum campaign revenue
+    let campaignRevenue = 0;
+    const campaignRevenueMap = new Map();
+    for (const row of campaignRows) {
+        const revenue = row.statistics.conversion_value ?? 0;
+        const id = String(row.groupings.campaign_id ?? "unknown");
+        campaignRevenue += revenue;
+        const existing = campaignRevenueMap.get(id);
+        if (existing) {
+            existing.revenue += revenue;
+        }
+        else {
+            campaignRevenueMap.set(id, { name: id, revenue });
+        }
+    }
+    // Sum flow revenue
+    let flowRevenue = 0;
+    const flowRevenueMap = new Map();
+    for (const row of flowRows) {
+        const revenue = row.statistics.conversion_value ?? 0;
+        const id = String(row.groupings.flow_id ?? "unknown");
+        flowRevenue += revenue;
+        const existing = flowRevenueMap.get(id);
+        if (existing) {
+            existing.revenue += revenue;
+        }
+        else {
+            flowRevenueMap.set(id, { name: id, revenue });
+        }
+    }
+    const emailTotalRevenue = campaignRevenue + flowRevenue;
+    // Get Shopify total revenue
+    let totalRevenue = emailTotalRevenue;
+    if (isShopifyConfigured()) {
+        try {
+            const sales = await getAggregatedSales(days);
+            totalRevenue = sales.netRevenue || emailTotalRevenue;
+        }
+        catch {
+            // Shopify unavailable — use email revenue as total
+        }
+    }
+    const emailPct = totalRevenue > 0
+        ? Math.round((emailTotalRevenue / totalRevenue) * 10000) / 100
+        : 0;
+    const topCampaigns = Array.from(campaignRevenueMap.values())
+        .sort((a, b) => b.revenue - a.revenue)
+        .slice(0, 5);
+    const topFlows = Array.from(flowRevenueMap.values())
+        .sort((a, b) => b.revenue - a.revenue)
+        .slice(0, 5);
+    return {
+        period_days: days,
+        total_revenue: Math.round(totalRevenue * 100) / 100,
+        email_campaign_revenue: Math.round(campaignRevenue * 100) / 100,
+        flow_revenue: Math.round(flowRevenue * 100) / 100,
+        email_total_revenue: Math.round(emailTotalRevenue * 100) / 100,
+        email_pct_of_total: emailPct,
+        flow_vs_campaign_split: {
+            campaign_pct: emailTotalRevenue > 0
+                ? Math.round((campaignRevenue / emailTotalRevenue) * 10000) / 100
+                : 0,
+            flow_pct: emailTotalRevenue > 0
+                ? Math.round((flowRevenue / emailTotalRevenue) * 10000) / 100
+                : 0,
+        },
+        top_revenue_campaigns: topCampaigns,
+        top_revenue_flows: topFlows,
+        note: "Revenue attribution uses Klaviyo's send-date model. Actual overlap with Shopify revenue may vary.",
+    };
+}
+/**
+ * Orchestrate a complete DTC health dashboard.
+ * Uses cached results from sub-queries to minimize API calls.
+ */
+export async function computeDashboard(days) {
+    // Run Klaviyo queries in parallel (these hit cache if recent calls were made)
+    const [campaignRows, flowRows] = await Promise.all([
+        getCampaignReport(days),
+        getFlowReport(days),
+    ]);
+    // Sum email revenue
+    let campaignRevenue = 0;
+    const topCampaigns = [];
+    const campaignMap = new Map();
+    for (const row of campaignRows) {
+        const id = String(row.groupings.campaign_id ?? "");
+        const existing = campaignMap.get(id) ?? { revenue: 0, opens: 0, recipients: 0 };
+        existing.revenue += row.statistics.conversion_value ?? 0;
+        existing.opens += row.statistics.opens_unique ?? row.statistics.opens ?? 0;
+        existing.recipients += row.statistics.recipients ?? 0;
+        campaignMap.set(id, existing);
+        campaignRevenue += row.statistics.conversion_value ?? 0;
+    }
+    for (const [name, stats] of campaignMap.entries()) {
+        topCampaigns.push({
+            name,
+            revenue: Math.round(stats.revenue * 100) / 100,
+            open_rate: stats.recipients > 0
+                ? Math.round((stats.opens / stats.recipients) * 10000) / 10000
+                : 0,
+        });
+    }
+    topCampaigns.sort((a, b) => b.revenue - a.revenue);
+    let flowRevenue = 0;
+    const topFlows = [];
+    const flowMap = new Map();
+    for (const row of flowRows) {
+        const id = String(row.groupings.flow_id ?? "");
+        flowMap.set(id, (flowMap.get(id) ?? 0) + (row.statistics.conversion_value ?? 0));
+        flowRevenue += row.statistics.conversion_value ?? 0;
+    }
+    for (const [name, revenue] of flowMap.entries()) {
+        topFlows.push({ name, revenue: Math.round(revenue * 100) / 100 });
+    }
+    topFlows.sort((a, b) => b.revenue - a.revenue);
+    const emailRevenue = campaignRevenue + flowRevenue;
+    // Shopify sales
+    let shopifyRevenue = emailRevenue;
+    let orderCount = 0;
+    let aov = 0;
+    if (isShopifyConfigured()) {
+        try {
+            const sales = await getAggregatedSales(days);
+            shopifyRevenue = sales.netRevenue || emailRevenue;
+            orderCount = sales.orderCount;
+            aov = orderCount > 0 ? Math.round((shopifyRevenue / orderCount) * 100) / 100 : 0;
+        }
+        catch {
+            // Shopify unavailable
+        }
+    }
+    return {
+        period_days: days,
+        sales: {
+            revenue: Math.round(shopifyRevenue * 100) / 100,
+            orders: orderCount,
+            aov,
+        },
+        email: {
+            email_revenue: Math.round(emailRevenue * 100) / 100,
+            email_pct_of_total: shopifyRevenue > 0
+                ? Math.round((emailRevenue / shopifyRevenue) * 10000) / 100
+                : 0,
+            top_campaigns: topCampaigns.slice(0, 5),
+            top_flows: topFlows.slice(0, 5),
+        },
+        subscribers: {
+            total: 0, // Would require a separate API call — omit to save rate limits
+            list_count: 0,
+        },
+    };
+}
+//# sourceMappingURL=correlator.js.map

package/dist/cross-platform/correlator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlator.js","sourceRoot":"","sources":["../../src/cross-platform/correlator.ts"],"names":[],"mappings":"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"}

package/dist/cross-platform/tools.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerCrossPlatformTools(server: McpServer): void;