@buygolinks/mcp 0.1.0

package/README.md

@@ -0,0 +1,80 @@
+# @buygolinks/mcp
+
+Model Context Protocol (MCP) server for [buygolinks.com](https://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, and others.
+
+## Install
+
+No install needed — use `npx`:
+
+```bash
+npx @buygolinks/mcp
+```
+
+## Get an API key
+
+1. Sign in at [app.buygolinks.com](https://app.buygolinks.com)
+2. Go to **Settings** → **API Keys** → **New Key**
+3. Copy the `bgl_…` token (shown once)
+
+## Configure your client
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "buygolinks": {
+      "command": "npx",
+      "args": ["-y", "@buygolinks/mcp"],
+      "env": {
+        "BUYGOLINKS_API_KEY": "bgl_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You'll see a 🔌 icon — buygolinks tools are now available.
+
+### Cursor
+
+`.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` globally:
+
+```json
+{
+  "mcpServers": {
+    "buygolinks": {
+      "command": "npx",
+      "args": ["-y", "@buygolinks/mcp"],
+      "env": { "BUYGOLINKS_API_KEY": "bgl_your_key_here" }
+    }
+  }
+}
+```
+
+### Cline / Continue / Hermes / others
+
+Most MCP clients use the same shape. Point them at the `npx -y @buygolinks/mcp` command with `BUYGOLINKS_API_KEY` in the env.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `create_link` | Create a short link. Amazon URLs auto-detect ASIN and trigger geo-routing. |
+| `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. |
+
+## Example prompts
+
+> "Create a short link for `https://www.amazon.com/dp/B0CFG6RB6T` with the title 'Anker GaN charger'."
+
+> "How many clicks did I get last week? Which country drove the most?"
+
+> "Show me the top 5 most-clicked links and their countries."
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@buygolinks/mcp",
+  "version": "0.1.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": {
+    "buygolinks-mcp": "src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "buygolinks",
+    "short-links",
+    "amazon-affiliate",
+    "claude",
+    "cursor"
+  ],
+  "homepage": "https://buygolinks.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/buygolinks/mcp.git"
+  },
+  "license": "MIT"
+}

package/src/index.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * buygolinks MCP server (stdio).
+ *
+ * Exposes the buygolinks.com API as MCP tools so any MCP-compatible agent
+ * (Claude Desktop, Cursor, Cline, Continue, Hermes, etc.) can create and
+ * manage branded short links on the user's behalf.
+ *
+ * Auth: BUYGOLINKS_API_KEY env var (personal access token, format bgl_…).
+ *       Create one at https://app.buygolinks.com/settings/account.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+const API_BASE = process.env.BUYGOLINKS_API_BASE || 'https://app.buygolinks.com';
+const API_KEY  = process.env.BUYGOLINKS_API_KEY;
+
+if (!API_KEY) {
+  console.error('[buygolinks-mcp] BUYGOLINKS_API_KEY env var is required.');
+  console.error('  Create one at https://app.buygolinks.com/settings/account');
+  process.exit(1);
+}
+
+async function api(path, init = {}) {
+  const r = await fetch(`${API_BASE}${path}`, {
+    ...init,
+    headers: {
+      'Authorization': `Bearer ${API_KEY}`,
+      'Content-Type': 'application/json',
+      ...(init.headers || {}),
+    },
+  });
+  const text = await r.text();
+  let body;
+  try { body = text ? JSON.parse(text) : null; } catch { body = text; }
+  if (!r.ok) {
+    const code = body?.error || r.statusText || `http_${r.status}`;
+    throw new Error(`buygolinks API ${r.status}: ${code}`);
+  }
+  return body;
+}
+
+const TOOLS = [
+  {
+    name: 'create_link',
+    description:
+      'Create a new branded short link on buygolinks.com. If the destination is an Amazon product URL (contains /dp/ASIN), the ASIN is auto-extracted and the link will geo-route to the visitor\'s local Amazon storefront with the owner\'s affiliate tag applied. Returns the short URL and link metadata.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        destination_url: {
+          type: 'string',
+          description: 'The full URL the short link should redirect to. Must be http(s).',
+        },
+        title: {
+          type: 'string',
+          description: 'Optional human-readable title for the link. If omitted on an Amazon URL, the product title is scraped.',
+        },
+        source_label: {
+          type: 'string',
+          description: 'Optional source label (campaign tag) — appears in ascsubtag on Amazon redirects for attribution.',
+        },
+      },
+      required: ['destination_url'],
+    },
+  },
+  {
+    name: 'list_links',
+    description:
+      'List all short links owned by the authenticated user, including per-link click counts. Returns links in newest-first order. Use include_archived=true to also include archived links.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        include_archived: {
+          type: 'boolean',
+          description: 'If true, include archived links. Defaults to false.',
+        },
+      },
+    },
+  },
+  {
+    name: 'get_link_stats',
+    description:
+      'Get aggregated click analytics for a single short link: clicks by day, country, device, browser, referrer, hour-of-day, and weekday. Use the link id returned from list_links or create_link.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        link_id: {
+          type: 'number',
+          description: 'The numeric id of the link (from list_links / create_link).',
+        },
+        days: {
+          type: 'number',
+          description: 'Window size in days (1–90). Defaults to 14.',
+        },
+      },
+      required: ['link_id'],
+    },
+  },
+  {
+    name: 'get_overview_stats',
+    description:
+      'Get account-wide click analytics across all of the user\'s links: total clicks, clicks by day, top countries, devices, browsers, referrers, peak hour and weekday. Use this for "how is my account doing" type questions.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days: {
+          type: 'number',
+          description: 'Window size in days (1–90). Defaults to 14.',
+        },
+      },
+    },
+  },
+];
+
+const server = new Server(
+  { name: 'buygolinks', version: '0.1.0' },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args } = req.params;
+  try {
+    let result;
+    switch (name) {
+      case 'create_link': {
+        result = await api('/api/links', {
+          method: 'POST',
+          body: JSON.stringify({
+            destination_url: args.destination_url,
+            title: args.title,
+            source_label: args.source_label,
+          }),
+        });
+        break;
+      }
+      case 'list_links': {
+        const qs = args?.include_archived ? '?include_archived=1' : '';
+        result = await api(`/api/links${qs}`);
+        break;
+      }
+      case 'get_link_stats': {
+        const days = args?.days ? `?days=${Number(args.days)}` : '';
+        result = await api(`/api/stats/link/${Number(args.link_id)}${days}`);
+        break;
+      }
+      case 'get_overview_stats': {
+        const days = args?.days ? `?days=${Number(args.days)}` : '';
+        result = await api(`/api/stats/overview${days}`);
+        break;
+      }
+      default:
+        throw new Error(`unknown tool: ${name}`);
+    }
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+  } catch (err) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: String(err.message || err) }],
+    };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error('[buygolinks-mcp] ready');