zuckerbot-mcp 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,133 @@
+# zuckerbot-mcp
+
+**MCP server for ZuckerBot — let AI agents run Facebook ad campaigns.**
+
+Give any MCP-compatible AI agent (Claude Desktop, OpenClaw, Cursor, etc.) the ability to create, launch, optimize, and monitor Meta ad campaigns through natural conversation.
+
+## Quick Start
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "zuckerbot": {
+      "command": "npx",
+      "args": ["-y", "zuckerbot-mcp"],
+      "env": {
+        "ZUCKERBOT_API_KEY": "zb_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### OpenClaw
+
+```
+/skill install zuckerbot
+```
+
+Or add to your OpenClaw config:
+
+```json
+{
+  "mcpServers": {
+    "zuckerbot": {
+      "command": "npx",
+      "args": ["-y", "zuckerbot-mcp"],
+      "env": {
+        "ZUCKERBOT_API_KEY": "zb_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### npx (standalone)
+
+```bash
+ZUCKERBOT_API_KEY=zb_live_your_key_here npx zuckerbot-mcp
+```
+
+### Install globally
+
+```bash
+npm install -g zuckerbot-mcp
+ZUCKERBOT_API_KEY=zb_live_your_key_here zuckerbot-mcp
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `ZUCKERBOT_API_KEY` | ✅ | — | Your ZuckerBot API key. Get one at [zuckerbot.ai/dashboard](https://zuckerbot.ai/dashboard). |
+| `ZUCKERBOT_API_URL` | — | `https://zuckerbot.ai/api/v1` | API base URL (override for self-hosted or staging). |
+
+## Tools
+
+| Tool | Description | Required Inputs |
+|------|-------------|-----------------|
+| `zuckerbot_preview_campaign` | Generate ad preview from a URL (no Meta account needed) | `url` |
+| `zuckerbot_create_campaign` | Create full campaign with strategy, targeting, and creatives | `url` |
+| `zuckerbot_launch_campaign` | Launch a draft campaign on Meta (spends real money) | `campaign_id`, `meta_access_token`, `meta_ad_account_id`, `meta_page_id` |
+| `zuckerbot_pause_campaign` | Pause or resume a live campaign | `campaign_id` |
+| `zuckerbot_get_performance` | Get real-time campaign metrics | `campaign_id` |
+| `zuckerbot_sync_conversion` | Send lead conversion feedback to Meta's algorithm | `campaign_id`, `lead_id`, `quality`, `meta_access_token` |
+| `zuckerbot_research_reviews` | Get review intelligence for a business | `business_name` |
+| `zuckerbot_research_competitors` | Analyze competitor ads in a category | `industry`, `location` |
+| `zuckerbot_research_market` | Get market intelligence and ad benchmarks | `industry`, `location` |
+| `zuckerbot_generate_creatives` | Generate ad copy and images independently | `business_name`, `description` |
+
+## Example Conversation
+
+> **User:** Can you set up Facebook ads for my yoga studio? Website is serenity-yoga.com
+>
+> **Agent:** Let me research your business first…
+> *(calls `zuckerbot_research_reviews` + `zuckerbot_research_competitors` in parallel)*
+>
+> Your studio has a 4.9-star rating with 89 reviews! Customers love the "calming atmosphere" and "expert instructors." Your competitors are running generic discount ads — none mention reviews or instructor credentials. That's your edge.
+>
+> Let me generate a preview of what your ads would look like…
+> *(calls `zuckerbot_preview_campaign`)*
+>
+> Here are two ad concepts:
+> 1. **"4.9 Stars, 89 Reviews"** — Leads with social proof. Your competitors aren't doing this.
+> 2. **"First Class Free"** — Low-commitment offer to get people in the door.
+>
+> Want me to create a full campaign with targeting and budget recommendations?
+>
+> **User:** Yes! Budget is $15/day.
+>
+> *(calls `zuckerbot_create_campaign` → reviews strategy → calls `zuckerbot_launch_campaign` with user's Meta credentials)*
+>
+> **Agent:** Your campaign is live! I'll check performance in 3 days.
+
+## Typical Agent Flow
+
+1. **Research** → `research_reviews` + `research_competitors` (parallel)
+2. **Preview** → `preview_campaign` (show the user what ads look like)
+3. **Create** → `create_campaign` (full strategy + creatives)
+4. **Launch** → `launch_campaign` (go live on Meta)
+5. **Monitor** → `get_performance` (check metrics periodically)
+6. **Optimize** → `sync_conversion` (feed back lead quality)
+
+## Development
+
+```bash
+git clone https://github.com/DatalisHQ/zuckerbot.git
+cd zuckerbot/mcp-server
+npm install
+npm run build
+npm start
+```
+
+## API Documentation
+
+Full API reference: [zuckerbot.ai/docs](https://zuckerbot.ai/docs)
+
+## License
+
+MIT — see [LICENSE](./LICENSE)

package/dist/client.d.ts

@@ -0,0 +1,17 @@
+export declare class ZuckerBotApiError extends Error {
+    readonly statusCode: number;
+    readonly errorCode: string;
+    readonly retryAfter?: number | undefined;
+    constructor(statusCode: number, errorCode: string, message: string, retryAfter?: number | undefined);
+}
+export declare class ZuckerBotClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly userAgent;
+    constructor();
+    private headers;
+    private handleResponse;
+    get(path: string): Promise<unknown>;
+    post(path: string, body?: Record<string, unknown>): Promise<unknown>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAIA,qBAAa,iBAAkB,SAAQ,KAAK;aAExB,UAAU,EAAE,MAAM;aAClB,SAAS,EAAE,MAAM;aAEjB,UAAU,CAAC,EAAE,MAAM;gBAHnB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjC,OAAO,EAAE,MAAM,EACC,UAAU,CAAC,EAAE,MAAM,YAAA;CAKtC;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;;IAkBnC,OAAO,CAAC,OAAO;YAQD,cAAc;IAgDtB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASnC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;CAS3E"}

package/dist/client.js

@@ -0,0 +1,83 @@
+// ── ZuckerBot API Client ─────────────────────────────────────────────
+const VERSION = "0.1.0";
+export class ZuckerBotApiError extends Error {
+    statusCode;
+    errorCode;
+    retryAfter;
+    constructor(statusCode, errorCode, message, retryAfter) {
+        super(message);
+        this.statusCode = statusCode;
+        this.errorCode = errorCode;
+        this.retryAfter = retryAfter;
+        this.name = "ZuckerBotApiError";
+    }
+}
+export class ZuckerBotClient {
+    baseUrl;
+    apiKey;
+    userAgent;
+    constructor() {
+        this.baseUrl = (process.env.ZUCKERBOT_API_URL || "https://zuckerbot.ai/api/v1").replace(/\/+$/, "");
+        const key = process.env.ZUCKERBOT_API_KEY;
+        if (!key) {
+            throw new Error("ZUCKERBOT_API_KEY environment variable is required. " +
+                "Get your API key at https://zuckerbot.ai/dashboard");
+        }
+        this.apiKey = key;
+        this.userAgent = `zuckerbot-mcp/${VERSION}`;
+    }
+    headers() {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+            "User-Agent": this.userAgent,
+        };
+    }
+    async handleResponse(response) {
+        const body = await response.text();
+        let data;
+        try {
+            data = JSON.parse(body);
+        }
+        catch {
+            data = { raw: body };
+        }
+        if (!response.ok) {
+            const err = data && typeof data === "object" && "error" in data
+                ? data.error
+                : null;
+            const code = err?.code || `http_${response.status}`;
+            const message = err?.message || `API request failed with status ${response.status}`;
+            const retryAfter = err?.retry_after;
+            switch (response.status) {
+                case 401:
+                    throw new ZuckerBotApiError(401, code, `Authentication failed: ${message}. Check your ZUCKERBOT_API_KEY.`);
+                case 429:
+                    throw new ZuckerBotApiError(429, code, `Rate limit exceeded: ${message}${retryAfter ? ` Retry after ${retryAfter}s.` : ""}`, retryAfter);
+                case 502:
+                    throw new ZuckerBotApiError(502, code, `Meta API error: ${message}`);
+                default:
+                    throw new ZuckerBotApiError(response.status, code, message, retryAfter);
+            }
+        }
+        return data;
+    }
+    async get(path) {
+        const url = `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+        const response = await fetch(url, {
+            method: "GET",
+            headers: this.headers(),
+        });
+        return this.handleResponse(response);
+    }
+    async post(path, body) {
+        const url = `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+        const response = await fetch(url, {
+            method: "POST",
+            headers: this.headers(),
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        return this.handleResponse(response);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// ── ZuckerBot MCP Server ─────────────────────────────────────────────
+//
+// Exposes the ZuckerBot API as MCP tools for AI agents.
+// Connect via stdio transport (standard for MCP servers).
+//
+// Environment variables:
+//   ZUCKERBOT_API_KEY  — Required. Your ZuckerBot API key.
+//   ZUCKERBOT_API_URL  — Optional. API base URL (default: https://zuckerbot.ai/api/v1)
+//
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ZuckerBotClient } from "./client.js";
+import { registerTools } from "./tools.js";
+async function main() {
+    // Initialize the API client (validates ZUCKERBOT_API_KEY)
+    const client = new ZuckerBotClient();
+    // Create the MCP server
+    const server = new McpServer({
+        name: "zuckerbot",
+        version: "0.1.0",
+    });
+    // Register all 10 tools
+    registerTools(server, client);
+    // Connect via stdio
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("Fatal error starting ZuckerBot MCP server:", err.message || err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,wEAAwE;AACxE,EAAE;AACF,wDAAwD;AACxD,0DAA0D;AAC1D,EAAE;AACF,yBAAyB;AACzB,2DAA2D;AAC3D,uFAAuF;AACvF,EAAE;AAEF,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,KAAK,UAAU,IAAI;IACjB,0DAA0D;IAC1D,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IAErC,wBAAwB;IACxB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,wBAAwB;IACxB,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE9B,oBAAoB;IACpB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,4CAA4C,EAAE,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,CAAC;IAChF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ZuckerBotClient } from "./client.js";
+export declare function registerTools(server: McpServer, client: ZuckerBotClient): void;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,eAAe,EAAqB,MAAM,aAAa,CAAC;AAkDjE,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAkT9E"}

package/dist/tools.js

@@ -0,0 +1,299 @@
+// ── ZuckerBot MCP Tool Definitions ───────────────────────────────────
+import { z } from "zod";
+import { ZuckerBotApiError } from "./client.js";
+// ── Helpers ──────────────────────────────────────────────────────────
+function formatResult(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+}
+function formatError(err) {
+    if (err instanceof ZuckerBotApiError) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: true,
+                        code: err.errorCode,
+                        status: err.statusCode,
+                        message: err.message,
+                        ...(err.retryAfter ? { retry_after: err.retryAfter } : {}),
+                    }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        ],
+        isError: true,
+    };
+}
+// ── Register all tools ───────────────────────────────────────────────
+export function registerTools(server, client) {
+    // ── 1. Preview Campaign ─────────────────────────────────────────
+    server.tool("zuckerbot_preview_campaign", "Generate a campaign preview from a business URL. Returns AI-generated ad creatives (headlines, copy, images) without needing a Meta account. Great for showing users what their ads would look like before they commit.", {
+        url: z.string().describe("Business website URL to generate ads for"),
+        ad_count: z
+            .number()
+            .int()
+            .min(1)
+            .max(3)
+            .default(2)
+            .describe("Number of ad variants to generate (1-3)"),
+    }, async ({ url, ad_count }) => {
+        try {
+            const result = await client.post("/campaigns/preview", {
+                url,
+                ad_count,
+            });
+            return formatResult(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    // ── 2. Create Campaign ──────────────────────────────────────────
+    server.tool("zuckerbot_create_campaign", "Create a full campaign with strategy, targeting, budget recommendations, and ad creatives. Returns a draft campaign ready to launch. Does NOT spend money or touch Meta until you call launch.", {
+        url: z.string().describe("Business website URL"),
+        business_name: z.string().optional().describe("Business name (auto-detected from URL if omitted)"),
+        business_type: z
+            .string()
+            .optional()
+            .describe("Business category (e.g., 'restaurant', 'fitness', 'roofing')"),
+        location: z
+            .object({
+            city: z.string().optional(),
+            state: z.string().optional(),
+            country: z.string().optional(),
+            lat: z.number().optional(),
+            lng: z.number().optional(),
+        })
+            .optional()
+            .describe("Business location for geo-targeting"),
+        budget_daily_cents: z
+            .number()
+            .int()
+            .optional()
+            .describe("Daily budget in cents (e.g., 2000 = $20/day)"),
+        objective: z
+            .enum(["leads", "traffic", "awareness"])
+            .optional()
+            .describe("Campaign objective"),
+    }, async ({ url, business_name, business_type, location, budget_daily_cents, objective }) => {
+        try {
+            const body = { url };
+            if (business_name)
+                body.business_name = business_name;
+            if (business_type)
+                body.business_type = business_type;
+            if (location)
+                body.location = location;
+            if (budget_daily_cents !== undefined)
+                body.budget_daily_cents = budget_daily_cents;
+            if (objective)
+                body.objective = objective;
+            const result = await client.post("/campaigns/create", body);
+            return formatResult(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    // ── 3. Launch Campaign ──────────────────────────────────────────
+    server.tool("zuckerbot_launch_campaign", "Launch a draft campaign on Meta (Facebook/Instagram). This is the money endpoint — it creates real ads on the user's Meta ad account and starts spending their budget. Requires Meta credentials.", {
+        campaign_id: z.string().describe("ZuckerBot campaign ID from the create step"),
+        meta_access_token: z.string().describe("User's Meta/Facebook access token"),
+        meta_ad_account_id: z.string().describe("Meta ad account ID (format: act_XXXXX)"),
+        meta_page_id: z.string().describe("Facebook Page ID for the lead form"),
+        variant_index: z
+            .number()
+            .int()
+            .default(0)
+            .describe("Which creative variant to launch (0-indexed)"),
+        daily_budget_cents: z
+            .number()
+            .int()
+            .optional()
+            .describe("Override daily budget in cents"),
+        radius_km: z.number().int().optional().describe("Override targeting radius in km"),
+    }, async ({ campaign_id, meta_access_token, meta_ad_account_id, meta_page_id, variant_index, daily_budget_cents, radius_km, }) => {
+        try {
+            const body = {
+                meta_access_token,
+                meta_ad_account_id,
+                meta_page_id,
+                variant_index,
+            };
+            if (daily_budget_cents !== undefined)
+                body.daily_budget_cents = daily_budget_cents;
+            if (radius_km !== undefined)
+                body.radius_km = radius_km;
+            const result = await client.post(`/campaigns/${campaign_id}/launch`, body);
+            return formatResult(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    // ── 4. Pause / Resume Campaign ─────────────────────────────────
+    server.tool("zuckerbot_pause_campaign", "Pause or resume a running campaign on Meta. Pausing stops ad delivery and spend immediately. Resuming restarts delivery.", {
+        campaign_id: z.string().describe("ZuckerBot campaign ID"),
+        action: z
+            .enum(["pause", "resume"])
+            .default("pause")
+            .describe("Whether to pause or resume the campaign"),
+    }, async ({ campaign_id, action }) => {
+        try {
+            const result = await client.post(`/campaigns/${campaign_id}/pause`, {
+                action,
+            });
+            return formatResult(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    // ── 5. Get Performance ──────────────────────────────────────────
+    server.tool("zuckerbot_get_performance", "Get real-time performance metrics for a campaign. Returns impressions, clicks, spend, leads, cost-per-lead, click-through rate, and a performance status (learning/healthy/underperforming/paused).", {
+        campaign_id: z.string().describe("ZuckerBot campaign ID"),
+    }, async ({ campaign_id }) => {
+        try {
+            const result = await client.get(`/campaigns/${campaign_id}/performance`);
+            return formatResult(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    // ── 6. Sync Conversion ─────────────────────────────────────────
+    server.tool("zuckerbot_sync_conversion", "Send conversion feedback to Meta's algorithm. When a lead converts (or doesn't), this teaches Meta to find more (or fewer) people like them. Critical for improving lead quality over time.", {
+        campaign_id: z.string().describe("ZuckerBot campaign ID"),
+        lead_id: z.string().describe("Lead ID to report conversion for"),
+        quality: z
+            .enum(["good", "bad"])
+            .describe("Lead quality: 'good' = converted/contacted, 'bad' = lost/unresponsive"),
+        meta_access_token: z.string().describe("User's Meta access token for CAPI"),
+        user_data: z
+            .object({
+            email: z.string().optional(),
+            phone: z.string().optional(),
+            first_name: z.string().optional(),
+            last_name: z.string().optional(),
+        })
+            .optional()
+            .describe("Optional user data to improve match rate"),
+    }, async ({ campaign_id, lead_id, quality, meta_access_token, user_data }) => {
+        try {
+            const body = {
+                lead_id,
+                quality,
+                meta_access_token,
+            };
+            if (user_data)
+                body.user_data = user_data;
+            const result = await client.post(`/campaigns/${campaign_id}/conversions`, body);
+            return formatResult(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    // ── 7. Research Reviews ─────────────────────────────────────────
+    server.tool("zuckerbot_research_reviews", "Get review intelligence for a business. Searches Google Reviews, Yelp, and other sources, then synthesizes themes, best quotes, and sentiment. Use this data to inform ad copy.", {
+        business_name: z.string().describe("Business name to research"),
+        location: z
+            .string()
+            .optional()
+            .describe("City/region for more accurate results (e.g., 'Austin, TX')"),
+    }, async ({ business_name, location }) => {
+        try {
+            const body = { business_name };
+            if (location)
+                body.location = location;
+            const result = await client.post("/research/reviews", body);
+            return formatResult(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    // ── 8. Research Competitors ─────────────────────────────────────
+    server.tool("zuckerbot_research_competitors", "Analyze competitor ads for a business category and location. Searches Meta Ad Library and web results to find active competitor campaigns, common hooks, and gaps you can exploit.", {
+        industry: z.string().describe("Business category (e.g., 'pizza restaurant', 'yoga studio')"),
+        location: z.string().describe("City/region (e.g., 'Austin, TX')"),
+        country: z
+            .string()
+            .default("US")
+            .describe("Country code (default: US)"),
+    }, async ({ industry, location, country }) => {
+        try {
+            const result = await client.post("/research/competitors", {
+                industry,
+                location,
+                country,
+            });
+            return formatResult(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    // ── 9. Research Market ──────────────────────────────────────────
+    server.tool("zuckerbot_research_market", "Get market intelligence for an industry and location. Returns market size, trends, audience demographics, and advertising benchmarks to inform campaign strategy.", {
+        industry: z.string().describe("Industry/business category (e.g., 'fitness', 'dental')"),
+        location: z.string().describe("City/region (e.g., 'Austin, TX')"),
+    }, async ({ industry, location }) => {
+        try {
+            const result = await client.post("/research/market", {
+                industry,
+                location,
+            });
+            return formatResult(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    // ── 10. Generate Creatives ──────────────────────────────────────
+    server.tool("zuckerbot_generate_creatives", "Generate ad creatives (copy + images) independently from campaign creation. Useful for refreshing creatives on an existing campaign or generating options to show a user.", {
+        business_name: z.string().describe("Business name"),
+        description: z.string().describe("Brief description of the business"),
+        count: z
+            .number()
+            .int()
+            .min(1)
+            .max(5)
+            .default(2)
+            .describe("Number of creative variants to generate (1-5)"),
+        generate_images: z
+            .boolean()
+            .default(true)
+            .describe("Whether to generate AI images (set false for copy-only)"),
+    }, async ({ business_name, description, count, generate_images }) => {
+        try {
+            const result = await client.post("/creatives/generate", {
+                business_name,
+                description,
+                count,
+                generate_images,
+            });
+            return formatResult(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,184 @@
+/** Standard API error envelope */
+export interface ApiError {
+    error: {
+        code: string;
+        message: string;
+        retry_after?: number;
+    };
+}
+export interface PreviewRequest {
+    url: string;
+    ad_count?: number;
+}
+export interface AdVariant {
+    headline: string;
+    copy: string;
+    rationale: string;
+    image_url?: string;
+    image_base64?: string;
+    cta?: string;
+    angle?: string;
+    image_prompt?: string;
+}
+export interface PreviewResponse {
+    id: string;
+    business_name: string;
+    description?: string;
+    ads: AdVariant[];
+    enrichment?: Record<string, unknown>;
+    created_at: string;
+}
+export interface LocationInput {
+    city?: string;
+    state?: string;
+    country?: string;
+    lat?: number;
+    lng?: number;
+}
+export interface CreateCampaignRequest {
+    url: string;
+    business_name?: string;
+    business_type?: string;
+    location?: LocationInput;
+    budget_daily_cents?: number;
+    objective?: "leads" | "traffic" | "awareness";
+}
+export interface CampaignStrategy {
+    objective: string;
+    summary: string;
+    strengths?: string[];
+    opportunities?: string[];
+    recommended_daily_budget_cents?: number;
+    projected_cpl_cents?: number;
+    projected_monthly_leads?: number;
+}
+export interface CampaignTargeting {
+    age_min?: number;
+    age_max?: number;
+    radius_km?: number;
+    interests?: string[];
+    geo_locations?: Record<string, unknown>;
+    publisher_platforms?: string[];
+    facebook_positions?: string[];
+    instagram_positions?: string[];
+}
+export interface CreateCampaignResponse {
+    id: string;
+    status: string;
+    business_name?: string;
+    business_type?: string;
+    strategy?: CampaignStrategy;
+    targeting?: CampaignTargeting;
+    variants?: AdVariant[];
+    roadmap?: Record<string, string[]>;
+    created_at: string;
+}
+export interface LaunchCampaignRequest {
+    campaign_id: string;
+    meta_access_token: string;
+    meta_ad_account_id: string;
+    meta_page_id: string;
+    variant_index?: number;
+    daily_budget_cents?: number;
+    radius_km?: number;
+}
+export interface LaunchCampaignResponse {
+    id: string;
+    status: string;
+    meta_campaign_id: string;
+    meta_adset_id: string;
+    meta_ad_id: string;
+    meta_leadform_id: string;
+    daily_budget_cents: number;
+    launched_at: string;
+}
+export interface PauseCampaignRequest {
+    campaign_id: string;
+    action?: "pause" | "resume";
+}
+export interface PerformanceResponse {
+    campaign_id: string;
+    status: string;
+    performance_status: string;
+    metrics: {
+        impressions: number;
+        clicks: number;
+        spend_cents: number;
+        leads_count: number;
+        cpl_cents: number;
+        ctr_pct: number;
+    };
+    hours_since_launch: number;
+    last_synced_at: string;
+}
+export interface UserData {
+    email?: string;
+    phone?: string;
+    first_name?: string;
+    last_name?: string;
+}
+export interface SyncConversionRequest {
+    campaign_id: string;
+    lead_id: string;
+    quality: "good" | "bad";
+    meta_access_token: string;
+    user_data?: UserData;
+}
+export interface SyncConversionResponse {
+    success: boolean;
+    capi_sent: boolean;
+    events_received: number;
+    quality: string;
+    lead_id: string;
+}
+export interface ResearchReviewsRequest {
+    business_name: string;
+    location?: string;
+}
+export interface ResearchReviewsResponse {
+    business_name: string;
+    rating: number;
+    review_count: number;
+    themes: string[];
+    best_quotes: string[];
+    sentiment_breakdown?: {
+        positive: number;
+        neutral: number;
+        negative: number;
+    };
+    sources: string[];
+}
+export interface ResearchCompetitorsRequest {
+    industry: string;
+    location: string;
+    country?: string;
+}
+export interface ResearchCompetitorsResponse {
+    competitor_ads: Array<{
+        page_name: string;
+        ad_body_text: string;
+        started_running_date?: string;
+        platforms?: string;
+    }>;
+    insights: {
+        summary: string;
+        common_hooks: string[];
+        gaps: string[];
+        opportunity: string;
+    };
+    ad_count: number;
+}
+export interface ResearchMarketRequest {
+    industry: string;
+    location: string;
+}
+export interface GenerateCreativesRequest {
+    business_name: string;
+    description: string;
+    count?: number;
+    generate_images?: boolean;
+}
+export interface GenerateCreativesResponse {
+    creatives: AdVariant[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,3 @@
+// ── ZuckerBot API Types ──────────────────────────────────────────────
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,wEAAwE"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "zuckerbot-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for ZuckerBot — let AI agents run Facebook ad campaigns",
+  "type": "module",
+  "bin": {
+    "zuckerbot-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "zuckerbot",
+    "facebook-ads",
+    "meta-ads",
+    "ai-agents",
+    "advertising",
+    "claude",
+    "openai",
+    "llm"
+  ],
+  "author": "DatalisHQ",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DatalisHQ/zuckerbot.git",
+    "directory": "mcp-server"
+  },
+  "homepage": "https://zuckerbot.ai",
+  "bugs": {
+    "url": "https://github.com/DatalisHQ/zuckerbot/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}