@cesteral/meta-mcp 1.0.0

package/dist/mcp-server/prompts/definitions/entity-duplication-workflow.prompt.js

@@ -0,0 +1,234 @@
+export const entityDuplicationWorkflowPrompt = {
+    name: "meta_entity_duplication_workflow",
+    description: "Step-by-step guide for duplicating Meta Ads campaigns, ad sets, and ads using meta_duplicate_entity — covers A/B testing, scaling, and common patterns.",
+    arguments: [
+        {
+            name: "entityType",
+            description: "Entity type to duplicate: campaign, adSet, or ad",
+            required: true,
+        },
+        {
+            name: "entityId",
+            description: "ID of the entity to duplicate",
+            required: true,
+        },
+    ],
+};
+export function getEntityDuplicationWorkflowMessage(args) {
+    const entityType = args?.entityType || "{entityType}";
+    const entityId = args?.entityId || "{entityId}";
+    return `# Meta Entity Duplication Workflow
+
+Entity Type: \`${entityType}\`
+Entity ID: \`${entityId}\`
+
+---
+
+## Overview
+
+\`meta_duplicate_entity\` creates a copy of a campaign, ad set, or ad via the Meta \`/{id}/copies\` endpoint. The copy includes all child entities and settings.
+
+| What Gets Copied | Details |
+|------------------|---------|
+| **Campaign** | All ad sets, ads, targeting, budgets, creatives |
+| **Ad Set** | All ads, targeting spec, budget, schedule |
+| **Ad** | Creative reference, tracking, status |
+
+---
+
+## Step 1: Review the Source Entity
+
+Before duplicating, inspect the entity you're copying:
+
+\`\`\`json
+{
+  "tool": "meta_get_entity",
+  "params": {
+    "entityType": "${entityType}",
+    "entityId": "${entityId}",
+    "fields": ["name", "status", "effective_status"]
+  }
+}
+\`\`\`
+
+Confirm this is the right entity and note its current state.
+
+---
+
+## Step 2: Duplicate the Entity
+
+### Basic Duplication (Paused)
+
+\`\`\`json
+{
+  "tool": "meta_duplicate_entity",
+  "params": {
+    "entityType": "${entityType}",
+    "entityId": "${entityId}",
+    "statusOption": "PAUSED"
+  }
+}
+\`\`\`
+
+### With Rename Options
+
+\`\`\`json
+{
+  "tool": "meta_duplicate_entity",
+  "params": {
+    "entityType": "${entityType}",
+    "entityId": "${entityId}",
+    "renameOptions": {
+      "prefix": "Copy of "
+    },
+    "statusOption": "PAUSED"
+  }
+}
+\`\`\`
+
+### Status Options
+
+| Option | Behavior |
+|--------|----------|
+| \`PAUSED\` | Copy is created paused (safest — review before activating) |
+| \`ACTIVE\` | Copy starts delivering immediately |
+| \`INHERITED\` | Copy inherits the source entity's status |
+
+⚠️ **GOTCHA**: Always use \`PAUSED\` unless you intentionally want the copy to start spending immediately.
+
+---
+
+## Step 3: Customize the Copy
+
+The duplication returns the new entity ID. Use it to modify the copy:
+
+### Update Name
+
+\`\`\`json
+{
+  "tool": "meta_update_entity",
+  "params": {
+    "entityId": "{newEntityId}",
+    "data": {
+      "name": "Campaign B - Broad Targeting Test"
+    }
+  }
+}
+\`\`\`
+
+### Update Targeting (Ad Set)
+
+\`\`\`json
+{
+  "tool": "meta_update_entity",
+  "params": {
+    "entityId": "{newAdSetId}",
+    "data": {
+      "targeting": {
+        "geo_locations": { "countries": ["US"] },
+        "interests": [{ "id": "6003384829981", "name": "Fitness and wellness" }],
+        "age_min": 18,
+        "age_max": 44
+      }
+    }
+  }
+}
+\`\`\`
+
+### Update Budget
+
+\`\`\`json
+{
+  "tool": "meta_update_entity",
+  "params": {
+    "entityId": "{newEntityId}",
+    "data": {
+      "daily_budget": 3000
+    }
+  }
+}
+\`\`\`
+
+⚠️ **GOTCHA**: Budget amounts are in **cents** — \`daily_budget: 3000\` means $30.00.
+
+⚠️ **GOTCHA**: Targeting updates **replace entirely**. Always send the complete targeting spec.
+
+---
+
+## Step 4: Activate When Ready
+
+After reviewing and customizing the copy:
+
+\`\`\`json
+{
+  "tool": "meta_bulk_update_status",
+  "params": {
+    "entityIds": ["{newEntityId}"],
+    "status": "ACTIVE"
+  }
+}
+\`\`\`
+
+---
+
+## Common Patterns
+
+### A/B Testing (Split Test)
+
+1. Duplicate the campaign or ad set
+2. Change one variable on the copy (targeting, creative, bid)
+3. Activate both and compare performance
+
+\`\`\`
+Original: "Summer Campaign - Interest A" (targeting: running)
+   Copy: "Summer Campaign - Interest B" (targeting: fitness)
+\`\`\`
+
+### Scaling to New Markets
+
+1. Duplicate a proven campaign
+2. Update geo targeting on the copy
+3. Adjust budget for the new market
+4. Activate
+
+### Creative Testing
+
+1. Duplicate an ad
+2. Update the creative reference on the copy
+3. Run both ads in the same ad set
+
+### Template Campaigns
+
+1. Create a "template" campaign with desired settings (PAUSED)
+2. Duplicate it for each new client/product
+3. Update names, budgets, targeting on each copy
+4. Activate when ready
+
+---
+
+## Verification
+
+After duplication, verify the copy:
+
+\`\`\`json
+{
+  "tool": "meta_get_entity",
+  "params": {
+    "entityType": "${entityType}",
+    "entityId": "{newEntityId}",
+    "fields": ["name", "status", "effective_status"]
+  }
+}
+\`\`\`
+
+## Success Criteria
+
+- [ ] Source entity reviewed before duplication
+- [ ] Copy created with \`PAUSED\` status
+- [ ] Copy renamed to distinguish from original
+- [ ] Desired changes applied (targeting, budget, creative)
+- [ ] Copy verified via \`meta_get_entity\`
+- [ ] Activated only after review
+`;
+}
+//# sourceMappingURL=entity-duplication-workflow.prompt.js.map

