dtc-mcp 0.2.0 → 1.0.0

package/dist/sdk/klaviyo/host.js

@@ -0,0 +1,218 @@
+import { config, log } from "../../config.js";
+import { TTLCache, buildCacheKey } from "../../shared/cache.js";
+import { KlaviyoApiError } from "../../shared/errors.js";
+const BASE_URL = "https://a.klaviyo.com/api";
+const REPORTING_CACHE_TTL = 10 * 60 * 1000;
+const reportingCache = new TTLCache(REPORTING_CACHE_TTL);
+const metricIdCache = new TTLCache(Number.MAX_SAFE_INTEGER);
+// Klaviyo's per-endpoint tiers aren't surfaced uniformly in their docs;
+// the reporting POST endpoints are a strict 1/s + 2/min, while everything
+// else gets the much friendlier 10/s + 150/min.
+class RateLimiter {
+    burstPerSecond;
+    steadyPerMinute;
+    recent = [];
+    constructor(burstPerSecond, steadyPerMinute) {
+        this.burstPerSecond = burstPerSecond;
+        this.steadyPerMinute = steadyPerMinute;
+    }
+    async acquire() {
+        const now = Date.now();
+        this.recent = this.recent.filter((t) => now - t < 60_000);
+        if (this.recent.length >= this.steadyPerMinute) {
+            const wait = 60_000 - (now - this.recent[0]) + jitter();
+            await sleep(wait);
+        }
+        const last1s = this.recent.filter((t) => Date.now() - t < 1_000);
+        if (last1s.length >= this.burstPerSecond) {
+            const wait = 1_000 - (Date.now() - last1s[0]) + jitter();
+            await sleep(wait);
+        }
+        this.recent.push(Date.now());
+    }
+}
+const standardLimiter = new RateLimiter(10, 150);
+const reportingLimiter = new RateLimiter(1, 2);
+function limiterFor(tier) {
+    return tier === "reporting" ? reportingLimiter : standardLimiter;
+}
+function headers() {
+    return {
+        Authorization: `Klaviyo-API-Key ${config.klaviyoApiKey}`,
+        revision: config.klaviyoRevision,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+    };
+}
+async function handleResponse(res) {
+    if (res.status === 429) {
+        const ra = res.headers.get("Retry-After");
+        throw new KlaviyoApiError(429, `Rate limited${ra ? `. Retry after ${ra}s` : ""}`);
+    }
+    if (!res.ok) {
+        let msg = `HTTP ${res.status}`;
+        try {
+            const body = (await res.json());
+            if (body.errors?.[0]?.detail)
+                msg = body.errors[0].detail;
+        }
+        catch {
+            // ignore
+        }
+        throw new KlaviyoApiError(res.status, msg);
+    }
+    return res.json();
+}
+async function withRetry(fn, max = 3) {
+    let last;
+    for (let i = 0; i <= max; i++) {
+        try {
+            return await fn();
+        }
+        catch (e) {
+            last = e;
+            if (e instanceof KlaviyoApiError && e.status === 429 && i < max) {
+                await sleep(Math.pow(2, i) * 1000 + jitter());
+                continue;
+            }
+            throw e;
+        }
+    }
+    throw last;
+}
+/**
+ * GET a Klaviyo endpoint. Returns the raw JSON:API response.
+ * Bracket params (`page[size]`, `fields[campaign]`) are NOT percent-encoded
+ * because Klaviyo's parser doesn't handle the encoded form.
+ */
+export async function klaviyoGet(path, options = {}) {
+    const tier = options.tier ?? "standard";
+    const params = options.params ?? {};
+    return withRetry(async () => {
+        await limiterFor(tier).acquire();
+        let url = `${BASE_URL}/${path.replace(/^\//, "")}`;
+        if (Object.keys(params).length) {
+            url +=
+                "?" +
+                    Object.entries(params)
+                        .map(([k, v]) => `${k}=${encodeURIComponent(v)}`)
+                        .join("&");
+        }
+        log("debug", "Klaviyo GET", { url });
+        return handleResponse(await fetch(url, { headers: headers() }));
+    });
+}
+/**
+ * POST to a Klaviyo endpoint. Used primarily for reporting endpoints.
+ * Reporting POSTs are cached with a 10-minute TTL — without this, the LLM
+ * will re-fetch the slowest endpoints on every sandbox call.
+ */
+export async function klaviyoPost(path, body, options = {}) {
+    const tier = options.tier ?? "standard";
+    if (tier === "reporting") {
+        const key = buildCacheKey(path, body);
+        const cached = reportingCache.get(key);
+        if (cached !== undefined) {
+            log("debug", "Klaviyo POST cache hit", { path });
+            return cached;
+        }
+    }
+    const result = await withRetry(async () => {
+        await limiterFor(tier).acquire();
+        const url = `${BASE_URL}/${path.replace(/^\//, "")}`;
+        log("debug", "Klaviyo POST", { url });
+        const res = await fetch(url, {
+            method: "POST",
+            headers: headers(),
+            body: JSON.stringify(body),
+        });
+        return handleResponse(res);
+    });
+    if (tier === "reporting") {
+        reportingCache.set(buildCacheKey(path, body), result);
+    }
+    return result;
+}
+/**
+ * Auto-paginate a GET endpoint. Useful for iterating all metrics, lists, etc.
+ * Capped at `maxPages` (default 5 → 500 items at default page size) so a runaway
+ * loop in the sandbox can't hammer the API.
+ */
+export async function klaviyoPaginate(path, options = {}) {
+    const maxPages = options.maxPages ?? 5;
+    const items = [];
+    let params = { ...(options.params ?? {}) };
+    let pages = 0;
+    while (pages < maxPages) {
+        const raw = (await klaviyoGet(path, { params, tier: options.tier }));
+        items.push(...(raw.data ?? []));
+        pages++;
+        const nextUrl = raw.links?.next;
+        if (!nextUrl)
+            return { items, truncated: false };
+        try {
+            const cursor = new URL(nextUrl).searchParams.get("page[cursor]");
+            if (!cursor)
+                return { items, truncated: false };
+            params = { ...(options.params ?? {}), "page[cursor]": cursor };
+        }
+        catch {
+            return { items, truncated: false };
+        }
+    }
+    return { items, truncated: true };
+}
+/**
+ * Discover the "Placed Order" conversion metric ID required by reporting endpoints.
+ * Cached for server lifetime — never changes per-store.
+ *
+ * The 2026-01-15 revision doesn't allow filtering metrics by name, so we paginate
+ * and match client-side. Exact match first, then fuzzy fallback.
+ */
+export async function getConversionMetricId() {
+    if (config.klaviyoConversionMetricId) {
+        metricIdCache.set("placed_order", config.klaviyoConversionMetricId);
+        return config.klaviyoConversionMetricId;
+    }
+    const cached = metricIdCache.get("placed_order");
+    if (cached)
+        return cached;
+    const { items } = await klaviyoPaginate("metrics", {
+        params: { "fields[metric]": "name" },
+    });
+    const exactNames = ["Placed Order", "Order Placed", "Shopify Placed Order"];
+    for (const wanted of exactNames) {
+        const m = items.find((item) => String(item.attributes.name ?? "").toLowerCase() ===
+            wanted.toLowerCase());
+        if (m) {
+            metricIdCache.set("placed_order", m.id);
+            log("info", "Conversion metric discovered (exact)", {
+                name: m.attributes.name,
+                id: m.id,
+            });
+            return m.id;
+        }
+    }
+    const fuzzy = items.find((item) => {
+        const n = String(item.attributes.name ?? "").toLowerCase();
+        if (n.includes("refund") || n.includes("cancel"))
+            return false;
+        return (n.includes("placed") && n.includes("order")) || n.includes("purchase");
+    });
+    if (fuzzy) {
+        metricIdCache.set("placed_order", fuzzy.id);
+        log("info", "Conversion metric discovered (fuzzy)", {
+            name: fuzzy.attributes.name,
+            id: fuzzy.id,
+        });
+        return fuzzy.id;
+    }
+    throw new KlaviyoApiError(500, 'Could not find "Placed Order" metric. Set KLAVIYO_CONVERSION_METRIC_ID to override.');
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+function jitter() {
+    return Math.floor(Math.random() * 200);
+}
+//# sourceMappingURL=host.js.map

package/dist/sdk/klaviyo/host.js.map

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

package/dist/sdk/shopify/host.d.ts

@@ -0,0 +1,23 @@
+export interface ShopifyGqlOptions {
+    variables?: Record<string, unknown>;
+    estimatedCost?: number;
+}
+/**
+ * Run a GraphQL query against Shopify Admin API. Cost-budget aware: waits
+ * until enough capacity restores before sending. Auto-retries once on THROTTLED.
+ */
+export declare function shopifyGql<T = unknown>(query: string, options?: ShopifyGqlOptions): Promise<T>;
+export interface ShopifyQLTable {
+    columns: Array<{
+        name: string;
+        dataType: string;
+        displayName: string;
+    }>;
+    rows: Record<string, string>[];
+}
+/**
+ * Run a ShopifyQL query. Results cached 5 minutes — repeat queries from the
+ * LLM (common when it's iterating an analysis) skip the API round-trip.
+ */
+export declare function shopifyQL(ql: string): Promise<ShopifyQLTable>;
+export declare function shopifyTimezone(): Promise<string>;

package/dist/sdk/shopify/host.js

@@ -0,0 +1,175 @@
+import { config, log } from "../../config.js";
+import { ShopifyApiError } from "../../shared/errors.js";
+import { TTLCache } from "../../shared/cache.js";
+const qlCache = new TTLCache(5 * 60 * 1000);
+// ---- Token Manager: dual-mode auth (Client Credentials / legacy) ----
+//
+// Client Credentials Grant: exchange client_id/secret for a short-lived access
+// token. We cache with a 60s buffer before expiry to avoid mid-flight refresh races.
+// Legacy: a static `shpat_...` token, passed through.
+class TokenManager {
+    accessToken = null;
+    expiresAt = 0;
+    async get() {
+        if (config.shopifyAuthMode === "legacy") {
+            return config.shopifyAccessToken;
+        }
+        if (this.accessToken && Date.now() < this.expiresAt - 60_000) {
+            return this.accessToken;
+        }
+        return this.refresh();
+    }
+    async refresh() {
+        log("info", "Acquiring Shopify access token (Client Credentials)");
+        const url = `https://${config.shopifyStore}/admin/oauth/access_token`;
+        const body = new URLSearchParams({
+            grant_type: "client_credentials",
+            client_id: config.shopifyClientId,
+            client_secret: config.shopifyClientSecret,
+        });
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: body.toString(),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new ShopifyApiError(`Token request failed (${res.status}): ${text}`);
+        }
+        const data = (await res.json());
+        this.accessToken = data.access_token;
+        this.expiresAt = Date.now() + data.expires_in * 1000;
+        log("info", "Shopify token acquired", {
+            expiresIn: `${Math.round(data.expires_in / 3600)}h`,
+        });
+        return this.accessToken;
+    }
+}
+const tokenManager = new TokenManager();
+// ---- Cost-based throttle (Shopify GraphQL cost budget) ----
+//
+// Shopify returns `extensions.cost.throttleStatus.currentlyAvailable` on every
+// GraphQL response. We mirror their bucket (1000 capacity, 50/s restore) and
+// wait when a query would overdraw it. Misjudging this = hard throttle errors,
+// so we keep the original implementation's tuning.
+class CostTracker {
+    available = 1000;
+    lastUpdated = Date.now();
+    restoreRate = 50;
+    async wait(estimatedCost) {
+        this.restore();
+        if (this.available >= estimatedCost)
+            return;
+        const deficit = estimatedCost - this.available;
+        const wait = (deficit / this.restoreRate) * 1000 + 100;
+        log("debug", `Shopify wait ${Math.round(wait)}ms for ${deficit} cost`);
+        await new Promise((r) => setTimeout(r, wait));
+        this.restore();
+    }
+    update(ext) {
+        const v = ext?.cost?.throttleStatus?.currentlyAvailable;
+        if (v !== undefined) {
+            this.available = v;
+            this.lastUpdated = Date.now();
+        }
+    }
+    restore() {
+        const elapsed = (Date.now() - this.lastUpdated) / 1000;
+        this.available = Math.min(1000, this.available + elapsed * this.restoreRate);
+        this.lastUpdated = Date.now();
+    }
+}
+const costTracker = new CostTracker();
+function endpoint() {
+    return `https://${config.shopifyStore}/admin/api/${config.shopifyApiVersion}/graphql.json`;
+}
+async function gqlHeaders() {
+    return {
+        "Content-Type": "application/json",
+        "X-Shopify-Access-Token": await tokenManager.get(),
+    };
+}
+/**
+ * Run a GraphQL query against Shopify Admin API. Cost-budget aware: waits
+ * until enough capacity restores before sending. Auto-retries once on THROTTLED.
+ */
+export async function shopifyGql(query, options = {}) {
+    const cost = options.estimatedCost ?? 10;
+    await costTracker.wait(cost);
+    let lastErr;
+    for (let attempt = 0; attempt <= 3; attempt++) {
+        try {
+            const res = await fetch(endpoint(), {
+                method: "POST",
+                headers: await gqlHeaders(),
+                body: JSON.stringify({ query, variables: options.variables }),
+            });
+            if (res.status === 429) {
+                const ra = res.headers.get("Retry-After");
+                await new Promise((r) => setTimeout(r, ra ? parseInt(ra) * 1000 : 2000));
+                continue;
+            }
+            if (!res.ok) {
+                throw new ShopifyApiError(`HTTP ${res.status}: ${res.statusText}`);
+            }
+            const json = (await res.json());
+            costTracker.update(json.extensions);
+            if (json.errors?.length) {
+                const throttled = json.errors.find((e) => e.extensions?.code === "THROTTLED");
+                if (throttled && attempt < 3) {
+                    await new Promise((r) => setTimeout(r, 2000));
+                    continue;
+                }
+                throw new ShopifyApiError(json.errors.map((e) => e.message).join("; "));
+            }
+            if (!json.data) {
+                throw new ShopifyApiError("No data in GraphQL response");
+            }
+            return json.data;
+        }
+        catch (e) {
+            lastErr = e;
+            if (attempt < 3) {
+                await new Promise((r) => setTimeout(r, Math.pow(2, attempt) * 1000));
+            }
+        }
+    }
+    throw lastErr;
+}
+/**
+ * Run a ShopifyQL query. Results cached 5 minutes — repeat queries from the
+ * LLM (common when it's iterating an analysis) skip the API round-trip.
+ */
+export async function shopifyQL(ql) {
+    const key = `ql:${ql}`;
+    const cached = qlCache.get(key);
+    if (cached)
+        return cached;
+    const data = await shopifyGql(`query ShopifyQL($q: String!) {
+      shopifyqlQuery(query: $q) {
+        tableData { columns { name dataType displayName } rows }
+        parseErrors
+      }
+    }`, { variables: { q: ql }, estimatedCost: 5 });
+    if (data.shopifyqlQuery.parseErrors?.length) {
+        throw new ShopifyApiError(`ShopifyQL parse error: ${data.shopifyqlQuery.parseErrors.join(", ")}`);
+    }
+    if (!data.shopifyqlQuery.tableData) {
+        throw new ShopifyApiError("No table data");
+    }
+    const result = {
+        columns: data.shopifyqlQuery.tableData.columns,
+        rows: data.shopifyqlQuery.tableData.rows,
+    };
+    qlCache.set(key, result);
+    return result;
+}
+let tzCache = null;
+export async function shopifyTimezone() {
+    if (tzCache)
+        return tzCache;
+    const data = await shopifyGql(`{ shop { ianaTimezone } }`, { estimatedCost: 1 });
+    tzCache = data.shop.ianaTimezone;
+    return tzCache;
+}
+//# sourceMappingURL=host.js.map

