atracker-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,113 @@
+# ATracker MCP Server
+
+[Model Context Protocol](https://modelcontextprotocol.io) server for managing your self-hosted ATracker instance from AI agents like Cursor and Claude Desktop.
+
+## Installation
+
+```bash
+npm install -g atracker-mcp-server
+```
+
+## Configuration
+
+### Cursor (`~/.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "atracker": {
+      "command": "npx",
+      "args": ["-y", "atracker-mcp-server"],
+      "env": {
+        "ATRACKER_URL": "http://your-tracker-ip",
+        "ATRACKER_TOKEN": "YOUR_API_TOKEN"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "atracker": {
+      "command": "npx",
+      "args": ["-y", "atracker-mcp-server"],
+      "env": {
+        "ATRACKER_URL": "http://your-tracker-ip",
+        "ATRACKER_TOKEN": "YOUR_API_TOKEN"
+      }
+    }
+  }
+}
+```
+
+## Getting an API Token
+
+1. Open your tracker in a browser.
+2. Go to **Settings → API Tokens**.
+3. Click **Create token**, give it a name, and select **All resources** (*) for full MCP access.
+4. Copy the token (it is shown only once).
+
+## Available Tools
+
+### Campaigns
+- `list_campaigns` — List all campaigns (optional status filter)
+- `get_campaign` — Get campaign details by ID
+- `create_campaign` — Create a new campaign
+- `update_campaign` — Update an existing campaign
+- `pause_campaign` — Pause a campaign
+- `resume_campaign` — Resume a paused campaign
+- `delete_campaign` — Archive a campaign
+
+### Offers
+- `list_offers` — List all offers
+- `get_offer` — Get offer details by ID
+- `create_offer` — Create a new offer
+- `update_offer` — Update an existing offer
+- `delete_offer` — Archive an offer
+
+### Flows
+- `list_flows` — List flows (optional campaign_id filter)
+- `get_flow` — Get flow details by ID
+- `create_flow` — Create a new flow
+- `update_flow` — Update an existing flow
+- `delete_flow` — Delete a flow
+
+### Landing Pages
+- `list_landings` — List landing pages
+- `get_landing` — Get landing page details by ID
+- `create_landing` — Create a new landing page
+- `update_landing` — Update an existing landing page
+- `delete_landing` — Archive a landing page
+
+### Traffic Sources
+- `list_sources` — List traffic sources
+- `get_source` — Get traffic source details by ID
+- `create_source` — Create a new traffic source
+- `update_source` — Update a traffic source
+- `delete_source` — Delete a traffic source
+
+### Domains
+- `list_domains` — List domains
+- `get_domain` — Get domain details by ID
+- `create_domain` — Create a new domain
+- `delete_domain` — Delete a domain
+
+### Reports & Conversions
+- `get_reports` — Get report data with date range and grouping
+- `get_conversions` — Get conversion data with filters
+
+### System
+- `get_system_status` — Get tracker system status
+- `get_settings` — Get tracker settings
+- `update_settings` — Update tracker settings
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ATRACKER_URL` | Yes | Tracker URL (e.g. `http://213.176.94.21`) |
+| `ATRACKER_TOKEN` | Yes | API token from Settings → API Tokens |

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "atracker-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP Server for ATracker self-hosted ad tracker",
+  "type": "module",
+  "bin": {
+    "atracker-mcp-server": "./src/index.js"
+  },
+  "files": ["src"],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "UNLICENSED"
+}

package/src/client.js

@@ -0,0 +1,48 @@
+class ApiError extends Error {
+  constructor(status, body) {
+    super(body?.error || `HTTP ${status}`);
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export function createClient(url, token) {
+  const base = (url || '').replace(/\/+$/, '');
+
+  async function request(method, path, { body, query } = {}) {
+    let fullUrl = `${base}/api/v1${path}`;
+    if (query) {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(query)) {
+        if (v !== undefined && v !== null && v !== '') params.set(k, String(v));
+      }
+      const qs = params.toString();
+      if (qs) fullUrl += `?${qs}`;
+    }
+
+    const opts = {
+      method,
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+      },
+    };
+    if (body && method !== 'GET') opts.body = JSON.stringify(body);
+
+    const res = await fetch(fullUrl, opts);
+    if (res.status === 204) return null;
+    let data;
+    try { data = await res.json(); } catch { data = null; }
+    if (!res.ok) throw new ApiError(res.status, data);
+    return data;
+  }
+
+  return {
+    get: (path, opts) => request('GET', path, opts),
+    post: (path, body, opts) => request('POST', path, { ...opts, body }),
+    put: (path, body, opts) => request('PUT', path, { ...opts, body }),
+    patch: (path, body, opts) => request('PATCH', path, { ...opts, body }),
+    del: (path, opts) => request('DELETE', path, opts),
+  };
+}

