@channel47/meta-ads-mcp 1.0.0

package/server/tools/query.js

@@ -0,0 +1,157 @@
+import { metaRequest } from '../http.js';
+import { fetchAllPages } from '../utils/paginate.js';
+import { formatError, formatSuccess } from '../utils/response-format.js';
+import {
+  ENTITY_FIELDS,
+  SUPPORTED_ENTITIES,
+  resolveInsightsDateRange
+} from '../utils/field-defaults.js';
+import { getAccountId, validateEnum } from '../utils/validation.js';
+
+const ENTITY_PATHS = {
+  campaigns: 'campaigns',
+  adsets: 'adsets',
+  ads: 'ads',
+  insights: 'insights',
+  audiences: 'customaudiences',
+  creatives: 'adcreatives'
+};
+
+function serializeField(field) {
+  if (typeof field === 'string') {
+    return field;
+  }
+
+  if (field && typeof field === 'object' && !Array.isArray(field)) {
+    const [name, nested] = Object.entries(field)[0] || [];
+    if (!name) {
+      return '';
+    }
+    return `${name}{${serializeFields(nested)}}`;
+  }
+
+  return String(field);
+}
+
+// Supports both simple fields ("id") and nested projections ({ creative: [...] }).
+function serializeFields(fields) {
+  if (Array.isArray(fields)) {
+    return fields.map(serializeField).filter(Boolean).join(',');
+  }
+
+  if (fields && typeof fields === 'object') {
+    return serializeField(fields);
+  }
+
+  return String(fields || '');
+}
+
+function getRequestedFields(entity, fields) {
+  return serializeFields(fields || ENTITY_FIELDS[entity]);
+}
+
+function getInlineInsightsFields(value) {
+  if (value === undefined || value === null || value === '') {
+    return [];
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((field) => String(field).trim()).filter(Boolean);
+  }
+
+  return String(value)
+    .split(',')
+    .map((field) => field.trim())
+    .filter(Boolean);
+}
+
+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, limit) {
+  let fields = getRequestedFields(entity, params.fields);
+
+  if (entity !== 'insights') {
+    const inlineInsightsFields = getInlineInsightsFields(params.inline_insights_fields);
+    if (inlineInsightsFields.length > 0 && !fields.includes('insights{')) {
+      fields = `${fields},insights{${inlineInsightsFields.join(',')}}`;
+    }
+  }
+
+  const queryParams = {
+    fields,
+    limit: String(limit)
+  };
+
+  if (Array.isArray(params.filters) && params.filters.length > 0) {
+    queryParams.filtering = JSON.stringify(params.filters);
+  }
+
+  if (params.sort) {
+    queryParams.sort = String(params.sort);
+  }
+
+  if (entity === 'insights') {
+    const timeRange = resolveInsightsDateRange(params.date_range);
+    queryParams.time_range = JSON.stringify(timeRange);
+
+    if (params.level) {
+      queryParams.level = String(params.level);
+    }
+
+    if (params.time_increment !== undefined && params.time_increment !== null) {
+      queryParams.time_increment = String(params.time_increment);
+    }
+
+    if (Array.isArray(params.breakdowns) && params.breakdowns.length > 0) {
+      queryParams.breakdowns = params.breakdowns.join(',');
+    }
+  }
+
+  return queryParams;
+}
+
+/**
+ * Query Meta Ads entities with cursor pagination and entity-specific parameters.
+ * @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 || metaRequest;
+
+  try {
+    validateEnum(params.entity, SUPPORTED_ENTITIES, 'entity');
+
+    const accountId = getAccountId(params);
+    const entity = params.entity;
+    const requestedLimit = getRequestedLimit(params.limit);
+    const path = `/act_${accountId}/${ENTITY_PATHS[entity]}`;
+
+    const queryParams = buildBaseParams(params, entity, requestedLimit);
+    const rows = await fetchAllPages(request, path, queryParams, requestedLimit);
+
+    return formatSuccess({
+      summary: `Returned ${rows.length} ${entity} row${rows.length === 1 ? '' : 's'}`,
+      data: rows,
+      metadata: {
+        entity,
+        accountId,
+        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);
+}

package/server/utils/field-defaults.js

@@ -0,0 +1,164 @@
+import { invalidParamsError } from './errors.js';
+
+/**
+ * Default field projections per query entity.
+ */
+export const ENTITY_FIELDS = {
+  campaigns: [
+    'id',
+    'name',
+    'status',
+    'objective',
+    'daily_budget',
+    'lifetime_budget',
+    'buying_type',
+    'bid_strategy',
+    'effective_status'
+  ],
+  adsets: [
+    'id',
+    'name',
+    'status',
+    'campaign_id',
+    'daily_budget',
+    'targeting',
+    'optimization_goal',
+    'billing_event',
+    'effective_status'
+  ],
+  ads: [
+    'id',
+    'name',
+    'status',
+    'adset_id',
+    { creative: ['id', 'name', 'title', 'body', 'image_url', 'video_id'] },
+    'effective_status'
+  ],
+  insights: [
+    'spend',
+    'impressions',
+    'clicks',
+    'ctr',
+    'cpm',
+    'cpc',
+    'conversions',
+    'cost_per_action_type',
+    'frequency',
+    'reach',
+    'actions'
+  ],
+  audiences: [
+    'id',
+    'name',
+    'subtype',
+    'approximate_count',
+    'data_source',
+    'delivery_status'
+  ],
+  creatives: [
+    'id',
+    'name',
+    'title',
+    'body',
+    'image_url',
+    'video_id',
+    'object_story_spec'
+  ]
+};
+
+export const SUPPORTED_ENTITIES = Object.keys(ENTITY_FIELDS);
+
+/**
+ * Supported date presets for insights queries.
+ */
+export const INSIGHTS_PRESETS = {
+  today: { sinceOffsetDays: 0, untilOffsetDays: 0 },
+  yesterday: { sinceOffsetDays: -1, untilOffsetDays: -1 },
+  last_14d: { sinceOffsetDays: -13, untilOffsetDays: 0 },
+  last_7d: { sinceOffsetDays: -6, untilOffsetDays: 0 },
+  last_30d: { sinceOffsetDays: -29, untilOffsetDays: 0 },
+  this_month: (now) => ({
+    since: toIsoDateUtc(new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1))),
+    until: toIsoDateUtc(now)
+  }),
+  this_week_mon_today: (now) => {
+    const day = now.getUTCDay();
+    const daysSinceMonday = day === 0 ? 6 : day - 1;
+    return {
+      since: toIsoDateUtc(offsetUtcDays(now, -daysSinceMonday)),
+      until: toIsoDateUtc(now)
+    };
+  },
+  last_quarter: (now) => {
+    const currentQuarter = Math.floor(now.getUTCMonth() / 3);
+    const lastQuarter = currentQuarter === 0 ? 3 : currentQuarter - 1;
+    const year = currentQuarter === 0 ? now.getUTCFullYear() - 1 : now.getUTCFullYear();
+    const startMonth = lastQuarter * 3;
+
+    return {
+      since: toIsoDateUtc(new Date(Date.UTC(year, startMonth, 1))),
+      until: toIsoDateUtc(new Date(Date.UTC(year, startMonth + 3, 0)))
+    };
+  }
+};
+
+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 validateDate(value, label) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    throw invalidParamsError(`Invalid ${label} date format: ${value}. Expected YYYY-MM-DD`);
+  }
+}
+
+/**
+ * Resolve a date_range preset or explicit range object to { since, until } (UTC date strings).
+ * @param {string | { since: string, until: string } | undefined} dateRange
+ * @param {Date} [now]
+ * @returns {{ since: string, until: string }}
+ */
+export function resolveInsightsDateRange(dateRange, now = new Date()) {
+  if (!dateRange) {
+    return resolveInsightsDateRange('last_7d', now);
+  }
+
+  if (typeof dateRange === 'string') {
+    const presetKey = dateRange.toLowerCase();
+    const preset = INSIGHTS_PRESETS[presetKey];
+    if (!preset) {
+      throw invalidParamsError(`Invalid date_range preset: ${dateRange}. Allowed: ${Object.keys(INSIGHTS_PRESETS).join(', ')}`);
+    }
+
+    if (typeof preset === 'function') {
+      return preset(now);
+    }
+
+    return {
+      since: toIsoDateUtc(offsetUtcDays(now, preset.sinceOffsetDays)),
+      until: toIsoDateUtc(offsetUtcDays(now, preset.untilOffsetDays))
+    };
+  }
+
+  if (typeof dateRange === 'object') {
+    const since = dateRange.since;
+    const until = dateRange.until;
+
+    if (!since || !until) {
+      throw invalidParamsError('date_range object must include both since and until');
+    }
+
+    validateDate(since, 'since');
+    validateDate(until, 'until');
+
+    return { since, until };
+  }
+
+  throw invalidParamsError('date_range must be a preset string or { since, until } object');
+}

