@channel47/pinterest-ads-mcp 0.1.0

package/server/tools/analytics.js

@@ -0,0 +1,102 @@
+import { pinterestRequest } from '../http.js';
+import { formatError, formatSuccess } from '../utils/response-format.js';
+import { invalidParamsError } from '../utils/errors.js';
+import { getAdAccountId, toIdList, validateEnum, validateRequired } from '../utils/validation.js';
+import {
+  ANALYTICS_LEVELS,
+  SUPPORTED_ANALYTICS_LEVELS,
+  resolveColumns,
+  resolveGranularity,
+  validateDateRange
+} from '../utils/analytics-params.js';
+
+const CONVERSION_REPORT_TIMES = ['TIME_OF_AD_ACTION', 'TIME_OF_CONVERSION'];
+const REPORTING_TIMEZONES = ['PINTEREST_TIME_ZONE', 'AD_ACCOUNT_TIME_ZONE'];
+const WINDOW_DAYS = [0, 1, 7, 14, 30, 60];
+const WINDOW_PARAMS = ['click_window_days', 'engagement_window_days', 'view_window_days'];
+
+function applyOptionalParams(queryParams, params) {
+  for (const windowParam of WINDOW_PARAMS) {
+    const value = params[windowParam];
+    if (value === undefined || value === null || value === '') {
+      continue;
+    }
+
+    const parsed = Number(value);
+    if (!WINDOW_DAYS.includes(parsed)) {
+      throw invalidParamsError(`Invalid ${windowParam}: ${value}. Allowed values: ${WINDOW_DAYS.join(', ')}`);
+    }
+    queryParams[windowParam] = String(parsed);
+  }
+
+  if (params.conversion_report_time) {
+    const value = String(params.conversion_report_time).toUpperCase();
+    validateEnum(value, CONVERSION_REPORT_TIMES, 'conversion_report_time');
+    queryParams.conversion_report_time = value;
+  }
+
+  if (params.reporting_timezone) {
+    const value = String(params.reporting_timezone).toUpperCase();
+    validateEnum(value, REPORTING_TIMEZONES, 'reporting_timezone');
+    queryParams.reporting_timezone = value;
+  }
+}
+
+/**
+ * Pull Pinterest Ads analytics at account, campaign, ad_group, or ad level.
+ * @param {Record<string, unknown>} [params]
+ * @param {{ request?: (path: string, params: Record<string, unknown>) => Promise<any> }} [dependencies]
+ * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
+ */
+export async function analytics(params = {}, dependencies = {}) {
+  const request = dependencies.request || pinterestRequest;
+
+  try {
+    const level = params.level === undefined || params.level === null || params.level === ''
+      ? 'account'
+      : String(params.level).toLowerCase();
+    validateEnum(level, SUPPORTED_ANALYTICS_LEVELS, 'level');
+    validateRequired(params, ['start_date', 'end_date']);
+
+    const adAccountId = getAdAccountId(params);
+    const { pathSuffix, idsParam } = ANALYTICS_LEVELS[level];
+    const { startDate, endDate } = validateDateRange(params.start_date, params.end_date);
+    const columns = resolveColumns(params.columns);
+    const granularity = resolveGranularity(params.granularity);
+
+    const queryParams = {
+      start_date: startDate,
+      end_date: endDate,
+      columns,
+      granularity
+    };
+
+    if (idsParam) {
+      const ids = toIdList(params[idsParam]);
+      if (ids.length === 0) {
+        throw invalidParamsError(`${idsParam} is required for level "${level}"`);
+      }
+      queryParams[idsParam] = ids;
+    }
+
+    applyOptionalParams(queryParams, params);
+
+    const response = await request(`/ad_accounts/${adAccountId}${pathSuffix}`, queryParams);
+    const rows = Array.isArray(response) ? response : [];
+
+    return formatSuccess({
+      summary: `Returned ${rows.length} ${level}-level analytics row${rows.length === 1 ? '' : 's'} for ${startDate} to ${endDate}`,
+      data: rows,
+      metadata: {
+        level,
+        adAccountId,
+        startDate,
+        endDate,
+        granularity,
+        columns
+      }
+    });
+  } catch (error) {
+    return formatError(error);
+  }
+}

package/server/tools/list-accounts.js