package/dist/mcp-server/prompts/definitions/entity-duplication-workflow.prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-duplication-workflow.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/entity-duplication-workflow.prompt.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,+BAA+B,GAAW;IACrD,IAAI,EAAE,kCAAkC;IACxC,WAAW,EACT,yJAAyJ;IAC3J,SAAS,EAAE;QACT;YACE,IAAI,EAAE,YAAY;YAClB,WAAW,EAAE,kDAAkD;YAC/D,QAAQ,EAAE,IAAI;SACf;QACD;YACE,IAAI,EAAE,UAAU;YAChB,WAAW,EAAE,+BAA+B;YAC5C,QAAQ,EAAE,IAAI;SACf;KACF;CACF,CAAC;AAEF,MAAM,UAAU,mCAAmC,CAAC,IAA6B;IAC/E,MAAM,UAAU,GAAG,IAAI,EAAE,UAAU,IAAI,cAAc,CAAC;IACtD,MAAM,QAAQ,GAAG,IAAI,EAAE,QAAQ,IAAI,YAAY,CAAC;IAEhD,OAAO;;iBAEQ,UAAU;eACZ,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;qBAwBF,UAAU;mBACZ,QAAQ;;;;;;;;;;;;;;;;;;qBAkBN,UAAU;mBACZ,QAAQ;;;;;;;;;;;;qBAYN,UAAU;mBACZ,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAyIN,UAAU;;;;;;;;;;;;;;;CAe9B,CAAC;AACF,CAAC"}

package/dist/mcp-server/prompts/definitions/entity-update-workflow.prompt.d.ts

@@ -0,0 +1,4 @@
+import type { Prompt } from "@modelcontextprotocol/sdk/types.js";
+export declare const entityUpdateWorkflowPrompt: Prompt;
+export declare function getEntityUpdateWorkflowMessage(args?: Record<string, string>): string;
+//# sourceMappingURL=entity-update-workflow.prompt.d.ts.map

