@buygolinks/mcp 0.16.0 → 0.20.0

package/README.md

@@ -63,7 +63,8 @@ Most MCP clients use the same shape. Point them at the `npx -y @buygolinks/mcp`
 | Tool | Description |
 |---|---|
 | `create_link` | Create a short link. The destination URL is passed through untouched (include your own affiliate tag). |
-| `update_link` | Edit a link's title, source label, custom domain, password, archive state, or custom alias (e.g. `summer-sale` → `https://click.example.com/summer-sale`). |
+| `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. |
 | `get_link_stats` | Per-link analytics (by day, country, device, browser, hour, weekday). |
 | `get_overview_stats` | Account-wide analytics. |
@@ -76,7 +77,7 @@ Most MCP clients use the same shape. Point them at the `npx -y @buygolinks/mcp`
 | `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` | Manage campaigns. 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 CAPI when configured) when the campaign converts. Each campaign also returns a `click_url` (`…/click?cmp={code}`) — the defined lander CTA link that always resolves to an offer (never a dead page). Set `direct_slug` to run traffic straight to a lander with no tracker hop (`?utm_campaign={direct_slug}` stitches via the property tag); `fallback_url` is the never-dead-end guarantee. |
+| `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 slug 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 CAPI when configured) when the campaign converts. 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={direct_slug}` forwarded onto the CTA. Set `direct_slug` to run traffic straight to a lander with no tracker hop (`?utm_campaign={direct_slug}` resolves the campaign at `/click` and stitches via the property tag); `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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buygolinks/mcp",
-  "version": "0.16.0",
+  "version": "0.20.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

