@channel47/meta-ads-mcp 1.0.0

package/server/prompts/templates.js

@@ -0,0 +1,112 @@
+export const PROMPT_TEMPLATES = {
+  creative_fatigue_check: {
+    name: 'creative_fatigue_check',
+    description: 'Check for ad creative fatigue signals and propose refresh priorities',
+    arguments: [
+      {
+        name: 'account_id',
+        description: 'Meta ad account ID (without act_ prefix)',
+        required: true
+      },
+      {
+        name: 'date_range',
+        description: 'Insights date preset (last_7d, last_30d, today, yesterday)',
+        required: false,
+        default: 'last_7d'
+      }
+    ],
+    template: `Run a creative fatigue analysis for Meta account {{account_id}} using {{date_range}} data:
+
+1. Pull ad-level insights (spend, impressions, clicks, ctr, frequency).
+2. Flag ads with high frequency and declining CTR.
+3. Group fatigued ads by campaign/ad set.
+4. Identify top creatives to refresh first by wasted spend.
+5. Return prioritized creative refresh recommendations with rationale.`
+  },
+  audience_overlap_check: {
+    name: 'audience_overlap_check',
+    description: 'Review audience definitions and identify overlap/conflict risk',
+    arguments: [
+      {
+        name: 'account_id',
+        description: 'Meta ad account ID (without act_ prefix)',
+        required: true
+      }
+    ],
+    template: `Run an audience overlap check for Meta account {{account_id}}:
+
+1. Pull active ad sets with targeting details.
+2. Pull custom audiences in the account.
+3. Identify segments likely competing in auction (same geo/age/interests/lookalikes).
+4. Flag exclusions that are missing and likely to cause overlap.
+5. Return concrete audience restructuring suggestions.`
+  },
+  spend_pacing_check: {
+    name: 'spend_pacing_check',
+    description: 'Check pacing against recent spend and budget signals',
+    arguments: [
+      {
+        name: 'account_id',
+        description: 'Meta ad account ID (without act_ prefix)',
+        required: true
+      },
+      {
+        name: 'date_range',
+        description: 'Insights date preset',
+        required: false,
+        default: 'last_7d'
+      }
+    ],
+    template: `Run a spend pacing check for Meta account {{account_id}} over {{date_range}}:
+
+1. Pull campaign-level insights and budget fields.
+2. Compare current spend velocity to available daily/lifetime budgets.
+3. Flag campaigns underpacing and overpacing.
+4. Highlight campaigns spending with weak conversion signals.
+5. Return top pacing issues and recommended budget actions.`
+  }
+};
+
+export function getPromptsList() {
+  return Object.values(PROMPT_TEMPLATES).map((prompt) => ({
+    name: prompt.name,
+    description: prompt.description,
+    arguments: prompt.arguments
+  }));
+}
+
+export function renderPrompt(name, args = {}) {
+  const template = PROMPT_TEMPLATES[name];
+  if (!template) {
+    throw new Error(`Unknown prompt: ${name}. Available prompts: ${Object.keys(PROMPT_TEMPLATES).join(', ')}`);
+  }
+
+  const missing = template.arguments
+    .filter((argument) => argument.required && !args[argument.name])
+    .map((argument) => argument.name);
+
+  if (missing.length > 0) {
+    throw new Error(`Missing required arguments for prompt "${name}": ${missing.join(', ')}`);
+  }
+
+  let text = template.template;
+
+  for (const argument of template.arguments) {
+    const value = args[argument.name] ?? argument.default;
+    if (value !== undefined) {
+      text = text.replace(new RegExp(`\\{\\{${argument.name}\\}\\}`, 'g'), String(value));
+    }
+  }
+
+  return {
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text
+        }
+      }
+    ]
+  };
+}

package/server/resources/entity-fields-reference.md