package/dist/mcp-server/prompts/definitions/entity-update-workflow.prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-update-workflow.prompt.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/entity-update-workflow.prompt.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oCAAoC,CAAC;AAQjE,eAAO,MAAM,0BAA0B,EAAE,MAgBxC,CAAC;AAEF,wBAAgB,8BAA8B,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CA8IpF"}

package/dist/mcp-server/prompts/definitions/entity-update-workflow.prompt.js

@@ -0,0 +1,159 @@
+export const entityUpdateWorkflowPrompt = {
+    name: "meta_entity_update_workflow",
+    description: "Step-by-step guide for safely updating Meta Ads entities: fetch current state, build partial update payload, execute update, and verify changes. Covers campaigns, ad sets, ads, ad creatives, and custom audiences.",
+    arguments: [
+        {
+            name: "entityType",
+            description: "Entity type to update: campaign, adSet, ad, adCreative, or customAudience",
+            required: true,
+        },
+        {
+            name: "entityId",
+            description: "ID of the entity to update",
+            required: true,
+        },
+    ],
+};
+export function getEntityUpdateWorkflowMessage(args) {
+    const entityType = args?.entityType || "{entityType}";
+    const entityId = args?.entityId || "{entityId}";
+    return `# Meta Ads Entity Update Workflow
+
+Entity Type: \`${entityType}\`
+Entity ID: \`${entityId}\`
+
+---
+
+## Step 1: Fetch Current State
+
+Before updating, always read the entity's current configuration:
+
+\`\`\`json
+{
+  "tool": "meta_get_entity",
+  "params": {
+    "entityType": "${entityType}",
+    "entityId": "${entityId}"
+  }
+}
+\`\`\`
+
+Review the current values to understand what you're changing. Save the current state mentally for rollback reference.
+
+**Resource reference:** Fetch \`entity-schema://${entityType}\` for the full field schema and \`entity-examples://${entityType}\` for common update patterns.
+
+---
+
+## Step 2: Build Update Payload
+
+Meta uses POST with PATCH semantics — only include the fields you want to change. Unspecified fields remain unchanged.
+
+### Campaign Updates
+
+\`\`\`json
+{
+  "tool": "meta_update_entity",
+  "params": {
+    "entityType": "campaign",
+    "entityId": "${entityId}",
+    "data": {
+      "name": "Updated Campaign Name",
+      "daily_budget": 5000,
+      "status": "PAUSED"
+    }
+  }
+}
+\`\`\`
+
+### Ad Set Updates
+
+\`\`\`json
+{
+  "tool": "meta_update_entity",
+  "params": {
+    "entityType": "adSet",
+    "entityId": "${entityId}",
+    "data": {
+      "daily_budget": 3000,
+      "bid_amount": 250,
+      "targeting": {
+        "geo_locations": {
+          "countries": ["US", "GB"]
+        },
+        "age_min": 25,
+        "age_max": 55
+      }
+    }
+  }
+}
+\`\`\`
+
+### Ad Updates
+
+\`\`\`json
+{
+  "tool": "meta_update_entity",
+  "params": {
+    "entityType": "ad",
+    "entityId": "${entityId}",
+    "data": {
+      "name": "Updated Ad Name",
+      "status": "ACTIVE"
+    }
+  }
+}
+\`\`\`
+
+---
+
+## Step 3: Execute and Verify
+
+After the update call succeeds, verify the changes took effect:
+
+\`\`\`json
+{
+  "tool": "meta_get_entity",
+  "params": {
+    "entityType": "${entityType}",
+    "entityId": "${entityId}"
+  }
+}
+\`\`\`
+
+Compare the returned values with what you set in Step 2.
+
+---
+
+## Gotchas
+
+- **Budget values are in cents**: \`daily_budget: 5000\` means $50.00 USD, not $5,000.
+- **Targeting replaces entirely**: When updating \`targeting\`, the entire targeting spec is replaced, not merged. Always include all targeting fields you want to keep.
+- **No updateMask**: Unlike DV360/Google Ads, Meta doesn't use an updateMask. Just send the fields you want to change.
+- **status field**: Use \`ACTIVE\`, \`PAUSED\`, or \`ARCHIVED\`. Archiving is irreversible.
+- **effective_status vs status**: \`status\` is what you set. \`effective_status\` reflects the actual delivery state (may differ if parent is paused). Always check \`effective_status\` after updates.
+- **special_ad_categories**: Cannot be changed after campaign creation. Must delete and recreate.
+- **48-hour reporting lag**: Performance data may take up to 48 hours to fully populate after changes.
+
+---
+
+## Rollback
+
+If an update causes issues, reverse it by sending the original values:
+
+\`\`\`json
+{
+  "tool": "meta_update_entity",
+  "params": {
+    "entityType": "${entityType}",
+    "entityId": "${entityId}",
+    "data": {
+      "field_that_was_changed": "{original_value}"
+    }
+  }
+}
+\`\`\`
+
+Report the rollback hint (original values) whenever you make a change so the user can revert if needed.
+`;
+}
+//# sourceMappingURL=entity-update-workflow.prompt.js.map

