@channel47/tiktok-ads-mcp 0.1.0

package/server/utils/mutate-operations.js

@@ -0,0 +1,168 @@
+import { validateArray } from './validation.js';
+
+/**
+ * Supported mutate entity identifiers.
+ */
+export const SUPPORTED_MUTATE_ENTITIES = ['campaign', 'adgroup', 'ad'];
+/**
+ * Supported mutate action identifiers.
+ */
+export const SUPPORTED_MUTATE_ACTIONS = ['create', 'update', 'pause', 'enable', 'delete'];
+
+// TikTok status update endpoints take plural id arrays.
+const STATUS_ID_FIELDS = {
+  campaign: 'campaign_ids',
+  adgroup: 'adgroup_ids',
+  ad: 'ad_ids'
+};
+
+// Update endpoints take a singular id field (ads identify targets via
+// creatives[].ad_id inside params instead — see /ad/update/).
+const UPDATE_ID_FIELDS = {
+  campaign: 'campaign_id',
+  adgroup: 'adgroup_id'
+};
+
+const STATUS_BY_ACTION = {
+  pause: 'DISABLE',
+  enable: 'ENABLE',
+  delete: 'DELETE'
+};
+
+// /campaign/create/ and /adgroup/create/ default operation_status to ENABLE
+// server-side; this server defaults them to DISABLE (paused) for safety.
+// /ad/create/ has no top-level operation_status field.
+const PAUSED_CREATE_ENTITIES = new Set(['campaign', 'adgroup']);
+
+function validateOperationShape(op, index) {
+  if (!op || typeof op !== 'object' || Array.isArray(op)) {
+    return { index, message: 'Operation must be an object' };
+  }
+
+  if (!op.entity) {
+    return { index, message: 'Missing required field: entity' };
+  }
+
+  if (!SUPPORTED_MUTATE_ENTITIES.includes(op.entity)) {
+    return {
+      index,
+      message: `Unsupported entity: ${op.entity}. Supported: ${SUPPORTED_MUTATE_ENTITIES.join(', ')}`
+    };
+  }
+
+  if (!op.action) {
+    return { index, message: 'Missing required field: action' };
+  }
+
+  if (!SUPPORTED_MUTATE_ACTIONS.includes(op.action)) {
+    return {
+      index,
+      message: `Unsupported action: ${op.action}. Supported: ${SUPPORTED_MUTATE_ACTIONS.join(', ')}`
+    };
+  }
+
+  if ((op.action === 'create' || op.action === 'update') && (!op.params || typeof op.params !== 'object' || Array.isArray(op.params))) {
+    return {
+      index,
+      message: `${op.action} requires params object`
+    };
+  }
+
+  const idOptional = op.action === 'create' || (op.action === 'update' && op.entity === 'ad');
+  if (!idOptional && !op.id) {
+    return {
+      index,
+      message: `${op.action} requires id`
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Validate mutate operation array shape and action/entity compatibility.
+ * @param {unknown} operations
+ * @returns {Array<{ index: number, message: string }>}
+ */
+export function validateOperations(operations) {
+  validateArray(operations, 'operations');
+
+  const errors = [];
+  for (let index = 0; index < operations.length; index += 1) {
+    const issue = validateOperationShape(operations[index], index);
+    if (issue) {
+      errors.push(issue);
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Build a TikTok Business API request payload from a single mutate operation.
+ * @param {{ entity: string, action: string, id?: string, params?: Record<string, unknown> }} operation
+ * @param {string} advertiserId
+ * @returns {{ method: string, path: string, body: Record<string, unknown> }}
+ */
+export function buildApiRequest(operation, advertiserId) {
+  const { entity, action } = operation;
+
+  if (action === 'create') {
+    const defaults = PAUSED_CREATE_ENTITIES.has(entity) ? { operation_status: 'DISABLE' } : {};
+    return {
+      method: 'POST',
+      path: `/${entity}/create/`,
+      body: {
+        advertiser_id: advertiserId,
+        ...defaults,
+        ...operation.params
+      }
+    };
+  }
+
+  if (action === 'update') {
+    const idField = UPDATE_ID_FIELDS[entity];
+    const idParams = idField && operation.id ? { [idField]: String(operation.id) } : {};
+    return {
+      method: 'POST',
+      path: `/${entity}/update/`,
+      body: {
+        advertiser_id: advertiserId,
+        ...idParams,
+        ...operation.params
+      }
+    };
+  }
+
+  return {
+    method: 'POST',
+    path: `/${entity}/status/update/`,
+    body: {
+      advertiser_id: advertiserId,
+      [STATUS_ID_FIELDS[entity]]: [String(operation.id)],
+      operation_status: STATUS_BY_ACTION[action]
+    }
+  };
+}
+
+/**
+ * Build a human-readable preview of API requests derived from operations.
+ * @param {Array<{ entity: string, action: string, id?: string, params?: Record<string, unknown> }>} operations
+ * @param {string} advertiserId
+ * @returns {{ requests: Array<Record<string, unknown>> }}
+ */
+export function buildRequestPreview(operations, advertiserId) {
+  return {
+    requests: operations.map((operation, index) => {
+      const request = buildApiRequest(operation, advertiserId);
+      return {
+        index,
+        entity: operation.entity,
+        action: operation.action,
+        method: request.method,
+        path: request.path,
+        body: request.body
+      };
+    })
+  };
+}

package/server/utils/response-format.js

@@ -0,0 +1,63 @@
+let SdkMcpError = null;
+let SdkErrorCode = null;
+
+try {
+  const sdkTypes = await import('@modelcontextprotocol/sdk/types.js');
+  SdkMcpError = sdkTypes.McpError;
+  SdkErrorCode = sdkTypes.ErrorCode;
+} catch {
+  // SDK may be absent in minimal test environments.
+}
+
+/**
+ * Format a successful tool result payload in MCP text content structure.
+ * @param {{ summary: string, data: any, metadata?: Record<string, unknown> }} payload
+ * @returns {import('@modelcontextprotocol/sdk/types.js').CallToolResult}
+ */
+export function formatSuccess({ summary, data, metadata = {} }) {
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        success: true,
+        summary,
+        data,
+        metadata: {
+          rowCount: Array.isArray(data) ? data.length : undefined,
+          warnings: [],
+          ...metadata
+        }
+      }, null, 2)
+    }]
+  };
+}
+
+function createMcpStyleError(code, message) {
+  if (SdkMcpError && SdkErrorCode && SdkErrorCode[code]) {
+    return new SdkMcpError(SdkErrorCode[code], message);
+  }
+
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+/**
+ * Convert thrown errors into MCP-compatible typed errors.
+ * @param {unknown} error
+ * @throws {Error}
+ */
+export function formatError(error) {
+  const message = error?.message || String(error) || 'Unknown error';
+  const explicitCode = error?.mcpCode === 'InvalidParams' || error?.code === 'InvalidParams'
+    ? 'InvalidParams'
+    : error?.mcpCode === 'InternalError' || error?.code === 'InternalError'
+      ? 'InternalError'
+      : null;
+
+  if (explicitCode) {
+    throw createMcpStyleError(explicitCode, message);
+  }
+
+  throw createMcpStyleError('InternalError', message);
+}

package/server/utils/validation.js

@@ -0,0 +1,70 @@
+import { invalidParamsError } from './errors.js';
+
+/**
+ * Validate that required fields are present on the params object.
+ */
+export function validateRequired(params, fields) {
+  const missing = fields.filter((field) => {
+    const value = params[field];
+    return value === undefined || value === null || value === '';
+  });
+
+  if (missing.length > 0) {
+    throw invalidParamsError(`Missing required parameter${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}`);
+  }
+}
+
+/**
+ * Validate an enum value against an allowed set.
+ */
+export function validateEnum(value, allowed, paramName = 'value') {
+  if (!allowed.includes(value)) {
+    throw invalidParamsError(`Invalid ${paramName}: ${value}. Allowed values: ${allowed.join(', ')}`);
+  }
+}
+
+/**
+ * Validate that a value is a non-empty array.
+ */
+export function validateArray(value, paramName = 'value') {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw invalidParamsError(`${paramName} must be a non-empty array`);
+  }
+}
+
+/**
+ * Validate a YYYY-MM-DD date string.
+ */
+export function validateDate(value, label = 'date') {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(String(value))) {
+    throw invalidParamsError(`Invalid ${label} format: ${value}. Expected YYYY-MM-DD`);
+  }
+}
+
+/**
+ * Resolve a positive row limit with default and cap.
+ */
+export function getRequestedLimit(limitValue, { defaultLimit = 100, maxLimit = 1000 } = {}) {
+  if (limitValue === undefined || limitValue === null || limitValue === '') {
+    return defaultLimit;
+  }
+
+  const parsed = Number(limitValue);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return defaultLimit;
+  }
+
+  return Math.min(Math.floor(parsed), maxLimit);
+}
+
+/**
+ * Resolve advertiser ID from params or environment.
+ */
+export function getAdvertiserId(params = {}) {
+  const advertiserId = params.advertiser_id || process.env.TIKTOK_ADS_ADVERTISER_ID;
+  if (!advertiserId) {
+    throw invalidParamsError('advertiser_id parameter or TIKTOK_ADS_ADVERTISER_ID environment variable required');
+  }
+
+  return String(advertiserId).trim();
+}