meta-ads-mcp 0.2.5__tar.gz → 0.2.6__tar.gz

{meta_ads_mcp-0.2.5 → meta_ads_mcp-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.2.5
+Version: 0.2.6
 Summary: Model Calling Protocol (MCP) plugin for interacting with Meta Ads API
 Project-URL: Homepage, https://github.com/nictuku/meta-ads-mcp
 Project-URL: Bug Tracker, https://github.com/nictuku/meta-ads-mcp/issues
@@ -187,7 +187,28 @@ Add this to your `claude_desktop_config.json` to integrate with Claude in Cursor
       - `ad_id`: Meta Ads ad ID
     - Returns: The ad image ready for direct visual analysis
 
-12. `mcp_meta_ads_get_insights`
+12. `mcp_meta_ads_update_ad`
+    - Update an ad with new settings
+    - Inputs:
+      - `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` (optional): Meta API access token (will use cached token if not provided)
+    - Returns: Confirmation with updated ad details and a confirmation link
+
+13. `mcp_meta_ads_update_adset`
+    - Update an ad set with new settings including frequency caps
+    - Inputs:
+      - `adset_id`: Meta Ads ad set ID
+      - `frequency_control_specs`: List of frequency control specifications
+      - `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
+      - `access_token` (optional): Meta API access token (will use cached token if not provided)
+    - Returns: Confirmation with updated ad set details and a confirmation link
+
+14. `mcp_meta_ads_get_insights`
     - Get performance insights for a campaign, ad set, ad or account
     - Inputs:
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -197,7 +218,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude in Cursor
       - `level`: Level of aggregation (ad, adset, campaign, account)
     - Returns: Performance metrics for the specified object
 
-13. `mcp_meta_ads_debug_image_download`
+15. `mcp_meta_ads_debug_image_download`
     - Debug image download issues and report detailed diagnostics
     - Inputs:
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -205,7 +226,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude in Cursor
       - `ad_id`: Meta Ads ad ID (optional, used if url is not provided)
     - Returns: Diagnostic information about image download attempts
 
-14. `mcp_meta_ads_get_login_link`
+16. `mcp_meta_ads_get_login_link`
     - Get a clickable login link for Meta Ads authentication
     - Inputs:
       - `access_token` (optional): Meta API access token (will use cached token if not provided)

{meta_ads_mcp-0.2.5 → meta_ads_mcp-0.2.6}/README.md

@@ -166,7 +166,28 @@ Add this to your `claude_desktop_config.json` to integrate with Claude in Cursor
       - `ad_id`: Meta Ads ad ID
     - Returns: The ad image ready for direct visual analysis
 
-12. `mcp_meta_ads_get_insights`
+12. `mcp_meta_ads_update_ad`
+    - Update an ad with new settings
+    - Inputs:
+      - `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` (optional): Meta API access token (will use cached token if not provided)
+    - Returns: Confirmation with updated ad details and a confirmation link
+
+13. `mcp_meta_ads_update_adset`
+    - Update an ad set with new settings including frequency caps
+    - Inputs:
+      - `adset_id`: Meta Ads ad set ID
+      - `frequency_control_specs`: List of frequency control specifications
+      - `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
+      - `access_token` (optional): Meta API access token (will use cached token if not provided)
+    - Returns: Confirmation with updated ad set details and a confirmation link
+
+14. `mcp_meta_ads_get_insights`
     - Get performance insights for a campaign, ad set, ad or account
     - Inputs:
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -176,7 +197,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude in Cursor
       - `level`: Level of aggregation (ad, adset, campaign, account)
     - Returns: Performance metrics for the specified object
 
-13. `mcp_meta_ads_debug_image_download`
+15. `mcp_meta_ads_debug_image_download`
     - Debug image download issues and report detailed diagnostics
     - Inputs:
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -184,7 +205,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude in Cursor
       - `ad_id`: Meta Ads ad ID (optional, used if url is not provided)
     - Returns: Diagnostic information about image download attempts
 
-14. `mcp_meta_ads_get_login_link`
+16. `mcp_meta_ads_get_login_link`
     - Get a clickable login link for Meta Ads authentication
     - Inputs:
       - `access_token` (optional): Meta API access token (will use cached token if not provided)

{meta_ads_mcp-0.2.5 → meta_ads_mcp-0.2.6}/meta_ads_mcp/__init__.py

@@ -7,7 +7,7 @@ with the Claude LLM.
 
 from meta_ads_mcp.core.server import main
 
-__version__ = "0.2.5"
+__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-0.2.5 → meta_ads_mcp-0.2.6}/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-0.2.5 → meta_ads_mcp-0.2.6}/meta_ads_mcp/core/adsets.py