package/dist/mcp-server/prompts/definitions/entity-update-workflow.prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-update-workflow.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/entity-update-workflow.prompt.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,0BAA0B,GAAW;IAChD,IAAI,EAAE,6BAA6B;IACnC,WAAW,EACT,sNAAsN;IACxN,SAAS,EAAE;QACT;YACE,IAAI,EAAE,YAAY;YAClB,WAAW,EAAE,2EAA2E;YACxF,QAAQ,EAAE,IAAI;SACf;QACD;YACE,IAAI,EAAE,UAAU;YAChB,WAAW,EAAE,4BAA4B;YACzC,QAAQ,EAAE,IAAI;SACf;KACF;CACF,CAAC;AAEF,MAAM,UAAU,8BAA8B,CAAC,IAA6B;IAC1E,MAAM,UAAU,GAAG,IAAI,EAAE,UAAU,IAAI,cAAc,CAAC;IACtD,MAAM,QAAQ,GAAG,IAAI,EAAE,QAAQ,IAAI,YAAY,CAAC;IAEhD,OAAO;;iBAEQ,UAAU;eACZ,QAAQ;;;;;;;;;;;;qBAYF,UAAU;mBACZ,QAAQ;;;;;;;kDAOuB,UAAU,wDAAwD,UAAU;;;;;;;;;;;;;;;mBAe3G,QAAQ;;;;;;;;;;;;;;;;;mBAiBR,QAAQ;;;;;;;;;;;;;;;;;;;;;;;mBAuBR,QAAQ;;;;;;;;;;;;;;;;;;;qBAmBN,UAAU;mBACZ,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA6BN,UAAU;mBACZ,QAAQ;;;;;;;;;CAS1B,CAAC;AACF,CAAC"}

package/dist/mcp-server/prompts/definitions/insights-reporting-workflow.prompt.d.ts

@@ -0,0 +1,4 @@
+import type { Prompt } from "@modelcontextprotocol/sdk/types.js";
+export declare const insightsReportingWorkflowPrompt: Prompt;
+export declare function getInsightsReportingWorkflowMessage(args?: Record<string, string>): string;
+//# sourceMappingURL=insights-reporting-workflow.prompt.d.ts.map

package/dist/mcp-server/prompts/definitions/insights-reporting-workflow.prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insights-reporting-workflow.prompt.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/insights-reporting-workflow.prompt.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oCAAoC,CAAC;AAEjE,eAAO,MAAM,+BAA+B,EAAE,MAe7C,CAAC;AAEF,wBAAgB,mCAAmC,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CA8DzF"}

package/dist/mcp-server/prompts/definitions/insights-reporting-workflow.prompt.js