@@ -0,0 +1,68 @@
+import { pinterestRequest } from '../http.js';
+import { formatError, formatSuccess } from '../utils/response-format.js';
+
+const PAGE_SIZE = 250;
+
+function mapAccount(account) {
+  return {
+    id: account?.id || '',
+    name: account?.name || '',
+    currency: account?.currency || null,
+    country: account?.country || null,
+    owner_username: account?.owner?.username || null,
+    time_zone: account?.time_zone || null,
+    permissions: Array.isArray(account?.permissions) ? account.permissions : []
+  };
+}
+
+async function fetchAllPages(request, path, initialParams = {}) {
+  const rows = [];
+  let bookmark = null;
+
+  while (true) {
+    const pageParams = { ...initialParams };
+    if (bookmark) {
+      pageParams.bookmark = bookmark;
+    }
+
+    const response = await request(path, pageParams);
+    const items = Array.isArray(response?.items) ? response.items : [];
+    rows.push(...items);
+
+    bookmark = response?.bookmark || null;
+    if (!bookmark) {
+      break;
+    }
+  }
+
+  return rows;
+}
+
+/**
+ * List all accessible Pinterest ad accounts for the authenticated token.
+ * @param {{ include_shared_accounts?: boolean }} [params]
+ * @param {{ request?: (path: string, params: Record<string, unknown>) => Promise<any> }} [dependencies]
+ * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
+ */
+export async function listAccounts(params = {}, dependencies = {}) {
+  const request = dependencies.request || pinterestRequest;
+
+  try {
+    const queryParams = { page_size: String(PAGE_SIZE) };
+    if (params.include_shared_accounts !== undefined) {
+      queryParams.include_shared_accounts = String(Boolean(params.include_shared_accounts));
+    }
+
+    const allAccounts = (await fetchAllPages(request, '/ad_accounts', queryParams)).map(mapAccount);
+
+    return formatSuccess({
+      summary: `Found ${allAccounts.length} accessible Pinterest ad account${allAccounts.length === 1 ? '' : 's'}`,
+      data: allAccounts,
+      metadata: {
+        totalAccounts: allAccounts.length
+      }
+    });
+  } catch (error) {
+    return formatError(error);
+  }
+}

package/server/tools/mutate.js