@@ -0,0 +1,134 @@
+# Meta Ads Entity Field Reference
+
+This document summarizes the default fields returned by the `query` tool for each entity and notes common additions.
+
+## campaigns
+
+Default:
+
+- `id`
+- `name`
+- `status`
+- `objective`
+- `daily_budget`
+- `lifetime_budget`
+- `buying_type`
+- `bid_strategy`
+- `effective_status`
+
+Common additions:
+
+- `start_time`
+- `stop_time`
+- `special_ad_categories`
+
+## adsets
+
+Default:
+
+- `id`
+- `name`
+- `status`
+- `campaign_id`
+- `daily_budget`
+- `targeting`
+- `optimization_goal`
+- `billing_event`
+- `effective_status`
+
+Common additions:
+
+- `lifetime_budget`
+- `promoted_object`
+- `attribution_spec`
+
+## ads
+
+Default:
+
+- `id`
+- `name`
+- `status`
+- `adset_id`
+- `creative{id,name,title,body,image_url,video_id}`
+- `effective_status`
+
+Common additions:
+
+- `tracking_specs`
+- `conversion_specs`
+- `preview_shareable_link`
+
+## insights
+
+Default:
+
+- `spend`
+- `impressions`
+- `clicks`
+- `ctr`
+- `cpm`
+- `cpc`
+- `conversions`
+- `cost_per_action_type`
+- `frequency`
+- `reach`
+- `actions`
+
+Common additions:
+
+- `inline_link_clicks`
+- `purchase_roas`
+- `video_play_actions`
+
+## audiences (`customaudiences`)
+
+Default:
+
+- `id`
+- `name`
+- `subtype`
+- `approximate_count`
+- `data_source`
+- `delivery_status`
+
+Common additions:
+
+- `retention_days`
+- `operation_status`
+- `lookalike_spec`
+
+## creatives (`adcreatives`)
+
+Default:
+
+- `id`
+- `name`
+- `title`
+- `body`
+- `image_url`
+- `video_id`
+- `object_story_spec`
+
+Common additions:
+
+- `object_type`
+- `thumbnail_url`
+- `asset_feed_spec`
+
+## Inline Insights on Non-Insights Entities
+
+For `campaigns`, `adsets`, `ads`, `audiences`, or `creatives`, you can append nested insights by passing `inline_insights_fields`.
+
+Example:
+
+```json
+{
+  "entity": "ads",
+  "inline_insights_fields": ["spend", "ctr", "frequency"]
+}
+```
+
+This produces a nested field projection similar to:
+
+`insights{spend,ctr,frequency}`

package/server/resources/graph-api-reference.md

@@ -0,0 +1,78 @@
+# Meta Ads Graph API Quick Reference
+
+## Base URL
+
+`https://graph.facebook.com/v25.0`
+
+## Authentication
+
+- Auth is provided via query param: `access_token=<TOKEN>`
+- This server reads token from `META_ADS_ACCESS_TOKEN`
+- No token refresh flow in v1 (supports long-lived user tokens and system user tokens)
+
+## Account Discovery
+
+- List accounts: `GET /me/adaccounts`
+- Suggested fields:
+  - `id,name,account_status,currency,timezone_name,business{name}`
+
+## Query Endpoints (by Account)
+
+Use normalized account IDs in tools (`1234567890`) and API paths with `act_` prefix:
+
+- Campaigns: `GET /act_<ACCOUNT_ID>/campaigns`
+- Ad sets: `GET /act_<ACCOUNT_ID>/adsets`
+- Ads: `GET /act_<ACCOUNT_ID>/ads`
+- Insights: `GET /act_<ACCOUNT_ID>/insights`
+- Audiences: `GET /act_<ACCOUNT_ID>/customaudiences`
+- Creatives: `GET /act_<ACCOUNT_ID>/adcreatives`
+
+Useful query params:
+
+- `fields`: comma-separated field list
+- `limit`: up to 1000
+- `after`: pagination cursor
+- `filtering`: JSON-encoded filter array
+- `sort`: sort expression
+
+Insights-only params:
+
+- `time_range`: JSON object (`{ "since": "YYYY-MM-DD", "until": "YYYY-MM-DD" }`)
+- `level`: `campaign` | `adset` | `ad`
+- `time_increment`: `1`, `7`, `monthly`, etc.
+
+## Mutations
+
+Typical write patterns:
+
+- Create: `POST /act_<ACCOUNT_ID>/<entity_collection>`
+- Update: `POST /<OBJECT_ID>`
+- Pause/Enable: `POST /<OBJECT_ID>` with `status=PAUSED` or `status=ACTIVE`
+- Delete: `DELETE /<OBJECT_ID>`
+
+Supported entity collections in this server:
+
+- Campaign: `campaigns`
+- Ad set: `adsets`
+- Ad: `ads`
+- Audience: `customaudiences`
+
+## Error Handling
+
+Retry strategy in this server:
+
+- Retry once on `401 Unauthorized`
+- Retry once on throttling:
+  - HTTP `429`
+  - Graph error codes `17` or `32`
+
+Error message extraction priority:
+
+1. `payload.error.message`
+2. `payload.message`
+3. Fallback generic message
+
+## Notes
+
+- Budget values are returned in minor currency units (e.g., `5000` => `$50.00` USD)
+- Graph API version is pinned in code (`v25.0`) for predictable behavior