@@ -0,0 +1,79 @@
+export const insightsReportingWorkflowPrompt = {
+    name: "meta_insights_reporting_workflow",
+    description: "Guide for querying Meta Ads performance insights with breakdowns and attribution",
+    arguments: [
+        {
+            name: "adAccountId",
+            description: "Meta Ad Account ID",
+            required: true,
+        },
+        {
+            name: "entityLevel",
+            description: "Reporting level: account, campaign, adset, ad",
+            required: false,
+        },
+    ],
+};
+export function getInsightsReportingWorkflowMessage(args) {
+    const adAccountId = args?.adAccountId || "{adAccountId}";
+    const entityLevel = args?.entityLevel || "campaign";
+    return `# Meta Insights Reporting Workflow
+
+## Step 1: Basic Performance Query
+
+\`\`\`json
+meta_get_insights({
+  "entityId": "${adAccountId}",
+  "datePreset": "last_7d",
+  "level": "${entityLevel}"
+})
+\`\`\`
+
+## Step 2: Add Breakdowns
+
+\`\`\`json
+meta_get_insights_breakdowns({
+  "entityId": "${adAccountId}",
+  "breakdowns": ["age", "gender"],
+  "datePreset": "last_30d",
+  "level": "${entityLevel}"
+})
+\`\`\`
+
+## Step 3: Daily Trend Analysis
+
+\`\`\`json
+meta_get_insights({
+  "entityId": "${adAccountId}",
+  "timeRange": { "since": "2026-01-01", "until": "2026-01-31" },
+  "timeIncrement": "1",
+  "level": "${entityLevel}"
+})
+\`\`\`
+
+## Step 4: Attribution Analysis
+
+\`\`\`json
+meta_get_insights_breakdowns({
+  "entityId": "${adAccountId}",
+  "breakdowns": ["device_platform"],
+  "fields": ["impressions", "clicks", "spend", "actions", "action_values"],
+  "datePreset": "last_30d",
+  "actionAttributionWindows": ["1d_click", "7d_click", "1d_view"]
+})
+\`\`\`
+
+## Resource References
+
+- Fetch \`insights-reference://all\` for full metrics and breakdowns list
+- Fetch \`entity-hierarchy://all\` for entity relationships
+
+## Tips
+
+- Data may lag up to **48 hours**
+- Use \`last_7d\` or \`last_30d\` for most analyses
+- Limit to ~20 metrics per call for best performance
+- Valid breakdown combos: age+gender, device+publisher (NOT country+region)
+`;
+}
+//# sourceMappingURL=insights-reporting-workflow.prompt.js.map

package/dist/mcp-server/prompts/definitions/insights-reporting-workflow.prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"insights-reporting-workflow.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/insights-reporting-workflow.prompt.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,MAAM,+BAA+B,GAAW;IACrD,IAAI,EAAE,kCAAkC;IACxC,WAAW,EAAE,kFAAkF;IAC/F,SAAS,EAAE;QACT;YACE,IAAI,EAAE,aAAa;YACnB,WAAW,EAAE,oBAAoB;YACjC,QAAQ,EAAE,IAAI;SACf;QACD;YACE,IAAI,EAAE,aAAa;YACnB,WAAW,EAAE,+CAA+C;YAC5D,QAAQ,EAAE,KAAK;SAChB;KACF;CACF,CAAC;AAEF,MAAM,UAAU,mCAAmC,CAAC,IAA6B;IAC/E,MAAM,WAAW,GAAG,IAAI,EAAE,WAAW,IAAI,eAAe,CAAC;IACzD,MAAM,WAAW,GAAG,IAAI,EAAE,WAAW,IAAI,UAAU,CAAC;IAEpD,OAAO;;;;;;iBAMQ,WAAW;;cAEd,WAAW;;;;;;;;iBAQR,WAAW;;;cAGd,WAAW;;;;;;;;iBAQR,WAAW;;;cAGd,WAAW;;;;;;;;iBAQR,WAAW;;;;;;;;;;;;;;;;;;;CAmB3B,CAAC;AACF,CAAC"}

package/dist/mcp-server/prompts/definitions/targeting-discovery-workflow.prompt.d.ts

@@ -0,0 +1,4 @@
+import type { Prompt } from "@modelcontextprotocol/sdk/types.js";
+export declare const targetingDiscoveryWorkflowPrompt: Prompt;
+export declare function getTargetingDiscoveryWorkflowMessage(args?: Record<string, string>): string;
+//# sourceMappingURL=targeting-discovery-workflow.prompt.d.ts.map

package/dist/mcp-server/prompts/definitions/targeting-discovery-workflow.prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"targeting-discovery-workflow.prompt.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/targeting-discovery-workflow.prompt.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oCAAoC,CAAC;AAQjE,eAAO,MAAM,gCAAgC,EAAE,MAiB9C,CAAC;AAEF,wBAAgB,oCAAoC,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAgR1F"}