package/server/utils/mutate-operations.js

@@ -0,0 +1,149 @@
+import { validateArray, withActPrefix } from './validation.js';
+
+/**
+ * Supported mutate entity identifiers.
+ */
+export const SUPPORTED_MUTATE_ENTITIES = ['campaign', 'adset', 'ad', 'audience', 'creative'];
+/**
+ * Supported mutate action identifiers.
+ */
+export const SUPPORTED_MUTATE_ACTIONS = ['create', 'update', 'pause', 'enable', 'archive', 'delete'];
+
+const CREATE_ENTITY_PATHS = {
+  campaign: 'campaigns',
+  adset: 'adsets',
+  ad: 'ads',
+  audience: 'customaudiences',
+  creative: 'adcreatives'
+};
+
+const STATUS_BY_ACTION = {
+  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(', ')}`
+    };
+  }
+
+  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`
+    };
+  }
+
+  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 Meta Graph API request payload from a single mutate operation.
+ * @param {{ entity: string, action: string, id?: string, params?: Record<string, unknown> }} operation
+ * @param {string} accountId
+ * @returns {{ method: string, path: string, params: Record<string, unknown> }}
+ */
+export function buildApiRequest(operation, accountId) {
+  const action = operation.action;
+
+  if (action === 'create') {
+    const parentPath = CREATE_ENTITY_PATHS[operation.entity];
+    return {
+      method: 'POST',
+      path: `/${withActPrefix(accountId)}/${parentPath}`,
+      params: {
+        status: 'PAUSED',
+        ...operation.params
+      }
+    };
+  }
+
+  if (action === 'delete') {
+    return {
+      method: 'DELETE',
+      path: `/${operation.id}`,
+      params: {}
+    };
+  }
+
+  const status = STATUS_BY_ACTION[action];
+  return {
+    method: 'POST',
+    path: `/${operation.id}`,
+    params: {
+      ...(status ? { status } : {}),
+      ...(operation.params || {})
+    }
+  };
+}
+
+/**
+ * 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} accountId
+ * @returns {{ requests: Array<Record<string, unknown>> }}
+ */
+export function buildRequestPreview(operations, accountId) {
+  return {
+    requests: operations.map((operation, index) => {
+      const request = buildApiRequest(operation, accountId);
+      return {
+        index,
+        entity: operation.entity,
+        action: operation.action,
+        method: request.method,
+        path: request.path,
+        params: request.params
+      };
+    })
+  };
+}

