mcp-meta-ads-incrementality 0.2.0

package/dist/lib/meta-client.js

@@ -0,0 +1,129 @@
+/* ------------------------------------------------------------------------- */
+/* Helpers                                                                   */
+/* ------------------------------------------------------------------------- */
+/**
+ * Normalize a Meta ad account id into the `act_<numeric>` form Meta requires.
+ * Accepts strings or numbers, with or without the `act_` prefix.
+ */
+export function normalizeAccountId(input) {
+    if (input == null) {
+        throw new Error('accountId is required');
+    }
+    const s = typeof input === 'number' ? String(input) : input;
+    if (s === '') {
+        throw new Error('accountId is required');
+    }
+    if (s.startsWith('act_')) {
+        const rest = s.slice(4);
+        if (!/^\d+$/.test(rest)) {
+            throw new Error(`accountId must be numeric after the act_ prefix, got "${s}"`);
+        }
+        return s;
+    }
+    if (!/^\d+$/.test(s)) {
+        throw new Error(`accountId must be numeric or act_-prefixed, got "${s}"`);
+    }
+    return `act_${s}`;
+}
+function fieldsForLevel(level) {
+    const base = ['date_start', 'date_stop', 'spend', 'actions', 'action_values'];
+    switch (level) {
+        case 'account':
+            return base;
+        case 'campaign':
+            return [...base, 'campaign_id', 'campaign_name'];
+        case 'adset':
+            return [...base, 'campaign_id', 'campaign_name', 'adset_id', 'adset_name'];
+        case 'ad':
+            return [
+                ...base,
+                'campaign_id',
+                'campaign_name',
+                'adset_id',
+                'adset_name',
+                'ad_id',
+                'ad_name',
+            ];
+    }
+}
+/* ------------------------------------------------------------------------- */
+/* MetaInsightsClient                                                         */
+/* ------------------------------------------------------------------------- */
+export class MetaInsightsClient {
+    sdk;
+    constructor(sdk, accessToken) {
+        this.sdk = sdk;
+        if (!accessToken) {
+            throw new Error('accessToken is required');
+        }
+        sdk.init(accessToken);
+    }
+    async getInsights(input) {
+        const accountId = normalizeAccountId(input.accountId);
+        const account = this.sdk.createAdAccount(accountId);
+        const fields = fieldsForLevel(input.level);
+        const params = {
+            level: input.level,
+            time_range: { since: input.dateRange.since, until: input.dateRange.until },
+            action_attribution_windows: [...input.attributionWindows],
+            use_unified_attribution_setting: true,
+        };
+        if (input.breakdowns && input.breakdowns.length > 0) {
+            params.breakdowns = [...input.breakdowns];
+        }
+        const filtering = [];
+        if (input.campaignId) {
+            filtering.push({ field: 'campaign.id', operator: 'EQUAL', value: input.campaignId });
+        }
+        if (input.adsetId) {
+            filtering.push({ field: 'adset.id', operator: 'EQUAL', value: input.adsetId });
+        }
+        if (filtering.length > 0) {
+            params.filtering = filtering;
+        }
+        const cursor = await account.getInsights(fields, params);
+        const rows = [];
+        let page = cursor;
+        while (page !== null) {
+            for (const item of page) {
+                rows.push(item._data ?? item);
+            }
+            if (page.hasNext()) {
+                await page.next();
+                // Cursor mutates in place — same reference, new page contents.
+            }
+            else {
+                page = null;
+            }
+        }
+        return rows;
+    }
+}
+/* ------------------------------------------------------------------------- */
+/* Default SDK adapter — wraps facebook-nodejs-business-sdk                   */
+/* ------------------------------------------------------------------------- */
+/**
+ * Create the production `MetaSdkLike` adapter that delegates to the real
+ * `facebook-nodejs-business-sdk`. Imported lazily so unit tests that inject
+ * fakes never have to load the SDK.
+ */
+export async function createDefaultMetaSdk() {
+    const sdkModule = await import('facebook-nodejs-business-sdk');
+    return {
+        init(token) {
+            sdkModule.FacebookAdsApi.init(token);
+        },
+        createAdAccount(accountId) {
+            const account = new sdkModule.AdAccount(accountId);
+            return {
+                async getInsights(fields, params) {
+                    // SDK returns Cursor | Promise<Cursor>; await normalizes both.
+                    // Type cast bridges the SDK's loose Record<string, any> items to our SdkCursor shape.
+                    const cursor = await account.getInsights(fields, params);
+                    return cursor;
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=meta-client.js.map

package/dist/lib/meta-client.js.map

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

package/dist/platform.d.ts

@@ -0,0 +1,5 @@
+export declare const configDir: string;
+export declare const credentialsFilePath: string;
+export declare function openBrowser(url: string): Promise<void>;
+export declare function findFreeLoopbackPort(): Promise<number>;
+//# sourceMappingURL=platform.d.ts.map

package/dist/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,SAAS,QAAe,CAAC;AACtC,eAAO,MAAM,mBAAmB,QAA8C,CAAC;AAE/E,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5D;AAKD,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAS5D"}

package/dist/platform.js

@@ -0,0 +1,34 @@
+// ============================================
+// CROSS-PLATFORM DISPATCH HELPERS
+// ============================================
+import envPaths from "env-paths";
+import openModule from "open";
+import { createServer } from "net";
+import path from "path";
+const paths = envPaths("mcp-meta-ads", { suffix: "nodejs" });
+export const configDir = paths.config;
+export const credentialsFilePath = path.join(paths.config, "credentials.json");
+export async function openBrowser(url) {
+    await openModule(url);
+}
+const LOOPBACK_PORT_RANGE_START = 8085;
+const LOOPBACK_PORT_RANGE_END = 8199;
+export async function findFreeLoopbackPort() {
+    for (let port = LOOPBACK_PORT_RANGE_START; port <= LOOPBACK_PORT_RANGE_END; port++) {
+        if (await isPortFree(port)) {
+            return port;
+        }
+    }
+    throw new Error(`No free port found in range ${LOOPBACK_PORT_RANGE_START}-${LOOPBACK_PORT_RANGE_END}.`);
+}
+function isPortFree(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", () => resolve(false));
+        server.once("listening", () => {
+            server.close(() => resolve(true));
+        });
+        server.listen(port, "127.0.0.1");
+    });
+}
+//# sourceMappingURL=platform.js.map

package/dist/platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,kCAAkC;AAClC,+CAA+C;AAE/C,OAAO,QAAQ,MAAM,WAAW,CAAC;AACjC,OAAO,UAAU,MAAM,MAAM,CAAC;AAC9B,OAAO,EAAE,YAAY,EAAE,MAAM,KAAK,CAAC;AAEnC,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,MAAM,KAAK,GAAG,QAAQ,CAAC,cAAc,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;AAE7D,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC;AACtC,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;AAE/E,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAW;IAC3C,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC;AAED,MAAM,yBAAyB,GAAG,IAAI,CAAC;AACvC,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAErC,MAAM,CAAC,KAAK,UAAU,oBAAoB;IACxC,KAAK,IAAI,IAAI,GAAG,yBAAyB,EAAE,IAAI,IAAI,uBAAuB,EAAE,IAAI,EAAE,EAAE,CAAC;QACnF,IAAI,MAAM,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CACb,+BAA+B,yBAAyB,IAAI,uBAAuB,GAAG,CACvF,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QAC3C,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,EAAE;YAC5B,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/tools/insights-incrementality.d.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import { type AttributionWindow } from '../lib/attribution.js';
+import { type ExtractedConversion, type MetaInsightsRow } from '../lib/insights.js';
+import type { GetInsightsParams, InsightsLevel } from '../lib/meta-client.js';
+export declare const insightsIncrementalityInputSchema: z.ZodObject<{
+    ad_account_id: z.ZodString;
+    date_range: z.ZodObject<{
+        since: z.ZodString;
+        until: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        since: string;
+        until: string;
+    }, {
+        since: string;
+        until: string;
+    }>;
+    conversion_event_name: z.ZodString;
+    attribution_windows: z.ZodEffects<z.ZodOptional<z.ZodArray<z.ZodEnum<["incrementality", "1d_click", "7d_click", "28d_click", "1d_view", "1d_ev", "dda", "skan_view", "skan_click"]>, "many">>, ("incrementality" | "1d_click" | "7d_click" | "28d_click" | "1d_view" | "1d_ev" | "dda" | "skan_view" | "skan_click")[], ("incrementality" | "1d_click" | "7d_click" | "28d_click" | "1d_view" | "1d_ev" | "dda" | "skan_view" | "skan_click")[] | undefined>;
+    level: z.ZodDefault<z.ZodOptional<z.ZodEnum<["account", "campaign", "adset", "ad"]>>>;
+    campaign_id: z.ZodOptional<z.ZodString>;
+    adset_id: z.ZodOptional<z.ZodString>;
+    breakdowns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    level: "account" | "campaign" | "adset" | "ad";
+    ad_account_id: string;
+    date_range: {
+        since: string;
+        until: string;
+    };
+    conversion_event_name: string;
+    attribution_windows: ("incrementality" | "1d_click" | "7d_click" | "28d_click" | "1d_view" | "1d_ev" | "dda" | "skan_view" | "skan_click")[];
+    campaign_id?: string | undefined;
+    adset_id?: string | undefined;
+    breakdowns?: string[] | undefined;
+}, {
+    ad_account_id: string;
+    date_range: {
+        since: string;
+        until: string;
+    };
+    conversion_event_name: string;
+    campaign_id?: string | undefined;
+    adset_id?: string | undefined;
+    level?: "account" | "campaign" | "adset" | "ad" | undefined;
+    breakdowns?: string[] | undefined;
+    attribution_windows?: ("incrementality" | "1d_click" | "7d_click" | "28d_click" | "1d_view" | "1d_ev" | "dda" | "skan_view" | "skan_click")[] | undefined;
+}>;
+export type InsightsIncrementalityInput = z.infer<typeof insightsIncrementalityInputSchema>;
+export interface InsightsIncrementalityRow extends ExtractedConversion {
+    /** Sum of 7d_click + 1d_view (whichever are present), the "default attributed" number agencies report. Null when neither is requested. */
+    default_attributed: number | null;
+    /** default_attributed / incrementality. Null when incrementality is 0 or default not requested. */
+    inflation_factor: number | null;
+    /** (default_attributed - incrementality) / default_attributed * 100. Null in the same cases as inflation_factor. */
+    overstatement_pct: number | null;
+}
+export interface InsightsIncrementalitySummary {
+    total_spend: number;
+    total_conversions: Record<string, number>;
+    cpa: Record<string, number | null>;
+    /** Computed from totals (not row averages): total_default_attributed / total_incrementality. Null if incrementality total is 0 or default not requested. */
+    inflation_factor: number | null;
+}
+export interface InsightsIncrementalityResult {
+    meta: {
+        ad_account_id: string;
+        date_range: {
+            since: string;
+            until: string;
+        };
+        level: InsightsLevel;
+        conversion_event_name: string;
+        attribution_windows: AttributionWindow[];
+    };
+    rows: InsightsIncrementalityRow[];
+    summary: InsightsIncrementalitySummary;
+}
+/** Minimal interface this tool needs from a Meta insights client. */
+export interface InsightsClient {
+    getInsights(params: GetInsightsParams): Promise<MetaInsightsRow[]>;
+}
+export interface InsightsIncrementalityDeps {
+    metaClient: InsightsClient;
+}
+export declare function runInsightsIncrementality(rawInput: unknown, deps: InsightsIncrementalityDeps): Promise<InsightsIncrementalityResult>;
+//# sourceMappingURL=insights-incrementality.d.ts.map

package/dist/tools/insights-incrementality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insights-incrementality.d.ts","sourceRoot":"","sources":["../../src/tools/insights-incrementality.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAe9E,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAY5C,CAAC;AAEH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAC/C,OAAO,iCAAiC,CACzC,CAAC;AAMF,MAAM,WAAW,yBAA0B,SAAQ,mBAAmB;IACpE,0IAA0I;IAC1I,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mGAAmG;IACnG,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,oHAAoH;IACpH,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,6BAA6B;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IACnC,4JAA4J;IAC5J,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE;QACJ,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;QAC7C,KAAK,EAAE,aAAa,CAAC;QACrB,qBAAqB,EAAE,MAAM,CAAC;QAC9B,mBAAmB,EAAE,iBAAiB,EAAE,CAAC;KAC1C,CAAC;IACF,IAAI,EAAE,yBAAyB,EAAE,CAAC;IAClC,OAAO,EAAE,6BAA6B,CAAC;CACxC;AAMD,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;CACpE;AAED,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,cAAc,CAAC;CAC5B;AA4CD,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,OAAO,EACjB,IAAI,EAAE,0BAA0B,GAC/B,OAAO,CAAC,4BAA4B,CAAC,CAwDvC"}

package/dist/tools/insights-incrementality.js

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+import { AttributionWindowSchema, parseAttributionWindows, } from '../lib/attribution.js';
+import { extractConversionRows, computeInflationFactor, } from '../lib/insights.js';
+/* ------------------------------------------------------------------------- */
+/* Input schema                                                              */
+/* ------------------------------------------------------------------------- */
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const dateRangeSchema = z.object({
+    since: z.string().regex(ISO_DATE, 'date must be YYYY-MM-DD'),
+    until: z.string().regex(ISO_DATE, 'date must be YYYY-MM-DD'),
+});
+const levelSchema = z.enum(['account', 'campaign', 'adset', 'ad']);
+export const insightsIncrementalityInputSchema = z.object({
+    ad_account_id: z.string().min(1, 'ad_account_id is required'),
+    date_range: dateRangeSchema,
+    conversion_event_name: z.string().min(1, 'conversion_event_name is required'),
+    attribution_windows: z
+        .array(AttributionWindowSchema)
+        .optional()
+        .transform((v) => parseAttributionWindows(v)),
+    level: levelSchema.optional().default('campaign'),
+    campaign_id: z.string().optional(),
+    adset_id: z.string().optional(),
+    breakdowns: z.array(z.string()).optional(),
+});
+/* ------------------------------------------------------------------------- */
+/* Implementation                                                            */
+/* ------------------------------------------------------------------------- */
+const DEFAULT_AGENCY_WINDOWS = ['7d_click', '1d_view'];
+function computeRowComparison(conversions, windows) {
+    const hasIncrementality = windows.includes('incrementality');
+    const defaultParts = DEFAULT_AGENCY_WINDOWS.filter((w) => windows.includes(w));
+    if (!hasIncrementality || defaultParts.length === 0) {
+        return { default_attributed: null, inflation_factor: null, overstatement_pct: null };
+    }
+    const defaultAttributed = defaultParts.reduce((sum, w) => sum + (conversions[w] ?? 0), 0);
+    const incrementality = conversions.incrementality ?? 0;
+    const inflation = computeInflationFactor({
+        incrementality,
+        comparison: defaultAttributed,
+    });
+    const overstatement = inflation == null || defaultAttributed === 0
+        ? null
+        : ((defaultAttributed - incrementality) / defaultAttributed) * 100;
+    return {
+        default_attributed: defaultAttributed,
+        inflation_factor: inflation,
+        overstatement_pct: overstatement,
+    };
+}
+export async function runInsightsIncrementality(rawInput, deps) {
+    const input = insightsIncrementalityInputSchema.parse(rawInput);
+    const windows = input.attribution_windows;
+    const fetchParams = {
+        accountId: input.ad_account_id,
+        dateRange: input.date_range,
+        attributionWindows: windows,
+        level: input.level,
+        ...(input.campaign_id ? { campaignId: input.campaign_id } : {}),
+        ...(input.adset_id ? { adsetId: input.adset_id } : {}),
+        ...(input.breakdowns ? { breakdowns: input.breakdowns } : {}),
+    };
+    const rawRows = await deps.metaClient.getInsights(fetchParams);
+    const extracted = extractConversionRows(rawRows, input.conversion_event_name, windows);
+    const rows = extracted.map((row) => ({
+        ...row,
+        ...computeRowComparison(row.conversions, windows),
+    }));
+    // Summary aggregation across rows
+    const totalSpend = rows.reduce((sum, r) => sum + (r.spend ?? 0), 0);
+    const totalConversions = {};
+    for (const w of windows)
+        totalConversions[w] = 0;
+    for (const r of rows) {
+        for (const w of windows) {
+            totalConversions[w] = (totalConversions[w] ?? 0) + (r.conversions[w] ?? 0);
+        }
+    }
+    const cpa = {};
+    for (const w of windows) {
+        const c = totalConversions[w] ?? 0;
+        cpa[w] = c > 0 ? totalSpend / c : null;
+    }
+    const summaryComparison = computeRowComparison(totalConversions, windows);
+    return {
+        meta: {
+            ad_account_id: input.ad_account_id,
+            date_range: input.date_range,
+            level: input.level,
+            conversion_event_name: input.conversion_event_name,
+            attribution_windows: [...windows],
+        },
+        rows,
+        summary: {
+            total_spend: totalSpend,
+            total_conversions: totalConversions,
+            cpa,
+            inflation_factor: summaryComparison.inflation_factor,
+        },
+    };
+}
+//# sourceMappingURL=insights-incrementality.js.map

package/dist/tools/insights-incrementality.js.map

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

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "mcp-meta-ads-incrementality",
+  "version": "0.2.0",
+  "description": "MCP server for Meta Marketing API focused on incrementality reporting. Surfaces Meta's incremental conversion attribution alongside default 7d-click/1d-view and dda windows so agencies can see the gap between reported and incremental performance.",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-meta-ads-incrementality": "dist/index.js",
+    "mcp-meta-ads-auth": "dist/auth-cli.js"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "meta-ads",
+    "facebook-ads",
+    "marketing-api",
+    "incrementality",
+    "attribution",
+    "advertising",
+    "agency"
+  ],
+  "author": "drak-marketing",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.5.0",
+    "env-paths": "^3.0.0",
+    "facebook-nodejs-business-sdk": "^24.0.1",
+    "open": "^10.0.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/facebook-nodejs-business-sdk": "^23.0.0",
+    "@types/node": "^20.10.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.18"
+  }
+}