package/dist/sdk/shopify/host.js.map

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

package/dist/server.js

@@ -1,15 +1,15 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { registerKlaviyoTools } from "./platforms/klaviyo/tools.js";
-import { registerShopifyTools } from "./platforms/shopify/tools.js";
-import { registerCrossPlatformTools } from "./cross-platform/tools.js";
+import { registerExecuteCode } from "./tools/execute_code.js";
+import { registerSearchDocs } from "./tools/search_docs.js";
+import { registerReadDoc } from "./tools/read_doc.js";
 export function createServer() {
     const server = new McpServer({
         name: "dtc-mcp",
-        version: "0.2.0",
+        version: "1.0.0",
     });
-    registerKlaviyoTools(server);
-    registerShopifyTools(server);
-    registerCrossPlatformTools(server);
+    registerExecuteCode(server);
+    registerSearchDocs(server);
+    registerReadDoc(server);
     return server;
 }
 //# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AAEvE,MAAM,UAAU,YAAY;IAC1B,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,0BAA0B,CAAC,MAAM,CAAC,CAAC;IAEnC,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,MAAM,UAAU,YAAY;IAC1B,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5B,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,eAAe,CAAC,MAAM,CAAC,CAAC;IAExB,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/shared/errors.d.ts

@@ -1,4 +1,3 @@
-import type { ToolResponse } from "./types.js";
 export declare class KlaviyoApiError extends Error {
     status: number;
     constructor(status: number, message: string);
@@ -10,16 +9,3 @@ export declare class ShopifyApiError extends Error {
 export declare class ConfigError extends Error {
     constructor(message: string);
 }
-/**
- * Format any error into an MCP tool error response.
- * All errors are actionable — they include what the user needs to do.
- */
-export declare function formatError(error: unknown): ToolResponse;
-/**
- * Return a "not configured" error for Shopify tools when credentials are missing.
- */
-export declare function shopifyNotConfigured(): ToolResponse;
-/**
- * Create a successful tool response from a JSON-serializable value.
- */
-export declare function toolResult(data: unknown): ToolResponse;

package/dist/shared/errors.js

@@ -20,77 +20,4 @@ export class ConfigError extends Error {
         this.name = "ConfigError";
     }
 }
-/**
- * Format any error into an MCP tool error response.
- * All errors are actionable — they include what the user needs to do.
- */
-export function formatError(error) {
-    if (error instanceof KlaviyoApiError) {
-        let advice = "";
-        if (error.status === 401) {
-            advice =
-                " Check that KLAVIYO_API_KEY is a valid private key (starts with pk_).";
-        }
-        else if (error.status === 429) {
-            advice = " Rate limited. Try again in a few seconds.";
-        }
-        else if (error.status === 403) {
-            advice =
-                " Your API key may not have the required scopes. Check Klaviyo API key permissions.";
-        }
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Klaviyo API Error (${error.status}): ${error.message}${advice}`,
-                },
-            ],
-            isError: true,
-        };
-    }
-    if (error instanceof ShopifyApiError) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Shopify API Error: ${error.message}`,
-                },
-            ],
-            isError: true,
-        };
-    }
-    if (error instanceof ConfigError) {
-        return {
-            content: [{ type: "text", text: error.message }],
-            isError: true,
-        };
-    }
-    const msg = error instanceof Error ? error.message : String(error);
-    return {
-        content: [{ type: "text", text: `Error: ${msg}` }],
-        isError: true,
-    };
-}
-/**
- * Return a "not configured" error for Shopify tools when credentials are missing.
- */
-export function shopifyNotConfigured() {
-    return {
-        content: [
-            {
-                type: "text",
-                text: "Shopify not configured. Set SHOPIFY_STORE + SHOPIFY_CLIENT_ID + SHOPIFY_CLIENT_SECRET (Dev Dashboard app), or SHOPIFY_STORE + SHOPIFY_ACCESS_TOKEN (legacy app).",
-            },
-        ],
-        isError: true,
-    };
-}
-/**
- * Create a successful tool response from a JSON-serializable value.
- */
-export function toolResult(data) {
-    return {
-        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
-    };
-}
 //# sourceMappingURL=errors.js.map

