atracker-mcp-server 1.1.0 → 1.1.2

package/package.json

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

package/src/client.js

@@ -1,6 +1,7 @@
-class ApiError extends Error {
+export class ApiError extends Error {
   constructor(status, body) {
-    super(body?.error || `HTTP ${status}`);
+    const detail = body?.message || body?.error || `HTTP ${status}`;
+    super(detail);
     this.status = status;
     this.body = body;
   }

package/src/index.js

@@ -27,7 +27,7 @@ const client = createClient(url, token);
 
 const server = new McpServer({
   name: 'atracker',
-  version: '1.1.0',
+  version: '1.1.1',
 });
 
 registerCampaignTools(server, client);

package/src/tools/campaigns.js

@@ -1,46 +1,64 @@
+import { defineTool, jsonText, stripUndefined, toolErrorText } from '../util.js';
+
 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) }] };
+  defineTool(server, 'list_campaigns', 'List all campaigns. Optional filter by status or group_name.', {
+    status: { type: 'string', description: 'active or paused', enum: ['active', 'paused'] },
+    group_name: { type: 'string', description: 'Filter by campaign group name (optional)' },
+  }, async ({ status, group_name }) => {
+    const rows = await client.get('/campaigns', { query: { status, group_name } });
+    return jsonText(rows);
   });
 
