meta-ads-mcp 0.11.0__tar.gz → 0.11.2__tar.gz

{meta_ads_mcp-0.11.0 → meta_ads_mcp-0.11.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.11.0
+Version: 0.11.2
 Summary: Model Context Protocol (MCP) server for interacting with Meta Ads API
 Project-URL: Homepage, https://github.com/pipeboard-co/meta-ads-mcp
 Project-URL: Bug Tracker, https://github.com/pipeboard-co/meta-ads-mcp/issues

{meta_ads_mcp-0.11.0 → meta_ads_mcp-0.11.2}/meta_ads_mcp/__init__.py

@@ -6,7 +6,7 @@ This package provides a Meta Ads MCP integration
 
 from meta_ads_mcp.core.server import main
 
-__version__ = "0.11.0"
+__version__ = "0.11.2"
 
 __all__ = [
     'get_ad_accounts',

{meta_ads_mcp-0.11.0 → meta_ads_mcp-0.11.2}/meta_ads_mcp/core/ads.py

@@ -14,6 +14,10 @@ from .utils import download_image, try_multiple_download_methods, ad_creative_im
 from .server import mcp_server
 
 
+# Only register the save_ad_image_locally function if explicitly enabled via environment variable
+ENABLE_SAVE_AD_IMAGE_LOCALLY = bool(os.environ.get("META_ADS_ENABLE_SAVE_AD_IMAGE_LOCALLY", ""))
+
+
 @mcp_server.tool()
 @meta_api_tool
 async def get_ads(account_id: str, access_token: Optional[str] = None, limit: int = 10, 
@@ -107,6 +111,10 @@ async def create_ad(
         tracking_specs: Optional tracking specifications (e.g., for pixel events).
                       Example: [{"action.type":"offsite_conversion","fb_pixel":["YOUR_PIXEL_ID"]}]
         access_token: Meta API access token (optional - will use cached token if not provided)
+
+    Note:
+        Dynamic Creative creatives require the parent ad set to have `is_dynamic_creative=true`.
+        Otherwise, ad creation will fail with error_subcode 1885998.
     """
     # Check required parameters
     if not account_id:
@@ -380,130 +388,131 @@ async def get_ad_image(ad_id: str, access_token: Optional[str] = None) -> Image:
         return f"Error processing image: {str(e)}"
 
 
-@mcp_server.tool()
-@meta_api_tool
-async def save_ad_image_locally(ad_id: str, access_token: Optional[str] = None, output_dir: str = "ad_images") -> str:
-    """
-    Get, download, and save a Meta ad image locally, returning the file path.
-    
-    Args:
-        ad_id: Meta Ads ad ID
-        access_token: Meta API access token (optional - will use cached token if not provided)
-        output_dir: Directory to save the image file (default: 'ad_images')
-    
-    Returns:
-        The file path to the saved image, or an error message string.
-    """
-    if not ad_id:
-        return json.dumps({"error": "No ad ID provided"}, indent=2)
+if ENABLE_SAVE_AD_IMAGE_LOCALLY:
+    @mcp_server.tool()
+    @meta_api_tool
+    async def save_ad_image_locally(ad_id: str, access_token: Optional[str] = None, output_dir: str = "ad_images") -> str:
+        """
+        Get, download, and save a Meta ad image locally, returning the file path.
         
-    print(f"Attempting to get and save creative image for ad {ad_id}")
-    
-    # First, get creative and account IDs
-    ad_endpoint = f"{ad_id}"
-    ad_params = {
-        "fields": "creative{id},account_id"
-    }
-    
-    ad_data = await make_api_request(ad_endpoint, access_token, ad_params)
-    
-    if "error" in ad_data:
-        return json.dumps({"error": f"Could not get ad data - {json.dumps(ad_data)}"}, indent=2)
-    
-    account_id = ad_data.get("account_id")
-    if not account_id:
-        return json.dumps({"error": "No account ID found for ad"}, indent=2)
-    
-    if "creative" not in ad_data:
-        return json.dumps({"error": "No creative found for this ad"}, indent=2)
+        Args:
+            ad_id: Meta Ads ad ID
+            access_token: Meta API access token (optional - will use cached token if not provided)
+            output_dir: Directory to save the image file (default: 'ad_images')
         
-    creative_data = ad_data.get("creative", {})
-    creative_id = creative_data.get("id")
-    if not creative_id:
-        return json.dumps({"error": "No creative ID found"}, indent=2)
-    
-    # Get creative details to find image hash
-    creative_endpoint = f"{creative_id}"
-    creative_params = {
-        "fields": "id,name,image_hash,asset_feed_spec"
-    }
-    creative_details = await make_api_request(creative_endpoint, access_token, creative_params)
-    
-    image_hashes = []
-    if "image_hash" in creative_details:
-        image_hashes.append(creative_details["image_hash"])
-    if "asset_feed_spec" in creative_details and "images" in creative_details["asset_feed_spec"]:
-        for image in creative_details["asset_feed_spec"]["images"]:
-            if "hash" in image:
-                image_hashes.append(image["hash"])
-    
-    if not image_hashes:
-        # Fallback attempt (as in get_ad_image)
-        creative_json = await get_ad_creatives(ad_id=ad_id, access_token=access_token) # Ensure ad_id is passed correctly
-        creative_data_list = json.loads(creative_json)
-        if 'data' in creative_data_list and creative_data_list['data']:
-             first_creative = creative_data_list['data'][0]
-             if 'object_story_spec' in first_creative and 'link_data' in first_creative['object_story_spec'] and 'image_hash' in first_creative['object_story_spec']['link_data']:
-                 image_hashes.append(first_creative['object_story_spec']['link_data']['image_hash'])
-             elif 'image_hash' in first_creative: # Check direct hash on creative data
-                  image_hashes.append(first_creative['image_hash'])
+        Returns:
+            The file path to the saved image, or an error message string.
+        """
+        if not ad_id:
+            return json.dumps({"error": "No ad ID provided"}, indent=2)
+            
+        print(f"Attempting to get and save creative image for ad {ad_id}")
+        
+        # First, get creative and account IDs
+        ad_endpoint = f"{ad_id}"
+        ad_params = {
+            "fields": "creative{id},account_id"
+        }
+        
+        ad_data = await make_api_request(ad_endpoint, access_token, ad_params)
+        
+        if "error" in ad_data:
+            return json.dumps({"error": f"Could not get ad data - {json.dumps(ad_data)}"}, indent=2)
+        
+        account_id = ad_data.get("account_id")
+        if not account_id:
+            return json.dumps({"error": "No account ID found for ad"}, indent=2)
+        
+        if "creative" not in ad_data:
+            return json.dumps({"error": "No creative found for this ad"}, indent=2)
+            
+        creative_data = ad_data.get("creative", {})
+        creative_id = creative_data.get("id")
+        if not creative_id:
+            return json.dumps({"error": "No creative ID found"}, indent=2)
+        
+        # Get creative details to find image hash
+        creative_endpoint = f"{creative_id}"
+        creative_params = {
+            "fields": "id,name,image_hash,asset_feed_spec"
+        }
+        creative_details = await make_api_request(creative_endpoint, access_token, creative_params)
+        
+        image_hashes = []
+        if "image_hash" in creative_details:
+            image_hashes.append(creative_details["image_hash"])
+        if "asset_feed_spec" in creative_details and "images" in creative_details["asset_feed_spec"]:
+            for image in creative_details["asset_feed_spec"]["images"]:
+                if "hash" in image:
+                    image_hashes.append(image["hash"])
+        
+        if not image_hashes:
+            # Fallback attempt (as in get_ad_image)
+            creative_json = await get_ad_creatives(ad_id=ad_id, access_token=access_token) # Ensure ad_id is passed correctly
+            creative_data_list = json.loads(creative_json)
+            if 'data' in creative_data_list and creative_data_list['data']:
+                 first_creative = creative_data_list['data'][0]
+                 if 'object_story_spec' in first_creative and 'link_data' in first_creative['object_story_spec'] and 'image_hash' in first_creative['object_story_spec']['link_data']:
+                     image_hashes.append(first_creative['object_story_spec']['link_data']['image_hash'])
+                 elif 'image_hash' in first_creative: # Check direct hash on creative data
+                      image_hashes.append(first_creative['image_hash'])
 
 
-    if not image_hashes:
-        return json.dumps({"error": "No image hashes found in creative or fallback"}, indent=2)
+        if not image_hashes:
+            return json.dumps({"error": "No image hashes found in creative or fallback"}, indent=2)
 
-    print(f"Found image hashes: {image_hashes}")
-    
-    # Fetch image data using the first hash
-    image_endpoint = f"act_{account_id}/adimages"
-    hashes_str = f'["{image_hashes[0]}"]'
-    image_params = {
-        "fields": "hash,url,width,height,name,status",
-        "hashes": hashes_str
-    }
-    
-    print(f"Requesting image data with params: {image_params}")
-    image_data = await make_api_request(image_endpoint, access_token, image_params)
-    
-    if "error" in image_data:
-        return json.dumps({"error": f"Failed to get image data - {json.dumps(image_data)}"}, indent=2)
-    
-    if "data" not in image_data or not image_data["data"]:
-        return json.dumps({"error": "No image data returned from API"}, indent=2)
+        print(f"Found image hashes: {image_hashes}")
         
-    first_image = image_data["data"][0]
-    image_url = first_image.get("url")
-    
-    if not image_url:
-        return json.dumps({"error": "No valid image URL found in API response"}, indent=2)
+        # Fetch image data using the first hash
+        image_endpoint = f"act_{account_id}/adimages"
+        hashes_str = f'["{image_hashes[0]}"]'
+        image_params = {
+            "fields": "hash,url,width,height,name,status",
+            "hashes": hashes_str
+        }
         
-    print(f"Downloading image from URL: {image_url}")
-    
-    # Download and Save Image
-    image_bytes = await download_image(image_url)
-    
-    if not image_bytes:
-        return json.dumps({"error": "Failed to download image"}, indent=2)
+        print(f"Requesting image data with params: {image_params}")
+        image_data = await make_api_request(image_endpoint, access_token, image_params)
         
-    try:
-        # Ensure output directory exists
-        if not os.path.exists(output_dir):
-            os.makedirs(output_dir)
+        if "error" in image_data:
+            return json.dumps({"error": f"Failed to get image data - {json.dumps(image_data)}"}, indent=2)
+        
+        if "data" not in image_data or not image_data["data"]:
+            return json.dumps({"error": "No image data returned from API"}, indent=2)
+            
+        first_image = image_data["data"][0]
+        image_url = first_image.get("url")
+        
+        if not image_url:
+            return json.dumps({"error": "No valid image URL found in API response"}, indent=2)
+            
+        print(f"Downloading image from URL: {image_url}")
+        
+        # Download and Save Image
+        image_bytes = await download_image(image_url)
+        
+        if not image_bytes:
+            return json.dumps({"error": "Failed to download image"}, indent=2)
             
-        # Create a filename (e.g., using ad_id and image hash)
-        file_extension = ".jpg" # Default extension, could try to infer from headers later
-        filename = f"{ad_id}_{image_hashes[0]}{file_extension}"
-        filepath = os.path.join(output_dir, filename)
-        
-        # Save the image bytes to the file
-        with open(filepath, "wb") as f:
-            f.write(image_bytes)
+        try:
+            # Ensure output directory exists
+            if not os.path.exists(output_dir):
+                os.makedirs(output_dir)
+                
+            # Create a filename (e.g., using ad_id and image hash)
+            file_extension = ".jpg" # Default extension, could try to infer from headers later
+            filename = f"{ad_id}_{image_hashes[0]}{file_extension}"
+            filepath = os.path.join(output_dir, filename)
             
-        print(f"Image saved successfully to: {filepath}")
-        return json.dumps({"filepath": filepath}, indent=2) # Return JSON with filepath
+            # Save the image bytes to the file
+            with open(filepath, "wb") as f:
+                f.write(image_bytes)
+                
+            print(f"Image saved successfully to: {filepath}")
+            return json.dumps({"filepath": filepath}, indent=2) # Return JSON with filepath
 
-    except Exception as e:
-        return json.dumps({"error": f"Failed to save image: {str(e)}"}, indent=2)
+        except Exception as e:
+            return json.dumps({"error": f"Failed to save image: {str(e)}"}, indent=2)
 
 
 @mcp_server.tool()

{meta_ads_mcp-0.11.0 → meta_ads_mcp-0.11.2}/meta_ads_mcp/core/adsets.py

@@ -27,14 +27,14 @@ async def get_adsets(account_id: str, access_token: Optional[str] = None, limit:
     if campaign_id:
         endpoint = f"{campaign_id}/adsets"
         params = {
-            "fields": "id,name,campaign_id,status,daily_budget,lifetime_budget,targeting,bid_amount,bid_strategy,optimization_goal,billing_event,start_time,end_time,created_time,updated_time,frequency_control_specs{event,interval_days,max_frequency}",
+            "fields": "id,name,campaign_id,status,daily_budget,lifetime_budget,targeting,bid_amount,bid_strategy,optimization_goal,billing_event,start_time,end_time,created_time,updated_time,is_dynamic_creative,frequency_control_specs{event,interval_days,max_frequency}",
             "limit": limit
         }
     else:
         # Use account endpoint if no campaign_id is given
         endpoint = f"{account_id}/adsets"
         params = {
-            "fields": "id,name,campaign_id,status,daily_budget,lifetime_budget,targeting,bid_amount,bid_strategy,optimization_goal,billing_event,start_time,end_time,created_time,updated_time,frequency_control_specs{event,interval_days,max_frequency}",
+            "fields": "id,name,campaign_id,status,daily_budget,lifetime_budget,targeting,bid_amount,bid_strategy,optimization_goal,billing_event,start_time,end_time,created_time,updated_time,is_dynamic_creative,frequency_control_specs{event,interval_days,max_frequency}",
             "limit": limit
         }
         # Note: Removed the attempt to add campaign_id to params for the account endpoint case, 
@@ -67,7 +67,7 @@ async def get_adset_details(adset_id: str, access_token: Optional[str] = None) -
     endpoint = f"{adset_id}"
     # Explicitly prioritize frequency_control_specs in the fields request
     params = {
-        "fields": "id,name,campaign_id,status,frequency_control_specs{event,interval_days,max_frequency},daily_budget,lifetime_budget,targeting,bid_amount,bid_strategy,optimization_goal,billing_event,start_time,end_time,created_time,updated_time,attribution_spec,destination_type,promoted_object,pacing_type,budget_remaining,dsa_beneficiary"
+        "fields": "id,name,campaign_id,status,frequency_control_specs{event,interval_days,max_frequency},daily_budget,lifetime_budget,targeting,bid_amount,bid_strategy,optimization_goal,billing_event,start_time,end_time,created_time,updated_time,attribution_spec,destination_type,promoted_object,pacing_type,budget_remaining,dsa_beneficiary,is_dynamic_creative"
     }
     
     data = await make_api_request(endpoint, access_token, params)
@@ -100,6 +100,7 @@ async def create_adset(
     dsa_beneficiary: Optional[str] = None,
     promoted_object: Optional[Dict[str, Any]] = None,
     destination_type: Optional[str] = None,
+    is_dynamic_creative: Optional[bool] = None,
     access_token: Optional[str] = None
 ) -> str:
     """
@@ -125,8 +126,9 @@ async def create_adset(
                         Optional fields: custom_event_type, pixel_id, page_id.
                         Example: {"application_id": "123456789012345", "object_store_url": "https://apps.apple.com/app/id123456789"}
         destination_type: Where users are directed after clicking the ad (e.g., 'APP_STORE', 'DEEPLINK', 'APP_INSTALL', 'ON_AD').
-                         Required for mobile app campaigns and lead generation campaigns.
-                         Use 'ON_AD' for lead generation campaigns where user interaction happens within the ad.
+                          Required for mobile app campaigns and lead generation campaigns.
+                          Use 'ON_AD' for lead generation campaigns where user interaction happens within the ad.
+        is_dynamic_creative: Enable Dynamic Creative for this ad set (required when using dynamic creatives with asset_feed_spec/dynamic_creative_spec).
         access_token: Meta API access token (optional - will use cached token if not provided)
     """
     # Check required parameters
@@ -249,6 +251,10 @@ async def create_adset(
     if destination_type:
         params["destination_type"] = destination_type
     
+    # Enable Dynamic Creative if requested
+    if is_dynamic_creative is not None:
+        params["is_dynamic_creative"] = "true" if bool(is_dynamic_creative) else "false"
+    
     try:
         data = await make_api_request(endpoint, access_token, params, method="POST")
         return json.dumps(data, indent=2)
@@ -290,6 +296,7 @@ async def create_adset(
 async def update_adset(adset_id: str, frequency_control_specs: Optional[List[Dict[str, Any]]] = None, bid_strategy: Optional[str] = None, 
                         bid_amount: Optional[int] = None, status: Optional[str] = None, targeting: Optional[Dict[str, Any]] = None, 
                         optimization_goal: Optional[str] = None, daily_budget: Optional[int] = None, lifetime_budget: Optional[int] = None, 
+                        is_dynamic_creative: Optional[bool] = None,
                         access_token: Optional[str] = None) -> str:
     """
     Update an ad set with new settings including frequency caps and budgets.
@@ -306,6 +313,7 @@ async def update_adset(adset_id: str, frequency_control_specs: Optional[List[Dic
         optimization_goal: Conversion optimization goal (e.g., 'LINK_CLICKS', 'CONVERSIONS', 'APP_INSTALLS', etc.)
         daily_budget: Daily budget in account currency (in cents) as a string
         lifetime_budget: Lifetime budget in account currency (in cents) as a string
+        is_dynamic_creative: Enable/disable Dynamic Creative for this ad set.
         access_token: Meta API access token (optional - will use cached token if not provided)
     """
     if not adset_id:
@@ -342,6 +350,9 @@ async def update_adset(adset_id: str, frequency_control_specs: Optional[List[Dic
     if lifetime_budget is not None:
         params['lifetime_budget'] = str(lifetime_budget)
     
+    if is_dynamic_creative is not None:
+        params['is_dynamic_creative'] = "true" if bool(is_dynamic_creative) else "false"
+    
     if not params:
         return json.dumps({"error": "No update parameters provided"}, indent=2)
 

{meta_ads_mcp-0.11.0 → meta_ads_mcp-0.11.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "meta-ads-mcp"
-version = "0.11.0"
+version = "0.11.2"
 description = "Model Context Protocol (MCP) server for interacting with Meta Ads API"
 readme = "README.md"
 requires-python = ">=3.10"

meta_ads_mcp-0.11.2/tests/test_is_dynamic_creative_adset.py

@@ -0,0 +1,77 @@
+import json
+import pytest
+from unittest.mock import AsyncMock, patch
+
+from meta_ads_mcp.core.adsets import create_adset, update_adset, get_adsets, get_adset_details
+
+
+@pytest.mark.asyncio
+async def test_create_adset_includes_is_dynamic_creative_true():
+    sample_response = {"id": "adset_1", "name": "DC Adset"}
+    with patch('meta_ads_mcp.core.adsets.make_api_request', new_callable=AsyncMock) as mock_api:
+        mock_api.return_value = sample_response
+
+        result = await create_adset(
+            account_id="act_123",
+            campaign_id="cmp_1",
+            name="DC Adset",
+            optimization_goal="LINK_CLICKS",
+            billing_event="IMPRESSIONS",
+            targeting={"geo_locations": {"countries": ["US"]}},
+            is_dynamic_creative=True,
+            access_token="test_token",
+        )
+
+        assert json.loads(result)["id"] == "adset_1"
+        # Verify param was sent as string boolean
+        call_args = mock_api.call_args
+        params = call_args[0][2]
+        assert params["is_dynamic_creative"] == "true"
+
+
+@pytest.mark.asyncio
+async def test_update_adset_includes_is_dynamic_creative_false():
+    sample_response = {"success": True}
+    with patch('meta_ads_mcp.core.adsets.make_api_request', new_callable=AsyncMock) as mock_api:
+        mock_api.return_value = sample_response
+
+        result = await update_adset(
+            adset_id="120",
+            is_dynamic_creative=False,
+            access_token="test_token",
+        )
+
+        assert json.loads(result)["success"] is True
+        call_args = mock_api.call_args
+        params = call_args[0][2]
+        assert params["is_dynamic_creative"] == "false"
+
+
+@pytest.mark.asyncio
+async def test_get_adsets_fields_include_is_dynamic_creative():
+    sample_response = {"data": []}
+    with patch('meta_ads_mcp.core.adsets.make_api_request', new_callable=AsyncMock) as mock_api:
+        mock_api.return_value = sample_response
+
+        result = await get_adsets(account_id="act_123", access_token="test_token", limit=1)
+        assert json.loads(result)["data"] == []
+
+        call_args = mock_api.call_args
+        params = call_args[0][2]
+        assert "is_dynamic_creative" in params.get("fields", "")
+
+
+@pytest.mark.asyncio
+async def test_get_adset_details_fields_include_is_dynamic_creative():
+    sample_response = {"id": "120", "name": "Test", "is_dynamic_creative": True}
+    with patch('meta_ads_mcp.core.adsets.make_api_request', new_callable=AsyncMock) as mock_api:
+        mock_api.return_value = sample_response
+
+        result = await get_adset_details(adset_id="120", access_token="test_token")
+        assert json.loads(result)["id"] == "120"
+
+        call_args = mock_api.call_args
+        params = call_args[0][2]
+        assert "is_dynamic_creative" in params.get("fields", "")
+
+