@channel47/pinterest-ads-mcp 0.1.0

package/server/utils/mutate-operations.js

@@ -0,0 +1,174 @@
+import { validateArray } from './validation.js';
+
+/**
+ * Supported mutate entity identifiers.
+ */
+export const SUPPORTED_MUTATE_ENTITIES = ['campaign', 'ad_group', 'ad'];
+/**
+ * Supported mutate action identifiers. Pinterest v5 has no delete for ads
+ * entities — ARCHIVED (via archive) is the terminal state.
+ */
+export const SUPPORTED_MUTATE_ACTIONS = ['create', 'update', 'pause', 'enable', 'archive'];
+
+const ENTITY_COLLECTIONS = {
+  campaign: 'campaigns',
+  ad_group: 'ad_groups',
+  ad: 'ads'
+};
+
+const CREATE_REQUIRED_FIELDS = {
+  campaign: ['name', 'objective_type'],
+  ad_group: ['name', 'campaign_id', 'billable_event'],
+  ad: ['ad_group_id', 'pin_id', 'creative_type']
+};
+
+const STATUS_ACTIONS = {
+  pause: 'PAUSED',
+  enable: 'ACTIVE',
+  archive: 'ARCHIVED'
+};
+
+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(', ')} (Pinterest has no delete — use archive)`
+    };
+  }
+
+  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`
+    };
+  }
+
+  if (op.action !== 'create' && !op.id) {
+    return {
+      index,
+      message: `${op.action} requires id`
+    };
+  }
+
+  if (op.action === 'create') {
+    const requiredFields = CREATE_REQUIRED_FIELDS[op.entity];
+    const missing = requiredFields.filter((field) => {
+      const value = op.params[field];
+      return value === undefined || value === null || value === '';
+    });
+
+    if (missing.length > 0) {
+      return {
+        index,
+        message: `${op.entity} create requires params: ${missing.join(', ')}`
+      };
+    }
+  }
+
+  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 Pinterest v5 API request from a single mutate operation.
+ * Creates are POST with a one-element array body; updates and status changes
+ * are PATCH with a one-element array body of { id, ...changes }.
+ * @param {{ entity: string, action: string, id?: string, params?: Record<string, unknown> }} operation
+ * @param {string} adAccountId
+ * @returns {{ method: string, path: string, body: Array<Record<string, unknown>> }}
+ */
+export function buildApiRequest(operation, adAccountId) {
+  const action = operation.action;
+  const path = `/ad_accounts/${adAccountId}/${ENTITY_COLLECTIONS[operation.entity]}`;
+
+  if (action === 'create') {
+    return {
+      method: 'POST',
+      path,
+      body: [{
+        status: 'PAUSED',
+        ...operation.params
+      }]
+    };
+  }
+
+  if (action === 'update') {
+    return {
+      method: 'PATCH',
+      path,
+      body: [{
+        ...operation.params,
+        id: String(operation.id)
+      }]
+    };
+  }
+
+  return {
+    method: 'PATCH',
+    path,
+    body: [{
+      ...(operation.params || {}),
+      id: String(operation.id),
+      status: STATUS_ACTIONS[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} adAccountId
+ * @returns {{ requests: Array<Record<string, unknown>> }}
+ */
+export function buildRequestPreview(operations, adAccountId) {
+  return {
+    requests: operations.map((operation, index) => {
+      const request = buildApiRequest(operation, adAccountId);
+      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,63 @@
+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`);
+  }
+}
+
+/**
+ * Coerce a comma-separated string or array into a trimmed string array.
+ */
+export function toIdList(value) {
+  if (value === undefined || value === null || value === '') {
+    return [];
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => String(entry).trim()).filter(Boolean);
+  }
+
+  return String(value)
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Resolve the ad account ID from params or environment.
+ */
+export function getAdAccountId(params = {}) {
+  const adAccountId = params.ad_account_id || process.env.PINTEREST_ADS_AD_ACCOUNT_ID;
+  if (!adAccountId) {
+    throw invalidParamsError('ad_account_id parameter or PINTEREST_ADS_AD_ACCOUNT_ID environment variable required');
+  }
+
+  return String(adAccountId).trim();
+}