@buygolinks/mcp 0.22.0 → 0.23.0

package/README.md

@@ -80,7 +80,8 @@ Most MCP clients use the same shape. Point them at the `npx -y @buygolinks/mcp`
 | `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. |
 | `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, breakdowns, recent events. |
+| `get_campaign_stats` | Full campaign report (TRACKER stream): visits, lander views, offer clicks, conversions, revenue, cost, profit, CTR/CR/EPC/ROI, breakdowns, recent events. |
+| `get_campaign_funnel` | Per-landing-page funnel (PROPERTY tag stream): each page's views, unique views, CTA clicks, conversions, page CTR & CVR, plus `paid_facebook_views` (pageviews carrying an fbclid). The right report for **direct-link** campaigns (ad → lander, no tracker hop). |
 | `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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buygolinks/mcp",
-  "version": "0.22.0",
+  "version": "0.23.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).",
   "type": "module",
   "bin": {

package/src/index.js

@@ -609,7 +609,7 @@ const TOOLS = [
   {
     name: 'get_campaign_stats',
     description:
-      'Get a campaign\'s full report: totals (visits / unique / lander_views / offer_clicks / conversions / revenue / cost / profit / CTR / CR / EPC / ROI), by_day / by_country / by_device / by_browser / by_referrer / by_hour, per-offer and per-lander performance, and the 50 most recent events.',
+      'Get a campaign\'s full report: totals (visits / unique / lander_views / offer_clicks / conversions / revenue / cost / profit / CTR / CR / EPC / ROI), by_day / by_country / by_device / by_browser / by_referrer / by_hour, per-offer and per-lander performance, and the 50 most recent events. This reads the TRACKER stream (short-link → lander → offer hops). For DIRECT-LINK campaigns (ad straight to a lander, tracked only by the property tag) use get_campaign_funnel for per-page CTR instead.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -619,6 +619,19 @@ const TOOLS = [
       required: ['campaign_id'],
     },
   },
+  {
+    name: 'get_campaign_funnel',
+    description:
+      'Get a campaign\'s per-landing-page funnel from the PROPERTY tag stream: for each page, its views, unique views, CTA clicks (outbound), conversions, and the derived page CTR (CTA clicks ÷ views) and CVR (conversions ÷ views). Also returns campaign totals including paid_facebook_views (pageviews carrying an fbclid — i.e. paid Facebook/Instagram traffic). This is the right tool for DIRECT-LINK campaigns where the ad points straight at the landing page (no buygolinks hop) and answers "what is the click-through rate of my landing page?". Requires the page to have the Property tag installed and the ad URL to carry ?utm_campaign={direct_slug}.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        campaign_id: { type: 'number' },
+        days: { type: 'number', description: 'Window size in days (1–90). Defaults to 30.' },
+      },
+      required: ['campaign_id'],
+    },
+  },
 
   // ─── Tracker: properties (GTM/GA-style site containers) ─────────────────
   {
@@ -1062,6 +1075,11 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         result = await api(`/api/campaigns/${Number(args.campaign_id)}/stats${days}`);
         break;
       }
+      case 'get_campaign_funnel': {
+        const days = args?.days ? `?days=${Number(args.days)}` : '';
+        result = await api(`/api/campaigns/${Number(args.campaign_id)}/funnel${days}`);
+        break;
+      }
 
       case 'list_properties': {
         result = await api('/api/properties');