@channel47/tiktok-ads-mcp 0.1.0

package/server/tools/list-accounts.js

@@ -0,0 +1,109 @@
+import { tiktokRequest } from '../http.js';
+import { getAppCredentials } from '../auth.js';
+import { formatError, formatSuccess } from '../utils/response-format.js';
+import { invalidParamsError } from '../utils/errors.js';
+
+// GET /advertiser/info/ accepts at most 100 advertiser ids per request.
+const INFO_BATCH_SIZE = 100;
+const INFO_FIELDS = [
+  'advertiser_id',
+  'name',
+  'status',
+  'currency',
+  'timezone',
+  'company',
+  'country',
+  'create_time'
+];
+
+function normalizeAdvertiserIds(value) {
+  if (value === undefined || value === null || value === '') {
+    return [];
+  }
+
+  const values = Array.isArray(value) ? value : String(value).split(',');
+  return values.map((id) => String(id).trim()).filter(Boolean);
+}
+
+function mapAccount(account) {
+  return {
+    advertiser_id: String(account?.advertiser_id || ''),
+    name: account?.name || '',
+    status: account?.status || 'UNKNOWN',
+    currency: account?.currency || null,
+    timezone: account?.timezone || null,
+    company: account?.company || null,
+    country: account?.country || null
+  };
+}
+
+function chunk(values, size) {
+  const chunks = [];
+  for (let index = 0; index < values.length; index += size) {
+    chunks.push(values.slice(index, index + size));
+  }
+  return chunks;
+}
+
+/**
+ * List accessible TikTok ad accounts (advertisers) with detail lookup.
+ *
+ * When TIKTOK_ADS_APP_ID and TIKTOK_ADS_APP_SECRET are configured, advertiser
+ * ids are discovered via GET /oauth2/advertiser/get/; otherwise ids must come
+ * from the advertiser_ids param or TIKTOK_ADS_ADVERTISER_ID.
+ * @param {{ advertiser_ids?: string[] | string }} [params]
+ * @param {{ request?: (path: string, params: Record<string, unknown>, options?: Record<string, unknown>) => Promise<any> }} [dependencies]
+ * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
+ */
+export async function listAccounts(params = {}, dependencies = {}) {
+  const request = dependencies.request || tiktokRequest;
+
+  try {
+    let advertiserIds = normalizeAdvertiserIds(params.advertiser_ids);
+    let discoveredViaOauth = false;
+
+    if (advertiserIds.length === 0) {
+      const credentials = getAppCredentials();
+
+      if (credentials) {
+        const response = await request('/oauth2/advertiser/get/', {
+          app_id: credentials.appId,
+          secret: credentials.appSecret
+        });
+        const list = Array.isArray(response?.data?.list) ? response.data.list : [];
+        advertiserIds = list.map((entry) => String(entry?.advertiser_id || '')).filter(Boolean);
+        discoveredViaOauth = true;
+      } else if (process.env.TIKTOK_ADS_ADVERTISER_ID) {
+        advertiserIds = [String(process.env.TIKTOK_ADS_ADVERTISER_ID)];
+      }
+    }
+
+    if (advertiserIds.length === 0) {
+      throw invalidParamsError(
+        'No advertiser ids available. Either pass advertiser_ids, set TIKTOK_ADS_ADVERTISER_ID, '
+        + 'or set TIKTOK_ADS_APP_ID and TIKTOK_ADS_APP_SECRET to enable discovery via /oauth2/advertiser/get/.'
+      );
+    }
+
+    const accounts = [];
+    for (const batch of chunk(advertiserIds, INFO_BATCH_SIZE)) {
+      const response = await request('/advertiser/info/', {
+        advertiser_ids: batch,
+        fields: INFO_FIELDS
+      });
+      const list = Array.isArray(response?.data?.list) ? response.data.list : [];
+      accounts.push(...list.map(mapAccount));
+    }
+
+    return formatSuccess({
+      summary: `Found ${accounts.length} accessible TikTok ad account${accounts.length === 1 ? '' : 's'}`,
+      data: accounts,
+      metadata: {
+        totalAccounts: accounts.length,
+        discoveredViaOauth
+      }
+    });
+  } catch (error) {
+    return formatError(error);
+  }
+}