package/server/resources/index.js

@@ -0,0 +1,65 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Static list of resource documents exposed by the server.
+ */
+export const RESOURCES = [
+  {
+    uri: 'metaads://reference',
+    name: 'Meta Ads Graph API Reference',
+    description: 'Core Graph API endpoints, query parameters, and error handling notes for Meta Ads workflows',
+    mimeType: 'text/markdown'
+  },
+  {
+    uri: 'metaads://entity-fields',
+    name: 'Meta Ads Entity Field Reference',
+    description: 'Default fields and common optional field expansions for queryable entities',
+    mimeType: 'text/markdown'
+  },
+  {
+    uri: 'metaads://rate-limits',
+    name: 'Meta Ads Rate Limits and Quotas',
+    description: 'Rate limiting behavior, backoff guidance, and operational recommendations',
+    mimeType: 'text/markdown'
+  }
+];
+
+const RESOURCE_FILE_MAP = {
+  'metaads://reference': 'graph-api-reference.md',
+  'metaads://entity-fields': 'entity-fields-reference.md',
+  'metaads://rate-limits': 'rate-limits-and-quotas.md'
+};
+
+export function getResourcesList() {
+  return RESOURCES;
+}
+
+/**
+ * Read a resource document by URI.
+ * @param {string} uri
+ * @returns {{ contents: Array<{ uri: string, mimeType: string, text: string }> }}
+ */
+export function readResource(uri) {
+  const filename = RESOURCE_FILE_MAP[uri];
+  if (!filename) {
+    throw new Error(`Unknown resource: ${uri}. Available: ${Object.keys(RESOURCE_FILE_MAP).join(', ')}`);
+  }
+
+  const filePath = join(__dirname, filename);
+  const content = readFileSync(filePath, 'utf8');
+
+  return {
+    contents: [
+      {
+        uri,
+        mimeType: 'text/markdown',
+        text: content
+      }
+    ]
+  };
+}

package/server/resources/rate-limits-and-quotas.md

@@ -0,0 +1,33 @@
+# Meta Ads Rate Limits and Quotas
+
+Meta Ads API enforces usage-based throttling. Limits are not fixed per endpoint; they depend on workload, account state, and system pressure.
+
+## What This MCP Server Does
+
+- Treats HTTP `429` and Graph error codes `17` and `32` as throttling signals.
+- Reads `Retry-After` response header when available.
+- Falls back to `60` seconds if `Retry-After` is missing or invalid.
+- Retries throttled requests once.
+
+## Backoff Behavior
+
+`Retry-After` values may be:
+
+- Integer seconds (for example `7`)
+- HTTP date string
+
+The server converts this to milliseconds and sleeps before a single retry.
+
+## Timeout Behavior
+
+- Requests use a default timeout of `30000` ms.
+- Override with `META_ADS_REQUEST_TIMEOUT_MS` environment variable.
+- Timeout errors are surfaced as request failures so callers can retry or degrade gracefully.
+
+## Operational Guidance
+
+- Keep requested field sets narrow.
+- Use `limit` deliberately and paginate only as needed.
+- Avoid broad fan-out query loops across many accounts at once.
+- Cache read-heavy metadata (account and entity lists) where possible.
+- Stagger high-volume jobs to reduce burst pressure.

package/server/tools/list-accounts.js

