meta-ads-mcp 0.7.8__py3-none-any.whl → 0.7.10__py3-none-any.whl

meta_ads_mcp/__init__.py

@@ -7,7 +7,7 @@ with the Claude LLM.
 
 from meta_ads_mcp.core.server import main
 
-__version__ = "0.7.8"
+__version__ = "0.7.10"
 
 __all__ = [
     'get_ad_accounts',

meta_ads_mcp/core/ads.py

@@ -171,7 +171,7 @@ async def get_ad_creatives(access_token: str = None, ad_id: str = None) -> str:
         
     endpoint = f"{ad_id}/adcreatives"
     params = {
-        "fields": "id,name,status,thumbnail_url,image_url,image_hash,object_story_spec" # Added image_hash
+        "fields": "id,name,status,thumbnail_url,image_url,image_hash,object_story_spec,asset_feed_spec,image_urls_for_viewing"
     }
     
     data = await make_api_request(endpoint, access_token, params)
@@ -279,14 +279,26 @@ async def get_ad_image(access_token: str = None, ad_id: str = None) -> Image:
             if "data" in creative_data and creative_data["data"]:
                 creative = creative_data["data"][0]
                 
-                # Try image_urls_for_viewing first (usually higher quality)
+                # Prioritize higher quality image URLs in this order:
+                # 1. image_urls_for_viewing (usually highest quality)
+                # 2. image_url (direct field)
+                # 3. object_story_spec.link_data.picture (usually full size)
+                # 4. thumbnail_url (last resort - often profile thumbnail)
+                
                 if "image_urls_for_viewing" in creative and creative["image_urls_for_viewing"]:
                     image_url = creative["image_urls_for_viewing"][0]
                     print(f"Using image_urls_for_viewing: {image_url}")
-                # Fall back to thumbnail_url
+                elif "image_url" in creative and creative["image_url"]:
+                    image_url = creative["image_url"]
+                    print(f"Using image_url: {image_url}")
+                elif "object_story_spec" in creative and "link_data" in creative["object_story_spec"]:
+                    link_data = creative["object_story_spec"]["link_data"]
+                    if "picture" in link_data and link_data["picture"]:
+                        image_url = link_data["picture"]
+                        print(f"Using object_story_spec.link_data.picture: {image_url}")
                 elif "thumbnail_url" in creative and creative["thumbnail_url"]:
                     image_url = creative["thumbnail_url"]
-                    print(f"Using thumbnail_url: {image_url}")
+                    print(f"Using thumbnail_url (fallback): {image_url}")
             
             if not image_url:
                 return "Error: No image URLs found in creative"
@@ -658,31 +670,31 @@ async def create_ad_creative(
     if not account_id.startswith("act_"):
         account_id = f"act_{account_id}"
     
-    # If no page ID is provided, try to find a page associated with the account
+    # Enhanced page discovery: If no page ID is provided, use robust discovery methods
     if not page_id:
         try:
-            # Query to get pages associated with the account
-            pages_endpoint = f"{account_id}/assigned_pages"
-            pages_params = {
-                "fields": "id,name",
-                "limit": 1 
-            }
-            
-            pages_data = await make_api_request(pages_endpoint, access_token, pages_params)
+            # Use the comprehensive page discovery logic from get_account_pages
+            page_discovery_result = await _discover_pages_for_account(account_id, access_token)
             
-            if "data" in pages_data and pages_data["data"]:
-                page_id = pages_data["data"][0]["id"]
-                print(f"Using page ID: {page_id} ({pages_data['data'][0].get('name', 'Unknown')})")
+            if page_discovery_result.get("success"):
+                page_id = page_discovery_result["page_id"]
+                page_name = page_discovery_result.get("page_name", "Unknown")
+                print(f"Auto-discovered page ID: {page_id} ({page_name})")
             else:
                 return json.dumps({
-                    "error": "No page ID provided and no pages found for this account",
-                    "suggestion": "Please provide a page_id parameter"
+                    "error": "No page ID provided and no suitable pages found for this account",
+                    "details": page_discovery_result.get("message", "Page discovery failed"),
+                    "suggestions": [
+                        "Use get_account_pages to see available pages",
+                        "Use search_pages_by_name to find specific pages",
+                        "Provide a page_id parameter manually"
+                    ]
                 }, indent=2)
         except Exception as e:
             return json.dumps({
-                "error": "Error finding page for account",
+                "error": "Error during page discovery",
                 "details": str(e),
-                "suggestion": "Please provide a page_id parameter"
+                "suggestion": "Please provide a page_id parameter or use get_account_pages to find available pages"
             }, indent=2)
     
     # Prepare the creative data
@@ -747,6 +759,191 @@ async def create_ad_creative(
         }, indent=2)
 
 
+async def _discover_pages_for_account(account_id: str, access_token: str) -> dict:
+    """
+    Internal function to discover pages for an account using multiple approaches.
+    Returns the best available page ID for ad creation.
+    """
+    try:
+        # Approach 1: Extract page IDs from tracking_specs in ads (most reliable)
+        endpoint = f"{account_id}/ads"
+        params = {
+            "fields": "id,name,adset_id,campaign_id,status,creative,created_time,updated_time,bid_amount,conversion_domain,tracking_specs",
+            "limit": 100
+        }
+        
+        tracking_ads_data = await make_api_request(endpoint, access_token, params)
+        
+        tracking_page_ids = set()
+        if "data" in tracking_ads_data:
+            for ad in tracking_ads_data.get("data", []):
+                tracking_specs = ad.get("tracking_specs", [])
+                if isinstance(tracking_specs, list):
+                    for spec in tracking_specs:
+                        if isinstance(spec, dict) and "page" in spec:
+                            page_list = spec["page"]
+                            if isinstance(page_list, list):
+                                for page_id in page_list:
+                                    if isinstance(page_id, (str, int)) and str(page_id).isdigit():
+                                        tracking_page_ids.add(str(page_id))
+        
+        if tracking_page_ids:
+            # Get details for the first page found
+            page_id = list(tracking_page_ids)[0]
+            page_endpoint = f"{page_id}"
+            page_params = {
+                "fields": "id,name,username,category,fan_count,link,verification_status,picture"
+            }
+            
+            page_data = await make_api_request(page_endpoint, access_token, page_params)
+            if "id" in page_data:
+                return {
+                    "success": True,
+                    "page_id": page_id,
+                    "page_name": page_data.get("name", "Unknown"),
+                    "source": "tracking_specs",
+                    "note": "Page ID extracted from existing ads - most reliable for ad creation"
+                }
+        
+        # Approach 2: Try client_pages endpoint
+        endpoint = f"{account_id}/client_pages"
+        params = {
+            "fields": "id,name,username,category,fan_count,link,verification_status,picture"
+        }
+        
+        client_pages_data = await make_api_request(endpoint, access_token, params)
+        
+        if "data" in client_pages_data and client_pages_data["data"]:
+            page = client_pages_data["data"][0]
+            return {
+                "success": True,
+                "page_id": page["id"],
+                "page_name": page.get("name", "Unknown"),
+                "source": "client_pages"
+            }
+        
+        # Approach 3: Try assigned_pages endpoint
+        pages_endpoint = f"{account_id}/assigned_pages"
+        pages_params = {
+            "fields": "id,name",
+            "limit": 1 
+        }
+        
+        pages_data = await make_api_request(pages_endpoint, access_token, pages_params)
+        
+        if "data" in pages_data and pages_data["data"]:
+            page = pages_data["data"][0]
+            return {
+                "success": True,
+                "page_id": page["id"],
+                "page_name": page.get("name", "Unknown"),
+                "source": "assigned_pages"
+            }
+        
+        # If all approaches failed
+        return {
+            "success": False,
+            "message": "No suitable pages found for this account",
+            "note": "Try using get_account_pages to see all available pages or provide page_id manually"
+        }
+        
+    except Exception as e:
+        return {
+            "success": False,
+            "message": f"Error during page discovery: {str(e)}"
+        }
+
+
+async def _search_pages_by_name_core(access_token: str, account_id: str, search_term: str = None) -> str:
+    """
+    Core logic for searching pages by name.
+    
+    Args:
+        access_token: Meta API access token
+        account_id: Meta Ads account ID (format: act_XXXXXXXXX)
+        search_term: Search term to find pages by name (optional - returns all pages if not provided)
+    
+    Returns:
+        JSON string with search results
+    """
+    # Ensure account_id has the 'act_' prefix
+    if not account_id.startswith("act_"):
+        account_id = f"act_{account_id}"
+    
+    try:
+        # Use the internal discovery function directly
+        page_discovery_result = await _discover_pages_for_account(account_id, access_token)
+        
+        if not page_discovery_result.get("success"):
+            return json.dumps({
+                "data": [],
+                "message": "No pages found for this account",
+                "details": page_discovery_result.get("message", "Page discovery failed")
+            }, indent=2)
+        
+        # Create a single page result
+        page_data = {
+            "id": page_discovery_result["page_id"],
+            "name": page_discovery_result.get("page_name", "Unknown"),
+            "source": page_discovery_result.get("source", "unknown")
+        }
+        
+        all_pages_data = {"data": [page_data]}
+        
+        # Filter pages by search term if provided
+        if search_term:
+            search_term_lower = search_term.lower()
+            filtered_pages = []
+            
+            for page in all_pages_data["data"]:
+                page_name = page.get("name", "").lower()
+                if search_term_lower in page_name:
+                    filtered_pages.append(page)
+            
+            return json.dumps({
+                "data": filtered_pages,
+                "search_term": search_term,
+                "total_found": len(filtered_pages),
+                "total_available": len(all_pages_data["data"])
+            }, indent=2)
+        else:
+            # Return all pages if no search term provided
+            return json.dumps({
+                "data": all_pages_data["data"],
+                "total_available": len(all_pages_data["data"]),
+                "note": "Use search_term parameter to filter pages by name"
+            }, indent=2)
+    
+    except Exception as e:
+        return json.dumps({
+            "error": "Failed to search pages by name",
+            "details": str(e)
+        }, indent=2)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def search_pages_by_name(access_token: str = None, account_id: str = None, search_term: str = None) -> str:
+    """
+    Search for pages by name within an account.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        account_id: Meta Ads account ID (format: act_XXXXXXXXX)
+        search_term: Search term to find pages by name (optional - returns all pages if not provided)
+    
+    Returns:
+        JSON response with matching pages
+    """
+    # Check required parameters
+    if not account_id:
+        return json.dumps({"error": "No account ID provided"}, indent=2)
+    
+    # Call the core function
+    result = await _search_pages_by_name_core(access_token, account_id, search_term)
+    return result
+
+
 @mcp_server.tool()
 @meta_api_tool
 async def get_account_pages(access_token: str = None, account_id: str = None) -> str:

meta_ads_mcp/core/utils.py

@@ -78,23 +78,31 @@ ad_creative_images = {}
 def extract_creative_image_urls(creative: Dict[str, Any]) -> List[str]:
     """
     Extract image URLs from a creative object for direct viewing.
+    Prioritizes higher quality images over thumbnails.
     
     Args:
         creative: Meta Ads creative object
         
     Returns:
-        List of image URLs found in the creative
+        List of image URLs found in the creative, prioritized by quality
     """
     image_urls = []
     
+    # Prioritize higher quality image URLs in this order:
+    # 1. image_urls_for_viewing (usually highest quality)
+    # 2. image_url (direct field)
+    # 3. object_story_spec.link_data.picture (usually full size)
+    # 4. asset_feed_spec images (multiple high-quality images)
+    # 5. thumbnail_url (last resort - often profile thumbnail)
+    
+    # Check for image_urls_for_viewing (highest priority)
+    if "image_urls_for_viewing" in creative and creative["image_urls_for_viewing"]:
+        image_urls.extend(creative["image_urls_for_viewing"])
+    
     # Check for direct image_url field
     if "image_url" in creative and creative["image_url"]:
         image_urls.append(creative["image_url"])
     
-    # Check for thumbnail_url field
-    if "thumbnail_url" in creative and creative["thumbnail_url"]:
-        image_urls.append(creative["thumbnail_url"])
-    
     # Check object_story_spec for image URLs
     if "object_story_spec" in creative:
         story_spec = creative["object_story_spec"]
@@ -103,7 +111,7 @@ def extract_creative_image_urls(creative: Dict[str, Any]) -> List[str]:
         if "link_data" in story_spec:
             link_data = story_spec["link_data"]
             
-            # Check for picture field
+            # Check for picture field (usually full size)
             if "picture" in link_data and link_data["picture"]:
                 image_urls.append(link_data["picture"])
                 
@@ -121,6 +129,10 @@ def extract_creative_image_urls(creative: Dict[str, Any]) -> List[str]:
             if "url" in image and image["url"]:
                 image_urls.append(image["url"])
     
+    # Check for thumbnail_url field (lowest priority)
+    if "thumbnail_url" in creative and creative["thumbnail_url"]:
+        image_urls.append(creative["thumbnail_url"])
+    
     # Remove duplicates while preserving order
     seen = set()
     unique_urls = []

{meta_ads_mcp-0.7.8.dist-info → meta_ads_mcp-0.7.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.7.8
+Version: 0.7.10
 Summary: Model Context Protocol (MCP) plugin 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.7.8.dist-info → meta_ads_mcp-0.7.10.dist-info}/RECORD

@@ -1,8 +1,8 @@
-meta_ads_mcp/__init__.py,sha256=BiSbN8PrAeLKejVnkAfsz06KLVM59vQJmehwssDnEzc,1492
+meta_ads_mcp/__init__.py,sha256=Y0Oj0zMOmh2TX_E4iBNehH9NFlM1w9O3injKT8FJMbw,1493
 meta_ads_mcp/__main__.py,sha256=XaQt3iXftG_7f0Zu7Wop9SeFgrD2WBn0EQOaPMc27d8,207
 meta_ads_mcp/core/__init__.py,sha256=6nYdue6yRepkt6JTAoPGhGbS51qfDSvmczRrDwYOG6A,1709
 meta_ads_mcp/core/accounts.py,sha256=4IAdGLZ4WE4j4pGW6E0qaXcXqbUIW6Wk2kuQUtlmRTQ,4030
-meta_ads_mcp/core/ads.py,sha256=aaK70mgfhBJRXr4cdkKag5mjYzvHuHpRttJvTMzPk4Y,36156
+meta_ads_mcp/core/ads.py,sha256=lUq5te8SDFHS2gn8IlwVa0svyFyqJBMvWtuxy1hacFI,44428
 meta_ads_mcp/core/ads_library.py,sha256=BBGVbtjO5eFV42iiY3XPU-wIV8HupzUKpHgPBrydSvU,3232
 meta_ads_mcp/core/adsets.py,sha256=vY5JNHmGK1a_sQ5B1LnjxLYXzs5_jOajTTjWHRDJ4_Y,12518
 meta_ads_mcp/core/api.py,sha256=aAzM6Q75VQOFXtr5D-mDmBRhxWK4wsiODsJYnR3mpDI,14994
@@ -20,9 +20,9 @@ meta_ads_mcp/core/reports.py,sha256=Dv3hfsPOR7IZ9WrYrKd_6SNgZl-USIphg7knva3UYAw,
 meta_ads_mcp/core/resources.py,sha256=-zIIfZulpo76vcKv6jhAlQq91cR2SZ3cjYZt3ek3x0w,1236
 meta_ads_mcp/core/server.py,sha256=WhbAag7xdhbGcp7rnU4sKhqXJ8Slapa_ba3T23Yp_2U,17889
 meta_ads_mcp/core/targeting.py,sha256=3HW1qirEdwaQurlBZGenbIwawcb5J06ghJKRfgu9ZEs,6318
-meta_ads_mcp/core/utils.py,sha256=ofKUhyo-5SZoJVuBeTVFPPQCffk0UKpwmDMrd8qQxNc,8715
-meta_ads_mcp-0.7.8.dist-info/METADATA,sha256=HjCu4iRgkgfEv5WYS3-E6CchfrkassZHZjMVbgfOphE,20409
-meta_ads_mcp-0.7.8.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-meta_ads_mcp-0.7.8.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
-meta_ads_mcp-0.7.8.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-meta_ads_mcp-0.7.8.dist-info/RECORD,,
+meta_ads_mcp/core/utils.py,sha256=ytj41yC5SqduLrAiZYBSd6OUwlJRaIClTwnnYKpNFds,9387
+meta_ads_mcp-0.7.10.dist-info/METADATA,sha256=DCV6TdsYdyLogsgvOpIu8hBjawrGo1FWiF4PuKp20AU,20410
+meta_ads_mcp-0.7.10.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+meta_ads_mcp-0.7.10.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
+meta_ads_mcp-0.7.10.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+meta_ads_mcp-0.7.10.dist-info/RECORD,,