package/server/tools/mutate.js

@@ -0,0 +1,129 @@
+import { tiktokRequest } from '../http.js';
+import { formatError, formatSuccess } from '../utils/response-format.js';
+import { invalidParamsError } from '../utils/errors.js';
+import { getAdvertiserId } from '../utils/validation.js';
+import {
+  buildApiRequest,
+  buildRequestPreview,
+  validateOperations
+} from '../utils/mutate-operations.js';
+
+function extractResultId(response, operation) {
+  const data = response?.data;
+  return (
+    data?.campaign_id
+    ?? data?.adgroup_id
+    ?? data?.ad_ids
+    ?? operation.id
+    ?? null
+  );
+}
+
+/**
+ * Validate and execute TikTok Ads mutation operations with dry-run safety defaults.
+ *
+ * TikTok has no server-side validate-only mode, so dry_run (default true)
+ * performs local validation and returns a preview of the exact requests
+ * (method, path, body) without calling the API.
+ * @param {Record<string, unknown>} [params]
+ * @param {{ request?: (path: string, params: Record<string, unknown>, options?: Record<string, unknown>) => Promise<any> }} [dependencies]
+ * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
+ */
+export async function mutate(params = {}, dependencies = {}) {
+  const request = dependencies.request || tiktokRequest;
+
+  try {
+    const operations = params.operations;
+    const advertiserId = getAdvertiserId(params);
+    const partialFailure = params.partial_failure === undefined ? true : Boolean(params.partial_failure);
+    const dryRun = params.dry_run === undefined ? true : Boolean(params.dry_run);
+
+    const validationErrors = validateOperations(operations);
+    if (validationErrors.length > 0) {
+      const errorMessage = validationErrors.map((issue) => `[${issue.index}] ${issue.message}`).join('; ');
+      throw invalidParamsError(`Invalid operations: ${errorMessage}`);
+    }
+
+    if (dryRun) {
+      const preview = buildRequestPreview(operations, advertiserId);
+
+      return formatSuccess({
+        summary: `Dry run: ${operations.length} operation(s) validated locally. `
+          + `${preview.requests.length} request(s) would be sent to the TikTok Ads API. No changes applied. `
+          + 'TikTok has no server-side validate-only mode — pass dry_run: false to execute.',
+        data: preview.requests,
+        metadata: {
+          dryRun: true,
+          serverValidated: false,
+          operationCount: operations.length,
+          apiCallCount: preview.requests.length,
+          advertiserId
+        }
+      });
+    }
+
+    if (process.env.TIKTOK_ADS_READ_ONLY === 'true') {
+      throw new Error('mutate is disabled in read-only mode (TIKTOK_ADS_READ_ONLY=true)');
+    }
+
+    const results = [];
+    let succeeded = 0;
+    let failed = 0;
+
+    for (let index = 0; index < operations.length; index += 1) {
+      const operation = operations[index];
+      const apiRequest = buildApiRequest(operation, advertiserId);
+
+      try {
+        const response = await request(apiRequest.path, {}, {
+          method: apiRequest.method,
+          body: apiRequest.body
+        });
+
+        results.push({
+          index,
+          entity: operation.entity,
+          action: operation.action,
+          success: true,
+          id: extractResultId(response, operation),
+          response: response?.data ?? response
+        });
+        succeeded += 1;
+      } catch (error) {
+        results.push({
+          index,
+          entity: operation.entity,
+          action: operation.action,
+          success: false,
+          error: {
+            message: error.message
+          }
+        });
+        failed += 1;
+
+        if (!partialFailure) {
+          break;
+        }
+      }
+    }
+
+    if (succeeded === 0 && failed > 0) {
+      const firstError = results.find((entry) => !entry.success)?.error?.message || 'Unknown';
+      throw new Error(`All ${failed} operation(s) failed. First error: ${firstError}`);
+    }
+
+    return formatSuccess({
+      summary: `Executed ${results.length} operation(s): ${succeeded} succeeded, ${failed} failed`,
+      data: results,
+      metadata: {
+        dryRun: false,
+        operationCount: results.length,
+        succeeded,
+        failed,
+        advertiserId
+      }
+    });
+  } catch (error) {
+    return formatError(error);
+  }
+}