package/src/index.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createClient } from './client.js';
+import { registerCampaignTools } from './tools/campaigns.js';
+import { registerOfferTools } from './tools/offers.js';
+import { registerFlowTools } from './tools/flows.js';
+import { registerLandingTools } from './tools/landings.js';
+import { registerSourceTools } from './tools/sources.js';
+import { registerDomainTools } from './tools/domains.js';
+import { registerReportTools } from './tools/reports.js';
+import { registerStatusTools } from './tools/status.js';
+import { registerSettingsTools } from './tools/settings.js';
+
+const url = process.env.ATRACKER_URL;
+const token = process.env.ATRACKER_TOKEN;
+
+if (!url || !token) {
+  process.stderr.write('Error: ATRACKER_URL and ATRACKER_TOKEN environment variables are required.\n');
+  process.stderr.write('Example:\n');
+  process.stderr.write('  ATRACKER_URL=http://your-tracker ATRACKER_TOKEN=atk_... npx atracker-mcp-server\n');
+  process.exit(1);
+}
+
+const client = createClient(url, token);
+
+const server = new McpServer({
+  name: 'atracker',
+  version: '1.0.0',
+});
+
+registerCampaignTools(server, client);
+registerOfferTools(server, client);
+registerFlowTools(server, client);
+registerLandingTools(server, client);
+registerSourceTools(server, client);
+registerDomainTools(server, client);
+registerReportTools(server, client);
+registerStatusTools(server, client);
+registerSettingsTools(server, client);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/tools/campaigns.js

@@ -0,0 +1,47 @@
+export function registerCampaignTools(server, client) {
+  server.tool('list_campaigns', 'List all campaigns. Optional filter by status.', { status: { type: 'string', description: 'active or paused', enum: ['active', 'paused'] } }, async ({ status }) => {
+    const rows = await client.get('/campaigns', { query: { status } });
+    return { content: [{ type: 'text', text: JSON.stringify(rows, null, 2) }] };
+  });
+
+  server.tool('get_campaign', 'Get campaign details by ID.', { id: { type: 'string', description: 'Campaign UUID' } }, async ({ id }) => {
+    const row = await client.get(`/campaigns/${id}`);
+    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+  });
+
+  server.tool('create_campaign', 'Create a new campaign.', {
+    name: { type: 'string', description: 'Campaign name' },
+    alias: { type: 'string', description: 'URL alias (optional)' },
+    domain: { type: 'string', description: 'Domain (optional)' },
+    traffic_source_id: { type: 'string', description: 'Traffic source UUID (optional)' },
+  }, async (args) => {
+    const row = await client.post('/campaigns', args);
+    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+  });
+
+  server.tool('update_campaign', 'Update an existing campaign.', {
+    id: { type: 'string', description: 'Campaign UUID' },
+    name: { type: 'string', description: 'New name (optional)' },
+    alias: { type: 'string', description: 'New alias (optional)' },
+    domain: { type: 'string', description: 'New domain (optional)' },
+  }, async ({ id, ...rest }) => {
+    const body = Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== undefined));
+    const row = await client.put(`/campaigns/${id}`, body);
+    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+  });
+
+  server.tool('pause_campaign', 'Pause a campaign.', { id: { type: 'string', description: 'Campaign UUID' } }, async ({ id }) => {
+    const row = await client.patch(`/campaigns/${id}/status`, { status: 'paused' });
+    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+  });
+
+  server.tool('resume_campaign', 'Resume a paused campaign.', { id: { type: 'string', description: 'Campaign UUID' } }, async ({ id }) => {
+    const row = await client.patch(`/campaigns/${id}/status`, { status: 'active' });
+    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+  });
+
+  server.tool('delete_campaign', 'Archive (soft-delete) a campaign.', { id: { type: 'string', description: 'Campaign UUID' } }, async ({ id }) => {
+    await client.del(`/campaigns/${id}`);
+    return { content: [{ type: 'text', text: 'Campaign archived.' }] };
+  });
+}

package/src/tools/domains.js

@@ -0,0 +1,21 @@
+export function registerDomainTools(server, client) {
+  server.tool('list_domains', 'List domains. Optional filter by status.', { status: { type: 'string', description: 'active or paused', enum: ['active', 'paused'] } }, async ({ status }) => {
+    const rows = await client.get('/domains', { query: { status } });
+    return { content: [{ type: 'text', text: JSON.stringify(rows, null, 2) }] };
+  });
+
+  server.tool('get_domain', 'Get domain details by ID.', { id: { type: 'string', description: 'Domain UUID' } }, async ({ id }) => {
+    const row = await client.get(`/domains/${id}`);
+    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+  });
+
+  server.tool('create_domain', 'Create a new domain.', { domain: { type: 'string', description: 'Domain name (e.g. trk.example.com)' } }, async (args) => {
+    const row = await client.post('/domains', args);
+    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+  });
+
+  server.tool('delete_domain', 'Delete a domain.', { id: { type: 'string', description: 'Domain UUID' } }, async ({ id }) => {
+    await client.del(`/domains/${id}`);
+    return { content: [{ type: 'text', text: 'Domain deleted.' }] };
+  });
+}