@@ -6,7 +6,7 @@ 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
 
 

meta_ads_mcp-0.2.6/meta_ads_mcp/core/auth.py

@@ -0,0 +1,446 @@
+"""Authentication related functionality for Meta Ads API."""
+
+from typing import Any, Dict, Optional
+import time
+import platform
+import pathlib
+import os
+import webbrowser
+import asyncio
+import json
+from .utils import logger
+import requests
+
+# Import from the new callback server module
+from .callback_server import (
+    start_callback_server, 
+    token_container,
+    update_confirmation
+)
+
+# Auth constants
+AUTH_SCOPE = "ads_management,ads_read,business_management"
+AUTH_REDIRECT_URI = "http://localhost:8888/callback"
+AUTH_RESPONSE_TYPE = "token"
+
+# Log important configuration information
+logger.info("Authentication module initialized")
+logger.info(f"Auth scope: {AUTH_SCOPE}")
+logger.info(f"Default redirect URI: {AUTH_REDIRECT_URI}")
+
+# Global flag for authentication state
+needs_authentication = False
+
+# Meta configuration singleton
+class MetaConfig:
+    _instance = None
+    
+    def __new__(cls):
+        if cls._instance is None:
+            logger.debug("Creating new MetaConfig instance")
+            cls._instance = super(MetaConfig, cls).__new__(cls)
+            cls._instance.app_id = os.environ.get("META_APP_ID", "")
+            logger.info(f"MetaConfig initialized with app_id from env: {cls._instance.app_id}")
+        return cls._instance
+    
+    def set_app_id(self, app_id):
+        """Set the Meta App ID for API calls"""
+        logger.info(f"Setting Meta App ID: {app_id}")
+        self.app_id = app_id
+        # Also update environment variable for modules that might read directly from it
+        os.environ["META_APP_ID"] = app_id
+        logger.debug(f"Updated META_APP_ID environment variable: {os.environ.get('META_APP_ID')}")
+    
+    def get_app_id(self):
+        """Get the current Meta App ID"""
+        # Check if we have one set
+        if hasattr(self, 'app_id') and self.app_id:
+            logger.debug(f"Using app_id from instance: {self.app_id}")
+            return self.app_id
+        
+        # If not, try environment variable
+        env_app_id = os.environ.get("META_APP_ID", "")
+        if env_app_id:
+            logger.debug(f"Using app_id from environment: {env_app_id}")
+            # Update our instance for future use
+            self.app_id = env_app_id
+            return env_app_id
+        
+        logger.warning("No app_id found in instance or environment variables")
+        return ""
+    
+    def is_configured(self):
+        """Check if the Meta configuration is complete"""
+        app_id = self.get_app_id()
+        configured = bool(app_id)
+        logger.debug(f"MetaConfig.is_configured() = {configured} (app_id: {app_id})")
+        return configured
+
+# Create singleton instance
+meta_config = MetaConfig()
+
+class TokenInfo:
+    """Stores token information including expiration"""
+    def __init__(self, access_token: str, expires_in: int = None, user_id: str = None):
+        self.access_token = access_token
+        self.expires_in = expires_in
+        self.user_id = user_id
+        self.created_at = int(time.time())
+        logger.debug(f"TokenInfo created. Expires in: {expires_in if expires_in else 'Not specified'}")
+    
+    def is_expired(self) -> bool:
+        """Check if the token is expired"""
+        if not self.expires_in:
+            return False  # If no expiration is set, assume it's not expired
+        
+        current_time = int(time.time())
+        return current_time > (self.created_at + self.expires_in)
+    
+    def serialize(self) -> Dict[str, Any]:
+        """Convert to a dictionary for storage"""
+        return {
+            "access_token": self.access_token,
+            "expires_in": self.expires_in,
+            "user_id": self.user_id,
+            "created_at": self.created_at
+        }
+    
+    @classmethod
+    def deserialize(cls, data: Dict[str, Any]) -> 'TokenInfo':
+        """Create from a stored dictionary"""
+        token = cls(
+            access_token=data.get("access_token", ""),
+            expires_in=data.get("expires_in"),
+            user_id=data.get("user_id")
+        )
+        token.created_at = data.get("created_at", int(time.time()))
+        return token
+
+
+class AuthManager:
+    """Manages authentication with Meta APIs"""
+    def __init__(self, app_id: str, redirect_uri: str = AUTH_REDIRECT_URI):
+        self.app_id = app_id
+        self.redirect_uri = redirect_uri
+        self.token_info = None
+        self._load_cached_token()
+    
+    def _get_token_cache_path(self) -> pathlib.Path:
+        """Get the platform-specific path for token cache file"""
+        if platform.system() == "Windows":
+            base_path = pathlib.Path(os.environ.get("APPDATA", ""))
+        elif platform.system() == "Darwin":  # macOS
+            base_path = pathlib.Path.home() / "Library" / "Application Support"
+        else:  # Assume Linux/Unix
+            base_path = pathlib.Path.home() / ".config"
+        
+        # Create directory if it doesn't exist
+        cache_dir = base_path / "meta-ads-mcp"
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        
+        return cache_dir / "token_cache.json"
+    
+    def _load_cached_token(self) -> bool:
+        """Load token from cache if available"""
+        cache_path = self._get_token_cache_path()
+        
+        if not cache_path.exists():
+            return False
+        
+        try:
+            with open(cache_path, "r") as f:
+                data = json.load(f)
+                self.token_info = TokenInfo.deserialize(data)
+                
+                # Check if token is expired
+                if self.token_info.is_expired():
+                    print("Cached token is expired")
+                    self.token_info = None
+                    return False
+                
+                print(f"Loaded cached token (expires in {(self.token_info.created_at + self.token_info.expires_in) - int(time.time())} seconds)")
+                return True
+        except Exception as e:
+            print(f"Error loading cached token: {e}")
+            return False
+    
+    def _save_token_to_cache(self) -> None:
+        """Save token to cache file"""
+        if not self.token_info:
+            return
+        
+        cache_path = self._get_token_cache_path()
+        
+        try:
+            with open(cache_path, "w") as f:
+                json.dump(self.token_info.serialize(), f)
+            print(f"Token cached at: {cache_path}")
+        except Exception as e:
+            print(f"Error saving token to cache: {e}")
+    
+    def get_auth_url(self) -> str:
+        """Generate the Facebook OAuth URL for desktop app flow"""
+        return (
+            f"https://www.facebook.com/v18.0/dialog/oauth?"
+            f"client_id={self.app_id}&"
+            f"redirect_uri={self.redirect_uri}&"
+            f"scope={AUTH_SCOPE}&"
+            f"response_type={AUTH_RESPONSE_TYPE}"
+        )
+    
+    def authenticate(self, force_refresh: bool = False) -> Optional[str]:
+        """
+        Authenticate with Meta APIs
+        
+        Args:
+            force_refresh: Force token refresh even if cached token exists
+            
+        Returns:
+            Access token if successful, None otherwise
+        """
+        # Check if we already have a valid token
+        if not force_refresh and self.token_info and not self.token_info.is_expired():
+            return self.token_info.access_token
+        
+        # Start the callback server if not already running
+        port = start_callback_server()
+        
+        # Update redirect URI with the actual port
+        self.redirect_uri = f"http://localhost:{port}/callback"
+        
+        # Generate the auth URL
+        auth_url = self.get_auth_url()
+        
+        # Open browser with auth URL
+        print(f"Opening browser with URL: {auth_url}")
+        webbrowser.open(auth_url)
+        
+        # We don't wait for the token here anymore
+        # The token will be processed by the callback server
+        # Just return None to indicate we've started the flow
+        return None
+    
+    def get_access_token(self) -> Optional[str]:
+        """
+        Get the current access token, refreshing if necessary
+        
+        Returns:
+            Access token if available, None otherwise
+        """
+        if not self.token_info or self.token_info.is_expired():
+            return None
+        
+        return self.token_info.access_token
+        
+    def invalidate_token(self) -> None:
+        """Invalidate the current token, usually because it has expired or is invalid"""
+        if self.token_info:
+            print(f"Invalidating token: {self.token_info.access_token[:10]}...")
+            self.token_info = None
+            
+            # Signal that authentication is needed
+            global needs_authentication
+            needs_authentication = True
+            
+            # Remove the cached token file
+            try:
+                cache_path = self._get_token_cache_path()
+                if cache_path.exists():
+                    os.remove(cache_path)
+                    print(f"Removed cached token file: {cache_path}")
+            except Exception as e:
+                print(f"Error removing cached token: {e}")
+    
+    def clear_token(self) -> None:
+        """Clear the current token and remove from cache"""
+        self.invalidate_token()
+
+
+def process_token_response(token_container):
+    """Process the token response from Facebook."""
+    global needs_authentication, auth_manager
+    
+    if token_container and token_container.get('token'):
+        logger.info("Processing token response from Facebook OAuth")
+        
+        # Exchange the short-lived token for a long-lived token
+        short_lived_token = token_container['token']
+        long_lived_token_info = exchange_token_for_long_lived(short_lived_token)
+        
+        if long_lived_token_info:
+            logger.info(f"Successfully exchanged for long-lived token (expires in {long_lived_token_info.expires_in} seconds)")
+            
+            try:
+                auth_manager.token_info = long_lived_token_info
+                logger.info(f"Long-lived token info set in auth_manager, expires in {long_lived_token_info.expires_in} seconds")
+            except NameError:
+                logger.error("auth_manager not defined when trying to process token")
+                
+            try:
+                logger.info("Attempting to save long-lived token to cache")
+                auth_manager._save_token_to_cache()
+                logger.info(f"Long-lived token successfully saved to cache at {auth_manager._get_token_cache_path()}")
+            except Exception as e:
+                logger.error(f"Error saving token to cache: {e}")
+                
+            needs_authentication = False
+            return True
+        else:
+            # Fall back to the short-lived token if exchange fails
+            logger.warning("Failed to exchange for long-lived token, using short-lived token instead")
+            token_info = TokenInfo(
+                access_token=short_lived_token,
+                expires_in=token_container.get('expires_in', 0)
+            )
+            
+            try:
+                auth_manager.token_info = token_info
+                logger.info(f"Short-lived token info set in auth_manager, expires in {token_info.expires_in} seconds")
+            except NameError:
+                logger.error("auth_manager not defined when trying to process token")
+                
+            try:
+                logger.info("Attempting to save token to cache")
+                auth_manager._save_token_to_cache()
+                logger.info(f"Token successfully saved to cache at {auth_manager._get_token_cache_path()}")
+            except Exception as e:
+                logger.error(f"Error saving token to cache: {e}")
+                
+            needs_authentication = False
+            return True
+    else:
+        logger.warning("Received empty token in process_token_response")
+        needs_authentication = True
+        return False
+
+
+def exchange_token_for_long_lived(short_lived_token):
+    """
+    Exchange a short-lived token for a long-lived token (60 days validity).
+    
+    Args:
+        short_lived_token: The short-lived access token received from OAuth flow
+        
+    Returns:
+        TokenInfo object with the long-lived token, or None if exchange failed
+    """
+    logger.info("Attempting to exchange short-lived token for long-lived token")
+    
+    try:
+        # Get the app ID from the configuration
+        app_id = meta_config.get_app_id()
+        
+        # Get the app secret - this should be securely stored
+        app_secret = os.environ.get("META_APP_SECRET", "")
+        
+        if not app_id or not app_secret:
+            logger.error("Missing app_id or app_secret for token exchange")
+            return None
+            
+        # Make the API request to exchange the token
+        url = "https://graph.facebook.com/v18.0/oauth/access_token"
+        params = {
+            "grant_type": "fb_exchange_token",
+            "client_id": app_id,
+            "client_secret": app_secret,
+            "fb_exchange_token": short_lived_token
+        }
+        
+        logger.debug(f"Making token exchange request to {url}")
+        response = requests.get(url, params=params)
+        
+        if response.status_code == 200:
+            data = response.json()
+            logger.debug(f"Token exchange response: {data}")
+            
+            # Create TokenInfo from the response
+            # The response includes access_token and expires_in (in seconds)
+            new_token = data.get("access_token")
+            expires_in = data.get("expires_in")
+            
+            if new_token:
+                logger.info(f"Received long-lived token, expires in {expires_in} seconds (~{expires_in//86400} days)")
+                return TokenInfo(
+                    access_token=new_token,
+                    expires_in=expires_in
+                )
+            else:
+                logger.error("No access_token in exchange response")
+                return None
+        else:
+            logger.error(f"Token exchange failed with status {response.status_code}: {response.text}")
+            return None
+    except Exception as e:
+        logger.error(f"Error exchanging token: {e}")
+        return None
+
+
+async def get_current_access_token() -> Optional[str]:
+    """Get the current access token from auth manager"""
+    # Use the singleton auth manager
+    global auth_manager
+    
+    # Log the function call and current app ID
+    logger.debug("get_current_access_token() called")
+    app_id = meta_config.get_app_id()
+    logger.debug(f"Current app_id: {app_id}")
+    
+    # Attempt to get access token
+    try:
+        token = auth_manager.get_access_token()
+        
+        if token:
+            logger.debug("Access token found in auth_manager")
+            return token
+        else:
+            logger.warning("No valid access token available in auth_manager")
+            return None
+    except Exception as e:
+        logger.error(f"Error getting access token: {str(e)}")
+        return None
+
+
+def login():
+    """
+    Start the login flow to authenticate with Meta
+    """
+    print("Starting Meta Ads authentication flow...")
+    
+    try:
+        # Start the callback server first
+        port = start_callback_server()
+        
+        # Get the auth URL and open the browser
+        auth_url = auth_manager.get_auth_url()
+        print(f"Opening browser with URL: {auth_url}")
+        webbrowser.open(auth_url)
+        
+        # Wait for token to be received
+        print("Waiting for authentication to complete...")
+        max_wait = 300  # 5 minutes
+        wait_interval = 2  # 2 seconds
+        
+        for _ in range(max_wait // wait_interval):
+            if token_container["token"]:
+                token = token_container["token"]
+                print("Authentication successful!")
+                # Verify token works by getting basic user info
+                try:
+                    from .api import make_api_request
+                    result = asyncio.run(make_api_request("me", token, {}))
+                    print(f"Authenticated as: {result.get('name', 'Unknown')} (ID: {result.get('id', 'Unknown')})")
+                    return
+                except Exception as e:
+                    print(f"Warning: Could not verify token: {e}")
+                    return
+            time.sleep(wait_interval)
+        
+        print("Authentication timed out. Please try again.")
+    except Exception as e:
+        print(f"Error during authentication: {e}")
+        print(f"Direct authentication URL: {auth_manager.get_auth_url()}")
+        print("You can manually open this URL in your browser to complete authentication.")
+
+# Initialize auth manager with a placeholder - will be updated at runtime
+META_APP_ID = os.environ.get("META_APP_ID", "YOUR_META_APP_ID")
+auth_manager = AuthManager(META_APP_ID)