@@ -0,0 +1,134 @@
+import { pinterestRequest } from '../http.js';
+import { formatError, formatSuccess } from '../utils/response-format.js';
+import { invalidParamsError } from '../utils/errors.js';
+import { getAdAccountId } from '../utils/validation.js';
+import {
+  buildApiRequest,
+  buildRequestPreview,
+  validateOperations
+} from '../utils/mutate-operations.js';
+
+function extractExceptionMessage(exceptions) {
+  if (!Array.isArray(exceptions) || exceptions.length === 0) {
+    return null;
+  }
+
+  return exceptions
+    .map((exception) => {
+      const code = exception?.code ? `[code ${exception.code}] ` : '';
+      return `${code}${exception?.message || 'Unknown exception'}`;
+    })
+    .join('; ');
+}
+
+/**
+ * Validate and execute Pinterest Ads mutation operations with dry-run safety defaults.
+ * Pinterest v5 has no server-side validate-only mode, so dry runs perform local
+ * validation and return a preview of the exact requests 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 || pinterestRequest;
+
+  try {
+    const operations = params.operations;
+    const adAccountId = getAdAccountId(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, adAccountId);
+
+      return formatSuccess({
+        summary: `Dry run: ${operations.length} operation(s) validated locally. ${preview.requests.length} request(s) would be sent — Pinterest has no server-side validate-only mode, so no API calls were made. Re-run with dry_run=false to execute.`,
+        data: preview.requests,
+        metadata: {
+          dryRun: true,
+          serverValidated: false,
+          operationCount: operations.length,
+          apiCallCount: preview.requests.length,
+          adAccountId
+        }
+      });
+    }
+
+    if (process.env.PINTEREST_ADS_READ_ONLY === 'true') {
+      throw new Error('mutate is disabled in read-only mode (PINTEREST_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, adAccountId);
+
+      try {
+        const response = await request(apiRequest.path, {}, {
+          method: apiRequest.method,
+          body: apiRequest.body
+        });
+
+        const item = Array.isArray(response?.items) ? response.items[0] : null;
+        const exceptionMessage = extractExceptionMessage(item?.exceptions);
+        if (exceptionMessage) {
+          throw new Error(exceptionMessage);
+        }
+
+        const resolvedId = item?.data?.id || operation.id || null;
+        results.push({
+          index,
+          entity: operation.entity,
+          action: operation.action,
+          success: true,
+          id: resolvedId,
+          data: item?.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,
+        adAccountId
+      }
+    });
+  } catch (error) {
+    return formatError(error);
+  }
+}

package/server/tools/query.js

@@ -0,0 +1,130 @@
+import { pinterestRequest } from '../http.js';
+import { formatError, formatSuccess } from '../utils/response-format.js';
+import { invalidParamsError } from '../utils/errors.js';
+import { getAdAccountId, toIdList, validateEnum } from '../utils/validation.js';
+
+const ENTITY_STATUSES = ['ACTIVE', 'PAUSED', 'ARCHIVED', 'DRAFT', 'DELETED_DRAFT'];
+const ORDERS = ['ASCENDING', 'DESCENDING'];
+const MAX_PAGE_SIZE = 250;
+
+/**
+ * Supported query entities mapped to their id-filter query parameters.
+ */
+export const QUERY_ENTITIES = {
+  campaigns: ['campaign_ids'],
+  ad_groups: ['campaign_ids', 'ad_group_ids'],
+  ads: ['campaign_ids', 'ad_group_ids', 'ad_ids']
+};
+
+export const SUPPORTED_QUERY_ENTITIES = Object.keys(QUERY_ENTITIES);
+
+const ALL_ID_FILTERS = ['campaign_ids', 'ad_group_ids', 'ad_ids'];
+
+function getRequestedLimit(limitValue) {
+  if (limitValue === undefined || limitValue === null || limitValue === '') {
+    return 100;
+  }
+
+  const parsed = Number(limitValue);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return 100;
+  }
+
+  return Math.min(Math.floor(parsed), 1000);
+}
+
+function buildBaseParams(params, entity) {
+  const queryParams = {};
+  const supportedFilters = QUERY_ENTITIES[entity];
+
+  for (const filterName of ALL_ID_FILTERS) {
+    const ids = toIdList(params[filterName]);
+    if (ids.length === 0) {
+      continue;
+    }
+
+    if (!supportedFilters.includes(filterName)) {
+      throw invalidParamsError(`${filterName} is not supported for entity "${entity}". Supported filters: ${supportedFilters.join(', ')}`);
+    }
+
+    queryParams[filterName] = ids;
+  }
+
+  const entityStatuses = toIdList(params.entity_statuses).map((status) => status.toUpperCase());
+  for (const status of entityStatuses) {
+    validateEnum(status, ENTITY_STATUSES, 'entity_statuses');
+  }
+  if (entityStatuses.length > 0) {
+    queryParams.entity_statuses = entityStatuses;
+  }
+
+  if (params.order) {
+    const order = String(params.order).toUpperCase();
+    validateEnum(order, ORDERS, 'order');
+    queryParams.order = order;
+  }
+
+  return queryParams;
+}
+
+async function fetchAllPages(path, initialParams, requestedLimit, request) {
+  let bookmark = null;
+  const results = [];
+
+  while (results.length < requestedLimit) {
+    const pageParams = {
+      ...initialParams,
+      page_size: String(Math.min(requestedLimit - results.length, MAX_PAGE_SIZE))
+    };
+
+    if (bookmark) {
+      pageParams.bookmark = bookmark;
+    }
+
+    const response = await request(path, pageParams);
+    const items = Array.isArray(response?.items) ? response.items : [];
+    results.push(...items);
+
+    bookmark = response?.bookmark || null;
+    if (!bookmark) {
+      break;
+    }
+  }
+
+  return results.slice(0, requestedLimit);
+}
+
+/**
+ * Query Pinterest Ads entities (campaigns, ad_groups, ads) with bookmark pagination.
+ * @param {Record<string, unknown>} [params]
+ * @param {{ request?: (path: string, params: Record<string, unknown>) => Promise<any> }} [dependencies]
+ * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
+ */
+export async function query(params = {}, dependencies = {}) {
+  const request = dependencies.request || pinterestRequest;
+
+  try {
+    validateEnum(params.entity, SUPPORTED_QUERY_ENTITIES, 'entity');
+
+    const adAccountId = getAdAccountId(params);
+    const entity = params.entity;
+    const requestedLimit = getRequestedLimit(params.limit);
+    const path = `/ad_accounts/${adAccountId}/${entity}`;
+
+    const queryParams = buildBaseParams(params, entity);
+    const rows = await fetchAllPages(path, queryParams, requestedLimit, request);
+
+    return formatSuccess({
+      summary: `Returned ${rows.length} ${entity} row${rows.length === 1 ? '' : 's'}`,
+      data: rows,
+      metadata: {
+        entity,
+        adAccountId,
+        limit: requestedLimit,
+        returned: rows.length
+      }
+    });
+  } catch (error) {
+    return formatError(error);
+  }
+}