package/server/tools/query.js

@@ -0,0 +1,149 @@
+import { tiktokRequest } from '../http.js';
+import { formatError, formatSuccess } from '../utils/response-format.js';
+import { invalidParamsError } from '../utils/errors.js';
+import { getAdvertiserId, getRequestedLimit, validateEnum } from '../utils/validation.js';
+
+/**
+ * Default field projections per query entity (TikTok Business API v1.3 field names).
+ */
+export const ENTITY_FIELDS = {
+  campaigns: [
+    'campaign_id',
+    'campaign_name',
+    'objective_type',
+    'campaign_type',
+    'budget',
+    'budget_mode',
+    'operation_status',
+    'secondary_status',
+    'create_time',
+    'modify_time'
+  ],
+  adgroups: [
+    'adgroup_id',
+    'adgroup_name',
+    'campaign_id',
+    'operation_status',
+    'secondary_status',
+    'budget',
+    'budget_mode',
+    'optimization_goal',
+    'billing_event',
+    'bid_type',
+    'bid_price',
+    'schedule_type',
+    'schedule_start_time',
+    'schedule_end_time'
+  ],
+  ads: [
+    'ad_id',
+    'ad_name',
+    'adgroup_id',
+    'campaign_id',
+    'operation_status',
+    'secondary_status',
+    'ad_format',
+    'ad_text',
+    'landing_page_url',
+    'create_time',
+    'modify_time'
+  ]
+};
+
+export const SUPPORTED_ENTITIES = Object.keys(ENTITY_FIELDS);
+
+const ENTITY_PATHS = {
+  campaigns: '/campaign/get/',
+  adgroups: '/adgroup/get/',
+  ads: '/ad/get/'
+};
+
+function getRequestedFields(entity, fields) {
+  if (fields === undefined || fields === null || fields === '') {
+    return ENTITY_FIELDS[entity];
+  }
+
+  const values = Array.isArray(fields) ? fields : String(fields).split(',');
+  const cleaned = values.map((field) => String(field).trim()).filter(Boolean);
+  return cleaned.length > 0 ? cleaned : ENTITY_FIELDS[entity];
+}
+
+function getFiltering(filtering) {
+  if (filtering === undefined || filtering === null) {
+    return null;
+  }
+
+  if (typeof filtering !== 'object' || Array.isArray(filtering)) {
+    throw invalidParamsError('filtering must be an object (e.g. { "primary_status": "STATUS_DELIVERY_OK" })');
+  }
+
+  return filtering;
+}
+
+async function fetchAllPages(path, baseParams, requestedLimit, request) {
+  const rows = [];
+  let page = 1;
+
+  while (rows.length < requestedLimit) {
+    const response = await request(path, {
+      ...baseParams,
+      page,
+      page_size: Math.min(requestedLimit, 1000)
+    });
+
+    const list = Array.isArray(response?.data?.list) ? response.data.list : [];
+    rows.push(...list);
+
+    const totalPage = Number(response?.data?.page_info?.total_page || 0);
+    if (list.length === 0 || !totalPage || page >= totalPage) {
+      break;
+    }
+
+    page += 1;
+  }
+
+  return rows.slice(0, requestedLimit);
+}
+
+/**
+ * Query TikTok Ads campaigns, ad groups, or ads with page-based pagination.
+ * @param {Record<string, unknown>} [params]
+ * @param {{ request?: (path: string, params: Record<string, unknown>, options?: Record<string, unknown>) => Promise<any> }} [dependencies]
+ * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
+ */
+export async function query(params = {}, dependencies = {}) {
+  const request = dependencies.request || tiktokRequest;
+
+  try {
+    validateEnum(params.entity, SUPPORTED_ENTITIES, 'entity');
+
+    const advertiserId = getAdvertiserId(params);
+    const entity = params.entity;
+    const requestedLimit = getRequestedLimit(params.limit);
+    const filtering = getFiltering(params.filtering);
+
+    const baseParams = {
+      advertiser_id: advertiserId,
+      fields: getRequestedFields(entity, params.fields)
+    };
+
+    if (filtering) {
+      baseParams.filtering = filtering;
+    }
+
+    const rows = await fetchAllPages(ENTITY_PATHS[entity], baseParams, requestedLimit, request);
+
+    return formatSuccess({
+      summary: `Returned ${rows.length} ${entity} row${rows.length === 1 ? '' : 's'}`,
+      data: rows,
+      metadata: {
+        entity,
+        advertiserId,
+        limit: requestedLimit,
+        returned: rows.length
+      }
+    });
+  } catch (error) {
+    return formatError(error);
+  }
+}

