@buygolinks/mcp 0.28.0 → 0.32.0

package/README.md

@@ -1,10 +1,10 @@
 # @buygolinks/mcp
 
-Model Context Protocol (MCP) server for [buygolinks.com](https://buygolinks.com) — create and manage branded short links, campaigns, offers, and analytics from any MCP-compatible AI agent: Claude Desktop, Cursor, Cline, Continue, Hermes, and others.
+Model Context Protocol (MCP) server for [buygolinks.com](https://buygolinks.com): create and manage branded short links, campaigns, offers, and analytics from any MCP-compatible AI agent: Claude Desktop, Cursor, Cline, Continue, Hermes, and others.
 
 ## Install
 
-No install needed — use `npx`:
+No install needed. Use `npx`:
 
 ```bash
 npx @buygolinks/mcp
@@ -36,7 +36,7 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o
 }
 ```
 
-Restart Claude Desktop. You'll see a 🔌 icon — buygolinks tools are now available.
+Restart Claude Desktop. You'll see a 🔌 icon, and buygolinks tools are now available.
 
 ### Cursor
 
@@ -65,29 +65,40 @@ Most MCP clients use the same shape. Point them at the `npx -y @buygolinks/mcp`
 | `create_link` | Create a short link. The destination URL is passed through untouched (include your own affiliate tag). |
 | `update_link` | Edit a link's destination URL, title, source label, custom domain, password, archive state, or custom alias (e.g. `summer-sale` → `https://click.example.com/summer-sale`). Repointing the destination preserves the short code, alias, and click history. |
 | `refresh_link_image` | Re-attempt fetching a link's product/preview image (Amazon PDP scrape for `/dp/` links, Open Graph otherwise). Use when a link has no thumbnail or a stale one. Returns `{ found: false }` if nothing could be fetched this time. |
-| `list_links` | List your links with click counts. |
+| `list_links` | List your links with click counts (`include_archived` for archived ones). |
+| `delete_link` | Permanently delete a link and its click history. Archive with `update_link` to keep the stats. |
+| `get_link_pixels` / `set_link_pixels` | Which tracking pixels fire on a link's clicks, and as what event. With no selection of its own a link fires every active account pixel. |
+| `set_link_collection` | Put a link in a collection, or `null` to take it out. |
+| `list_collections` / `get_collection` / `create_collection` / `update_collection` / `delete_collection` | Folders of links with their own click analytics. A collection can be a **rotator**: `https://buygolinks.com/c/{rotator_alias}` sends each visitor to a random link in it. |
+| `get_account` | Plan, billing dates, monthly usage, report time zone and the universal postback URL. |
+| `list_api_keys` / `create_api_key` / `delete_api_key` | Manage API keys. A new key's token is shown once. |
 | `get_link_stats` | Per-link analytics (by day, country, device, browser, hour, weekday). |
 | `get_overview_stats` | Account-wide analytics. |
 | `list_domains` | List your branded custom short-link domains with provisioning + SSL status. |
 | `create_domain` | Register a new branded domain (e.g. `go.acme.com`). Returns the CNAME target. |
 | `verify_domain` | Force a fresh Cloudflare status check after DNS is added. |
+| `check_domain_dns` | Detect where a domain's DNS is hosted and the easiest way to connect it. |
+| `connect_domain_cloudflare` | Add the CNAME to the user's own Cloudflare zone with a one-time API token (never stored). For agents with no browser. In the app, the Connect Cloudflare button needs no token. |
 | `delete_domain` | Remove a branded domain. |
-| `get_universal_postback_url` | Get the account's **universal postback URL** (Voluum-style, `/postback/u/{token}`): ONE URL that works for every campaign and every network. It matches the click by `clickid` (alias `cid`) and credits whichever campaign the click belongs to — paste it once into any network's S2S settings or your own webhook (n8n, Zapier, store order webhooks) and never update it again. Optional `payout`, `currency`, `txid` params. Prefer this over per-campaign/per-network postbacks unless you want campaign-scoped validation. |
-| `list_affiliate_networks` / `create_affiliate_network` / `update_affiliate_network` / `delete_affiliate_network` | Manage affiliate networks. Each network exposes a per-network postback URL (`/postback/n/{token}`) the user pastes into the network's S2S settings. Set `amazon_tag` (e.g. `yourtagid-20`) on an Amazon network to auto-tag every Amazon link with `?tag=…` at click time. |
-| `list_offers` / `create_offer` / `update_offer` / `delete_offer` | Manage destination URLs ("offers"). Optionally tied to an affiliate network so the right conversion-param name is propagated on outbound clicks. |
+| `get_universal_postback_url` | Get the account's **universal postback URL** (Voluum-style, `/postback/u/{token}`): ONE URL that works for every campaign and every network. It matches the click by `clickid` (alias `cid`) and credits whichever campaign the click belongs to. Paste it once into any network's S2S settings or your own webhook (n8n, Zapier, store order webhooks) and never update it again. Optional `payout`, `currency`, `txid` params. It is the account's only postback URL: campaigns and networks have none of their own. Conversions are deduped by txid: at most one conversion per (account, txid). A re-fired postback with the same txid is ignored, and a re-fire with a different payout updates the stored conversion's revenue instead of stacking a second one. No `event` param records a sale. `event=refund` or `event=chargeback` subtracts from revenue, and `event={slug}` records a custom event. A blank or unknown event gets a 400. |
+| `list_custom_events` / `create_custom_event` / `update_custom_event` / `delete_custom_event` | Manage the account's custom postback events. Sale, refund and chargeback are built in; anything else (add to cart, upsell, lead, registration) is user defined. `event={slug}` on any postback URL records one, and it gets its own column in campaign reports. `counts_revenue` adds the payout to revenue and dedupes by txid; otherwise it is counted once per click. |
+| `list_report_views` / `create_report_view` / `update_report_view` / `delete_report_view` / `set_active_report_view` | Saved report views: a name plus the report columns in the user's order, kept on the account. `active` is the view reports open on: `fewer`, `all`, or a view id. Views change which columns show, never the numbers. |
+| `set_account_timezone` | Set the IANA time zone (e.g. `America/New_York`) the account's reports count days, weekdays and hours in, or `null` to clear it. `get_campaign_stats`, `get_tracker_overview` and `get_property_stats` also take `tz` to override it for one call, and echo the zone they used as `timezone`. |
+| `list_affiliate_networks` / `create_affiliate_network` / `update_affiliate_network` / `delete_affiliate_network` | Manage affiliate networks. Their sales come back on the account's one postback URL (`get_universal_postback_url`); networks have no postback URL of their own. `conversion_param` is the click id name appended to the network's offer URLs. Set `amazon_tag` (e.g. `yourtagid-20`) on an Amazon network to auto-tag every Amazon link with `?tag=…` at click time. |
+| `list_offers` / `create_offer` / `update_offer` / `delete_offer` | Manage destination URLs ("offers"). Optionally tied to an affiliate network so the right conversion-param name is propagated on outbound clicks. An offer has no short link of its own; the link for an ad comes from a campaign. |
 | `list_landers` / `create_lander` / `update_lander` / `delete_lander` | Manage landing pages. Lander URLs may contain `{clickid}` tokens which the resolver expands. |
-| `list_traffic_sources` / `create_traffic_source` / `update_traffic_source` / `delete_traffic_source` | Manage **traffic sources** — the platforms you buy traffic from (Facebook, TikTok, Google, …). Each has a `name`, optional `platform`, and `token_params` mapping the source's click macros onto sub1..sub5 (e.g. Facebook sub1 = Ad ID `{{ad.id}}`). `list_traffic_sources` returns a `presets` catalog. Campaigns reference one via `traffic_source_id`. |
-| `list_tracking_pixels` / `create_tracking_pixel` / `update_tracking_pixel` / `delete_tracking_pixel` | Manage ad-platform pixels (Facebook, Google, TikTok, …). Each pixel has a `default_event` (e.g. `Purchase`, `Lead`, `CompletePayment`) and, for Facebook/TikTok, an optional server-side Conversions API `capi_token`. `list_tracking_pixels` also returns a `platforms` catalog with each platform's valid `events`, `defaultEvent`, and `capi` support. Pixels fire on short-link clicks and can be chosen as a campaign's conversion pixel. |
-| `list_campaigns` / `create_campaign` / `get_campaign` / `update_campaign` / `delete_campaign` / `duplicate_campaign` | Manage campaigns. `duplicate_campaign` deep-copies a campaign (settings + full routing flow + offer/lander pools) into a fresh short link named `COPY - {name}` (`COPY (1) - …` when copying a copy); stats and the unique direct-link tags are not carried over. One campaign = one tracked short link + N offers (weighted) + N optional landers + a per-campaign postback URL + a pixel snippet. A campaign references one saved traffic source via `traffic_source_id` and an optional `conversion_pixel_id` + `conversion_event` that fires **server-side via the pixel's CAPI token** when the campaign converts (a pixel with no CAPI token can't fire back). `report_value_mode` controls the value reported back — `payout` (real), `fixed` (a set number), or `adjusted` (payout − `report_value_adjust_pct`% − `report_value_adjust_flat`) so you can withhold your margin. Each campaign also returns a `click_url` (`…/click`) — the single, campaign-agnostic lander CTA link (same on every campaign, so one lander serves many) that always resolves to an offer (never a dead page); the campaign is read from the visitor's cookie or the ad's `?utm_campaign={slug}` (matched against any of the campaign's direct-link tags) forwarded onto the CTA. As of **0.22.0**, `create_campaign`/`update_campaign` gained **`direct_slugs`** — a campaign can claim MULTIPLE direct-link tags (an array of strings or `{ slug, label }` objects, each routing through the campaign's flow) so you run traffic straight to a lander with no tracker hop (`?utm_campaign={slug}` resolves the campaign at `/click` and stitches via the property tag); handy for migrating an older campaign or turning a lander already getting direct traffic into a campaign. The legacy single `direct_slug` is deprecated but still accepted (responses mirror it to the oldest slug). `fallback_url` is the never-dead-end guarantee. |
+| `list_traffic_sources` / `create_traffic_source` / `update_traffic_source` / `delete_traffic_source` | Manage **traffic sources**: the platforms you buy traffic from (Facebook, TikTok, Google, …). Each has a `name`, optional `platform`, and `token_params` mapping the source's click macros onto the UTM params (e.g. Facebook `utm_content` = Ad ID `{{ad.id}}`). `list_traffic_sources` returns a `presets` catalog. Campaigns reference one via `traffic_source_id`. |
+| `list_tracking_pixels` / `create_tracking_pixel` / `update_tracking_pixel` / `delete_tracking_pixel` / `test_tracking_pixel` | Manage ad-platform pixels (Facebook, Google, TikTok, …). Each pixel has a `default_event` (e.g. `Purchase`, `Lead`, `CompletePayment`) and, for Facebook/TikTok, an optional server-side Conversions API `capi_token` and a Meta `test_event_code` (test mode: events land in Test events and never count). Pixels report `last_sent_at` / `last_error` for their last server send, and `test_tracking_pixel` sends one test event (it needs a test event code). `list_tracking_pixels` also returns a `platforms` catalog with each platform's valid `events`, `defaultEvent`, and `capi` support. Pixels fire on short-link clicks and can be chosen as a campaign's conversion pixel. |
+| `list_campaigns` (`include_archived`) / `create_campaign` / `get_campaign` / `update_campaign` / `delete_campaign` / `duplicate_campaign` | Manage campaigns. `duplicate_campaign` deep-copies a campaign (settings + full routing flow + offer/lander pools) into a fresh short link named `COPY - {name}` (`COPY (1) - …` when copying a copy); stats and the unique direct-link tags are not carried over. One campaign = one tracked short link + N offers (weighted) + N optional landers + a pixel snippet. Sales come back on the account's one postback URL. A campaign references one saved traffic source via `traffic_source_id` and an optional `conversion_pixel_id` that receives the campaign's events **server-side via the pixel's CAPI token** (a pixel with no CAPI token can't fire back). `pixel_events` says which events reach it and as what, keyed by `conversion` (a sale) or a custom event slug, e.g. `{"conversion":{"event":"Purchase","first_only":true},"upsell":{"event":"Purchase"},"initiate_checkout":{"event":"InitiateCheckout"}}`; with none set, only sales are sent, as `conversion_event`. Add `&email=` to the postback URL so the platform can match buyers (hashed, never stored). `report_value_mode` controls the value reported back: `payout` (real), `fixed` (a set number), or `adjusted` (payout − `report_value_adjust_pct`% − `report_value_adjust_flat`) so you can withhold your margin. Each campaign also returns a `click_url` (`…/click`): the single, campaign-agnostic lander CTA link (same on every campaign, so one lander serves many) that always resolves to an offer (never a dead page); the campaign is read from the visitor's cookie or the ad's `?utm_campaign={slug}` (matched against any of the campaign's direct-link tags) forwarded onto the CTA. `direct_slugs` lets a campaign can claim MULTIPLE direct-link tags (an array of strings or `{ slug, label }` objects, each routing through the campaign's flow) so you run traffic straight to a lander with no tracker hop (`?utm_campaign={slug}` resolves the campaign at `/click` and stitches via the property tag); handy for migrating an older campaign or turning a lander already getting direct traffic into a campaign. The legacy single `direct_slug` is deprecated but still accepted (responses mirror it to the oldest slug). `fallback_url` is the never-dead-end guarantee. `open_in_browser` (0.32.0) sends a phone's tap to the offer out of Facebook's or Instagram's in-app browser to Safari or Chrome; app offers such as Amazon always open their app. |
 | `set_campaign_offers` / `set_campaign_landers` | Replace the campaign's offer/lander split. Items are `{ offer_id, weight }` / `{ lander_id, weight }`. |