@@ -0,0 +1,63 @@
+import { metaRequest } from '../http.js';
+import { fetchAllPages } from '../utils/paginate.js';
+import { formatError, formatSuccess } from '../utils/response-format.js';
+import { normalizeAccountId } from '../utils/validation.js';
+
+const ACCOUNT_STATUS_MAP = {
+  1: 'ACTIVE',
+  2: 'DISABLED',
+  3: 'UNSETTLED',
+  7: 'PENDING_REVIEW',
+  8: 'PENDING_CLOSURE',
+  9: 'IN_GRACE_PERIOD',
+  100: 'PENDING_RISK_REVIEW'
+};
+
+function normalizeStatus(code) {
+  return ACCOUNT_STATUS_MAP[Number(code)] || 'UNKNOWN';
+}
+
+function mapAccount(account) {
+  return {
+    id: normalizeAccountId(account?.id),
+    name: account?.name || '',
+    account_status: Number(account?.account_status || 0),
+    status: normalizeStatus(account?.account_status),
+    currency: account?.currency || null,
+    timezone_name: account?.timezone_name || null,
+    business_name: account?.business?.name || null
+  };
+}
+
+/**
+ * List all accessible ad accounts for the authenticated user token.
+ * @param {{ status?: string }} [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 || metaRequest;
+
+  try {
+    const allPages = await fetchAllPages(request, '/me/adaccounts', {
+      fields: 'id,name,account_status,currency,timezone_name,business{name}'
+    });
+    const allAccounts = allPages.map(mapAccount);
+    const statusFilter = params.status ? String(params.status).toUpperCase() : null;
+
+    const filteredAccounts = statusFilter
+      ? allAccounts.filter((account) => account.status === statusFilter)
+      : allAccounts;
+
+    return formatSuccess({
+      summary: `Found ${filteredAccounts.length} accessible Meta ad account${filteredAccounts.length === 1 ? '' : 's'}`,
+      data: filteredAccounts,
+      metadata: {
+        totalAccounts: filteredAccounts.length,
+        appliedStatusFilter: statusFilter
+      }
+    });
+  } catch (error) {
+    return formatError(error);
+  }
+}

package/server/tools/mutate.js

@@ -0,0 +1,179 @@
+import { metaRequest } from '../http.js';
+import { formatError, formatSuccess } from '../utils/response-format.js';
+import { invalidParamsError } from '../utils/errors.js';
+import { getAccountId } from '../utils/validation.js';
+import {
+  buildApiRequest,
+  buildRequestPreview,
+  validateOperations
+} from '../utils/mutate-operations.js';
+
+/**
+ * Validate and execute Meta Ads mutation operations with dry-run safety defaults.
+ * @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 || metaRequest;
+
+  try {
+    const operations = params.operations;
+    const accountId = getAccountId(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 validationResults = [];
+      let serverValidated = true;
+
+      try {
+        for (let index = 0; index < operations.length; index += 1) {
+          const operation = operations[index];
+          const apiRequest = buildApiRequest(operation, accountId);
+
+          if (operation.action === 'create' || operation.action === 'update') {
+            const validateParams = {
+              ...apiRequest.params,
+              execution_options: ['validate_only', 'include_recommendations']
+            };
+
+            try {
+              const response = await request(apiRequest.path, validateParams, {
+                method: apiRequest.method
+              });
+              validationResults.push({
+                index,
+                entity: operation.entity,
+                action: operation.action,
+                valid: true,
+                recommendations: response?.recommendations || null
+              });
+            } catch (opError) {
+              validationResults.push({
+                index,
+                entity: operation.entity,
+                action: operation.action,
+                valid: false,
+                error: opError.message
+              });
+
+              if (!partialFailure) {
+                break;
+              }
+            }
+          } else {
+            validationResults.push({
+              index,
+              entity: operation.entity,
+              action: operation.action,
+              valid: true,
+              note: `${operation.action} validated client-side only`
+            });
+          }
+        }
+      } catch (outerError) {
+        serverValidated = false;
+        const preview = buildRequestPreview(operations, accountId);
+        return formatSuccess({
+          summary: `Dry run: ${operations.length} operation(s) validated client-side only (server validation failed: ${outerError.message}). ${preview.requests.length} request(s) would be sent.`,
+          data: preview.requests,
+          metadata: {
+            dryRun: true,
+            serverValidated: false,
+            warning: `Server-side validation unavailable: ${outerError.message}`,
+            operationCount: operations.length,
+            apiCallCount: preview.requests.length,
+            accountId
+          }
+        });
+      }
+
+      const validCount = validationResults.filter((r) => r.valid).length;
+      const invalidCount = validationResults.filter((r) => !r.valid).length;
+
+      return formatSuccess({
+        summary: `Dry run: ${operations.length} operation(s) validated server-side via Meta API. ${validCount} valid, ${invalidCount} invalid. No changes applied.`,
+        data: validationResults,
+        metadata: {
+          dryRun: true,
+          serverValidated: true,
+          operationCount: operations.length,
+          validCount,
+          invalidCount,
+          accountId
+        }
+      });
+    }
+
+    if (process.env.META_ADS_READ_ONLY === 'true') {
+      throw new Error('mutate is disabled in read-only mode (META_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, accountId);
+
+      try {
+        const response = await request(apiRequest.path, apiRequest.params, {
+          method: apiRequest.method
+        });
+
+        const resolvedId = response?.id || operation.id || null;
+        results.push({
+          index,
+          entity: operation.entity,
+          action: operation.action,
+          success: true,
+          id: resolvedId,
+          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,
+        accountId
+      }
+    });
+  } catch (error) {
+    return formatError(error);
+  }
+}