-  server.tool('get_campaign', 'Get campaign details by ID.', { id: { type: 'string', description: 'Campaign UUID' } }, async ({ id }) => {
+  defineTool(server, '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) }] };
+    return jsonText(row);
   });
 
-  server.tool('create_campaign', 'Create a new campaign.', {
-    name: { type: 'string', description: 'Campaign name' },
+  defineTool(server, 'create_campaign', 'Create a new campaign. Requires name.', {
+    name: { type: 'string', description: 'Campaign name (required)' },
     alias: { type: 'string', description: 'URL alias (optional)' },
-    domain: { type: 'string', description: 'Domain (optional)' },
+    domain_id: { type: 'string', description: 'Domain UUID (optional)' },
+    domain: { type: 'string', description: 'Domain hostname — resolved to domain_id if set (optional)' },
+    group_name: { type: 'string', description: 'Campaign group name (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) }] };
+    const body = stripUndefined(args);
+    if (!body.name) return toolErrorText('Validation error: name is required');
+    const row = await client.post('/campaigns', body);
+    return jsonText(row);
   });
 
-  server.tool('update_campaign', 'Update an existing campaign.', {
+  defineTool(server, '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)' },
+    domain_id: { type: 'string', description: 'Domain UUID (optional)' },
+    domain: { type: 'string', description: 'Domain hostname — resolved to domain_id if set (optional)' },
+    group_name: { type: 'string', description: 'Campaign group name (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) }] };
+    const row = await client.put(`/campaigns/${id}`, stripUndefined(rest));
+    return jsonText(row);
   });
 
-  server.tool('pause_campaign', 'Pause a campaign.', { id: { type: 'string', description: 'Campaign UUID' } }, async ({ id }) => {
+  defineTool(server, '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) }] };
+    return jsonText(row);
   });
 
-  server.tool('resume_campaign', 'Resume a paused campaign.', { id: { type: 'string', description: 'Campaign UUID' } }, async ({ id }) => {
+  defineTool(server, '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) }] };
+    return jsonText(row);
   });
 
-  server.tool('delete_campaign', 'Archive (soft-delete) a campaign.', { id: { type: 'string', description: 'Campaign UUID' } }, async ({ id }) => {
+  defineTool(server, '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

@@ -1,20 +1,32 @@
+import { defineTool, jsonText, stripUndefined, toolErrorText } from '../util.js';
+
 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 }) => {
+  defineTool(server, '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) }] };
+    return jsonText(rows);
   });
 
-  server.tool('get_domain', 'Get domain details by ID.', { id: { type: 'string', description: 'Domain UUID' } }, async ({ id }) => {
+  defineTool(server, '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) }] };
+    return jsonText(row);
   });
 
-  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) }] };
+  defineTool(server, 'create_domain', 'Create a new domain. Requires domain hostname.', {
+    domain: { type: 'string', description: 'Domain name e.g. trk.example.com (required)' },
+  }, async (args) => {
+    const body = stripUndefined(args);
+    if (!body.domain) return toolErrorText('Validation error: domain is required');
+    const row = await client.post('/domains', body);
+    return jsonText(row);
   });
 
-  server.tool('delete_domain', 'Delete a domain.', { id: { type: 'string', description: 'Domain UUID' } }, async ({ id }) => {
+  defineTool(server, '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

@@ -1,32 +1,43 @@
+import { defineTool, jsonText, stripUndefined, toolErrorText } from '../util.js';
+
 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 }) => {
+  defineTool(server, '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) }] };
+    return jsonText(rows);
   });
 
-  server.tool('get_flow', 'Get flow details by ID.', { id: { type: 'string', description: 'Flow UUID' } }, async ({ id }) => {
+  defineTool(server, '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) }] };
+    return jsonText(row);
   });
 
-  server.tool('create_flow', 'Create a new flow for a campaign.', {
-    campaign_id: { type: 'string', description: 'Campaign UUID' },
-    name: { type: 'string', description: 'Flow name' },
+  defineTool(server, 'create_flow', 'Create a new flow for a campaign.', {
+    campaign_id: { type: 'string', description: 'Campaign UUID (required)' },
+    name: { type: 'string', description: 'Flow name (required)' },
   }, async (args) => {
-    const row = await client.post('/flows', args);
-    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+    const body = stripUndefined(args);
+    if (!body.campaign_id) return toolErrorText('Validation error: campaign_id is required');
+    if (!body.name) return toolErrorText('Validation error: name is required');
+    const row = await client.post('/flows', body);
+    return jsonText(row);
   });
 
-  server.tool('update_flow', 'Update an existing flow.', {
+  defineTool(server, 'update_flow', 'Update an existing flow.', {
     id: { type: 'string', description: 'Flow UUID' },
     name: { type: 'string', description: 'New name (optional)' },
+    campaign_id: { type: 'string', description: 'Move flow to another campaign UUID (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) }] };
+    const row = await client.put(`/flows/${id}`, stripUndefined(rest));
+    return jsonText(row);
   });
 
-  server.tool('delete_flow', 'Delete a flow.', { id: { type: 'string', description: 'Flow UUID' } }, async ({ id }) => {
+  defineTool(server, '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/geo.js

@@ -1,3 +1,5 @@
+import { defineTool, jsonText, stripUndefined } from '../util.js';
+
 const CATEGORIES = ['geo', 'asn', 'threat'];
 const POLL_INTERVAL_MS = 1000;
 const POLL_TIMEOUT_MS = 30 * 60 * 1000;
@@ -8,12 +10,14 @@ async function waitForDownload(client, categories) {
   // eslint-disable-next-line no-constant-condition
   while (true) {
     if (Date.now() - startedAt > POLL_TIMEOUT_MS) {
-      throw new Error('Timed out waiting for geo bundle download');
+      throw new Error('Timed out waiting for geo bundle download (30 min)');
     }
     const state = await client.get('/geo2ip/download-status');
     const summaries = targets.map((c) => ({ category: c, ...(state[c] || {}) }));
     const errored = summaries.find((s) => s.status === 'error');
-    if (errored) throw new Error(`Download failed for ${errored.category}: ${errored.error || 'unknown'}`);
+    if (errored) {
+      throw new Error(`Download failed for ${errored.category}: ${errored.error || 'unknown'}`);
+    }
     const active = summaries.find((s) => !['done', 'idle'].includes(s.status));
     if (!active) return summaries;
     await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
@@ -21,58 +25,51 @@ async function waitForDownload(client, categories) {
 }
 
 export function registerGeoTools(server, client) {
-  server.tool(
+  defineTool(
+    server,
     'geo_status',
-    'Get current geo2ip bundle versions, sizes, and last download status for all three categories (geo, asn, threat).',
+    'Get geo2ip bundle versions, sizes, and download state (admin token).',
     {},
-    async () => {
-      const data = await client.get('/geo2ip/bundle-status');
-      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
-    }
+    async () => jsonText(await client.get('/geo2ip/bundle-status')),
   );
 
-  server.tool(
+  defineTool(
+    server,
     'geo_check_update',
-    'Check the ATracker platform for newer geo bundle versions. Returns current versions, available manifests (including delta info), and the list of categories that have updates.',
+    'Check platform for newer geo bundle versions (admin token).',
     {},
-    async () => {
-      const data = await client.post('/geo2ip/check-updates', {});
-      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
-    }
+    async () => jsonText(await client.post('/geo2ip/check-updates', {})),
   );
 
-  server.tool(
+  defineTool(
+    server,
     'geo_update',
-    'Download and apply the latest geo bundles from the platform. Optionally limit to specific categories (geo|asn|threat). Polls until completion and returns the final bundle status.',
+    'Download and apply latest geo bundles (admin token). Polls until complete.',
     {
-      categories: { type: 'array', items: { type: 'string', enum: CATEGORIES }, description: 'Optional subset of categories to update' },
+      categories: {
+        type: 'array',
+        items: { type: 'string', enum: CATEGORIES },
+        description: 'Optional subset: geo, asn, threat',
+      },
       force: { type: 'boolean', description: 'Re-download even if bundles are up to date' },
     },
     async (args = {}) => {
-      const body = {};
-      if (Array.isArray(args.categories) && args.categories.length) body.categories = args.categories;
-      if (args.force) body.force = true;
+      const body = stripUndefined({
+        categories: Array.isArray(args.categories) && args.categories.length ? args.categories : undefined,
+        force: args.force ? true : undefined,
+      });
       await client.post('/geo2ip/download-bundle', body);
       const summaries = await waitForDownload(client, body.categories);
       const finalStatus = await client.get('/geo2ip/bundle-status');
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({ summaries, status: finalStatus }, null, 2),
-        }],
-      };
-    }
+      return jsonText({ summaries, status: finalStatus });
+    },
   );
 
-  server.tool(
+  defineTool(
+    server,
     'geo_lookup',
-    'Look up geo, ASN, and threat info for an IPv4/IPv6 address using the locally loaded bundles. Returns resolved data with per-field source attribution.',
-    {
-      ip: { type: 'string', description: 'IPv4 or IPv6 address to look up' },
-    },
-    async ({ ip }) => {
-      const data = await client.post('/geo2ip/test-lookup', { ip });
-      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
-    }
+    'Look up geo, ASN, and threat info for an IP (admin token).',
+    { ip: { type: 'string', description: 'IPv4 or IPv6 address' } },
+    async ({ ip }) => jsonText(await client.post('/geo2ip/test-lookup', { ip })),
   );
 }

package/src/tools/landings.js

@@ -1,33 +1,44 @@
+import { defineTool, jsonText, stripUndefined, toolErrorText } from '../util.js';
+
 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 }) => {
+  defineTool(server, '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) }] };
+    return jsonText(rows);
   });
 
-  server.tool('get_landing', 'Get landing page details by ID.', { id: { type: 'string', description: 'Landing page UUID' } }, async ({ id }) => {
+  defineTool(server, '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) }] };
+    return jsonText(row);
   });
 
-  server.tool('create_landing', 'Create a new landing page.', {
-    name: { type: 'string', description: 'Landing page name' },
-    url: { type: 'string', description: 'Landing page URL' },
+  defineTool(server, 'create_landing', 'Create a new landing page. Requires name.', {
+    name: { type: 'string', description: 'Landing page name (required)' },
+    url: { type: 'string', description: 'Landing page URL (optional)' },
+    group_name: { type: 'string', description: 'Landing group name (optional)' },
   }, async (args) => {
-    const row = await client.post('/landings', args);
-    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+    const body = stripUndefined(args);
+    if (!body.name) return toolErrorText('Validation error: name is required');
+    const row = await client.post('/landings', body);
+    return jsonText(row);
   });
 
-  server.tool('update_landing', 'Update an existing landing page.', {
+  defineTool(server, '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)' },
+    group_name: { type: 'string', description: 'Landing group name (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) }] };
+    const row = await client.put(`/landings/${id}`, stripUndefined(rest));
+    return jsonText(row);
   });
 
-  server.tool('delete_landing', 'Archive (soft-delete) a landing page.', { id: { type: 'string', description: 'Landing page UUID' } }, async ({ id }) => {
+  defineTool(server, '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

@@ -1,36 +1,48 @@
+import { defineTool, jsonText, stripUndefined, toolErrorText } from '../util.js';
+
 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 }) => {
+  defineTool(server, '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) }] };
+    return jsonText(rows);
   });
 
-  server.tool('get_offer', 'Get offer details by ID.', { id: { type: 'string', description: 'Offer UUID' } }, async ({ id }) => {
+  defineTool(server, '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) }] };
+    return jsonText(row);
   });
 
-  server.tool('create_offer', 'Create a new offer.', {
-    name: { type: 'string', description: 'Offer name' },
-    url: { type: 'string', description: 'Offer URL' },
+  defineTool(server, 'create_offer', 'Create a new offer. Requires name.', {
+    name: { type: 'string', description: 'Offer name (required)' },
+    url: { type: 'string', description: 'Offer URL (optional)' },
     payout: { type: 'number', description: 'Payout amount (optional)' },
     currency: { type: 'string', description: 'Currency code (optional)' },
+    group_name: { type: 'string', description: 'Offer group name (optional)' },
   }, async (args) => {
-    const row = await client.post('/offers', args);
-    return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+    const body = stripUndefined(args);
+    if (!body.name) return toolErrorText('Validation error: name is required');
+    const row = await client.post('/offers', body);
+    return jsonText(row);
   });
 
-  server.tool('update_offer', 'Update an existing offer.', {
+  defineTool(server, '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)' },
+    currency: { type: 'string', description: 'Currency code (optional)' },
+    group_name: { type: 'string', description: 'Offer group name (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) }] };
+    const row = await client.put(`/offers/${id}`, stripUndefined(rest));
+    return jsonText(row);
   });
 
-  server.tool('delete_offer', 'Archive (soft-delete) an offer.', { id: { type: 'string', description: 'Offer UUID' } }, async ({ id }) => {
+  defineTool(server, '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

@@ -1,22 +1,41 @@
+import { defineTool, jsonText } from '../util.js';
+
+function normalizeLimit(limit) {
+  if (limit === undefined || limit === null || limit === '') return undefined;
+  const n = Number(limit);
+  if (!Number.isFinite(n) || n < 1) return 100;
+  return Math.min(Math.floor(n), 1000);
+}
+
 export function registerReportTools(server, client) {
-  server.tool('get_reports', 'Get tracker report data with date range and grouping.', {
+  defineTool(server, '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.' },
+    date_to: { type: 'string', description: 'End date YYYY-MM-DD inclusive (default: today)' },
+    group_by: { type: 'string', description: 'Group by field: campaign, offer, country, category, city, hour' },
     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) }] };
+    const data = await client.get('/reports', {
+      query: { date_from, date_to, group_by, campaign_id },
+    });
+    return jsonText(data);
   });
 
-  server.tool('get_conversions', 'Get conversion data with date range and filters.', {
+  defineTool(server, 'get_conversions', 'Get conversion log 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' },
+    date_to: { type: 'string', description: 'End date YYYY-MM-DD inclusive' },
     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)' },
+    status: { type: 'string', description: 'Conversion status: lead, sale, rejected, registration, deposit, rebill (optional)' },
+    limit: { type: 'number', description: 'Max rows (default 100, max 1000)' },
   }, 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) }] };
+    const data = await client.get('/conversions', {
+      query: {
+        date_from,
+        date_to,
+        campaign_id,
+        status,
+        limit: normalizeLimit(limit),
+      },
+    });
+    return jsonText(data);
   });
 }

package/src/tools/settings.js

@@ -1,20 +1,39 @@
+import { defineTool, jsonText, toolErrorText } from '../util.js';
+
 export function registerSettingsTools(server, client) {
-  server.tool('get_settings', 'Get all tracker settings. Optional filter by category.', {
+  defineTool(server, 'get_settings', 'Get tracker settings (admin token). Optional filter by category. Secrets are redacted.', {
     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) }] };
+    return jsonText(data);
   });
 
-  server.tool('update_settings', 'Update one or more tracker settings.', {
+  defineTool(server, 'update_settings', 'Update one or more tracker settings (admin token). Body is JSON array of {key, value}.', {
     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 }; }
+    try {
+      items = JSON.parse(settings);
+    } catch {
+      return toolErrorText('Error: settings must be a valid JSON array of {key, value} objects.');
+    }
+    if (!Array.isArray(items)) {
+      return toolErrorText('Error: settings must be a JSON array.');
+    }
     const data = await client.put('/settings', items);
-    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    return jsonText(data);
+  });
+
+  defineTool(server, 'get_global_postback', 'Get global postback URL and installation token (resolves campaign from subid).', {}, async () => {
+    const data = await client.get('/global-postback');
+    return jsonText(data);
+  });
+
+  defineTool(server, 'regenerate_global_postback_token', 'Regenerate global postback token. The old global postback URL stops working.', {}, async () => {
+    const data = await client.post('/global-postback/regenerate');
+    return jsonText(data);
   });
 }

package/src/tools/sources.js

@@ -1,32 +1,40 @@
+import { defineTool, jsonText, stripUndefined, toolErrorText } from '../util.js';
+
 export function registerSourceTools(server, client) {
-  server.tool('list_sources', 'List traffic sources.', {}, async () => {
+  defineTool(server, 'list_sources', 'List traffic sources.', {}, async () => {
     const rows = await client.get('/sources');
-    return { content: [{ type: 'text', text: JSON.stringify(rows, null, 2) }] };
+    return jsonText(rows);
   });
 
-  server.tool('get_source', 'Get traffic source details by ID.', { id: { type: 'string', description: 'Traffic source UUID' } }, async ({ id }) => {
+  defineTool(server, '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) }] };
+    return jsonText(row);
   });
 
-  server.tool('create_source', 'Create a new traffic source.', {
-    name: { type: 'string', description: 'Source name' },
+  defineTool(server, 'create_source', 'Create a new traffic source. Requires name.', {
+    name: { type: 'string', description: 'Source name (required)' },
     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) }] };
+    const body = stripUndefined(args);
+    if (!body.name) return toolErrorText('Validation error: name is required');
+    const row = await client.post('/sources', body);
+    return jsonText(row);
   });
 
-  server.tool('update_source', 'Update a traffic source.', {
+  defineTool(server, 'update_source', 'Update a traffic source.', {
     id: { type: 'string', description: 'Traffic source UUID' },
     name: { type: 'string', description: 'New name (optional)' },
+    type: { type: 'string', description: 'Source type (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) }] };
+    const row = await client.put(`/sources/${id}`, stripUndefined(rest));
+    return jsonText(row);
   });
 
-  server.tool('delete_source', 'Delete a traffic source.', { id: { type: 'string', description: 'Traffic source UUID' } }, async ({ id }) => {
+  defineTool(server, '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

@@ -1,6 +1,8 @@
+import { defineTool, jsonText } from '../util.js';
+
 export function registerStatusTools(server, client) {
-  server.tool('get_system_status', 'Get tracker system status: hostname, CPU, memory, uptime, version.', {}, async () => {
+  defineTool(server, '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) }] };
+    return jsonText(data);
   });
 }

package/src/util.js

@@ -0,0 +1,48 @@
+import { ApiError } from './client.js';
+
+export function stripUndefined(obj) {
+  if (!obj || typeof obj !== 'object') return {};
+  return Object.fromEntries(
+    Object.entries(obj).filter(([, v]) => v !== undefined && v !== null),
+  );
+}
+
+export function formatApiErrorMessage(err) {
+  if (err instanceof ApiError) {
+    const body = err.body;
+    const detail =
+      (body && (body.message || body.error)) ||
+      err.message ||
+      `HTTP ${err.status}`;
+    return `API error ${err.status}: ${detail}`;
+  }
+  return err?.message || String(err);
+}
+
+export function jsonText(data) {
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+
+export function toolError(err) {
+  return {
+    content: [{ type: 'text', text: formatApiErrorMessage(err) }],
+    isError: true,
+  };
+}
+
+export function toolErrorText(text) {
+  return { content: [{ type: 'text', text }], isError: true };
+}
+
+/**
+ * Registers an MCP tool with consistent API error handling (isError + message).
+ */
+export function defineTool(server, name, description, schema, handler) {
+  server.tool(name, description, schema, async (args) => {
+    try {
+      return await handler(args ?? {});
+    } catch (err) {
+      return toolError(err);
+    }
+  });
+}

package/src/util.test.js

@@ -0,0 +1,27 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { ApiError } from './client.js';
+import { stripUndefined, formatApiErrorMessage } from './util.js';
+
+describe('stripUndefined', () => {
+  it('removes null and undefined keys', () => {
+    assert.deepEqual(stripUndefined({ a: 1, b: undefined, c: null, d: '' }), { a: 1, d: '' });
+  });
+});
+
+describe('formatApiErrorMessage', () => {
+  it('prefers Fastify message over generic error', () => {
+    const err = new ApiError(500, {
+      statusCode: 500,
+      error: 'Internal Server Error',
+      message: 'reportService.getCampaignReport is not a function',
+    });
+    const msg = formatApiErrorMessage(err);
+    assert.match(msg, /getCampaignReport/);
+    assert.notEqual(msg, 'API error 500: Internal Server Error');
+  });
+
+  it('formats plain errors', () => {
+    assert.equal(formatApiErrorMessage(new Error('network')), 'network');
+  });
+});