zuckerbot-mcp 0.2.30 → 0.2.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +238 -162
  2. package/dist/tools.d.ts.map +1 -1
  3. package/dist/tools.js +86 -211
  4. package/dist/tools.js.map +1 -1
  5. package/dist/types.d.ts +7 -326
  6. package/dist/types.d.ts.map +1 -1
  7. package/package.json +5 -5
package/README.md CHANGED
@@ -1,41 +1,49 @@
1
- # zuckerbot-mcp
1
+ <div align="center">
2
2
 
3
- **CLI + MCP server for ZuckerBot — run Facebook ad campaigns from your terminal or AI agent.**
3
+ # ZuckerBot
4
4
 
5
- Install one package and get both:
5
+ **Give your AI agent Facebook Ads.**
6
6
 
7
- - `zuckerbot` for humans running campaigns from the terminal
8
- - `zuckerbot-mcp` for MCP-compatible AI agents
9
- - `zuckerbot serve` as an alternative way to start MCP server mode
7
+ One MCP server to create, launch, and autonomously manage Meta ad campaigns.
10
8
 
11
- The CLI and MCP server both use the same ZuckerBot API client, authentication, and endpoints.
9
+ [![npm version](https://img.shields.io/npm/v/zuckerbot-mcp?style=flat-square&color=CB3837)](https://www.npmjs.com/package/zuckerbot-mcp)
10
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat-square)](./LICENSE)
11
+ [![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.Crumbedsausage/zuckerbot-8A2BE2?style=flat-square)](https://github.com/modelcontextprotocol/servers)
12
+ [![GitHub stars](https://img.shields.io/github/stars/DatalisHQ/zuckerbot?style=flat-square)](https://github.com/DatalisHQ/zuckerbot/stargazers)
12
13
 
13
- ## Quick Start
14
+ ```json
15
+ {
16
+ "mcpServers": {
17
+ "zuckerbot": {
18
+ "command": "npx",
19
+ "args": ["-y", "zuckerbot-mcp"],
20
+ "env": { "ZUCKERBOT_API_KEY": "zb_live_your_key_here" }
21
+ }
22
+ }
23
+ }
24
+ ```
14
25
 
15
- ### Human CLI
26
+ [Website](https://zuckerbot.ai) · [npm](https://www.npmjs.com/package/zuckerbot-mcp) · [API Docs](https://zuckerbot.ai/docs) · [Get API Key](https://zuckerbot.ai/developer)
16
27
 
17
- ```bash
18
- npm install -g zuckerbot-mcp
19
- export ZUCKERBOT_API_KEY=zb_live_your_key_here
28
+ </div>
20
29
 
21
- zuckerbot preview https://example.com
22
- zuckerbot create https://example.com --budget 2000 --objective leads
23
- zuckerbot meta status
24
- ```
30
+ ---
25
31
 
26
- ### Global install
32
+ ## 🧠 Why ZuckerBot
27
33
 
28
- ```bash
29
- npm install -g zuckerbot-mcp
30
- ```
34
+ Most Meta Ads MCP tools let you *read* your ad data. ZuckerBot lets your AI agent **run the whole show** — from market research to campaign creation, AI-generated creatives, launch, real-time optimization, and conversion feedback. One API, full lifecycle, no Ads Manager tab.
31
35
 
32
- After global install, these commands are available:
36
+ - **44 MCP tools** covering the entire ad lifecycle
37
+ - **AI creative generation** — Seedream/Imagen images and Kling video ads, generated on demand
38
+ - **Autonomous optimization** — policy-driven budget scaling, pausing, and rebalancing
39
+ - **CAPI pipeline** — map CRM stages to Meta conversion events, ingest webhooks, monitor attribution
40
+ - **Audience portfolios** — template-based tier budgeting with auto-rebalancing
41
+ - **CLI for humans** — run campaigns from your terminal, not just through an agent
42
+ - **Works without a Meta account** — preview campaigns and generate creatives with zero setup
33
43
 
34
- - `zuckerbot`
35
- - `zuckerbot-mcp`
36
- - `zuckerbot serve`
44
+ ## ⚡ Quick Start
37
45
 
38
- ### MCP Server: Claude Desktop
46
+ ### Claude Desktop
39
47
 
40
48
  Add to your `claude_desktop_config.json`:
41
49
 
@@ -53,13 +61,9 @@ Add to your `claude_desktop_config.json`:
53
61
  }
54
62
  ```
55
63
 
56
- ### MCP Server: OpenClaw
64
+ ### Cursor
57
65
 
58
- ```
59
- /skill install zuckerbot
60
- ```
61
-
62
- Or add to your OpenClaw config:
66
+ Add to `.cursor/mcp.json`:
63
67
 
64
68
  ```json
65
69
  {
@@ -75,168 +79,240 @@ Or add to your OpenClaw config:
75
79
  }
76
80
  ```
77
81
 
78
- ### MCP Server: npx (standalone)
82
+ ### OpenClaw
79
83
 
80
- ```bash
81
- ZUCKERBOT_API_KEY=zb_live_your_key_here npx zuckerbot-mcp
84
+ ```
85
+ /skill install zuckerbot
82
86
  ```
83
87
 
84
- ### MCP Server: global install
88
+ ### CLI
85
89
 
86
90
  ```bash
87
91
  npm install -g zuckerbot-mcp
88
- ZUCKERBOT_API_KEY=zb_live_your_key_here zuckerbot-mcp
89
- ZUCKERBOT_API_KEY=zb_live_your_key_here zuckerbot serve
92
+ export ZUCKERBOT_API_KEY=zb_live_your_key_here
93
+
94
+ zuckerbot preview https://your-business.com
90
95
  ```
91
96
 
92
- ## Environment Variables
97
+ Get your API key at [zuckerbot.ai/developer](https://zuckerbot.ai/developer). Try preview and creative generation without a key (5 free/day).
98
+
99
+ ### Environment Variables
93
100
 
94
101
  | Variable | Required | Default | Description |
95
102
  |----------|----------|---------|-------------|
96
- | `ZUCKERBOT_API_KEY` | ✅ | — | Your ZuckerBot API key. Get one at [zuckerbot.ai/dashboard](https://zuckerbot.ai/dashboard). |
97
- | `ZUCKERBOT_API_URL` | — | `https://zuckerbot.ai/api/v1` | API base URL (override for self-hosted or staging). |
98
-
99
- ## CLI Commands
100
-
101
- | Command | Description |
102
- |---------|-------------|
103
- | `zuckerbot preview <url>` | Generate an ad preview from a business URL |
104
- | `zuckerbot create <url>` | Create a full campaign with strategy, targeting, and creatives |
105
- | `zuckerbot launch <campaign_id>` | Launch a draft campaign on Meta |
106
- | `zuckerbot status <campaign_id>` | Get real-time campaign performance metrics |
107
- | `zuckerbot pause <campaign_id>` | Pause a running campaign |
108
- | `zuckerbot resume <campaign_id>` | Resume a paused campaign |
109
- | `zuckerbot creatives <business_name> <description>` | Generate ad creatives |
110
- | `zuckerbot conversion <campaign_id> <lead_id> <quality>` | Sync lead quality feedback to Meta |
111
- | `zuckerbot research reviews <url>` | Review intelligence |
112
- | `zuckerbot research competitors <category> <location>` | Competitor analysis |
113
- | `zuckerbot research market <industry> <location>` | Market intelligence |
114
- | `zuckerbot meta status` | Check Meta connection status |
115
- | `zuckerbot meta accounts` | List Meta ad accounts |
116
- | `zuckerbot meta select-account <ad_account_id>` | Select a Meta ad account |
117
- | `zuckerbot meta pages` | List Facebook pages |
118
- | `zuckerbot meta select-page <page_id>` | Select a Facebook page |
119
- | `zuckerbot meta credentials` | Check stored launch credentials |
120
- | `zuckerbot serve` | Start MCP server mode from the unified CLI |
121
-
122
- ## MCP Tools
123
-
124
- | Tool | Description | Required Inputs |
125
- |------|-------------|-----------------|
126
- | `zuckerbot_quickstart` | Show demo/full mode status, setup steps, and the recommended tool flow | none |
127
- | `zuckerbot_preview_campaign` | Generate ad preview from a URL (no Meta account needed) | `url` |
128
- | `zuckerbot_create_campaign` | Create a legacy or intelligence campaign draft with strategy, targeting, and creatives | `url` |
129
- | `zuckerbot_enrich_business` | Crawl a business website and cache structured context for intelligence planning | `business_id` |
130
- | `zuckerbot_upload_business_context` | Upload text business context and extract structured insights | `business_id`, `filename`, `content` |
131
- | `zuckerbot_list_business_context` | List uploaded business-context files and extracted summaries | `business_id` |
132
- | `zuckerbot_get_campaign` | Get campaign detail, workflow state, stored creatives, and linked tier executions | `campaign_id` |
133
- | `zuckerbot_approve_campaign_strategy` | Approve the generated tiers and creative angles for an intelligence campaign | `campaign_id` |
134
- | `zuckerbot_request_creative` | Create or dispatch a creative handoff package for an intelligence campaign | `campaign_id` |
135
- | `zuckerbot_upload_creative` | Upload finished creative assets and provision paused Meta executions | `campaign_id`, `creatives` |
136
- | `zuckerbot_activate_campaign` | Activate the ready tiers for an intelligence campaign | `campaign_id` |
137
- | `zuckerbot_suggest_angles` | Read a campaign draft and return the proposed creative angles and audience tiers | `campaign_id` |
138
- | `zuckerbot_launch_campaign` | Launch one variant from a draft campaign on Meta (uses stored credentials when available) | `campaign_id` |
139
- | `zuckerbot_launch_all_variants` | Launch all variants for A/B testing in one call | `campaign_id` |
140
- | `zuckerbot_pause_campaign` | Pause or resume a live campaign | `campaign_id` |
141
- | `zuckerbot_get_performance` | Get real-time campaign metrics | `campaign_id` |
142
- | `zuckerbot_create_seed_audience` | Build a Meta custom audience from hashed CAPI users | `source_stage` |
143
- | `zuckerbot_create_lookalike_audience` | Create a Meta lookalike from a stored seed audience | `seed_audience_id` |
144
- | `zuckerbot_list_audiences` | List stored audience registry rows for a business | none |
145
- | `zuckerbot_refresh_audience` | Refresh a stored audience or sync its latest state | `audience_id` |
146
- | `zuckerbot_get_audience_status` | Fetch the latest Meta audience status and update the registry row | `audience_id` |
147
- | `zuckerbot_delete_audience` | Delete a stored audience from Meta and ZuckerBot | `audience_id` |
148
- | `zuckerbot_sync_conversion` | Send lead conversion feedback to Meta's algorithm | `campaign_id`, `lead_id`, `quality`, `meta_access_token` |
149
- | `zuckerbot_research_reviews` | Get review intelligence for a business | `business_name` |
150
- | `zuckerbot_research_competitors` | Analyze competitor ads in a category | `industry`, `location` |
151
- | `zuckerbot_research_market` | Get market intelligence and ad benchmarks | `industry`, `location` |
152
- | `zuckerbot_meta_status` | Check whether Meta is connected for this API key/user | none |
153
- | `zuckerbot_list_ad_accounts` | List available Meta ad accounts and the current selection | none |
154
- | `zuckerbot_select_ad_account` | Select/save a Meta ad account ID for future launches | `ad_account_id` |
155
- | `zuckerbot_list_pixels` | List available Meta pixels for the selected ad account and the current selection | none |
156
- | `zuckerbot_select_pixel` | Select/save a Meta pixel ID for future conversion tracking | `pixel_id` |
157
- | `zuckerbot_list_meta_pages` | List available Facebook pages and current selected page | none |
158
- | `zuckerbot_select_meta_page` | Select/save a Facebook page ID for future launches | `page_id` |
159
- | `zuckerbot_get_launch_credentials` | Resolve stored launch credentials and report missing fields | none |
160
- | `zuckerbot_generate_creatives` | Generate ad copy and creatives (images or Kling video) | `business_name`, `description` |
161
- | `zuckerbot_capi_config` | Get or update the per-business CAPI configuration, including Meta `action_source` | none for read; config fields for update |
162
- | `zuckerbot_capi_status` | Get 7-day and 30-day CAPI delivery and attribution status | none |
163
- | `zuckerbot_capi_test` | Send a synthetic CAPI test event through the configured pipeline | none |
164
- | `zuckerbot_create_portfolio` | Create a business-owned audience portfolio from a template | none |
165
- | `zuckerbot_portfolio_performance` | Get tier-by-tier audience portfolio performance | `portfolio_id` |
166
- | `zuckerbot_rebalance_portfolio` | Dry-run or apply a portfolio rebalance | `portfolio_id` |
167
-
168
- For intelligence campaigns, the recommended flow is `create -> approve -> request/upload creative -> activate`.
169
-
170
- Business context can also be refreshed independently through `zuckerbot_enrich_business`, `zuckerbot_upload_business_context`, and `zuckerbot_list_business_context`.
171
-
172
- ## Example Conversation
173
-
174
- > **User:** Can you set up Facebook ads for my yoga studio? Website is serenity-yoga.com
103
+ | `ZUCKERBOT_API_KEY` | Yes | — | Your API key (`zb_live_` or `zb_test_`) |
104
+ | `ZUCKERBOT_API_URL` | No | `https://zuckerbot.ai/api/v1` | Override for self-hosted or staging |
105
+
106
+ ## 📊 How It Compares
107
+
108
+ | Feature | ZuckerBot | Pipeboard (meta-ads-mcp) | Manual Ads Manager |
109
+ |---|---|---|---|
110
+ | MCP tools | **44** | ~25 | 0 |
111
+ | Full campaign creation from URL | ✅ AI-planned strategy | ❌ Manual campaign struct | ✅ Manual |
112
+ | AI creative generation | ✅ Seedream / Imagen / Kling video | ❌ | Manual upload |
113
+ | Autonomous optimization | ✅ Policy-driven | ❌ | Manual |
114
+ | CAPI pipeline | ✅ Config, ingest, monitor | ❌ | Manual setup |
115
+ | Audience portfolios | ✅ Template-based tiers | ❌ | Manual |
116
+ | Performance analytics | ✅ | ✅ (core strength) | ✅ |
117
+ | Campaign management | ✅ Launch, pause, resume, A/B | ✅ Create, update, pause | ✅ |
118
+ | Market research & intel | ✅ Reviews, competitors, benchmarks | ❌ | Third-party |
119
+ | CLI for humans | ✅ | ❌ | N/A |
120
+ | Language | TypeScript | Python | N/A |
121
+ | License | MIT | Source-available + paid cloud | N/A |
122
+
123
+ > Pipeboard is strong for analytics and reading existing campaign data. ZuckerBot is built for the full autonomous lifecycle — **research → create → generate creatives → launch → optimize → convert**.
124
+
125
+ ## 🛠️ Available Tools (44)
126
+
127
+ ### Campaign Lifecycle
128
+
129
+ | Tool | Description |
130
+ |------|-------------|
131
+ | `zuckerbot_quickstart` | Show mode status, setup steps, and recommended flow |
132
+ | `zuckerbot_preview_campaign` | Generate ad preview from a URL — no Meta account needed |
133
+ | `zuckerbot_create_campaign` | Create an intelligence campaign draft with strategy, tiers, and angles |
134
+ | `zuckerbot_get_campaign` | Get campaign detail, workflow state, and linked executions |
135
+ | `zuckerbot_approve_campaign_strategy` | Approve audience tiers and creative angles |
136
+ | `zuckerbot_suggest_angles` | Read a draft and return proposed creative angles + tiers |
137
+ | `zuckerbot_launch_campaign` | Launch a variant on Meta (the money endpoint) |
138
+ | `zuckerbot_launch_all_variants` | Launch all variants for A/B testing in one call |
139
+ | `zuckerbot_pause_campaign` | Pause or resume a live campaign |
140
+ | `zuckerbot_get_performance` | Real-time metrics: impressions, clicks, spend, leads, CPL |
141
+ | `zuckerbot_activate_campaign` | Activate ready tiers after creative upload |
142
+
143
+ ### Creative Pipeline
144
+
145
+ | Tool | Description |
146
+ |------|-------------|
147
+ | `zuckerbot_generate_creatives` | AI images (Seedream/Imagen) or video (Kling) + ad copy |
148
+ | `zuckerbot_suggest_angles` | Proposed creative angles for a campaign draft |
149
+ | `zuckerbot_request_creative` | Dispatch a creative handoff package |
150
+ | `zuckerbot_upload_creative` | Upload finished assets and provision Meta executions |
151
+
152
+ ### Business Intelligence
153
+
154
+ | Tool | Description |
155
+ |------|-------------|
156
+ | `zuckerbot_enrich_business` | Crawl a website and cache structured business context |
157
+ | `zuckerbot_upload_business_context` | Upload text context and extract planning insights |
158
+ | `zuckerbot_list_business_context` | List uploaded context files and summaries |
159
+
160
+ ### Audience Management
161
+
162
+ | Tool | Description |
163
+ |------|-------------|
164
+ | `zuckerbot_create_seed_audience` | Build a Meta custom audience from hashed CAPI users |
165
+ | `zuckerbot_create_lookalike_audience` | Create a 1-20% lookalike from a seed audience |
166
+ | `zuckerbot_list_audiences` | List stored audiences with sizes and delivery status |
167
+ | `zuckerbot_refresh_audience` | Rebuild seed or sync lookalike status |
168
+ | `zuckerbot_get_audience_status` | Fetch latest Meta audience status |
169
+ | `zuckerbot_delete_audience` | Delete from Meta and ZuckerBot registry |
170
+
171
+ ### CAPI & Conversions
172
+
173
+ | Tool | Description |
174
+ |------|-------------|
175
+ | `zuckerbot_capi_config` | Get or update per-business CAPI configuration |
176
+ | `zuckerbot_capi_status` | 7-day and 30-day delivery and attribution status |
177
+ | `zuckerbot_capi_test` | Send a synthetic test event through the pipeline |
178
+ | `zuckerbot_sync_conversion` | Feed lead quality back to Meta's algorithm |
179
+
180
+ ### Portfolio Management
181
+
182
+ | Tool | Description |
183
+ |------|-------------|
184
+ | `zuckerbot_create_portfolio` | Create audience portfolio from template |
185
+ | `zuckerbot_portfolio_performance` | Tier-by-tier performance with attributed conversions |
186
+ | `zuckerbot_rebalance_portfolio` | Dry-run or apply portfolio rebalance |
187
+
188
+ ### Research & Intelligence
189
+
190
+ | Tool | Description |
191
+ |------|-------------|
192
+ | `zuckerbot_research_reviews` | Review intelligence: sentiment, proof points for ad copy |
193
+ | `zuckerbot_research_competitors` | Competitor ad analysis for a category and location |
194
+ | `zuckerbot_research_market` | Market size, audience estimates, and ad benchmarks |
195
+ | `zuckerbot_get_account_insights` | Historical Meta account insights over date ranges |
196
+
197
+ ### Meta Account Setup
198
+
199
+ | Tool | Description |
200
+ |------|-------------|
201
+ | `zuckerbot_meta_status` | Check Meta connection status |
202
+ | `zuckerbot_list_ad_accounts` | List available Meta ad accounts |
203
+ | `zuckerbot_select_ad_account` | Select ad account for launches |
204
+ | `zuckerbot_list_pixels` | List Meta pixels for the selected account |
205
+ | `zuckerbot_select_pixel` | Select pixel for conversion tracking |
206
+ | `zuckerbot_list_meta_pages` | List Facebook pages |
207
+ | `zuckerbot_select_meta_page` | Select page for launches |
208
+ | `zuckerbot_list_lead_forms` | List Meta lead forms (Instant Forms) |
209
+ | `zuckerbot_select_lead_form` | Select lead form for lead gen campaigns |
210
+ | `zuckerbot_get_launch_credentials` | Resolve stored credentials for autonomous launch |
211
+
212
+ ## 🔌 API Endpoints
213
+
214
+ Base URL: `https://zuckerbot.ai/api/v1`
215
+
216
+ | Method | Path | Description |
217
+ |--------|------|-------------|
218
+ | `POST` | `/campaigns/preview` | Generate ad preview from a URL |
219
+ | `POST` | `/campaigns/create` | Create campaign with strategy and targeting |
220
+ | `POST` | `/campaigns/:id/launch` | Launch a draft on Meta |
221
+ | `POST` | `/campaigns/:id/pause` | Pause or resume a live campaign |
222
+ | `GET` | `/campaigns/:id/performance` | Real-time metrics with tier breakdowns |
223
+ | `POST` | `/campaigns/:id/conversions` | Send lead quality feedback |
224
+ | `POST` | `/creatives/generate` | Generate ad copy + AI media |
225
+ | `GET` | `/capi/config` | Get CAPI config and webhook URL |
226
+ | `PUT` | `/capi/config` | Update CAPI config |
227
+ | `POST` | `/capi/config/test` | Send synthetic CAPI test event |
228
+ | `POST` | `/capi/events` | Ingest CRM webhook events |
229
+ | `GET` | `/capi/status` | CAPI delivery and attribution status |
230
+ | `POST` | `/portfolios/create` | Create audience portfolio |
231
+ | `GET` | `/portfolios/:id/performance` | Tier-by-tier portfolio performance |
232
+ | `POST` | `/portfolios/:id/rebalance` | Dry-run or apply rebalance |
233
+ | `POST` | `/research/reviews` | Review intelligence |
234
+ | `POST` | `/research/competitors` | Competitor ad analysis |
235
+ | `POST` | `/research/market` | Market benchmarks |
236
+ | `GET` | `/meta/status` | Meta connection status |
237
+ | `GET` | `/meta/ad-accounts` | List ad accounts |
238
+ | `GET` | `/meta/pages` | List Facebook pages |
239
+
240
+ All endpoints require `Authorization: Bearer zb_live_...` except where noted. Full reference at [zuckerbot.ai/docs](https://zuckerbot.ai/docs).
241
+
242
+ ## 💻 CLI Examples
243
+
244
+ ```bash
245
+ # Preview what ads would look like for any URL
246
+ zuckerbot preview https://serenity-yoga.com
247
+
248
+ # Create a full campaign with budget and objective
249
+ zuckerbot create https://serenity-yoga.com --budget 2000 --objective leads
250
+
251
+ # Launch it on Meta
252
+ zuckerbot launch camp_abc123
253
+
254
+ # Check real-time performance
255
+ zuckerbot status camp_abc123
256
+
257
+ # Generate standalone creatives
258
+ zuckerbot creatives "Sunrise Yoga" "Hot yoga and meditation in Austin, TX"
259
+
260
+ # Research the competitive landscape
261
+ zuckerbot research competitors "yoga studios" "Austin, TX"
262
+
263
+ # Check your Meta connection
264
+ zuckerbot meta status
265
+ ```
266
+
267
+ ## 🤖 Example Agent Conversation
268
+
269
+ > **User:** Set up Facebook ads for my yoga studio — serenity-yoga.com, $15/day budget
175
270
  >
176
271
  > **Agent:** Let me research your business first…
177
- > *(calls `zuckerbot_research_reviews` + `zuckerbot_research_competitors` in parallel)*
178
- >
179
- > 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.
272
+ > *(calls `zuckerbot_research_reviews` + `zuckerbot_research_competitors`)*
180
273
  >
181
- > Let me generate a preview of what your ads would look like…
182
- > *(calls `zuckerbot_preview_campaign`)*
274
+ > You have a 4.9★ rating with 89 reviews. Customers love the "calming atmosphere." Your competitors aren't using social proof in their ads — that's your edge.
183
275
  >
184
- > Here are two ad concepts:
185
- > 1. **"4.9 Stars, 89 Reviews"** — Leads with social proof. Your competitors aren't doing this.
186
- > 2. **"First Class Free"** — Low-commitment offer to get people in the door.
276
+ > *(calls `zuckerbot_create_campaign` with intelligence mode)*
187
277
  >
188
- > Want me to create a full campaign with targeting and budget recommendations?
278
+ > I created a campaign draft with two audience tiers:
279
+ > 1. **Broad Local** — yoga-interested women 25-54 within 10mi
280
+ > 2. **Customer Lookalike** — 1% lookalike from your existing customers
189
281
  >
190
- > **User:** Yes. Budget is $15/day. Use the smarter flow if you can.
282
+ > Two creative angles: "4.9 Stars, 89 Reviews" (social proof) and "First Class Free" (low commitment).
191
283
  >
192
- > *(calls `zuckerbot_create_campaign` with `mode: "auto"` and gets an intelligence draft)*
284
+ > *(calls `zuckerbot_approve_campaign_strategy` → `zuckerbot_request_creative` → `zuckerbot_upload_creative` → `zuckerbot_activate_campaign`)*
193
285
  >
194
- > **Agent:** The account has enough business context, so I created an intelligence draft. Best plan is:
195
- > 1. Approve the broad local tier and the customer lookalike tier
196
- > 2. Send two angles to creative production
197
- > 3. Activate only the tiers that have finished assets
198
- >
199
- > *(calls `zuckerbot_approve_campaign_strategy`, then `zuckerbot_request_creative`)*
200
- >
201
- > **User:** Upload these finished assets and launch the ready tier.
202
- >
203
- > *(calls `zuckerbot_upload_creative`, then `zuckerbot_activate_campaign`)*
204
- >
205
- > **Agent:** The approved tier is live. I can monitor performance and sync lead quality back into Meta as conversions arrive.
286
+ > **Agent:** Your campaign is live. I'll monitor performance and feed lead quality back to Meta's algorithm as conversions come in.
287
+
288
+ ## 💰 Pricing
289
+
290
+ | Plan | Price | Requests/mo | Rate Limit |
291
+ |------|-------|-------------|------------|
292
+ | **Anonymous** | Free | 5/day | — |
293
+ | **Free** | $0 | 25 | 10 req/min |
294
+ | **Pro** | $49/mo | 500 | 60 req/min |
295
+ | **Enterprise** | Custom | Custom | 300 req/min |
296
+
297
+ [Get your API key →](https://zuckerbot.ai/developer)
206
298
 
207
- ## Typical Agent Flow
299
+ ## 🔗 Links
208
300
 
209
- 1. **Research** → `research_reviews` + `research_competitors` (parallel)
210
- 2. **Preview** → `preview_campaign` (show the user what ads look like)
211
- 3. **Create** → `create_campaign` (returns intelligence draft when a business can be resolved)
212
- 4. **Approve** → `approve_campaign_strategy`
213
- 5. **Creative** → `request_creative` or `upload_creative`
214
- 6. **Activate** → `activate_campaign`
215
- 7. **Monitor** → `get_performance`
216
- 8. **Optimize** → `sync_conversion` and audience tools as downstream signal volume grows
301
+ - **Website:** [zuckerbot.ai](https://zuckerbot.ai)
302
+ - **npm:** [npmjs.com/package/zuckerbot-mcp](https://www.npmjs.com/package/zuckerbot-mcp)
303
+ - **API Docs:** [zuckerbot.ai/docs](https://zuckerbot.ai/docs)
304
+ - **MCP Registry:** [io.github.Crumbedsausage/zuckerbot](https://github.com/modelcontextprotocol/servers)
217
305
 
218
306
  ## Development
219
307
 
220
308
  ```bash
221
309
  git clone https://github.com/DatalisHQ/zuckerbot.git
222
- cd zuckerbot/mcp-server
310
+ cd zuckerbot
223
311
  npm install
224
312
  npm run build
225
313
  npm start
226
314
  ```
227
315
 
228
- Human CLI development:
229
-
230
- ```bash
231
- node dist/cli.js --help
232
- node dist/cli.js preview https://example.com
233
- node dist/cli.js serve
234
- ```
235
-
236
- ## API Documentation
237
-
238
- Full API reference: [zuckerbot.ai/docs](https://zuckerbot.ai/docs)
239
-
240
316
  ## License
241
317
 
242
318
  MIT — see [LICENSE](./LICENSE)
package/dist/tools.d.ts.map CHANGED
@@ -1 +1 @@
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;AA8OjE,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CA0uC9E;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAsGlF"}
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;AA8MjE,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAgiC9E;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAyMlF"}