-| `get_campaign_flow` / `set_campaign_flow` | Read/replace the campaign's **routing flow graph** (n8n-style). Nodes are `source` (one entry) / `lander` / `offer`; weighted edges go source→lander, source→offer, or lander→offer. The resolver walks this graph per click so a specific lander routes to its own specific offers — use it to split-test offers, divert a lander to a different offer, or insert a landing page before an offer. Saving also re-derives the flat offer/lander pools. |
-| `get_campaign_stats` | Full campaign report: visits, lander views, offer clicks, conversions, revenue, cost, profit, CTR/CR/EPC/ROI, recent events, plus Voluum-style `breakdowns` — grouped rows (`{key, visits, clicks, conversions, revenue, ctr, cr, epc}`) for 9 dimensions: utm_campaign / utm_source / utm_content / utm_term / lander / offer / country / device / day. Downstream events attribute to the utm values of the visit that minted their click_id; the `offer` dimension attributes each visit to the offer its click routed to (keyed by offer name); the `lander` dimension is the page the click came from (host+path — full paths for pages running the property tag, ad-platform hosts for straight-from-ad clicks); empty values group as `(none)`. **Drill-down:** pass any dimension as a filter (e.g. `utm_campaign` + read `breakdowns.offer` to see which split-test offer converts for that ad) — the whole report narrows to that slice; filters combine. Window: rolling `days` or an explicit `from`/`to` range. |
-| `list_properties` / `create_property` / `get_property` / `update_property` / `delete_property` | Manage **properties** — GTM/GA-style site containers. One property = one universal tag (`/t.js?p={key}`) the user installs on every page of their site. Every page auto-reports pageviews, time-on-page, scroll, outbound clicks, and conversions; campaign traffic auto-attributes by click. `create_property` requires an active custom domain (the tag is served first-party from the user's own domain so it tracks on iOS/Safari) and returns the bound `tracking_domain` + install `snippet`. |
+| `get_campaign_flow` / `set_campaign_flow` | Read/replace the campaign's **routing flow graph** (n8n-style). Nodes are `source` (one entry) / `lander` / `offer`; weighted edges go source→lander, source→offer, or lander→offer. The resolver walks this graph per click so a specific lander routes to its own specific offers. Use it to split-test offers, divert a lander to a different offer, or insert a landing page before an offer. Set `direct: true` on a lander the ad links straight to, so the campaign link goes on to its offers instead of back to the page. Saving also re-derives the flat offer/lander pools. |
+| `get_campaign_stats` | Full campaign report: visits, lander views, offer clicks, conversions (sales), refunds, chargebacks, custom events, net `revenue`, `gross_revenue`, `reversed_revenue`, cost, profit, CTR/CR/EPC/AOV/ROI (AOV is net revenue per sale), recent events, plus Voluum-style `breakdowns`: grouped rows (`{key, visits, clicks, conversions, refunds, chargebacks, revenue, custom, ctr, cr, epc}`) for 10 dimensions: utm_campaign / utm_source / utm_content / utm_term / lander / offer / country / device / day. Downstream events attribute to the utm values of the visit that minted their click_id; the `offer` dimension attributes each visit to the offer its click routed to (keyed by offer name); the `lander` dimension is the page the click came from (host+path; full paths for pages running the property tag, ad-platform hosts for straight-from-ad clicks); empty values group as `(none)`. **Drill-down:** pass any dimension as a filter (e.g. `utm_campaign` + read `breakdowns.offer` to see which split-test offer converts for that ad), and the whole report narrows to that slice; filters combine. Window: rolling `days` or an explicit `from`/`to` range. Pass `group` (up to 3 dimensions, custom tokens as `param:<name>`) for a stacked `report.rows` tree, which defaults to `offer`. `passed_dims` lists the tokens the URLs really carried, and `dim_labels` the names the user gave them, set with `update_campaign`. `breakdowns: false` skips the ten fixed breakdowns for a faster call. |
+| `list_properties` / `create_property` / `get_property` / `update_property` / `delete_property` | Manage **properties**: GTM/GA-style site containers. One property = one universal tag (`/t.js?p={key}`) the user installs on every page of their site. Every page auto-reports pageviews, time-on-page, scroll, outbound clicks, and conversions; campaign traffic auto-attributes by click. `create_property` requires an active custom domain (the tag is served first-party from the user's own domain so it tracks on iOS/Safari) and returns the bound `tracking_domain` + install `snippet`. |
 | `set_property_campaigns` | Link/unlink campaigns to a property (many-to-many, for the source split in reports). Items are `{ campaign_id }`. |
 | `get_property_stats` | Full property report: page views, unique visitors, outbound, conversions, revenue, avg time/scroll, top pages, source split (organic vs campaign), country/device/browser/referrer breakdowns, recent events. |
-| `list_property_pages` | Distinct pages seen across all the user's properties (most-viewed first): `{ url, path, title, property_name, views }`. Any page here can be used as a campaign **lander** — pass its `url` to `create_lander`, then wire that lander into a campaign flow with `set_campaign_flow`. |
-| `get_tracker_overview` | Unified Tracker dashboard across **both** streams (sites + campaigns) in one call: totals (page views / visitors / visits / offer clicks / conversions / revenue), daily activity, country/device/browser breakdowns, per-property + per-campaign rollups, a **per-UTM-campaign** rollup (auto-detected Google `utm_*` tags), and the 50 most recent events. The "is everything running and getting traffic?" view. |
-| `get_tracker_events` | Unified event log across both streams with full **search / filter / sort** over auto-detected UTM tags. `q` free-text, `stream`, `event`, exact `utm_*` filters, `sort`/`dir` (ts\|revenue\|utm_campaign\|utm_source\|country), pagination. Returns events + `facets` (distinct UTM values) + `total`. |
+| `list_property_pages` | Distinct pages seen across all the user's properties (most-viewed first): `{ url, path, title, property_name, views }`. Any page here can be used as a campaign **lander**: pass its `url` to `create_lander`, then wire that lander into a campaign flow with `set_campaign_flow`. |
+| `get_tracker_overview` | Unified Tracker dashboard across **both** streams (sites + campaigns) in one call: totals (page views / visitors / visits / offer clicks / conversions / revenue), daily activity, country/device/browser breakdowns, per-property + per-campaign rollups (each campaign with `lander_views` and `direct_lander`), a **per-UTM-campaign** rollup (auto-detected Google `utm_*` tags), a per-`utm_source` rollup with sales credited to the visit's UTMs, and the 50 most recent events. Window: `days` or `from`/`to`; scope with `offer_id` or `property_id`. The "is everything running and getting traffic?" view. |
+| `get_tracker_events` | Unified event log across both streams with full **search / filter / sort** over auto-detected UTM tags. `q` free-text, `stream`, `event`, exact `utm_*` filters, scope by `campaign_id` / `offer_id` / `property_id` / `link_id`, `days` or `from`/`to`, `sort`/`dir` on any column, pagination. Campaign rows carry the location, IP and UTMs of the visit on their click. Returns events + `facets` (distinct UTM values) + `total`. |
 
 ## Example prompts
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@buygolinks/mcp",
-  "version": "0.28.0",
-  "description": "MCP server for buygolinks.com — create and manage branded short links with Amazon affiliate geo-routing from any MCP-compatible AI agent (Claude Desktop, Cursor, Cline, Continue, Hermes).",
+  "version": "0.32.0",
+  "description": "MCP server for buygolinks.com: branded short links, campaign tracking, postbacks and reports from any MCP-compatible AI agent (Claude Desktop, Cursor, Cline, Continue, Hermes).",
   "type": "module",
   "bin": {
     "buygolinks-mcp": "src/index.js"
@@ -21,14 +21,12 @@
     "model-context-protocol",
     "buygolinks",
     "short-links",
-    "amazon-affiliate",
+    "link-tracking",
+    "affiliate-tracker",
+    "postback",
     "claude",
     "cursor"
   ],
   "homepage": "https://buygolinks.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/buygolinks/mcp.git"
-  },
   "license": "MIT"
 }