meta-ads-mcp 0.2.4__py3-none-any.whl → 0.2.6__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.2.4"
+__version__ = "0.2.6"
 
 __all__ = [
     'get_ad_accounts',
@@ -22,6 +22,7 @@ __all__ = [
     'get_ad_details',
     'get_ad_creatives',
     'get_ad_image',
+    'update_ad',
     'get_insights',
     'debug_image_download',
     'get_login_link',
@@ -43,6 +44,7 @@ from .core import (
     get_ad_details,
     get_ad_creatives,
     get_ad_image,
+    update_ad,
     get_insights,
     debug_image_download,
     get_login_link,

meta_ads_mcp/core/ads.py

@@ -363,4 +363,64 @@ async def get_ad_image(access_token: str = None, ad_id: str = None) -> Image:
         return Image(data=img_bytes, format="jpeg")
         
     except Exception as e:
-        return f"Error processing image: {str(e)}" 
+        return f"Error processing image: {str(e)}"
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def update_ad(ad_id: str, status: str = None, bid_amount: int = None, access_token: str = None) -> str:
+    """
+    Update an ad with new settings.
+    
+    Args:
+        ad_id: Meta Ads ad ID
+        status: Update ad status (ACTIVE, PAUSED, etc.)
+        bid_amount: Bid amount in account currency (in cents for USD)
+        access_token: Meta API access token (optional - will use cached token if not provided)
+    """
+    if not ad_id:
+        return json.dumps({"error": "No ad ID provided"}, indent=2)
+    
+    changes = {}
+    
+    if status is not None:
+        changes['status'] = status
+        
+    if bid_amount is not None:
+        changes['bid_amount'] = bid_amount
+    
+    if not changes:
+        return json.dumps({"error": "No update parameters provided"}, indent=2)
+    
+    # Get current ad details for comparison
+    current_details_json = await get_ad_details(ad_id=ad_id, access_token=access_token)
+    current_details = json.loads(current_details_json)
+    
+    # Import the callback server components
+    from .callback_server import start_callback_server, update_confirmation
+    import urllib.parse
+    
+    # Start the callback server if not already running
+    port = start_callback_server()
+    
+    # Generate confirmation URL with properly encoded parameters
+    changes_json = json.dumps(changes)
+    encoded_changes = urllib.parse.quote(changes_json)
+    confirmation_url = f"http://localhost:{port}/confirm-update?ad_id={ad_id}&token={access_token}&changes={encoded_changes}"
+    
+    # Reset the update confirmation
+    update_confirmation.clear()
+    update_confirmation.update({"approved": False})
+    
+    # Return the confirmation link
+    response = {
+        "message": "Please confirm the ad update",
+        "confirmation_url": confirmation_url,
+        "markdown_link": f"[Click here to confirm ad update]({confirmation_url})",
+        "current_details": current_details,
+        "proposed_changes": changes,
+        "instructions_for_llm": "You must present this link as clickable Markdown to the user using the markdown_link format provided.",
+        "note": "After authenticating, the token will be automatically saved and your ad will be updated. Refresh the browser page if it doesn't load immediately."
+    }
+    
+    return json.dumps(response, indent=2) 

meta_ads_mcp/core/adsets.py

@@ -6,7 +6,8 @@ from .api import meta_api_tool, make_api_request
 from .accounts import get_ad_accounts
 from .server import mcp_server
 import asyncio
-from .auth import start_callback_server, update_confirmation
+from .callback_server import start_callback_server, update_confirmation
+import urllib.parse
 
 
 @mcp_server.tool()
@@ -77,7 +78,7 @@ async def get_adset_details(access_token: str = None, adset_id: str = None) -> s
 @mcp_server.tool()
 @meta_api_tool
 async def update_adset(adset_id: str, frequency_control_specs: List[Dict[str, Any]] = None, bid_strategy: str = None, 
-                        bid_amount: int = None, status: str = None, access_token: str = None) -> str:
+                        bid_amount: int = None, status: str = None, targeting: Dict[str, Any] = None, access_token: str = None) -> str:
     """
     Update an ad set with new settings including frequency caps.
     
@@ -88,6 +89,8 @@ async def update_adset(adset_id: str, frequency_control_specs: List[Dict[str, An
         bid_strategy: Bid strategy (e.g., 'LOWEST_COST_WITH_BID_CAP')
         bid_amount: Bid amount in account currency (in cents for USD)
         status: Update ad set status (ACTIVE, PAUSED, etc.)
+        targeting: Targeting specifications including targeting_automation
+                  (e.g. {"targeting_automation":{"advantage_audience":1}})
         access_token: Meta API access token (optional - will use cached token if not provided)
     """
     if not adset_id:
@@ -106,6 +109,32 @@ async def update_adset(adset_id: str, frequency_control_specs: List[Dict[str, An
         
     if status is not None:
         changes['status'] = status
+        
+    if targeting is not None:
+        # Get current ad set details to preserve existing targeting settings
+        current_details_json = await get_adset_details(adset_id=adset_id, access_token=access_token)
+        current_details = json.loads(current_details_json)
+        
+        # Check if the current ad set has targeting information
+        current_targeting = current_details.get('targeting', {})
+        
+        if 'targeting_automation' in targeting:
+            # Only update targeting_automation while preserving other targeting settings
+            if current_targeting:
+                merged_targeting = current_targeting.copy()
+                merged_targeting['targeting_automation'] = targeting['targeting_automation']
+                changes['targeting'] = merged_targeting
+            else:
+                # If there's no existing targeting, we need to create a basic one
+                # Meta requires at least a geo_locations setting
+                basic_targeting = {
+                    'targeting_automation': targeting['targeting_automation'],
+                    'geo_locations': {'countries': ['US']}  # Using US as default location
+                }
+                changes['targeting'] = basic_targeting
+        else:
+            # Full targeting replacement
+            changes['targeting'] = targeting
     
     if not changes:
         return json.dumps({"error": "No update parameters provided"}, indent=2)
@@ -119,7 +148,8 @@ async def update_adset(adset_id: str, frequency_control_specs: List[Dict[str, An
     
     # Generate confirmation URL with properly encoded parameters
     changes_json = json.dumps(changes)
-    confirmation_url = f"http://localhost:{port}/confirm-update?adset_id={adset_id}&token={access_token}&changes={changes_json}"
+    encoded_changes = urllib.parse.quote(changes_json)
+    confirmation_url = f"http://localhost:{port}/confirm-update?adset_id={adset_id}&token={access_token}&changes={encoded_changes}"
     
     # Reset the update confirmation
     update_confirmation.clear()

meta_ads_mcp/core/api.py

@@ -59,9 +59,9 @@ async def make_api_request(
     if not access_token:
         logger.error("API request attempted with blank access token")
         return {
-            "error": "Authentication Required",
-            "details": {
-                "message": "A valid access token is required to access the Meta API",
+            "error": {
+                "message": "Authentication Required",
+                "details": "A valid access token is required to access the Meta API",
                 "action_required": "Please authenticate first"
             }
         }
@@ -89,7 +89,18 @@ async def make_api_request(
             if method == "GET":
                 response = await client.get(url, params=request_params, headers=headers, timeout=30.0)
             elif method == "POST":
-                response = await client.post(url, json=request_params, headers=headers, timeout=30.0)
+                # For Meta API, POST requests need data, not JSON
+                if 'targeting' in request_params and isinstance(request_params['targeting'], dict):
+                    # Convert targeting dict to string for the API
+                    request_params['targeting'] = json.dumps(request_params['targeting'])
+                
+                # Convert lists and dicts to JSON strings    
+                for key, value in request_params.items():
+                    if isinstance(value, (list, dict)):
+                        request_params[key] = json.dumps(value)
+                
+                logger.debug(f"POST params (prepared): {masked_params}")
+                response = await client.post(url, data=request_params, headers=headers, timeout=30.0)
             elif method == "DELETE":
                 response = await client.delete(url, params=request_params, headers=headers, timeout=30.0)
             else:
@@ -97,7 +108,16 @@ async def make_api_request(
             
             response.raise_for_status()
             logger.debug(f"API Response status: {response.status_code}")
-            return response.json()
+            
+            # Ensure the response is JSON and return it as a dictionary
+            try:
+                return response.json()
+            except json.JSONDecodeError:
+                # If not JSON, return text content in a structured format
+                return {
+                    "text_response": response.text,
+                    "status_code": response.status_code
+                }
         
         except httpx.HTTPStatusError as e:
             error_info = {}
@@ -123,8 +143,7 @@ async def make_api_request(
                         logger.error(f"Current app_id: {app_id}")
                         # Provide a clearer error message without the confusing "Provide valid app ID" message
                         return {
-                            "error": f"HTTP Error: {e.response.status_code}",
-                            "details": {
+                            "error": {
                                 "message": "Meta API authentication configuration issue. Please check your app credentials.",
                                 "original_error": error_obj.get("message"),
                                 "code": error_obj.get("code")
@@ -132,11 +151,28 @@ async def make_api_request(
                         }
                     auth_manager.invalidate_token()
             
-            return {"error": f"HTTP Error: {e.response.status_code}", "details": error_info}
+            # Include full details for technical users
+            full_response = {
+                "headers": dict(e.response.headers),
+                "status_code": e.response.status_code,
+                "url": str(e.response.url),
+                "reason": getattr(e.response, "reason_phrase", "Unknown reason"),
+                "request_method": e.request.method,
+                "request_url": str(e.request.url)
+            }
+            
+            # Return a properly structured error object
+            return {
+                "error": {
+                    "message": f"HTTP Error: {e.response.status_code}",
+                    "details": error_info,
+                    "full_response": full_response
+                }
+            }
         
         except Exception as e:
             logger.error(f"Request Error: {str(e)}")
-            return {"error": str(e)}
+            return {"error": {"message": str(e)}}
 
 
 # Generic wrapper for all Meta API tools
@@ -174,12 +210,14 @@ def meta_api_tool(func):
                 logger.warning("No access token available, authentication needed")
                 auth_url = auth_manager.get_auth_url()
                 return json.dumps({
-                    "error": "Authentication Required",
-                    "details": {
-                        "message": "You need to authenticate with the Meta API before using this tool",
-                        "action_required": "Please authenticate first",
-                        "auth_url": auth_url,
-                        "markdown_link": f"[Click here to authenticate with Meta Ads API]({auth_url})"
+                    "error": {
+                        "message": "Authentication Required",
+                        "details": {
+                            "description": "You need to authenticate with the Meta API before using this tool",
+                            "action_required": "Please authenticate first",
+                            "auth_url": auth_url,
+                            "markdown_link": f"[Click here to authenticate with Meta Ads API]({auth_url})"
+                        }
                     }
                 }, indent=2)
                 
@@ -200,18 +238,24 @@ def meta_api_tool(func):
                                 logger.error(f"Current app_id: {app_id}")
                                 # Replace the confusing error with a more user-friendly one
                                 return json.dumps({
-                                    "error": "Meta API Configuration Issue",
-                                    "details": {
-                                        "message": "Your Meta API app is not properly configured",
-                                        "action_required": "Check your META_APP_ID environment variable",
-                                        "current_app_id": app_id,
-                                        "original_error": error_obj.get("message")
+                                    "error": {
+                                        "message": "Meta API Configuration Issue",
+                                        "details": {
+                                            "description": "Your Meta API app is not properly configured",
+                                            "action_required": "Check your META_APP_ID environment variable",
+                                            "current_app_id": app_id,
+                                            "original_error": error_obj.get("message")
+                                        }
                                     }
                                 }, indent=2)
                 except Exception:
-                    # Not JSON or other parsing error, just continue
-                    pass
-                
+                    # Not JSON or other parsing error, wrap it in a dictionary
+                    return json.dumps({"data": result}, indent=2)
+            
+            # If result is already a dictionary, ensure it's properly serialized
+            if isinstance(result, dict):
+                return json.dumps(result, indent=2)
+            
             return result
         except Exception as e:
             logger.error(f"Error in {func.__name__}: {str(e)}")