package/server/utils/analytics-params.js

@@ -0,0 +1,106 @@
+import { invalidParamsError } from './errors.js';
+import { toIdList, validateEnum } from './validation.js';
+
+/**
+ * Default analytics columns returned when the caller does not request specific columns.
+ * All names are valid `columns` values on Pinterest v5 analytics endpoints.
+ */
+export const DEFAULT_ANALYTICS_COLUMNS = [
+  'SPEND_IN_DOLLAR',
+  'IMPRESSION_2',
+  'CLICKTHROUGH_2',
+  'CTR_2',
+  'TOTAL_CONVERSIONS'
+];
+
+/**
+ * Supported analytics granularity values.
+ */
+export const GRANULARITIES = ['TOTAL', 'DAY', 'HOUR', 'WEEK', 'MONTH'];
+
+/**
+ * Supported analytics levels mapped to endpoint paths and required id params.
+ */
+export const ANALYTICS_LEVELS = {
+  account: { pathSuffix: '/analytics', idsParam: null },
+  campaign: { pathSuffix: '/campaigns/analytics', idsParam: 'campaign_ids' },
+  ad_group: { pathSuffix: '/ad_groups/analytics', idsParam: 'ad_group_ids' },
+  ad: { pathSuffix: '/ads/analytics', idsParam: 'ad_ids' }
+};
+
+export const SUPPORTED_ANALYTICS_LEVELS = Object.keys(ANALYTICS_LEVELS);
+
+const MAX_LOOKBACK_DAYS = 90;
+const MAX_RANGE_DAYS = 90;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function parseIsoDate(value, label) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(String(value || ''))) {
+    throw invalidParamsError(`Invalid ${label} date format: ${value}. Expected YYYY-MM-DD`);
+  }
+
+  const parsed = Date.parse(`${value}T00:00:00.000Z`);
+  if (!Number.isFinite(parsed)) {
+    throw invalidParamsError(`Invalid ${label} date: ${value}`);
+  }
+
+  return parsed;
+}
+
+/**
+ * Validate an analytics date range against Pinterest API constraints:
+ * YYYY-MM-DD format, start_date <= end_date, start_date no more than 90 days
+ * back from today, and end_date no more than 90 days past start_date.
+ * @param {string} startDate
+ * @param {string} endDate
+ * @param {Date} [now]
+ * @returns {{ startDate: string, endDate: string }}
+ */
+export function validateDateRange(startDate, endDate, now = new Date()) {
+  const startMs = parseIsoDate(startDate, 'start_date');
+  const endMs = parseIsoDate(endDate, 'end_date');
+
+  if (startMs > endMs) {
+    throw invalidParamsError(`start_date (${startDate}) must not be after end_date (${endDate})`);
+  }
+
+  const todayMs = Date.parse(`${now.toISOString().slice(0, 10)}T00:00:00.000Z`);
+  if (todayMs - startMs > MAX_LOOKBACK_DAYS * DAY_MS) {
+    throw invalidParamsError(`start_date (${startDate}) cannot be more than ${MAX_LOOKBACK_DAYS} days back from today`);
+  }
+
+  if (endMs - startMs > MAX_RANGE_DAYS * DAY_MS) {
+    throw invalidParamsError(`Date range exceeds ${MAX_RANGE_DAYS} days: ${startDate} to ${endDate}`);
+  }
+
+  return { startDate, endDate };
+}
+
+/**
+ * Resolve requested analytics columns to a validated non-empty string array.
+ * @param {string | string[] | undefined} columns
+ * @returns {string[]}
+ */
+export function resolveColumns(columns) {
+  const resolved = toIdList(columns);
+  if (resolved.length === 0) {
+    return [...DEFAULT_ANALYTICS_COLUMNS];
+  }
+
+  return resolved.map((column) => column.toUpperCase());
+}
+
+/**
+ * Resolve and validate the requested granularity (default TOTAL).
+ * @param {string | undefined} granularity
+ * @returns {string}
+ */
+export function resolveGranularity(granularity) {
+  if (granularity === undefined || granularity === null || granularity === '') {
+    return 'TOTAL';
+  }
+
+  const normalized = String(granularity).toUpperCase();
+  validateEnum(normalized, GRANULARITIES, 'granularity');
+  return normalized;
+}

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);
+}