dtc-mcp 1.0.3 → 1.0.5

package/data/docs.json

@@ -1,6 +1,6 @@
 {
   "version": "v2026-05-25",
-  "generatedAt": "2026-05-25T02:57:04.731Z",
+  "generatedAt": "2026-05-25T22:02:22.894Z",
   "chunks": [
     {
       "id": "guide.output-discipline",
@@ -52,8 +52,8 @@
       "title": "Recipe: top N campaigns by revenue (replaces klaviyo_campaign_summary)",
       "platform": "guide",
       "category": "recipe",
-      "summary": "Replicates the old klaviyo_campaign_summary tool in <20 lines.",
-      "content": "```js\nconst metricId = await klaviyo.getConversionMetricId();\nconst report = await klaviyo.reporting.campaignValues({\n  data: { type: 'campaign-values-report', attributes: {\n    timeframe: { key: 'last_30_days' },\n    conversion_metric_id: metricId,\n    statistics: ['recipients', 'opens_unique', 'open_rate', 'clicks_unique', 'click_rate', 'conversion_value'],\n  }}\n});\n\nconst rows = (report.data.attributes.results || [])\n  .map(r => ({\n    campaign_id: r.groupings.campaign_id,\n    recipients: r.statistics.recipients,\n    open_rate: r.statistics.open_rate,\n    click_rate: r.statistics.click_rate,\n    revenue: r.statistics.conversion_value,\n  }))\n  .sort((a, b) => b.revenue - a.revenue)\n  .slice(0, 10);\n\n// Hydrate names (only for the top 10 — saves rate-limit budget)\nfor (const row of rows) {\n  const { data } = await klaviyo.campaigns.get(row.campaign_id, {\n    'fields[campaign]': 'name,send_time',\n  });\n  row.name = data.attributes.name;\n  row.send_time = data.attributes.send_time;\n}\nreturn rows;\n```",
+      "summary": "Replicates the old klaviyo_campaign_summary tool in <30 lines.",
+      "content": "Aggregates report rows up to the campaign level before ranking — see `klaviyo.reporting.campaignValues` for why the raw rows are per-message and must be summed first.\n\n```js\nconst metricId = await klaviyo.getConversionMetricId();\nconst report = await klaviyo.reporting.campaignValues({\n  data: { type: 'campaign-values-report', attributes: {\n    timeframe: { key: 'last_30_days' },\n    conversion_metric_id: metricId,\n    statistics: ['recipients', 'opens_unique', 'clicks_unique', 'conversion_value'],\n  }}\n});\n\n// Sum across all (campaign_id, message_id, channel) rows for each campaign_id.\nconst byCampaign = new Map();\nfor (const r of report.data.attributes.results || []) {\n  const id = r.groupings.campaign_id;\n  const slot = byCampaign.get(id) ?? { campaign_id: id, recipients: 0, opens_unique: 0, clicks_unique: 0, revenue: 0 };\n  slot.recipients += r.statistics.recipients || 0;\n  slot.opens_unique += r.statistics.opens_unique || 0;\n  slot.clicks_unique += r.statistics.clicks_unique || 0;\n  slot.revenue += r.statistics.conversion_value || 0;\n  byCampaign.set(id, slot);\n}\n\nconst rows = [...byCampaign.values()]\n  .map(c => ({ ...c,\n    open_rate: c.recipients ? c.opens_unique / c.recipients : 0,\n    click_rate: c.recipients ? c.clicks_unique / c.recipients : 0,\n  }))\n  .sort((a, b) => b.revenue - a.revenue)\n  .slice(0, 10);\n\n// Hydrate names (only for the top 10 — saves rate-limit budget)\nfor (const row of rows) {\n  const { data } = await klaviyo.campaigns.get(row.campaign_id, {\n    'fields[campaign]': 'name,send_time',\n  });\n  row.name = data.attributes.name;\n  row.send_time = data.attributes.send_time;\n}\nreturn rows;\n```",
       "tags": [
         "recipe",
         "campaigns",
@@ -61,6 +61,21 @@
         "top"
       ]
     },
+    {
+      "id": "guide.recipe.top-flows",
+      "title": "Recipe: top N flows by revenue",
+      "platform": "guide",
+      "category": "recipe",
+      "summary": "Rank live flows by 30-day attributed revenue. Aggregates per-message report rows up to flow level.",
+      "content": "Flow value reports return one row per (flow_id, flow_message_id, send_channel). A 5-message welcome flow shows up as 5 rows. To rank FLOWS (not individual messages within flows) you have to sum the per-message rows. Then optionally hydrate names + filter to live status.\n\n```js\nconst metricId = await klaviyo.getConversionMetricId();\nconst report = await klaviyo.reporting.flowValues({\n  data: { type: 'flow-values-report', attributes: {\n    timeframe: { key: 'last_30_days' },\n    conversion_metric_id: metricId,\n    statistics: ['recipients', 'opens_unique', 'clicks_unique', 'conversion_value'],\n  }}\n});\n\n// Sum across all rows for each flow_id.\nconst byFlow = new Map();\nfor (const r of report.data.attributes.results || []) {\n  const id = r.groupings.flow_id;\n  const slot = byFlow.get(id) ?? { flow_id: id, recipients: 0, opens_unique: 0, clicks_unique: 0, revenue: 0, messageCount: 0 };\n  slot.recipients += r.statistics.recipients || 0;\n  slot.opens_unique += r.statistics.opens_unique || 0;\n  slot.clicks_unique += r.statistics.clicks_unique || 0;\n  slot.revenue += r.statistics.conversion_value || 0;\n  slot.messageCount += 1;\n  byFlow.set(id, slot);\n}\n\nconst rows = [...byFlow.values()]\n  .map(f => ({ ...f,\n    open_rate: f.recipients ? f.opens_unique / f.recipients : 0,\n    click_rate: f.recipients ? f.clicks_unique / f.recipients : 0,\n  }))\n  .sort((a, b) => b.revenue - a.revenue)\n  .slice(0, 5);\n\n// Hydrate names + status + trigger_type. Filter to live if the user asked for it.\nfor (const row of rows) {\n  const { data } = await klaviyo.flows.get(row.flow_id, {\n    'fields[flow]': 'name,status,trigger_type',\n  });\n  row.name = data.attributes.name;\n  row.status = data.attributes.status;\n  row.trigger_type = data.attributes.trigger_type;\n}\nreturn rows;\n```",
+      "tags": [
+        "recipe",
+        "flows",
+        "summary",
+        "top",
+        "revenue"
+      ]
+    },
     {
       "id": "guide.shopify-not-configured",
       "title": "Klaviyo-only mode (no Shopify)",
@@ -80,7 +95,7 @@
       "platform": "guide",
       "category": "guide",
       "summary": "The sandbox keeps one context alive per MCP connection. Assign to globalThis to share data across execute_code calls. Beats Stainless's stateless Cloudflare-Workers model for iterative DTC analyses.",
-      "content": "## Stateful sandbox sessions\n\nThe sandbox keeps a **single context alive for the lifetime of your MCP connection**. Variables you assign to `globalThis` in one `execute_code` call are visible in every subsequent call within the same conversation. This is intentional and is one of the architectural differences from Stainless (which runs each call in a fresh Cloudflare Worker isolate — stateless).\n\nFor multi-step DTC analyses (a typical workflow: fetch campaigns → drill into a specific one → cross-reference Shopify orders), this means:\n- The first call fetches and caches expensive data into `globalThis`.\n- Subsequent calls reference those values directly without re-fetching.\n- The host's reporting cache STILL handles repeat API calls within the same session — statefulness compounds with it.\n\n### Sharing data: use globalThis\n\nBecause user code runs as a fresh script per call, top-level `const` / `let` declarations are **scoped to that call only** — they're NOT visible later. Use `globalThis` (or `globalThis.x = ...` shorthand) for anything you want to carry forward.\n\n```js\n// Call 1\nconst metricId = await klaviyo.getConversionMetricId();\nglobalThis.metricId = metricId;  // persisted\nconst topCampaigns = topN(\n  (await klaviyo.reporting.campaignValues({\n    data: { type: 'campaign-values-report', attributes: {\n      timeframe: { key: 'last_30_days' },\n      conversion_metric_id: metricId,\n      statistics: ['conversion_value', 'recipients']\n    }}\n  })).data.attributes.results,\n  5,\n  (r) => r.statistics.conversion_value\n);\nglobalThis.topCampaigns = topCampaigns;  // persisted\nreturn pick(topCampaigns, { groupings: { campaign_id: true }, statistics: { conversion_value: true } });\n```\n\n```js\n// Call 2 — no re-fetch needed\nconst topIds = globalThis.topCampaigns.map(c => c.groupings.campaign_id);\nconst details = await Promise.all(topIds.map(id =>\n  klaviyo.campaigns.get(id, { 'fields[campaign]': 'name,send_time' })\n));\nreturn details.map(d => ({ id: d.data.id, name: d.data.attributes.name }));\n```\n\n### Session reset (TTL + memory)\n\nThe context is recreated when any of the following happens:\n- The MCP connection closes (Claude Desktop is quit or the extension is disabled)\n- 30 minutes of idle time pass with no `execute_code` call (configurable via env)\n- Memory usage exceeds the per-isolate cap (256 MB)\n- The user manually reloads the extension\n\nWhen the context is recreated, the next call's response includes `sessionReset: true` and a `sessionResetNote`. If you see that, any globals you set previously are gone — re-declare what you need.\n\n```js\n// You can detect a reset by checking globalThis.\nif (typeof globalThis.cachedMetricId === 'undefined') {\n  globalThis.cachedMetricId = await klaviyo.getConversionMetricId();\n}\nconst metricId = globalThis.cachedMetricId;\n```\n\n### Why this beats Stainless's stateless model\n\nStainless's Cloudflare-Workers sandbox runs each `execute` in a fresh isolate. For iterative analyses they require re-fetching at every step, which inflates token cost AND duration. Our self-hosted sidecar trivially supports state because it owns the isolate lifecycle.",
+      "content": "## Stateful sandbox sessions\n\nThe sandbox keeps a **single context alive for the lifetime of your MCP connection**. Variables you assign to `globalThis` in one `execute_code` call are visible in every subsequent call within the same conversation. This is intentional and is one of the architectural differences from Stainless (which runs each call in a fresh Cloudflare Worker isolate — stateless).\n\nFor multi-step DTC analyses (a typical workflow: fetch campaigns → drill into a specific one → cross-reference Shopify orders), this means:\n- The first call fetches and caches expensive data into `globalThis`.\n- Subsequent calls reference those values directly without re-fetching.\n- The host's reporting cache STILL handles repeat API calls within the same session — statefulness compounds with it.\n\n### Discovering what's stashed: use globals()\n\nAt the start of any follow-up call, run `globals()` to see what data is already stashed from prior calls. The helper returns `{ name: summary }` for every user-added global (e.g. `{ topCampaigns: 'Array(5)', metricId: 'string(8 chars)' }`). This is the cheap way to avoid re-fetching: check what's there before fetching again.\n\n```js\n// Start of a follow-up call\nconst stashed = globals();\nif (stashed.topCampaigns) {\n  // reuse globalThis.topCampaigns — skip the re-fetch\n  return globalThis.topCampaigns;\n}\n```\n\n### Sharing data: use globalThis\n\nBecause user code runs as a fresh script per call, top-level `const` / `let` declarations are **scoped to that call only** — they're NOT visible later. Use `globalThis` (or `globalThis.x = ...` shorthand) for anything you want to carry forward.\n\n```js\n// Call 1\nconst metricId = await klaviyo.getConversionMetricId();\nglobalThis.metricId = metricId;  // persisted\nconst topCampaigns = topN(\n  (await klaviyo.reporting.campaignValues({\n    data: { type: 'campaign-values-report', attributes: {\n      timeframe: { key: 'last_30_days' },\n      conversion_metric_id: metricId,\n      statistics: ['conversion_value', 'recipients']\n    }}\n  })).data.attributes.results,\n  5,\n  (r) => r.statistics.conversion_value\n);\nglobalThis.topCampaigns = topCampaigns;  // persisted\nreturn pick(topCampaigns, { groupings: { campaign_id: true }, statistics: { conversion_value: true } });\n```\n\n```js\n// Call 2 — no re-fetch needed\nconst topIds = globalThis.topCampaigns.map(c => c.groupings.campaign_id);\nconst details = await Promise.all(topIds.map(id =>\n  klaviyo.campaigns.get(id, { 'fields[campaign]': 'name,send_time' })\n));\nreturn details.map(d => ({ id: d.data.id, name: d.data.attributes.name }));\n```\n\n### Session reset (TTL + memory)\n\nThe context is recreated when any of the following happens:\n- The MCP connection closes (Claude Desktop is quit or the extension is disabled)\n- 30 minutes of idle time pass with no `execute_code` call (configurable via env)\n- Memory usage exceeds the per-isolate cap (256 MB)\n- The user manually reloads the extension\n\nWhen the context is recreated, the next call's response includes `sessionReset: true` and a `sessionResetNote`. If you see that, any globals you set previously are gone — re-declare what you need.\n\n```js\n// You can detect a reset by checking globalThis.\nif (typeof globalThis.cachedMetricId === 'undefined') {\n  globalThis.cachedMetricId = await klaviyo.getConversionMetricId();\n}\nconst metricId = globalThis.cachedMetricId;\n```\n\n### Why this beats Stainless's stateless model\n\nStainless's Cloudflare-Workers sandbox runs each `execute` in a fresh isolate. For iterative analyses they require re-fetching at every step, which inflates token cost AND duration. Our self-hosted sidecar trivially supports state because it owns the isolate lifecycle.",
       "tags": [
         "stateful",
         "sessions",
@@ -108,7 +123,7 @@
       "platform": "klaviyo",
       "category": "method",
       "summary": "List campaigns (sugar for klaviyo.get('campaigns', ...)).",
-      "content": "## klaviyo.campaigns.list(params?)\n\nSee https://developers.klaviyo.com/en/reference/get_campaigns. Filter syntax required — at minimum a `filter` param scoping to a channel.\n\n```js\nconst { data } = await klaviyo.campaigns.list({\n  filter: 'equals(messages.channel,\"email\")',\n  sort: '-send_time',\n  'page[size]': '20',\n  'fields[campaign]': 'name,status,send_time',\n});\nreturn data.map(c => ({ id: c.id, ...c.attributes }));\n```",
+      "content": "## klaviyo.campaigns.list(params?)\n\nSee https://developers.klaviyo.com/en/reference/get_campaigns. Filter syntax required — at minimum a `filter` param scoping to a channel.\n\nValid `sort` values: `created_at`, `updated_at`, `scheduled_at`, `id`, `name` (prefix with `-` for descending). NOTE: `send_time` is a response field but is NOT a valid sort key — use `-scheduled_at` to get the most-recently-sent campaigns first.\n\n```js\nconst { data } = await klaviyo.campaigns.list({\n  filter: 'equals(messages.channel,\"email\")',\n  sort: '-scheduled_at',\n  'page[size]': '20',\n  'fields[campaign]': 'name,status,send_time,scheduled_at',\n});\nreturn data.map(c => ({ id: c.id, ...c.attributes }));\n```",
       "tags": [
         "klaviyo",
         "campaigns",
@@ -4258,7 +4273,7 @@
       "platform": "klaviyo",
       "category": "method",
       "summary": "Campaign reporting (revenue, opens, clicks). Cached 10 min.",
-      "content": "## klaviyo.reporting.campaignValues(body)\n\nWrapper for `POST /campaign-values-reports`. Reporting tier — rate limited at 1/s, 2/min. Results cached 10 minutes.\n\n```js\nconst metricId = await klaviyo.getConversionMetricId();\nconst report = await klaviyo.reporting.campaignValues({\n  data: { type: 'campaign-values-report', attributes: {\n    timeframe: { key: 'last_30_days' },\n    conversion_metric_id: metricId,\n    statistics: ['recipients', 'opens', 'open_rate', 'clicks', 'click_rate', 'conversion_value', 'conversions'],\n  }}\n});\nreturn report.data.attributes.results\n  .sort((a, b) => b.statistics.conversion_value - a.statistics.conversion_value)\n  .slice(0, 5);\n```",
+      "content": "## klaviyo.reporting.campaignValues(body)\n\nWrapper for `POST /campaign-values-reports`. Reporting tier — rate limited at 1/s, 2/min. Results cached 10 minutes.\n\n**Response grain (important).** Each row in `report.data.attributes.results` is keyed by `(campaign_id, campaign_message_id, send_channel)`, NOT by campaign. A campaign with multiple message variations (A/B tests, multi-channel sends) produces multiple rows. For campaign-level totals (revenue, recipients, conversions) you MUST sum the `statistics.*` fields across all rows sharing the same `campaign_id` before sorting. A naive `sort + slice` of raw rows ranks individual messages, not campaigns.\n\n```js\nconst metricId = await klaviyo.getConversionMetricId();\nconst report = await klaviyo.reporting.campaignValues({\n  data: { type: 'campaign-values-report', attributes: {\n    timeframe: { key: 'last_30_days' },\n    conversion_metric_id: metricId,\n    statistics: ['recipients', 'opens', 'open_rate', 'clicks', 'click_rate', 'conversion_value', 'conversions'],\n  }}\n});\n\n// Aggregate per campaign_id (sum revenue/recipients/etc., weighted-mean rates).\nconst byCampaign = new Map();\nfor (const row of report.data.attributes.results || []) {\n  const id = row.groupings.campaign_id;\n  const slot = byCampaign.get(id) ?? { campaign_id: id, revenue: 0, recipients: 0, opens: 0, clicks: 0 };\n  slot.revenue += row.statistics.conversion_value || 0;\n  slot.recipients += row.statistics.recipients || 0;\n  slot.opens += row.statistics.opens || 0;\n  slot.clicks += row.statistics.clicks || 0;\n  byCampaign.set(id, slot);\n}\nreturn [...byCampaign.values()]\n  .map(c => ({ ...c, open_rate: c.recipients ? c.opens / c.recipients : 0, click_rate: c.recipients ? c.clicks / c.recipients : 0 }))\n  .sort((a, b) => b.revenue - a.revenue)\n  .slice(0, 5);\n```",
       "tags": [
         "klaviyo",
         "reporting",
@@ -4272,7 +4287,7 @@
       "platform": "klaviyo",
       "category": "method",
       "summary": "Flow reporting (revenue, opens, clicks). Cached 10 min.",
-      "content": "## klaviyo.reporting.flowValues(body)\n\nSame shape as campaignValues but for flows. `POST /flow-values-reports`.\n\n```js\nconst metricId = await klaviyo.getConversionMetricId();\nconst report = await klaviyo.reporting.flowValues({\n  data: { type: 'flow-values-report', attributes: {\n    timeframe: { key: 'last_30_days' },\n    conversion_metric_id: metricId,\n    statistics: ['recipients', 'click_rate', 'conversion_rate', 'conversion_value'],\n  }}\n});\n```",
+      "content": "## klaviyo.reporting.flowValues(body)\n\nSame shape as campaignValues but for flows. `POST /flow-values-reports`. Reporting tier — rate limited at 1/s, 2/min. Results cached 10 minutes.\n\n**Response grain (important).** Each row in `report.data.attributes.results` is keyed by `(flow_id, flow_message_id, send_channel)`, NOT by flow. A typical welcome / abandoned-cart flow has 5-10 messages → 5-10 rows per flow. For flow-level totals (revenue, recipients) you MUST sum the `statistics.*` fields across all rows sharing the same `flow_id` before sorting. A naive `sort + slice` of raw rows ranks individual messages-within-flows, not flows.\n\n```js\nconst metricId = await klaviyo.getConversionMetricId();\nconst report = await klaviyo.reporting.flowValues({\n  data: { type: 'flow-values-report', attributes: {\n    timeframe: { key: 'last_30_days' },\n    conversion_metric_id: metricId,\n    statistics: ['recipients', 'opens_unique', 'click_rate', 'conversion_rate', 'conversion_value'],\n  }}\n});\n\n// Aggregate per flow_id (correct flow-level totals).\nconst byFlow = new Map();\nfor (const row of report.data.attributes.results || []) {\n  const id = row.groupings.flow_id;\n  const slot = byFlow.get(id) ?? { flow_id: id, revenue: 0, recipients: 0, opens_unique: 0 };\n  slot.revenue += row.statistics.conversion_value || 0;\n  slot.recipients += row.statistics.recipients || 0;\n  slot.opens_unique += row.statistics.opens_unique || 0;\n  byFlow.set(id, slot);\n}\nreturn [...byFlow.values()]\n  .map(f => ({ ...f, open_rate: f.recipients ? f.opens_unique / f.recipients : 0 }))\n  .sort((a, b) => b.revenue - a.revenue)\n  .slice(0, 5);\n```",
       "tags": [
         "klaviyo",
         "reporting",

package/dist/index.js

@@ -17,5 +17,5 @@ server.connect(transport).catch((err) => {
     console.error("[dtc-mcp] fatal: failed to connect:", err);
     process.exit(1);
 });
-console.error("[dtc-mcp] v1.0.3 ready");
+console.error("[dtc-mcp] v1.0.4 ready");
 //# sourceMappingURL=index.js.map

package/dist/sandbox/sandbox-helpers.js

@@ -94,5 +94,59 @@ globalThis.summarize = function summarize(arr, opts) {
   }
   return result;
 };
+
+/**
+ * globals() — introspect what's currently stashed on globalThis.
+ *
+ * Returns { name: summary } for every user-added global, filtering out the
+ * sandbox's built-in helpers and standard JS globals. Use at the start of a
+ * follow-up turn to see what data is already available from prior calls and
+ * avoid re-fetching anything that's already there.
+ *
+ *   // Call 1
+ *   globalThis.flowReport = await klaviyo.reporting.flowValues({...});
+ *
+ *   // Call 2 (next turn) — check what's stashed before re-fetching
+ *   const stashed = globals();
+ *   // → { flowReport: 'Object(2 keys)' }
+ *
+ * Implementation: captures the baseline of Object.keys(globalThis) at module
+ * load time via an IIFE closure. Anything added after bootstrap is "user
+ * state" and shows up in the listing.
+ */
+(function () {
+  const __baseline = new Set(Object.keys(globalThis));
+  globalThis.globals = function globals() {
+    const out = {};
+    for (const k of Object.keys(globalThis)) {
+      if (__baseline.has(k)) continue;
+      if (k === 'globals') continue;
+      if (k.startsWith('__')) continue;
+      let summary;
+      try {
+        const v = globalThis[k];
+        if (v === null || v === undefined) {
+          summary = String(v);
+        } else if (Array.isArray(v)) {
+          summary = 'Array(' + v.length + ')';
+        } else if (typeof v === 'object') {
+          summary = 'Object(' + Object.keys(v).length + ' keys)';
+        } else if (typeof v === 'string') {
+          summary = v.length > 40
+            ? 'string(' + v.length + ' chars)'
+            : JSON.stringify(v);
+        } else if (typeof v === 'function') {
+          summary = 'function';
+        } else {
+          summary = typeof v + ': ' + String(v);
+        }
+      } catch (_e) {
+        summary = '<unreadable>';
+      }
+      out[k] = summary;
+    }
+    return out;
+  };
+})();
 `.trim();
 //# sourceMappingURL=sandbox-helpers.js.map

package/dist/sandbox/sandbox-helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox-helpers.js","sourceRoot":"","sources":["../../src/sandbox/sandbox-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmFrC,CAAC,IAAI,EAAE,CAAC"}
+{"version":3,"file":"sandbox-helpers.js","sourceRoot":"","sources":["../../src/sandbox/sandbox-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyIrC,CAAC,IAAI,EAAE,CAAC"}

package/dist/server.js

@@ -5,7 +5,7 @@ import { registerReadDoc } from "./tools/read_doc.js";
 export function createServer() {
     const server = new McpServer({
         name: "dtc-mcp",
-        version: "1.0.3",
+        version: "1.0.4",
     });
     registerExecuteCode(server);
     registerSearchDocs(server);

package/dist/tools/execute_code.js

@@ -3,7 +3,7 @@ import { runSandbox } from "../sandbox/runner.js";
 import { resolveTimeout } from "../sandbox/timeout.js";
 import { log } from "../config.js";
 const codeShape = {
-    code: z.string().describe("TypeScript-like JavaScript to execute. Wrap top-level await calls naturally — the code runs in an async context. Return a value via `return ...` to receive it as the tool result. Globals available: `klaviyo`, `shopify`, `console`. No `fetch`/`process`/`require`/`import`. Add `// @timeout 2m` (max 5m) at the top to extend the default 30s wall-clock limit. Discover SDK methods via the `search_docs` tool."),
+    code: z.string().describe("TypeScript-like JavaScript to execute. Wrap top-level await calls naturally — the code runs in an async context. Return a value via `return ...` to receive it as the tool result. Globals available: `klaviyo`, `shopify`, `console`, plus helpers `pick`, `topN`, `summarize`, `globals`. No `fetch`/`process`/`require`/`import`. Add `// @timeout 2m` (max 5m) at the top to extend the default 30s wall-clock limit. Discover SDK methods via the `search_docs` tool."),
 };
 const description = `
 Execute JavaScript against the typed Klaviyo + Shopify SDKs in a stateful V8 sandbox.
@@ -12,11 +12,18 @@ The host applies rate limits, auth, and caching transparently. The sandbox keeps
 context alive per MCP connection — variables you assign to globalThis persist across
 calls, so iterative analyses don't re-fetch.
 
+STRONGLY RECOMMENDED for multi-turn investigations: stash any expensive fetch
+(reporting payloads, paginated lists, computed aggregates) on globalThis so
+follow-up turns reference the stashed data instead of re-fetching it. Re-running
+a 5,000-row report costs ~30k tokens; reading globalThis.report costs near zero.
+Call \`globals()\` at the start of any follow-up call to see what's already stashed.
+
 Available globals:
 - klaviyo: { get, post, paginate, campaigns, flows, lists, segments, profiles, events, metrics, reporting }
 - shopify: { gql, ql, timezone } — Shopify Admin GraphQL + ShopifyQL
 - console: { log, error, warn, info } — captured and returned as stdout
 - pick(value, schema) / topN(arr, n, by) / summarize(arr, opts) — output-discipline helpers
+- globals() — returns { name: summary } of everything currently stashed on globalThis
 - globalThis.* — assignments persist across calls within this MCP session
 
 Discovery: use read_doc({}) at session start to list every available SDK path, then

package/dist/tools/execute_code.js.map

@@ -1 +1 @@
-{"version":3,"file":"execute_code.js","sourceRoot":"","sources":["../../src/tools/execute_code.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAEnC,MAAM,SAAS,GAAG;IAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CACvB,uZAAuZ,CACxZ;CACF,CAAC;AAEF,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwCnB,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,UAAU,mBAAmB,CAAC,MAAiB;IACnD,MAAM,CAAC,IAAI,CACT,cAAc,EACd,WAAW,EACX,SAAS,EACT;QACE,KAAK,EAAE,0BAA0B;QACjC,YAAY,EAAE,KAAK;QACnB,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,KAAK;QACrB,aAAa,EAAE,IAAI;KACpB,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;QACjB,MAAM,SAAS,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;QACvC,GAAG,CAAC,OAAO,EAAE,cAAc,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;QAEjE,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;QAErD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CACzB;YACE,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;YACpE,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,GAAG,CAAC,MAAM,CAAC,YAAY;gBACrB,CAAC,CAAC;oBACE,YAAY,EAAE,IAAI;oBAClB,gBAAgB,EACd,8SAA8S;iBACjT;gBACH,CAAC,CAAC,EAAE,CAAC;SACR,EACD,IAAI,EACJ,CAAC,CACF,CAAC;QAEF,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;YACjC,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE;SACpB,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"execute_code.js","sourceRoot":"","sources":["../../src/tools/execute_code.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAEnC,MAAM,SAAS,GAAG;IAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CACvB,4cAA4c,CAC7c;CACF,CAAC;AAEF,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+CnB,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,UAAU,mBAAmB,CAAC,MAAiB;IACnD,MAAM,CAAC,IAAI,CACT,cAAc,EACd,WAAW,EACX,SAAS,EACT;QACE,KAAK,EAAE,0BAA0B;QACjC,YAAY,EAAE,KAAK;QACnB,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,KAAK;QACrB,aAAa,EAAE,IAAI;KACpB,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;QACjB,MAAM,SAAS,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;QACvC,GAAG,CAAC,OAAO,EAAE,cAAc,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;QAEjE,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;QAErD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CACzB;YACE,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;YACpE,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,GAAG,CAAC,MAAM,CAAC,YAAY;gBACrB,CAAC,CAAC;oBACE,YAAY,EAAE,IAAI;oBAClB,gBAAgB,EACd,8SAA8S;iBACjT;gBACH,CAAC,CAAC,EAAE,CAAC;SACR,EACD,IAAI,EACJ,CAAC,CACF,CAAC;QAEF,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;YACjC,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE;SACpB,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dtc-mcp",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Code-execution MCP server for Klaviyo + Shopify analytics. The LLM writes TypeScript against typed SDKs in a stateful V8 sandbox — three composable tools instead of dozens.",
   "type": "module",
   "bin": {