docs(create_adset): clarify OUTCOME_ENGAGEMENT conversion locations (#140)

* docs(create_adset): clarify OUTCOME_ENGAGEMENT conversion locations

On Post engagement uses destination_type=ON_POST (not ON_AD) and needs promoted_object={page_id} set at creation (immutable; otherwise create_ad fails with subcode 1885154). ON_AD is the OUTCOME_LEADS instant-form destination and Meta rejects it for OUTCOME_ENGAGEMENT (subcode 1815715).

Also list the ON_POST/ON_PAGE/ON_EVENT/ON_VIDEO destination_type values and document that the Ads Manager Profile and Page visits goal (PROFILE_AND_PAGE_ENGAGEMENT) is not available via the Marketing API for OUTCOME_ENGAGEMENT. Docstring only; no behavior change (destination_type still passes through to Meta).

* chore(release): bump to 1.0.116

Author: nictuku

meta_ads_mcp/__init__.py

@@ -6,7 +6,7 @@
 
 from meta_ads_mcp.core.server import main
 
-__version__ = "1.0.115"
+__version__ = "1.0.116"
 
 __all__ = [
     'get_ad_accounts',

meta_ads_mcp/core/adsets.py

@@ -122,11 +122,12 @@ async def create_adset(
         name: Ad set name
         optimization_goal: Conversion optimization goal. Valid values depend on the campaign objective and destination_type.
                           OUTCOME_ENGAGEMENT + destination_type=WEBSITE: OFFSITE_CONVERSIONS, LANDING_PAGE_VIEWS, LINK_CLICKS, IMPRESSIONS, REACH.
-                          OUTCOME_ENGAGEMENT + On Post: POST_ENGAGEMENT, IMPRESSIONS, REACH.
-                          OUTCOME_ENGAGEMENT + On Video: THRUPLAY, TWO_SECOND_CONTINUOUS_VIDEO_VIEWS.
-                          OUTCOME_ENGAGEMENT + On Event: EVENT_RESPONSES, IMPRESSIONS, POST_ENGAGEMENT, REACH.
-                          OUTCOME_ENGAGEMENT + On Page: PAGE_LIKES.
+                          OUTCOME_ENGAGEMENT + On Post (destination_type=ON_POST): POST_ENGAGEMENT, IMPRESSIONS, REACH. Also set promoted_object={page_id} at creation (immutable; without it create_ad fails with subcode 1885154). Do NOT use ON_AD here — ON_AD is the OUTCOME_LEADS instant-form destination and Meta rejects it for OUTCOME_ENGAGEMENT (subcode 1815715).
+                          OUTCOME_ENGAGEMENT + On Video (destination_type=ON_VIDEO): THRUPLAY, TWO_SECOND_CONTINUOUS_VIDEO_VIEWS.
+                          OUTCOME_ENGAGEMENT + On Event (destination_type=ON_EVENT): EVENT_RESPONSES, IMPRESSIONS, POST_ENGAGEMENT, REACH.
+                          OUTCOME_ENGAGEMENT + On Page (destination_type=ON_PAGE): PAGE_LIKES.
                           OUTCOME_ENGAGEMENT + Messaging (MESSENGER/WHATSAPP/INSTAGRAM_DIRECT): CONVERSATIONS, LINK_CLICKS.
+                          OUTCOME_ENGAGEMENT "Profile and Page visits" (PROFILE_AND_PAGE_ENGAGEMENT with destination_type INSTAGRAM_PROFILE / FACEBOOK_PAGE / INSTAGRAM_PROFILE_AND_FACEBOOK_PAGE) is shown in Ads Manager but NOT supported via the Marketing API — Meta rejects every variant (code 100). Closest API-supported option is POST_ENGAGEMENT + ON_POST.
                           OUTCOME_TRAFFIC + WEBSITE: LANDING_PAGE_VIEWS, LINK_CLICKS, IMPRESSIONS, REACH.
                           OUTCOME_AWARENESS: REACH, IMPRESSIONS, AD_RECALL_LIFT, THRUPLAY.
                           OUTCOME_LEADS: LEAD_GENERATION, QUALITY_LEAD (forms), QUALITY_CALL (calls), OFFSITE_CONVERSIONS, LINK_CLICKS (website).
@@ -179,10 +180,16 @@ async def create_adset(
                         Required for EU-targeted ad sets along with dsa_payor.
         dsa_payor: DSA payor for European compliance (person/org paying for the ads).
                    Required for EU-targeted ad sets along with dsa_beneficiary.
-        promoted_object: App config for APP_INSTALLS. Required: application_id, object_store_url.
-        destination_type: Where users go after click. Common values: 'WEBSITE', 'WHATSAPP', 'MESSENGER',
-                         'INSTAGRAM_DIRECT', 'ON_AD', 'APP', 'FACEBOOK', 'SHOP_AUTOMATIC'.
-                         Also supports multi-channel combos like 'MESSAGING_MESSENGER_WHATSAPP'.
+        promoted_object: For APP_INSTALLS: app config, required application_id + object_store_url.
+                        For OUTCOME_ENGAGEMENT On-Post (destination_type=ON_POST): set {"page_id": "<id>"} at
+                        creation — required for ads (else create_ad fails with subcode 1885154) and immutable
+                        afterward (cannot be added via update_adset).
+        destination_type: Conversion location / where users go. Pass-through to Meta (no client-side validation).
+                         Common values: 'WEBSITE', 'WHATSAPP', 'MESSENGER', 'INSTAGRAM_DIRECT', 'APP', 'FACEBOOK',
+                         'SHOP_AUTOMATIC'. OUTCOME_ENGAGEMENT on-asset locations: 'ON_POST' (post engagement; needs
+                         promoted_object={page_id}), 'ON_PAGE' (PAGE_LIKES), 'ON_EVENT', 'ON_VIDEO'. 'ON_AD' is the
+                         OUTCOME_LEADS instant-form destination — do NOT use it for OUTCOME_ENGAGEMENT (Meta rejects
+                         it with subcode 1815715). Also supports multi-channel combos like 'MESSAGING_MESSENGER_WHATSAPP'.
         is_dynamic_creative: Enable Dynamic Creative for this ad set.
         frequency_control_specs: Frequency cap specs. MUST be set at creation time — Meta makes this field
                                  immutable after the ad set is created (error 1815198).
@@ -275,9 +282,11 @@ async def create_adset(
             }, indent=2)
 
     # destination_type is passed through to Meta's API without client-side validation.
-    # Meta supports 23+ values (WHATSAPP, MESSENGER, INSTAGRAM_DIRECT, ON_AD, WEBSITE,
-    # APP, FACEBOOK, SHOP_AUTOMATIC, multi-channel MESSAGING_* combos, etc.)
-    # and may add more. Let Meta's API reject invalid values.
+    # Meta supports 23+ values (WHATSAPP, MESSENGER, INSTAGRAM_DIRECT, ON_AD, ON_POST,
+    # ON_PAGE, ON_EVENT, ON_VIDEO, WEBSITE, APP, FACEBOOK, SHOP_AUTOMATIC, multi-channel
+    # MESSAGING_* combos, etc.) and may add more. Validity depends on the campaign
+    # objective (e.g. ON_AD is for OUTCOME_LEADS, ON_POST for OUTCOME_ENGAGEMENT) — let
+    # Meta's API reject incompatible combinations.
     # See: facebook-python-business-sdk AdSet.DestinationType
 
     # Basic targeting is required if not provided

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "meta-ads-mcp"
-version = "1.0.115"
+version = "1.0.116"
 description = "Model Context Protocol (MCP) server for Meta Ads - Use Remote MCP at pipeboard.co for easiest setup"
 readme = "README.md"
 requires-python = ">=3.10"

server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "co.pipeboard/meta-ads-mcp",
   "description": "Facebook / Meta Ads automation with AI: analyze performance, test creatives, optimize spend.",
-  "version": "1.0.115",
+  "version": "1.0.116",
   "remotes": [
     {
       "type": "streamable-http",