package/server/utils/paginate.js

@@ -0,0 +1,30 @@
+/**
+ * Follow Graph API cursor pagination, aggregating rows up to maxRows.
+ * @param {(path: string, params: Record<string, unknown>) => Promise<any>} request
+ * @param {string} path
+ * @param {Record<string, unknown>} [initialParams]
+ * @param {number} [maxRows]
+ * @returns {Promise<any[]>}
+ */
+export async function fetchAllPages(request, path, initialParams = {}, maxRows = Infinity) {
+  const rows = [];
+  let after = null;
+
+  while (rows.length < maxRows) {
+    const pageParams = { ...initialParams };
+    if (after) {
+      pageParams.after = after;
+    }
+
+    const response = await request(path, pageParams);
+    const data = Array.isArray(response?.data) ? response.data : [];
+    rows.push(...data);
+
+    after = response?.paging?.cursors?.after;
+    if (!after) {
+      break;
+    }
+  }
+
+  return rows.length > maxRows ? rows.slice(0, maxRows) : rows;
+}

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,55 @@
+import { invalidParamsError } from './errors.js';
+
+/**
+ * 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`);
+  }
+}
+
+/**
+ * Normalize ad account IDs by removing optional act_ prefix.
+ */
+export function normalizeAccountId(accountId) {
+  const raw = String(accountId || '').trim();
+  if (!raw) {
+    return '';
+  }
+
+  return raw.startsWith('act_') ? raw.slice(4) : raw;
+}
+
+/**
+ * Ensure ad account ID includes act_ prefix.
+ */
+export function withActPrefix(accountId) {
+  const normalized = normalizeAccountId(accountId);
+  if (!normalized) {
+    return '';
+  }
+
+  return `act_${normalized}`;
+}
+
+/**
+ * Resolve account ID from params or environment, normalized without act_ prefix.
+ */
+export function getAccountId(params = {}) {
+  const accountId = params.account_id || process.env.META_ADS_ACCOUNT_ID;
+  if (!accountId) {
+    throw invalidParamsError('account_id parameter or META_ADS_ACCOUNT_ID environment variable required');
+  }
+
+  return normalizeAccountId(accountId);
+}