@@ -75,11 +75,12 @@ const TOOLS = [
   {
     name: 'update_link',
     description:
-      'Update an existing short link. Supports renaming (title), changing the campaign source label, swapping the branded domain it resolves under (domain_id), setting a memorable custom alias (alias), archiving/unarchiving, and password-protecting the link. Pass `alias` to give the link a memorable URL slug on its custom domain (e.g. alias="summer-sale" → https://click.example.com/summer-sale). Aliases require the link to be on a custom domain. Setting `alias` REPLACES any previous alias — the old alias stops resolving immediately and is freed for any other link to claim. The link\'s original random short code (link.code) keeps working forever regardless of alias changes. Pass alias="" or alias=null to remove the alias. Changing the link\'s `domain_id` clears the alias automatically. To set or change the password, pass `password` as a non-empty string. To remove password protection, pass an empty string for `password`. To move the link back to the platform default (buygolinks.com), pass `domain_id: null`. Returns the updated link row including `short_domain`, `alias`, and `password_protected` (boolean — the plaintext is never returned).',
+      'Update an existing short link. Supports changing where it redirects (destination_url), renaming (title), changing the campaign source label, swapping the branded domain it resolves under (domain_id), setting a memorable custom alias (alias), archiving/unarchiving, and password-protecting the link. Pass `destination_url` to repoint the link at a new target — the short code, alias, and click history are preserved; only the redirect destination moves (the ASIN is re-extracted automatically for Amazon /dp/ URLs). Pass `alias` to give the link a memorable URL slug on its custom domain (e.g. alias="summer-sale" → https://click.example.com/summer-sale). Aliases require the link to be on a custom domain. Setting `alias` REPLACES any previous alias — the old alias stops resolving immediately and is freed for any other link to claim. The link\'s original random short code (link.code) keeps working forever regardless of alias changes. Pass alias="" or alias=null to remove the alias. Changing the link\'s `domain_id` clears the alias automatically. To set or change the password, pass `password` as a non-empty string. To remove password protection, pass an empty string for `password`. To move the link back to the platform default (buygolinks.com), pass `domain_id: null`. Returns the updated link row including `short_domain`, `alias`, and `password_protected` (boolean — the plaintext is never returned).',
     inputSchema: {
       type: 'object',
       properties: {
         link_id:      { type: 'number', description: 'The numeric id of the link (from list_links / create_link).' },
+        destination_url: { type: 'string', description: 'New destination URL the short link redirects to (must be http(s)). The short code, alias, and click history are preserved.' },
         title:        { type: 'string', description: 'New display title.' },
         source_label: { type: 'string', description: 'New source label (campaign tag).' },
         archived:     { type: 'boolean', description: 'Set true to archive the link, false to unarchive.' },
@@ -90,6 +91,18 @@ const TOOLS = [
       required: ['link_id'],
     },
   },
+  {
+    name: 'refresh_link_image',
+    description:
+      'Re-attempt fetching the product/preview image for an existing short link. Re-runs the same best-effort scrape used at link creation — the Amazon product-image scraper for Amazon /dp/ links, or a generic Open Graph (og:image / twitter:image) scrape for any other URL — and rehosts the result on buygolinks storage. Use this when a link was created without an image (the thumbnail shows a letter/placeholder) or to update a stale image. Returns { found: true, link } with the updated `product_image_url` on success, or { found: false } if no image could be fetched this time (the existing image, if any, is left untouched — try again later).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        link_id: { type: 'number', description: 'The numeric id of the link (from list_links / create_link).' },
+      },
+      required: ['link_id'],
+    },
+  },
   {
     name: 'list_links',
     description:
@@ -193,7 +206,7 @@ const TOOLS = [
   {
     name: 'create_affiliate_network',
     description:
-      'Add a new affiliate network. The server mints a per-network postback URL (https://buygolinks.com/postback/n/{token}) the user pastes into the network. Returns the network row including postback_url.',
+      'Add a new affiliate network. The server mints a per-network postback URL (https://buygolinks.com/postback/n/{token}) the user pastes into the network. The postback accepts ?{conversion_param}={clickid}&{payout_param}={payout}&{currency_param}={currency}&{txid_param}={txid} — payout, currency, and txid are optional. Returns the network row including postback_url.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -201,6 +214,7 @@ const TOOLS = [
         conversion_param: { type: 'string', description: 'What the network calls the click id in its postback (default "clickid").' },
         payout_param:     { type: 'string', description: 'What the network calls the payout amount (default "payout").' },
         currency_param:   { type: 'string', description: 'What the network calls the currency code (default "currency").' },
+        txid_param:       { type: 'string', description: 'What the network calls the transaction/order id in its postback (default "txid"). Stored on the conversion for reconciliation/dedupe.' },
       },
       required: ['name'],
     },
@@ -216,6 +230,7 @@ const TOOLS = [
         conversion_param: { type: 'string' },
         payout_param: { type: 'string' },
         currency_param: { type: 'string' },
+        txid_param: { type: 'string' },
         archived: { type: 'boolean' },
       },
       required: ['network_id'],
@@ -428,7 +443,7 @@ const TOOLS = [
   {
     name: 'create_campaign',
     description:
-      'Create a campaign. A campaign mints one short link (campaign.code) that the user pastes into Facebook / TikTok / etc. The resolver mints a click_id per visit, optionally routes through a lander (weighted), then redirects to an offer (weighted). The response also includes a `click_url` (`…/click?cmp={code}`) — the DEFINED lander click URL the user pastes into their lander\'s CTA button; it always resolves to an offer (chosen by the flow graph), never a lander, never a dead page. For DIRECT-LINK campaigns (ad points straight at the lander, no tracker hop), set `direct_slug` and put `?utm_campaign={direct_slug}` on the ad URL — the property tag then stitches the page view to this campaign. `fallback_url` guarantees the click never dead-ends. Conversions come back via the campaign\'s postback URL or the affiliate network\'s postback URL. You can optionally attach offer_ids / lander_ids inline with matching offer_weights / lander_weights arrays for a one-call setup.',
+      'Create a campaign. A campaign mints one short link (campaign.code) that the user pastes into Facebook / TikTok / etc. The resolver mints a click_id per visit, optionally routes through a lander (weighted), then redirects to an offer (weighted). The response also includes a `click_url` (`…/click`) — the single, campaign-agnostic DEFINED lander click URL the user pastes into their lander\'s CTA button. It\'s the same on every campaign, so one lander can be reused across many; the campaign is resolved at click time from the visitor\'s `bgl_clk_{code}` cookie (short-link traffic) or the ad\'s `?utm_campaign={direct_slug}` that the lander forwards onto the CTA (direct-link). It always resolves to an offer (chosen by the flow graph), never a lander, never a dead page. For DIRECT-LINK campaigns (ad points straight at the lander, no tracker hop), set `direct_slug`, put `?utm_campaign={direct_slug}` on the ad URL, and have the lander forward that utm_campaign onto the CTA — `/click` resolves the campaign from it and the property tag stitches the page view too. `fallback_url` guarantees the click never dead-ends. Conversions come back via the campaign\'s postback URL or the affiliate network\'s postback URL. You can optionally attach offer_ids / lander_ids inline with matching offer_weights / lander_weights arrays for a one-call setup.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -443,6 +458,10 @@ const TOOLS = [
         domain_id: { type: ['number', 'null'], description: 'Optional id of one of the user\'s active custom domains (from list_domains). The campaign\'s short link will resolve at that hostname. If omitted, defaults to the user\'s first active custom domain, or buygolinks.com if they have none. Pass null to force the platform default.' },
         conversion_pixel_id: { type: ['number', 'null'], description: 'Optional id of one of the user\'s tracking pixels (from list_tracking_pixels) to fire when this campaign converts (server-side via the pixel\'s CAPI token when set). Pass null for no conversion pixel.' },
         conversion_event: { type: 'string', description: 'Event name to fire on conversion (e.g. "Purchase", "Lead", "CompletePayment"). Must be a valid event for the conversion pixel\'s platform; defaults to that pixel\'s default_event.' },
+        report_value_mode: { type: 'string', enum: ['payout', 'fixed', 'adjusted'], description: 'What revenue VALUE to report back to the ad platform on a CAPI conversion. "payout" (default) = the real conversion payout; "fixed" = always report report_value_fixed (e.g. 1); "adjusted" = real payout minus report_value_adjust_pct % then minus report_value_adjust_flat (so the user\'s margin/cost is withheld from what the platform optimizes against). Floored at 0.' },
+        report_value_fixed: { type: ['number', 'null'], description: 'Used when report_value_mode = "fixed": the exact value (USD) reported on every conversion regardless of real payout.' },
+        report_value_adjust_pct: { type: ['number', 'null'], description: 'Used when report_value_mode = "adjusted": percentage (0–100) subtracted from the real payout first (e.g. 10 reports payout − 10%).' },
+        report_value_adjust_flat: { type: ['number', 'null'], description: 'Used when report_value_mode = "adjusted": flat amount (USD) subtracted after the percentage.' },
         direct_slug: { type: ['string', 'null'], description: 'Optional direct-link tag, unique per user (lowercased alnum + dashes, e.g. "bsu-fb-cold"). For running traffic STRAIGHT to a lander with no tracker hop: put `?utm_campaign={direct_slug}` on the ad URL and the property tag stitches the page view to this campaign. Returns 409 (direct_slug_taken) if another campaign already uses it. Pass null to clear.' },
         fallback_url: { type: ['string', 'null'], description: 'Optional URL the click falls back to when the flow yields no live offer — the never-dead-end guarantee. Pass null to use the platform default.' },
         offer_ids: { type: 'array', items: { type: 'number' } },
@@ -476,6 +495,10 @@ const TOOLS = [
         domain_id: { type: ['number', 'null'], description: 'Id of one of the user\'s active custom domains, or null to move the campaign back to buygolinks.com.' },
         conversion_pixel_id: { type: ['number', 'null'], description: 'Id of a tracking pixel to fire on conversion, or null to clear.' },
         conversion_event: { type: 'string', description: 'Event the conversion pixel fires (must be valid for that pixel\'s platform).' },
+        report_value_mode: { type: 'string', enum: ['payout', 'fixed', 'adjusted'], description: 'What revenue value to report back to the ad platform on conversion: "payout" (real), "fixed" (report_value_fixed), or "adjusted" (real payout − report_value_adjust_pct% − report_value_adjust_flat, floored at 0).' },
+        report_value_fixed: { type: ['number', 'null'], description: 'Fixed value (USD) reported on every conversion when report_value_mode = "fixed". Null to clear.' },
+        report_value_adjust_pct: { type: ['number', 'null'], description: 'Percentage (0–100) subtracted from real payout when report_value_mode = "adjusted". Null to clear.' },
+        report_value_adjust_flat: { type: ['number', 'null'], description: 'Flat USD amount subtracted (after the %) when report_value_mode = "adjusted". Null to clear.' },
         direct_slug: { type: ['string', 'null'], description: 'Direct-link tag for utm_campaign-based stitching (unique per user), or null to clear. Returns 409 (direct_slug_taken) on collision.' },
         fallback_url: { type: ['string', 'null'], description: 'Never-dead-end fallback URL when no live offer exists, or null to use the platform default.' },
         archived: { type: 'boolean' },
@@ -488,6 +511,11 @@ const TOOLS = [
     description: 'Delete a campaign. The short link stops resolving immediately. Tracker events for this campaign are also deleted (cascade).',
     inputSchema: { type: 'object', properties: { campaign_id: { type: 'number' } }, required: ['campaign_id'] },
   },
+  {
+    name: 'duplicate_campaign',
+    description: 'Deep-copy a campaign: clones the campaign settings plus its full routing flow (source → landers → offers graph and split-test weights) and its offer/lander pools. The copy gets a fresh short link + postback token and a name like "COPY - {original}" (or "COPY (1) - {original}", "COPY (2) - …" when copying a copy). Stats are NOT copied; the direct-link slug is left blank (it must be unique). Returns the new campaign, including its short_url/click_url. Useful for spinning up a new geo/angle variant of a working campaign without rebuilding the flow.',
+    inputSchema: { type: 'object', properties: { campaign_id: { type: 'number' } }, required: ['campaign_id'] },
+  },
   {
     name: 'set_campaign_offers',
     description: 'Replace the campaign\'s offer split with the supplied items. Each item is { offer_id, weight }. Weight is an integer; higher = more traffic. To direct all traffic to one offer use weight=100 for that offer and don\'t include the others.',
@@ -672,6 +700,12 @@ const TOOLS = [
       'List the distinct pages observed across ALL the user\'s properties (the pageview stream), most-viewed first. Each entry is `{ url, path, title, property_id, property_name, views }`. Any of these pages can be used as a campaign LANDER — pass its `url` to `create_lander` (the page title makes a good lander name) and then wire the resulting lander into a campaign flow via `set_campaign_flow`. Use this to turn a real page on the user\'s site into a lander without retyping its URL.',
     inputSchema: { type: 'object', properties: {} },
   },
+  {
+    name: 'list_observed_campaign_tags',
+    description:
+      'List the distinct `utm_campaign` values that have actually been SEEN arriving on the user\'s properties/visits over the last 90 days, most-active first. Each entry is `{ utm_campaign, events, utm_source, utm_medium, lander_url, claimed_by }` where `claimed_by` is `{ id, name }` of the BGL campaign whose `direct_slug` already owns that tag, or null if unclaimed. Use this to WIRE UP AN ALREADY-RUNNING DIRECT-LINK CAMPAIGN: when an ad on FB/Google points straight at a lander (no tracker hop) with `?utm_campaign={tag}`, that tag shows up here once the universal property tag reports a page view. Pick an unclaimed tag and set it as a campaign\'s `direct_slug` (via `update_campaign`) so BGL attributes that traffic — and its `/click` CTA — to the right campaign + offer. Skip tags whose `claimed_by` is non-null (another campaign already owns them).',
+    inputSchema: { type: 'object', properties: {} },
+  },
   {
     name: 'get_tracker_overview',
     description:
@@ -735,6 +769,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
       }
       case 'update_link': {
         const body = {};
+        if (typeof args.destination_url === 'string') body.destination_url = args.destination_url;
         if (typeof args.title === 'string')        body.title = args.title;
         if (typeof args.source_label === 'string') body.source_label = args.source_label;
         if (typeof args.archived === 'boolean')    body.archived = args.archived;
@@ -751,6 +786,12 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         });
         break;
       }
+      case 'refresh_link_image': {
+        result = await api(`/api/links/${Number(args.link_id)}/refresh-image`, {
+          method: 'POST',
+        });
+        break;
+      }
       case 'list_links': {
         const qs = args?.include_archived ? '?include_archived=1' : '';
         result = await api(`/api/links${qs}`);
@@ -796,6 +837,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         if (typeof args.conversion_param === 'string') body.conversion_param = args.conversion_param;
         if (typeof args.payout_param === 'string')     body.payout_param     = args.payout_param;
         if (typeof args.currency_param === 'string')   body.currency_param   = args.currency_param;
+        if (typeof args.txid_param === 'string')       body.txid_param       = args.txid_param;
         result = await api('/api/affiliate-networks', { method: 'POST', body: JSON.stringify(body) });
         break;
       }
@@ -805,6 +847,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         if (typeof args.conversion_param === 'string') body.conversion_param = args.conversion_param;
         if (typeof args.payout_param === 'string')     body.payout_param = args.payout_param;
         if (typeof args.currency_param === 'string')   body.currency_param = args.currency_param;
+        if (typeof args.txid_param === 'string')       body.txid_param = args.txid_param;
         if (typeof args.archived === 'boolean')        body.archived = args.archived;
         result = await api(`/api/affiliate-networks/${Number(args.network_id)}`, { method: 'PATCH', body: JSON.stringify(body) });
         break;
@@ -939,6 +982,10 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         if ('domain_id' in args)                body.domain_id = args.domain_id;
         if ('traffic_source_id' in args)        body.traffic_source_id = args.traffic_source_id;
         if ('conversion_pixel_id' in args)      body.conversion_pixel_id = args.conversion_pixel_id;
+        if (typeof args.report_value_mode === 'string') body.report_value_mode = args.report_value_mode;
+        if ('report_value_fixed' in args)       body.report_value_fixed = args.report_value_fixed;
+        if ('report_value_adjust_pct' in args)  body.report_value_adjust_pct = args.report_value_adjust_pct;
+        if ('report_value_adjust_flat' in args) body.report_value_adjust_flat = args.report_value_adjust_flat;
         if ('direct_slug' in args)              body.direct_slug = args.direct_slug;
         if ('fallback_url' in args)             body.fallback_url = args.fallback_url;
         if (Array.isArray(args.offer_ids))      body.offer_ids = args.offer_ids;
@@ -962,6 +1009,10 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         if (typeof args.cost_value === 'number') body.cost_value = args.cost_value;
         if ('domain_id' in args)                body.domain_id = args.domain_id;
         if ('conversion_pixel_id' in args)      body.conversion_pixel_id = args.conversion_pixel_id;
+        if (typeof args.report_value_mode === 'string') body.report_value_mode = args.report_value_mode;
+        if ('report_value_fixed' in args)       body.report_value_fixed = args.report_value_fixed;
+        if ('report_value_adjust_pct' in args)  body.report_value_adjust_pct = args.report_value_adjust_pct;
+        if ('report_value_adjust_flat' in args) body.report_value_adjust_flat = args.report_value_adjust_flat;
         if ('direct_slug' in args)              body.direct_slug = args.direct_slug;
         if ('fallback_url' in args)             body.fallback_url = args.fallback_url;
         if (typeof args.archived === 'boolean') body.archived = args.archived;
@@ -972,6 +1023,10 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         result = await api(`/api/campaigns/${Number(args.campaign_id)}`, { method: 'DELETE' });
         break;
       }
+      case 'duplicate_campaign': {
+        result = await api(`/api/campaigns/${Number(args.campaign_id)}/duplicate`, { method: 'POST' });
+        break;
+      }
       case 'set_campaign_offers': {
         result = await api(`/api/campaigns/${Number(args.campaign_id)}/offers`, {
           method: 'PUT', body: JSON.stringify({ items: args.items }),
@@ -1043,6 +1098,10 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         result = await api('/api/property-pages');
         break;
       }
+      case 'list_observed_campaign_tags': {
+        result = await api('/api/observed-campaign-tags');
+        break;
+      }
 
       case 'get_tracker_overview': {
         const days = args?.days ? `?days=${Number(args.days)}` : '';