package/dist/shared/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAE/B;IADT,YACS,MAAc,EACrB,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHR,WAAM,GAAN,MAAM,CAAQ;QAIrB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAG/B;IAFT,YACE,OAAe,EACR,UAAoC;QAE3C,KAAK,CAAC,OAAO,CAAC,CAAC;QAFR,eAAU,GAAV,UAAU,CAA0B;QAG3C,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,YAAY,eAAe,EAAE,CAAC;QACrC,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACzB,MAAM;gBACJ,uEAAuE,CAAC;QAC5E,CAAC;aAAM,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAChC,MAAM,GAAG,4CAA4C,CAAC;QACxD,CAAC;aAAM,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAChC,MAAM;gBACJ,oFAAoF,CAAC;QACzF,CAAC;QACD,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,sBAAsB,KAAK,CAAC,MAAM,MAAM,KAAK,CAAC,OAAO,GAAG,MAAM,EAAE;iBACvE;aACF;YACD,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,YAAY,eAAe,EAAE,CAAC;QACrC,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,sBAAsB,KAAK,CAAC,OAAO,EAAE;iBAC5C;aACF;YACD,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;QACjC,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;YAChD,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACnE,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,EAAE,EAAE,CAAC;QAClD,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,kKAAkK;aACzK;SACF;QACD,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;KACjE,CAAC;AACJ,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAE/B;IADT,YACS,MAAc,EACrB,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHR,WAAM,GAAN,MAAM,CAAQ;QAIrB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAG/B;IAFT,YACE,OAAe,EACR,UAAoC;QAE3C,KAAK,CAAC,OAAO,CAAC,CAAC;QAFR,eAAU,GAAV,UAAU,CAA0B;QAG3C,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF"}