package/src/tools/flows.js

@@ -0,0 +1,33 @@
+export function registerFlowTools(server, client) {
+  server.tool('list_flows', 'List flows. Optional filter by campaign_id.', { campaign_id: { type: 'string', description: 'Campaign UUID (optional)' } }, async ({ campaign_id }) => {
+    const rows = await client.get('/flows', { query: { campaign_id } });
+    return { content: [{ type: 'text', text: JSON.stringify(rows, null, 2) }] };
+  });
+
+  server.tool('get_flow', 'Get flow details by ID.', { id: { type: 'string', description: 'Flow UUID' } }, async ({ id }) => {
+    const row = await client.get(`/flows/${id}`);
+    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+  });
+
+  server.tool('create_flow', 'Create a new flow for a campaign.', {
+    campaign_id: { type: 'string', description: 'Campaign UUID' },
+    name: { type: 'string', description: 'Flow name' },
+  }, async (args) => {
+    const row = await client.post('/flows', args);
+    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+  });
+
+  server.tool('update_flow', 'Update an existing flow.', {
+    id: { type: 'string', description: 'Flow UUID' },
+    name: { type: 'string', description: 'New name (optional)' },
+  }, async ({ id, ...rest }) => {
+    const body = Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== undefined));
+    const row = await client.put(`/flows/${id}`, body);
+    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+  });
+
+  server.tool('delete_flow', 'Delete a flow.', { id: { type: 'string', description: 'Flow UUID' } }, async ({ id }) => {
+    await client.del(`/flows/${id}`);
+    return { content: [{ type: 'text', text: 'Flow deleted.' }] };
+  });
+}

package/src/tools/landings.js

@@ -0,0 +1,34 @@
+export function registerLandingTools(server, client) {
+  server.tool('list_landings', 'List landing pages. Optional filter by status.', { status: { type: 'string', description: 'active or paused', enum: ['active', 'paused'] } }, async ({ status }) => {
+    const rows = await client.get('/landings', { query: { status } });
+    return { content: [{ type: 'text', text: JSON.stringify(rows, null, 2) }] };
+  });
+
+  server.tool('get_landing', 'Get landing page details by ID.', { id: { type: 'string', description: 'Landing page UUID' } }, async ({ id }) => {
+    const row = await client.get(`/landings/${id}`);
+    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+  });
+
+  server.tool('create_landing', 'Create a new landing page.', {
+    name: { type: 'string', description: 'Landing page name' },
+    url: { type: 'string', description: 'Landing page URL' },
+  }, async (args) => {
+    const row = await client.post('/landings', args);
+    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+  });
+
+  server.tool('update_landing', 'Update an existing landing page.', {
+    id: { type: 'string', description: 'Landing page UUID' },
+    name: { type: 'string', description: 'New name (optional)' },
+    url: { type: 'string', description: 'New URL (optional)' },
+  }, async ({ id, ...rest }) => {
+    const body = Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== undefined));
+    const row = await client.put(`/landings/${id}`, body);
+    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+  });
+
+  server.tool('delete_landing', 'Archive (soft-delete) a landing page.', { id: { type: 'string', description: 'Landing page UUID' } }, async ({ id }) => {
+    await client.del(`/landings/${id}`);
+    return { content: [{ type: 'text', text: 'Landing page archived.' }] };
+  });
+}

package/src/tools/offers.js

@@ -0,0 +1,37 @@
+export function registerOfferTools(server, client) {
+  server.tool('list_offers', 'List all offers. Optional filter by status.', { status: { type: 'string', description: 'active or paused', enum: ['active', 'paused'] } }, async ({ status }) => {
+    const rows = await client.get('/offers', { query: { status } });
+    return { content: [{ type: 'text', text: JSON.stringify(rows, null, 2) }] };
+  });
+
+  server.tool('get_offer', 'Get offer details by ID.', { id: { type: 'string', description: 'Offer UUID' } }, async ({ id }) => {
+    const row = await client.get(`/offers/${id}`);
+    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+  });
+
+  server.tool('create_offer', 'Create a new offer.', {
+    name: { type: 'string', description: 'Offer name' },
+    url: { type: 'string', description: 'Offer URL' },
+    payout: { type: 'number', description: 'Payout amount (optional)' },
+    currency: { type: 'string', description: 'Currency code (optional)' },
+  }, async (args) => {
+    const row = await client.post('/offers', args);
+    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+  });
+
+  server.tool('update_offer', 'Update an existing offer.', {
+    id: { type: 'string', description: 'Offer UUID' },
+    name: { type: 'string', description: 'New name (optional)' },
+    url: { type: 'string', description: 'New URL (optional)' },
+    payout: { type: 'number', description: 'New payout (optional)' },
+  }, async ({ id, ...rest }) => {
+    const body = Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== undefined));
+    const row = await client.put(`/offers/${id}`, body);
+    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+  });
+
+  server.tool('delete_offer', 'Archive (soft-delete) an offer.', { id: { type: 'string', description: 'Offer UUID' } }, async ({ id }) => {
+    await client.del(`/offers/${id}`);
+    return { content: [{ type: 'text', text: 'Offer archived.' }] };
+  });
+}

