@thenavidm/facebook-ad-library-mcp 0.1.0

package/dist/backends/scrapecreators.js

@@ -0,0 +1,185 @@
+/**
+ * ScrapeCreators backend. Needs a key, works serverless, about $1.88 per 1,000 ads.
+ *
+ * Use this instead of the browser when Chromium cannot run (a serverless
+ * function, a container without a browser) or when the volume makes babysitting
+ * Meta's rate limits not worth it.
+ *
+ * Request parameters are taken from their published OpenAPI spec, read
+ * 2026-08-31. Their *response* envelope is not published, so nothing here
+ * assumes a path into it: we walk the payload for ad-shaped objects. See
+ * `adlibrary/harvest.ts`.
+ *
+ * One thing this backend can do that the browser cannot: `transcribe`, which is
+ * server-side speech to text on a video ad.
+ */
+import { AdLibraryError } from "../errors.js";
+import { findConnections, parsePayloads } from "../adlibrary/harvest.js";
+import { adFromGraphql } from "../adlibrary/normalize.js";
+const BASE = "https://api.scrapecreators.com";
+// Their vocabulary is uppercase, ours is lowercase. Map at the boundary.
+const STATUS = { active: "ACTIVE", inactive: "INACTIVE", all: "ALL" };
+const MEDIA = {
+    all: "ALL",
+    image: "IMAGE",
+    meme: "MEME",
+    video: "VIDEO",
+    none: "NONE",
+};
+/** Their cursor field is undocumented, so accept any plausible spelling. */
+function cursorFrom(payload) {
+    for (const conn of findConnections(payload)) {
+        const info = conn["page_info"];
+        if (typeof info === "object" && info !== null) {
+            const endCursor = info["end_cursor"];
+            if (typeof endCursor === "string") {
+                return { cursor: endCursor, hasMore: info["has_next_page"] === true };
+            }
+        }
+    }
+    if (typeof payload === "object" && payload !== null) {
+        for (const key of ["cursor", "nextCursor", "next_cursor", "paginationToken"]) {
+            const value = payload[key];
+            if (typeof value === "string" && value)
+                return { cursor: value, hasMore: true };
+        }
+    }
+    return { hasMore: false };
+}
+export class ScrapeCreatorsBackend {
+    apiKey;
+    timeoutMs;
+    name = "scrapecreators";
+    needsKey = true;
+    constructor(apiKey, timeoutMs = 120_000) {
+        this.apiKey = apiKey;
+        this.timeoutMs = timeoutMs;
+        if (!apiKey) {
+            throw new AdLibraryError("The scrapecreators backend needs an API key.", {
+                backend: this.name,
+                hint: "Set SCRAPECREATORS_API_KEY, or use the free browser backend with FBADS_BACKEND=browser.",
+            });
+        }
+    }
+    async close() {
+        // Nothing to release: this backend is stateless fetch calls.
+    }
+    async get(path, params) {
+        const url = new URL(path, BASE);
+        for (const [key, value] of Object.entries(params)) {
+            if (value === undefined || value === null || value === "" || value === false)
+                continue;
+            url.searchParams.set(key, String(value));
+        }
+        const response = await fetch(url, {
+            headers: { "x-api-key": this.apiKey },
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        if (response.status === 401) {
+            throw new AdLibraryError("ScrapeCreators rejected the key (401).", {
+                backend: this.name,
+                hint: "Check SCRAPECREATORS_API_KEY.",
+            });
+        }
+        if (response.status === 402) {
+            throw new AdLibraryError("ScrapeCreators is out of credits (402).", {
+                backend: this.name,
+                hint: "Top up the account, or switch to the free browser backend with FBADS_BACKEND=browser.",
+            });
+        }
+        if (!response.ok) {
+            const body = (await response.text()).slice(0, 300);
+            throw new AdLibraryError(`ScrapeCreators error ${response.status}: ${body}`, {
+                backend: this.name,
+            });
+        }
+        try {
+            return await response.json();
+        }
+        catch {
+            throw new AdLibraryError("ScrapeCreators returned a body that is not JSON.", {
+                backend: this.name,
+            });
+        }
+    }
+    async search(params) {
+        if (!params.query && !params.pageId) {
+            throw new AdLibraryError("Pass either query or page_id.", { backend: this.name });
+        }
+        const limit = params.limit ?? 30;
+        const common = {
+            country: params.country ?? "US",
+            status: STATUS[params.activeStatus ?? "active"],
+            media_type: MEDIA[params.mediaType ?? "all"],
+            cursor: params.cursor,
+        };
+        const payload = params.pageId
+            ? await this.get("/v1/facebook/adLibrary/company/ads", { ...common, pageId: params.pageId })
+            : await this.get("/v1/facebook/adLibrary/search/ads", {
+                ...common,
+                query: params.query,
+                ad_type: params.adType === "political_and_issue_ads" ? "POLITICAL_AND_ISSUE_ADS" : "ALL",
+            });
+        const harvest = parsePayloads(payload);
+        const fallback = harvest.cursor ? undefined : cursorFrom(payload);
+        const ads = harvest.nodes.map((node) => adFromGraphql(node, this.name));
+        const kept = ads.slice(0, limit);
+        return {
+            backend: this.name,
+            count: kept.length,
+            hasMore: harvest.hasMore || fallback?.hasMore || ads.length > limit,
+            cursor: harvest.cursor ?? fallback?.cursor,
+            totalAvailable: harvest.total,
+            note: kept.length > 0 ? undefined : "ScrapeCreators returned no ads for these filters.",
+            ads: kept,
+        };
+    }
+    async listAdvertisers(query) {
+        const payload = await this.get("/v1/facebook/adLibrary/search/companies", { query });
+        const items = Array.isArray(payload)
+            ? payload
+            : (payload?.["searchResults"] ??
+                payload?.["results"] ??
+                payload?.["companies"] ??
+                []);
+        const out = [];
+        for (const raw of Array.isArray(items) ? items : []) {
+            if (typeof raw !== "object" || raw === null)
+                continue;
+            const item = raw;
+            const pageId = item["page_id"] ?? item["pageId"] ?? item["id"];
+            if (!pageId)
+                continue;
+            out.push({
+                pageId: String(pageId),
+                pageName: (item["name"] ?? item["page_name"] ?? item["pageName"]),
+                pageUrl: (item["page_url"] ?? item["pageUrl"]),
+                pageLikes: (item["likes"] ?? item["page_like_count"]),
+                verified: (item["verified"] ?? item["is_verified"]),
+                category: item["category"],
+                profilePictureUrl: (item["image_uri"] ?? item["profile_picture_url"]),
+            });
+        }
+        return out;
+    }
+    async getAd(libraryId) {
+        const payload = await this.get("/v1/facebook/adLibrary/ad", { id: libraryId });
+        const harvest = parsePayloads(payload);
+        const node = harvest.nodes[0];
+        return node ? adFromGraphql(node, this.name) : undefined;
+    }
+    async transcribe(libraryId) {
+        const payload = await this.get("/v1/facebook/adLibrary/ad/transcript", { id: libraryId });
+        if (typeof payload === "string")
+            return payload;
+        if (typeof payload === "object" && payload !== null) {
+            for (const key of ["transcript", "text", "transcription"]) {
+                const value = payload[key];
+                if (typeof value === "string" && value)
+                    return value;
+            }
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=scrapecreators.js.map

package/dist/backends/scrapecreators.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Settings, all from the environment.
+ *
+ * Environment variables rather than CLI flags: a user editing a client config is
+ * already inside a JSON `env` block, and flags mean editing `args` separately.
+ */
+import type { BackendName } from "./adlibrary/types.js";
+export type Config = {
+    backend: BackendName;
+    headless: boolean;
+    scrapeCreatorsKey?: string;
+    apifyToken?: string;
+    archiveToken?: string;
+    storeDir?: string;
+    hydrateMs: number;
+    scrollWaitMs: number;
+};
+export declare function loadConfig(): Config;

package/dist/config.js

@@ -0,0 +1,33 @@
+/**
+ * Settings, all from the environment.
+ *
+ * Environment variables rather than CLI flags: a user editing a client config is
+ * already inside a JSON `env` block, and flags mean editing `args` separately.
+ */
+function intFromEnv(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const value = Number.parseInt(raw, 10);
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+function backendFromEnv() {
+    const raw = (process.env["FBADS_BACKEND"] ?? "browser").toLowerCase();
+    if (raw === "scrapecreators" || raw === "apify" || raw === "browser")
+        return raw;
+    return "browser";
+}
+export function loadConfig() {
+    return {
+        backend: backendFromEnv(),
+        // Headed is for watching why a search came back empty.
+        headless: process.env["FBADS_HEADED"] !== "1",
+        scrapeCreatorsKey: process.env["SCRAPECREATORS_API_KEY"] || undefined,
+        apifyToken: process.env["APIFY_TOKEN"] || undefined,
+        archiveToken: process.env["META_ADS_ARCHIVE_TOKEN"] || undefined,
+        storeDir: process.env["FBADS_STORE_DIR"] || undefined,
+        hydrateMs: intFromEnv("FBADS_HYDRATE_MS", 9000),
+        scrollWaitMs: intFromEnv("FBADS_SCROLL_WAIT_MS", 4000),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAeH,SAAS,UAAU,CAAC,IAAY,EAAE,QAAgB;IAChD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC1B,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACvC,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;AAChE,CAAC;AAED,SAAS,cAAc;IACrB,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;IACtE,IAAI,GAAG,KAAK,gBAAgB,IAAI,GAAG,KAAK,OAAO,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC;IACjF,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO;QACL,OAAO,EAAE,cAAc,EAAE;QACzB,uDAAuD;QACvD,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,KAAK,GAAG;QAC7C,iBAAiB,EAAE,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,IAAI,SAAS;QACrE,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,SAAS;QACnD,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,IAAI,SAAS;QAChE,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,SAAS;QACrD,SAAS,EAAE,UAAU,CAAC,kBAAkB,EAAE,IAAI,CAAC;QAC/C,YAAY,EAAE,UAAU,CAAC,sBAAsB,EAAE,IAAI,CAAC;KACvD,CAAC;AACJ,CAAC"}

package/dist/doctor.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `facebook-ad-library-mcp doctor`
+ *
+ * The command someone runs when a tool came back empty and they cannot tell
+ * whether the problem is their setup, Meta, or the search itself. It answers
+ * that without needing an MCP client attached.
+ *
+ * Exit code 0 means usable. 1 means something needs fixing.
+ */
+export declare function runDoctor(): Promise<number>;

package/dist/doctor.js

@@ -0,0 +1,131 @@
+/**
+ * `facebook-ad-library-mcp doctor`
+ *
+ * The command someone runs when a tool came back empty and they cannot tell
+ * whether the problem is their setup, Meta, or the search itself. It answers
+ * that without needing an MCP client attached.
+ *
+ * Exit code 0 means usable. 1 means something needs fixing.
+ */
+import { loadConfig } from "./config.js";
+import { buildUrl } from "./adlibrary/url.js";
+import { inlinePayloads, parsePayloads } from "./adlibrary/harvest.js";
+function line(check) {
+    return `${check.ok ? "  ok  " : " fix  "} ${check.label}\n       ${check.detail}\n`;
+}
+async function checkPlaywright() {
+    try {
+        await import("playwright");
+    }
+    catch {
+        return {
+            label: "Playwright",
+            ok: false,
+            detail: "Not installed. Run `npx playwright install chromium`, or use a provider backend.",
+        };
+    }
+    try {
+        const { chromium } = await import("playwright");
+        const browser = await chromium.launch({ headless: true });
+        await browser.close();
+        return { label: "Playwright", ok: true, detail: "Chromium launches." };
+    }
+    catch (error) {
+        return {
+            label: "Playwright",
+            ok: false,
+            detail: `Installed, but Chromium will not launch: ${error.message}. Run \`npx playwright install chromium\`.`,
+        };
+    }
+}
+/** The check that matters: can we actually read ads right now. */
+async function checkLiveRead() {
+    try {
+        const { chromium } = await import("playwright");
+        const browser = await chromium.launch({ headless: true });
+        try {
+            const page = await browser.newPage();
+            const bodies = [];
+            page.on("response", (response) => {
+                if (String(response.url()).includes("/api/graphql")) {
+                    void response.text().then((b) => bodies.push(b)).catch(() => undefined);
+                }
+            });
+            await page.goto(buildUrl({ query: "shoes", country: "US" }), {
+                waitUntil: "domcontentloaded",
+                timeout: 60_000,
+            });
+            await page.waitForTimeout(9000);
+            bodies.push(...inlinePayloads(await page.content()));
+            const harvest = parsePayloads(bodies);
+            if (harvest.captcha) {
+                return {
+                    label: "Live read",
+                    ok: false,
+                    detail: "Meta served a captcha. Wait a few minutes, or use a provider backend.",
+                };
+            }
+            if (harvest.nodes.length === 0) {
+                return {
+                    label: "Live read",
+                    ok: false,
+                    detail: "Connected, but no ads parsed. Meta may be rate limiting this machine.",
+                };
+            }
+            return {
+                label: "Live read",
+                ok: true,
+                detail: `Read ${harvest.nodes.length} ads for a test search.`,
+            };
+        }
+        finally {
+            await browser.close();
+        }
+    }
+    catch (error) {
+        return { label: "Live read", ok: false, detail: error.message };
+    }
+}
+export async function runDoctor() {
+    const config = loadConfig();
+    const checks = [];
+    checks.push({
+        label: "Backend",
+        ok: true,
+        detail: `${config.backend}${config.backend === "browser" ? " (free, no key)" : " (bills per ad)"}`,
+    });
+    if (config.backend === "browser") {
+        const playwright = await checkPlaywright();
+        checks.push(playwright);
+        if (playwright.ok)
+            checks.push(await checkLiveRead());
+    }
+    if (config.backend === "scrapecreators") {
+        checks.push({
+            label: "SCRAPECREATORS_API_KEY",
+            ok: Boolean(config.scrapeCreatorsKey),
+            detail: config.scrapeCreatorsKey ? "Set." : "Not set. Get one at scrapecreators.com.",
+        });
+    }
+    if (config.backend === "apify") {
+        checks.push({
+            label: "APIFY_TOKEN",
+            ok: Boolean(config.apifyToken),
+            detail: config.apifyToken ? "Set." : "Not set. Get one from your Apify account settings.",
+        });
+    }
+    checks.push({
+        label: "META_ADS_ARCHIVE_TOKEN",
+        ok: true,
+        detail: config.archiveToken
+            ? "Set. get_eu_transparency will return EU spend and reach."
+            : "Not set. Optional: everything works without it except get_eu_transparency.",
+    });
+    process.stdout.write(`facebook-ad-library-mcp doctor\n\n${checks.map(line).join("")}\n`);
+    const failed = checks.filter((c) => !c.ok);
+    process.stdout.write(failed.length === 0
+        ? "Everything checks out.\n"
+        : `${failed.length} thing${failed.length === 1 ? "" : "s"} to fix, listed above.\n`);
+    return failed.length === 0 ? 0 : 1;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * One error type, so every failure reaching a model says what to do next.
+ *
+ * A tool that fails with "Error: request failed" costs the model a turn and
+ * usually a wrong guess. Every message here names the fix: which variable to
+ * set, which backend to switch to, how long to wait.
+ */
+export declare class AdLibraryError extends Error {
+    readonly hint?: string;
+    readonly backend?: string;
+    constructor(message: string, options?: {
+        hint?: string;
+        backend?: string;
+    });
+    toJSON(): Record<string, unknown>;
+}

package/dist/errors.js

@@ -0,0 +1,25 @@
+/**
+ * One error type, so every failure reaching a model says what to do next.
+ *
+ * A tool that fails with "Error: request failed" costs the model a turn and
+ * usually a wrong guess. Every message here names the fix: which variable to
+ * set, which backend to switch to, how long to wait.
+ */
+export class AdLibraryError extends Error {
+    hint;
+    backend;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = "AdLibraryError";
+        this.hint = options.hint;
+        this.backend = options.backend;
+    }
+    toJSON() {
+        return {
+            error: this.message,
+            ...(this.hint ? { hint: this.hint } : {}),
+            ...(this.backend ? { backend: this.backend } : {}),
+        };
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAU;IACd,OAAO,CAAU;IAE1B,YAAY,OAAe,EAAE,UAA+C,EAAE;QAC5E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IACjC,CAAC;IAED,MAAM;QACJ,OAAO;YACL,KAAK,EAAE,IAAI,CAAC,OAAO;YACnB,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACnD,CAAC;IACJ,CAAC;CACF"}

package/dist/format/ads.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shaping ads for a model rather than for a parser.
+ *
+ * A raw ad card is mostly nulls and CDN URLs. Dumping thirty of them spends
+ * thousands of tokens on fields nobody reads, and buries the three that decide
+ * whether an ad is worth studying: how long it has run, what it says, and where
+ * it sends people.
+ *
+ * So the list view is compact and the detail view is complete. `get_ad` returns
+ * everything; `search_ads` returns enough to choose which ad to look at.
+ */
+import type { Ad } from "../adlibrary/types.js";
+/** One ad in a result list. Enough to judge it, not everything about it. */
+export declare function summarise(ad: Ad): Record<string, unknown>;
+/** One ad in full, for `get_ad`. Every creative, every copy variant. */
+export declare function detail(ad: Ad): Record<string, unknown>;

package/dist/format/ads.js

@@ -0,0 +1,97 @@
+/**
+ * Shaping ads for a model rather than for a parser.
+ *
+ * A raw ad card is mostly nulls and CDN URLs. Dumping thirty of them spends
+ * thousands of tokens on fields nobody reads, and buries the three that decide
+ * whether an ad is worth studying: how long it has run, what it says, and where
+ * it sends people.
+ *
+ * So the list view is compact and the detail view is complete. `get_ad` returns
+ * everything; `search_ads` returns enough to choose which ad to look at.
+ */
+/** Drop keys that are undefined or empty, so the JSON a model reads has no noise. */
+function compact(input) {
+    const out = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (value === undefined || value === null || value === "")
+            continue;
+        if (Array.isArray(value) && value.length === 0)
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+function truncate(text, max) {
+    if (!text)
+        return undefined;
+    return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+/** One ad in a result list. Enough to judge it, not everything about it. */
+export function summarise(ad) {
+    const videos = ad.creatives.filter((c) => c.kind === "video").length;
+    return compact({
+        library_id: ad.libraryId,
+        advertiser: ad.pageName,
+        page_id: ad.pageId,
+        active: ad.isActive,
+        started: ad.startedRunning,
+        stopped: ad.stoppedRunning,
+        days_active: ad.daysActive,
+        platforms: ad.platforms,
+        format: ad.displayFormat,
+        cta: ad.ctaText,
+        landing_domain: ad.linkDomain,
+        body: truncate(ad.body, 600),
+        creatives: ad.creatives.length,
+        videos: videos > 0 ? videos : undefined,
+        variants_using_creative: ad.variantsUsingCreative,
+        spend: ad.spend,
+        reach: ad.reachEstimate,
+        details: ad.adDetailsUrl,
+    });
+}
+/** One ad in full, for `get_ad`. Every creative, every copy variant. */
+export function detail(ad) {
+    return compact({
+        library_id: ad.libraryId,
+        details_url: ad.adDetailsUrl,
+        advertiser: compact({
+            name: ad.pageName,
+            page_id: ad.pageId,
+            url: ad.pageUrl,
+            likes: ad.pageLikes,
+            categories: ad.pageCategories,
+            profile_picture: ad.pageProfilePictureUrl,
+        }),
+        run: compact({
+            active: ad.isActive,
+            started: ad.startedRunning,
+            stopped: ad.stoppedRunning,
+            days_active: ad.daysActive,
+            platforms: ad.platforms,
+            countries: ad.countries,
+            categories: ad.categories,
+        }),
+        copy: compact({
+            title: ad.title,
+            body: ad.body,
+            caption: ad.caption,
+            link_description: ad.linkDescription,
+            cta: ad.ctaText,
+            cta_type: ad.ctaType,
+            link_url: ad.linkUrl,
+            link_domain: ad.linkDomain,
+        }),
+        format: ad.displayFormat,
+        variants_using_creative: ad.variantsUsingCreative,
+        creatives: ad.creatives.map((creative) => compact({ ...creative })),
+        transparency: compact({
+            spend: ad.spend,
+            currency: ad.currency,
+            reach: ad.reachEstimate,
+            impressions: ad.impressions,
+        }),
+        source: ad.source,
+    });
+}
+//# sourceMappingURL=ads.js.map

package/dist/format/ads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ads.js","sourceRoot":"","sources":["../../src/format/ads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,qFAAqF;AACrF,SAAS,OAAO,CAAoC,KAAQ;IAC1D,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE;YAAE,SAAS;QACpE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACzD,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACnB,CAAC;IACD,OAAO,GAAiB,CAAC;AAC3B,CAAC;AAED,SAAS,QAAQ,CAAC,IAAwB,EAAE,GAAW;IACrD,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5B,OAAO,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;AAClE,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,SAAS,CAAC,EAAM;IAC9B,MAAM,MAAM,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,MAAM,CAAC;IACrE,OAAO,OAAO,CAAC;QACb,UAAU,EAAE,EAAE,CAAC,SAAS;QACxB,UAAU,EAAE,EAAE,CAAC,QAAQ;QACvB,OAAO,EAAE,EAAE,CAAC,MAAM;QAClB,MAAM,EAAE,EAAE,CAAC,QAAQ;QACnB,OAAO,EAAE,EAAE,CAAC,cAAc;QAC1B,OAAO,EAAE,EAAE,CAAC,cAAc;QAC1B,WAAW,EAAE,EAAE,CAAC,UAAU;QAC1B,SAAS,EAAE,EAAE,CAAC,SAAS;QACvB,MAAM,EAAE,EAAE,CAAC,aAAa;QACxB,GAAG,EAAE,EAAE,CAAC,OAAO;QACf,cAAc,EAAE,EAAE,CAAC,UAAU;QAC7B,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC;QAC5B,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM;QAC9B,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;QACvC,uBAAuB,EAAE,EAAE,CAAC,qBAAqB;QACjD,KAAK,EAAE,EAAE,CAAC,KAAK;QACf,KAAK,EAAE,EAAE,CAAC,aAAa;QACvB,OAAO,EAAE,EAAE,CAAC,YAAY;KACzB,CAAC,CAAC;AACL,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,MAAM,CAAC,EAAM;IAC3B,OAAO,OAAO,CAAC;QACb,UAAU,EAAE,EAAE,CAAC,SAAS;QACxB,WAAW,EAAE,EAAE,CAAC,YAAY;QAC5B,UAAU,EAAE,OAAO,CAAC;YAClB,IAAI,EAAE,EAAE,CAAC,QAAQ;YACjB,OAAO,EAAE,EAAE,CAAC,MAAM;YAClB,GAAG,EAAE,EAAE,CAAC,OAAO;YACf,KAAK,EAAE,EAAE,CAAC,SAAS;YACnB,UAAU,EAAE,EAAE,CAAC,cAAc;YAC7B,eAAe,EAAE,EAAE,CAAC,qBAAqB;SAC1C,CAAC;QACF,GAAG,EAAE,OAAO,CAAC;YACX,MAAM,EAAE,EAAE,CAAC,QAAQ;YACnB,OAAO,EAAE,EAAE,CAAC,cAAc;YAC1B,OAAO,EAAE,EAAE,CAAC,cAAc;YAC1B,WAAW,EAAE,EAAE,CAAC,UAAU;YAC1B,SAAS,EAAE,EAAE,CAAC,SAAS;YACvB,SAAS,EAAE,EAAE,CAAC,SAAS;YACvB,UAAU,EAAE,EAAE,CAAC,UAAU;SAC1B,CAAC;QACF,IAAI,EAAE,OAAO,CAAC;YACZ,KAAK,EAAE,EAAE,CAAC,KAAK;YACf,IAAI,EAAE,EAAE,CAAC,IAAI;YACb,OAAO,EAAE,EAAE,CAAC,OAAO;YACnB,gBAAgB,EAAE,EAAE,CAAC,eAAe;YACpC,GAAG,EAAE,EAAE,CAAC,OAAO;YACf,QAAQ,EAAE,EAAE,CAAC,OAAO;YACpB,QAAQ,EAAE,EAAE,CAAC,OAAO;YACpB,WAAW,EAAE,EAAE,CAAC,UAAU;SAC3B,CAAC;QACF,MAAM,EAAE,EAAE,CAAC,aAAa;QACxB,uBAAuB,EAAE,EAAE,CAAC,qBAAqB;QACjD,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;QACnE,YAAY,EAAE,OAAO,CAAC;YACpB,KAAK,EAAE,EAAE,CAAC,KAAK;YACf,QAAQ,EAAE,EAAE,CAAC,QAAQ;YACrB,KAAK,EAAE,EAAE,CAAC,aAAa;YACvB,WAAW,EAAE,EAAE,CAAC,WAAW;SAC5B,CAAC;QACF,MAAM,EAAE,EAAE,CAAC,MAAM;KAClB,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Entry point.
+ *
+ * `facebook-ad-library-mcp`          stdio, which is what MCP clients launch
+ * `facebook-ad-library-mcp --http`   HTTP, for running it somewhere always on
+ * `facebook-ad-library-mcp doctor`   check the setup and say what is wrong
+ */
+export {};