package/dist/{platforms/klaviyo/tools.d.ts → tools/execute_code.d.ts}

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

package/dist/tools/execute_code.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+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."),
+};
+const description = `
+Execute JavaScript against the typed Klaviyo + Shopify SDKs in a stateful V8 sandbox.
+
+The host applies rate limits, auth, and caching transparently. The sandbox keeps one
+context alive per MCP connection — variables you assign to globalThis persist across
+calls, so iterative analyses don't re-fetch.
+
+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
+- globalThis.* — assignments persist across calls within this MCP session
+
+Discovery: use read_doc({}) at session start to list every available SDK path, then
+read_doc({ path }) for any chunk's signature and example. Use search_docs for
+intent-based queries when the path is not known.
+
+The host caps return values at ~100 KB; oversized returns are replaced with a
+truncation envelope. Use pick/topN/summarize to stay under the cap.
+
+Example (top 5 campaigns by revenue last 30d):
+  const metricId = await klaviyo.getConversionMetricId();
+  const report = await klaviyo.reporting.campaignValues({
+    data: { type: "campaign-values-report", attributes: {
+      timeframe: { key: "last_30_days" },
+      conversion_metric_id: metricId,
+      statistics: ["recipients", "open_rate", "click_rate", "conversion_value"],
+    }}
+  });
+  return topN(report.data.attributes.results, 5, (r) => r.statistics.conversion_value);
+`.trim();
+export function registerExecuteCode(server) {
+    server.tool("execute_code", description, codeShape, {
+        title: "Execute code (sandboxed)",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    }, async ({ code }) => {
+        const timeoutMs = resolveTimeout(code);
+        log("debug", "execute_code", { length: code.length, timeoutMs });
+        const result = await runSandbox(code, { timeoutMs });
+        const text = JSON.stringify({
+            ok: result.ok,
+            ...(result.ok ? { result: result.result } : { error: result.error }),
+            stdout: result.stdout,
+            durationMs: result.durationMs,
+            sandbox: result.sandbox,
+            ...(result.sessionReset
+                ? {
+                    sessionReset: true,
+                    sessionResetNote: "This is the first execute_code call in this MCP session (or the sandbox was idle >30 min). The sandbox context is FRESH — there is no prior globalThis state to recover. From this call forward, anything you assign to globalThis WILL persist into the next execute_code call. No fallback fetches needed.",
+                }
+                : {}),
+        }, null, 2);
+        return {
+            content: [{ type: "text", text }],
+            isError: !result.ok,
+        };
+    });
+}
+//# sourceMappingURL=execute_code.js.map