package/server/tools/report.js

@@ -0,0 +1,195 @@
+import { tiktokRequest } from '../http.js';
+import { formatError, formatSuccess } from '../utils/response-format.js';
+import { invalidParamsError } from '../utils/errors.js';
+import {
+  getAdvertiserId,
+  getRequestedLimit,
+  validateDate,
+  validateEnum
+} from '../utils/validation.js';
+
+export const SUPPORTED_REPORT_TYPES = ['BASIC', 'AUDIENCE'];
+export const SUPPORTED_DATA_LEVELS = [
+  'AUCTION_ADVERTISER',
+  'AUCTION_CAMPAIGN',
+  'AUCTION_ADGROUP',
+  'AUCTION_AD'
+];
+
+const LEVEL_ID_DIMENSIONS = {
+  AUCTION_ADVERTISER: 'advertiser_id',
+  AUCTION_CAMPAIGN: 'campaign_id',
+  AUCTION_ADGROUP: 'adgroup_id',
+  AUCTION_AD: 'ad_id'
+};
+
+/**
+ * Default metric selection for integrated reports.
+ */
+export const DEFAULT_METRICS = [
+  'spend',
+  'impressions',
+  'clicks',
+  'ctr',
+  'cpc',
+  'cpm',
+  'conversion',
+  'cost_per_conversion',
+  'conversion_rate'
+];
+
+function toIsoDateUtc(date) {
+  return date.toISOString().slice(0, 10);
+}
+
+function offsetUtcDays(date, days) {
+  const copy = new Date(date);
+  copy.setUTCDate(copy.getUTCDate() + days);
+  return copy;
+}
+
+function normalizeStringArray(value) {
+  if (value === undefined || value === null || value === '') {
+    return [];
+  }
+
+  const values = Array.isArray(value) ? value : String(value).split(',');
+  return values.map((entry) => String(entry).trim()).filter(Boolean);
+}
+
+// query_lifetime=true cannot be combined with time dimensions or explicit dates.
+function resolveDateWindow(params, lifetime, now) {
+  if (lifetime) {
+    if (params.start_date || params.end_date) {
+      throw invalidParamsError('start_date/end_date cannot be combined with lifetime=true');
+    }
+    return null;
+  }
+
+  if ((params.start_date && !params.end_date) || (!params.start_date && params.end_date)) {
+    throw invalidParamsError('start_date and end_date must be provided together');
+  }
+
+  if (params.start_date && params.end_date) {
+    validateDate(params.start_date, 'start_date');
+    validateDate(params.end_date, 'end_date');
+    return { start_date: String(params.start_date), end_date: String(params.end_date) };
+  }
+
+  return {
+    start_date: toIsoDateUtc(offsetUtcDays(now, -6)),
+    end_date: toIsoDateUtc(now)
+  };
+}
+
+function resolveDimensions(params, dataLevel, lifetime) {
+  const requested = normalizeStringArray(params.dimensions);
+  if (requested.length > 0) {
+    return requested;
+  }
+
+  const idDimension = LEVEL_ID_DIMENSIONS[dataLevel];
+  return lifetime ? [idDimension] : [idDimension, 'stat_time_day'];
+}
+
+function flattenRow(row) {
+  return {
+    ...(row?.dimensions || {}),
+    ...(row?.metrics || {})
+  };
+}
+
+async function fetchAllPages(baseParams, requestedLimit, request) {
+  const rows = [];
+  let page = 1;
+
+  while (rows.length < requestedLimit) {
+    const response = await request('/report/integrated/get/', {
+      ...baseParams,
+      page,
+      page_size: Math.min(requestedLimit, 1000)
+    });
+
+    const list = Array.isArray(response?.data?.list) ? response.data.list : [];
+    rows.push(...list.map(flattenRow));
+
+    const totalPage = Number(response?.data?.page_info?.total_page || 0);
+    if (list.length === 0 || !totalPage || page >= totalPage) {
+      break;
+    }
+
+    page += 1;
+  }
+
+  return rows.slice(0, requestedLimit);
+}
+
+/**
+ * Run a synchronous TikTok integrated report (GET /report/integrated/get/).
+ * @param {Record<string, unknown>} [params]
+ * @param {{ request?: (path: string, params: Record<string, unknown>, options?: Record<string, unknown>) => Promise<any> }} [dependencies]
+ * @param {Date} [now]
+ * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
+ */
+export async function report(params = {}, dependencies = {}, now = new Date()) {
+  const request = dependencies.request || tiktokRequest;
+
+  try {
+    const advertiserId = getAdvertiserId(params);
+    const reportType = params.report_type ? String(params.report_type).toUpperCase() : 'BASIC';
+    validateEnum(reportType, SUPPORTED_REPORT_TYPES, 'report_type');
+
+    const dataLevel = params.data_level ? String(params.data_level).toUpperCase() : 'AUCTION_CAMPAIGN';
+    validateEnum(dataLevel, SUPPORTED_DATA_LEVELS, 'data_level');
+
+    const lifetime = params.lifetime === true || params.lifetime === 'true';
+    const requestedLimit = getRequestedLimit(params.limit);
+    const dateWindow = resolveDateWindow(params, lifetime, now);
+    const dimensions = resolveDimensions(params, dataLevel, lifetime);
+    const requestedMetrics = normalizeStringArray(params.metrics);
+    const metrics = requestedMetrics.length > 0 ? requestedMetrics : DEFAULT_METRICS;
+
+    const baseParams = {
+      advertiser_id: advertiserId,
+      report_type: reportType,
+      data_level: dataLevel,
+      dimensions,
+      metrics
+    };
+
+    if (lifetime) {
+      baseParams.query_lifetime = true;
+    } else {
+      baseParams.start_date = dateWindow.start_date;
+      baseParams.end_date = dateWindow.end_date;
+    }
+
+    if (Array.isArray(params.filtering) && params.filtering.length > 0) {
+      baseParams.filtering = params.filtering;
+    }
+
+    if (params.order_field) {
+      baseParams.order_field = String(params.order_field);
+      baseParams.order_type = params.order_type ? String(params.order_type).toUpperCase() : 'DESC';
+    }
+
+    const rows = await fetchAllPages(baseParams, requestedLimit, request);
+
+    return formatSuccess({
+      summary: `Returned ${rows.length} ${reportType} report row${rows.length === 1 ? '' : 's'} at ${dataLevel}`,
+      data: rows,
+      metadata: {
+        advertiserId,
+        reportType,
+        dataLevel,
+        dimensions,
+        metrics,
+        dateRange: lifetime ? 'lifetime' : dateWindow,
+        limit: requestedLimit,
+        returned: rows.length
+      }
+    });
+  } catch (error) {
+    return formatError(error);
+  }
+}

package/server/utils/errors.js

@@ -0,0 +1,12 @@
+function createTypedError(code, message) {
+  const error = new Error(message);
+  error.mcpCode = code;
+  return error;
+}
+
+/**
+ * Create an InvalidParams typed error.
+ */
+export function invalidParamsError(message) {
+  return createTypedError('InvalidParams', message);
+}