package/src/tools/reports.js

@@ -0,0 +1,22 @@
+export function registerReportTools(server, client) {
+  server.tool('get_reports', 'Get tracker report data with date range and grouping.', {
+    date_from: { type: 'string', description: 'Start date YYYY-MM-DD (default: 7 days ago)' },
+    date_to: { type: 'string', description: 'End date YYYY-MM-DD (default: today)' },
+    group_by: { type: 'string', description: 'Group by field: campaign, offer, country, etc.' },
+    campaign_id: { type: 'string', description: 'Filter by campaign UUID (optional)' },
+  }, async ({ date_from, date_to, group_by, campaign_id }) => {
+    const data = await client.get('/reports', { query: { date_from, date_to, group_by, campaign_id } });
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+  });
+
+  server.tool('get_conversions', 'Get conversion data with date range and filters.', {
+    date_from: { type: 'string', description: 'Start date YYYY-MM-DD' },
+    date_to: { type: 'string', description: 'End date YYYY-MM-DD' },
+    campaign_id: { type: 'string', description: 'Filter by campaign UUID (optional)' },
+    status: { type: 'string', description: 'Conversion status (optional)' },
+    limit: { type: 'number', description: 'Max rows (default 100, max 10000)' },
+  }, async ({ date_from, date_to, campaign_id, status, limit }) => {
+    const data = await client.get('/conversions', { query: { date_from, date_to, campaign_id, status, limit } });
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+  });
+}

package/src/tools/settings.js

@@ -0,0 +1,20 @@
+export function registerSettingsTools(server, client) {
+  server.tool('get_settings', 'Get all tracker settings. Optional filter by category.', {
+    category: { type: 'string', description: 'Settings category (optional)' },
+  }, async ({ category }) => {
+    const data = await client.get('/settings', { query: { category } });
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+  });
+
+  server.tool('update_settings', 'Update one or more tracker settings.', {
+    settings: {
+      type: 'string',
+      description: 'JSON array of { key, value } objects, e.g. [{"key":"default_currency","value":"EUR"}]',
+    },
+  }, async ({ settings }) => {
+    let items;
+    try { items = JSON.parse(settings); } catch { return { content: [{ type: 'text', text: 'Error: settings must be a valid JSON array of {key, value} objects.' }], isError: true }; }
+    const data = await client.put('/settings', items);
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+  });
+}

package/src/tools/sources.js

@@ -0,0 +1,33 @@
+export function registerSourceTools(server, client) {
+  server.tool('list_sources', 'List traffic sources.', {}, async () => {
+    const rows = await client.get('/sources');
+    return { content: [{ type: 'text', text: JSON.stringify(rows, null, 2) }] };
+  });
+
+  server.tool('get_source', 'Get traffic source details by ID.', { id: { type: 'string', description: 'Traffic source UUID' } }, async ({ id }) => {
+    const row = await client.get(`/sources/${id}`);
+    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+  });
+
+  server.tool('create_source', 'Create a new traffic source.', {
+    name: { type: 'string', description: 'Source name' },
+    type: { type: 'string', description: 'Source type (optional)' },
+  }, async (args) => {
+    const row = await client.post('/sources', args);
+    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+  });
+
+  server.tool('update_source', 'Update a traffic source.', {
+    id: { type: 'string', description: 'Traffic source UUID' },
+    name: { type: 'string', description: 'New name (optional)' },
+  }, async ({ id, ...rest }) => {
+    const body = Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== undefined));
+    const row = await client.put(`/sources/${id}`, body);
+    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+  });
+
+  server.tool('delete_source', 'Delete a traffic source.', { id: { type: 'string', description: 'Traffic source UUID' } }, async ({ id }) => {
+    await client.del(`/sources/${id}`);
+    return { content: [{ type: 'text', text: 'Traffic source deleted.' }] };
+  });
+}

package/src/tools/status.js

@@ -0,0 +1,6 @@
+export function registerStatusTools(server, client) {
+  server.tool('get_system_status', 'Get tracker system status: hostname, CPU, memory, uptime, version.', {}, async () => {
+    const data = await client.get('/system-status');
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+  });
+}