meta-ads-mcp-python 1.0.79__py3-none-any.whl

meta_ads_mcp/core/authentication.py

@@ -0,0 +1,207 @@
+"""Authentication-specific functionality for Meta Ads API.
+
+The Meta Ads MCP server supports three authentication modes:
+
+1. **Development/Local Mode** (default)
+   - Uses local callback server on localhost:8080+ for OAuth redirect
+   - Requires META_ADS_DISABLE_CALLBACK_SERVER to NOT be set
+   - Best for local development and testing
+
+2. **Production with API Token** 
+   - Uses PIPEBOARD_API_TOKEN for server-to-server authentication
+   - Bypasses OAuth flow entirely
+   - Best for server deployments with pre-configured tokens
+
+3. **Production OAuth Flow** (NEW)
+   - Uses Pipeboard OAuth endpoints for dynamic client registration
+   - Triggered when META_ADS_DISABLE_CALLBACK_SERVER is set but no PIPEBOARD_API_TOKEN
+   - Supports MCP clients that implement OAuth 2.0 discovery
+
+Environment Variables:
+- PIPEBOARD_API_TOKEN: Enables mode 2 (token-based auth)  
+- META_ADS_DISABLE_CALLBACK_SERVER: Disables local server, enables mode 3
+- META_ACCESS_TOKEN: Direct Meta token (fallback)
+- META_ADS_DISABLE_LOGIN_LINK: Hard-disables the get_login_link tool; returns a disabled message
+"""
+
+import json
+from typing import Optional
+import asyncio
+import os
+from .api import meta_api_tool
+from . import auth
+from .auth import start_callback_server, shutdown_callback_server, auth_manager
+from .server import mcp_server
+from .utils import logger, META_APP_SECRET
+from .pipeboard_auth import pipeboard_auth_manager
+
+# Only register the login link tool if not explicitly disabled
+ENABLE_LOGIN_LINK = not bool(os.environ.get("META_ADS_DISABLE_LOGIN_LINK", ""))
+
+
+async def get_login_link(access_token: Optional[str] = None) -> str:
+    """
+    Get a clickable login link for Meta Ads authentication.
+    
+    NOTE: This method should only be used if you're using your own Facebook app.
+    If using Pipeboard authentication (recommended), set the PIPEBOARD_API_TOKEN
+    environment variable instead (token obtainable via https://pipeboard.co).
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+    
+    Returns:
+        A clickable resource link for Meta authentication
+    """
+    # Check if we're using pipeboard authentication
+    using_pipeboard = bool(os.environ.get("PIPEBOARD_API_TOKEN", ""))
+    callback_server_disabled = bool(os.environ.get("META_ADS_DISABLE_CALLBACK_SERVER", ""))
+    
+    if using_pipeboard:
+        # Pipeboard token-based authentication
+        try:
+            logger.info("Using Pipeboard token-based authentication")
+            
+            # If an access token was provided, this is likely a test - return success
+            if access_token:
+                return json.dumps({
+                    "message": " Authentication Token Provided",
+                    "status": "Using provided access token for authentication",
+                    "token_info": f"Token preview: {access_token[:10]}...",
+                    "authentication_method": "manual_token",
+                    "ready_to_use": "You can now use all Meta Ads MCP tools and commands."
+                }, indent=2)
+            
+            # Check if Pipeboard token is working
+            token = pipeboard_auth_manager.get_access_token()
+            if token:
+                return json.dumps({
+                    "message": " Already Authenticated",
+                    "status": "You're successfully authenticated with Meta Ads via Pipeboard!",
+                    "token_info": f"Token preview: {token[:10]}...",
+                    "authentication_method": "pipeboard_token",
+                    "ready_to_use": "You can now use all Meta Ads MCP tools and commands."
+                }, indent=2)
+            
+            # Start Pipeboard auth flow
+            auth_data = pipeboard_auth_manager.initiate_auth_flow()
+            login_url = auth_data.get('loginUrl')
+            
+            if login_url:
+                return json.dumps({
+                    "message": " Click to Authenticate",
+                    "login_url": login_url,
+                    "markdown_link": f"[ Authenticate with Meta Ads]({login_url})",
+                    "instructions": "Click the link above to complete authentication with Meta Ads.",
+                    "authentication_method": "pipeboard_oauth",
+                    "what_happens_next": "After clicking, you'll be redirected to Meta's authentication page. Once completed, your token will be automatically saved.",
+                    "token_duration": "Your token will be valid for approximately 60 days."
+                }, indent=2)
+            else:
+                return json.dumps({
+                    "message": " Authentication Error",
+                    "error": "Could not generate authentication URL from Pipeboard",
+                    "troubleshooting": [
+                        "Check that your PIPEBOARD_API_TOKEN is valid",
+                        "Ensure the Pipeboard service is accessible",
+                        "Try again in a few moments"
+                    ],
+                    "authentication_method": "pipeboard_oauth_failed"
+                }, indent=2)
+                
+        except Exception as e:
+            logger.error(f"Error initiating Pipeboard auth flow: {e}")
+            return json.dumps({
+                "message": " Pipeboard Authentication Error",
+                "error": f"Failed to initiate Pipeboard authentication: {str(e)}",
+                "troubleshooting": [
+                    " Check that PIPEBOARD_API_TOKEN environment variable is set correctly",
+                    " Verify that pipeboard.co is accessible from your network",
+                    " Try refreshing your Pipeboard API token",
+                    " Wait a moment and try again"
+                ],
+                "get_help": "Contact support if the issue persists",
+                "authentication_method": "pipeboard_error"
+            }, indent=2)
+    elif callback_server_disabled:
+        # Production OAuth flow - use Pipeboard OAuth endpoints directly
+        logger.info("Production OAuth flow - using Pipeboard OAuth endpoints")
+        
+        return json.dumps({
+            "message": " Authentication Required",
+            "instructions": "Please sign in to your Pipeboard account to authenticate with Meta Ads.",
+            "sign_in_url": "https://pipeboard.co/auth/signin",
+            "markdown_link": "[ Sign in to Pipeboard](https://pipeboard.co/auth/signin)",
+            "what_to_do": "Click the link above to sign in to your Pipeboard account and complete authentication.",
+            "authentication_method": "production_oauth"
+        }, indent=2)
+    else:
+        # Original Meta authentication flow (development/local)
+        # Check if we have a cached token
+        cached_token = auth_manager.get_access_token()
+        token_status = "No token" if not cached_token else "Valid token"
+        
+        # If we already have a valid token and none was provided, just return success
+        if cached_token and not access_token:
+            logger.info("get_login_link called with existing valid token")
+            return json.dumps({
+                "message": " Already Authenticated", 
+                "status": "You're successfully authenticated with Meta Ads!",
+                "token_info": f"Token preview: {cached_token[:10]}...",
+                "created_at": auth_manager.token_info.created_at if hasattr(auth_manager, "token_info") else None,
+                "expires_in": auth_manager.token_info.expires_in if hasattr(auth_manager, "token_info") else None,
+                "authentication_method": "meta_oauth",
+                "ready_to_use": "You can now use all Meta Ads MCP tools and commands."
+            }, indent=2)
+        
+        # IMPORTANT: Start the callback server first by calling our helper function
+        # This ensures the server is ready before we provide the URL to the user
+        logger.info("Starting callback server for authentication")
+        try:
+            port = start_callback_server()
+            logger.info(f"Callback server started on port {port}")
+            
+            # Generate direct login URL
+            auth_manager.redirect_uri = f"http://localhost:{port}/callback"  # Ensure port is set correctly
+            logger.info(f"Setting redirect URI to {auth_manager.redirect_uri}")
+            login_url = auth_manager.get_auth_url()
+            logger.info(f"Generated login URL: {login_url}")
+        except Exception as e:
+            logger.error(f"Failed to start callback server: {e}")
+            return json.dumps({
+                "message": " Local Authentication Unavailable",
+                "error": "Cannot start local callback server for authentication",
+                "reason": str(e),
+                "solutions": [
+                    " Use Pipeboard authentication: Set PIPEBOARD_API_TOKEN environment variable",
+                    " Use direct token: Set META_ACCESS_TOKEN environment variable", 
+                    " Check if another service is using the required ports"
+                ],
+                "authentication_method": "meta_oauth_disabled"
+            }, indent=2)
+        
+        # Check if we can exchange for long-lived tokens
+        token_exchange_supported = bool(META_APP_SECRET)
+        token_duration = "60 days" if token_exchange_supported else "1-2 hours"
+        
+        # Return a special format that helps the LLM format the response properly
+        response = {
+            "message": " Click to Authenticate",
+            "login_url": login_url,
+            "markdown_link": f"[ Authenticate with Meta Ads]({login_url})",
+            "instructions": "Click the link above to authenticate with Meta Ads.",
+            "server_info": f"Local callback server running on port {port}",
+            "token_duration": f"Your token will be valid for approximately {token_duration}",
+            "authentication_method": "meta_oauth",
+            "what_happens_next": "After clicking, you'll be redirected to Meta's authentication page. Once completed, your token will be automatically saved.",
+            "security_note": "This uses a secure local callback server for development purposes."
+        }
+        
+        # Wait a moment to ensure the server is fully started
+        await asyncio.sleep(1)
+        
+    return json.dumps(response, indent=2)
+
+# Conditionally register as MCP tool only when enabled
+if ENABLE_LOGIN_LINK:
+    get_login_link = mcp_server.tool()(get_login_link)

meta_ads_mcp/core/budget_schedules.py

@@ -0,0 +1,70 @@
+"""Budget Schedule-related functionality for Meta Ads API."""
+
+import json
+from typing import Optional, Dict, Any
+
+from .api import meta_api_tool, make_api_request
+from .server import mcp_server
+# Assuming no other specific dependencies from adsets.py are needed for this single function.
+# If other utilities from adsets.py (like get_ad_accounts) were needed, they'd be imported here.
+
+@meta_api_tool
+async def create_budget_schedule(
+    campaign_id: str,
+    budget_value: int,
+    budget_value_type: str,
+    time_start: int,
+    time_end: int,
+    access_token: Optional[str] = None
+) -> str:
+    """
+    Create a budget schedule for a Meta Ads campaign.
+
+    Allows scheduling budget increases based on anticipated high-demand periods.
+    The times should be provided as Unix timestamps.
+    
+    Args:
+        campaign_id: Meta Ads campaign ID.
+        budget_value: Amount of budget increase. Interpreted based on budget_value_type.
+        budget_value_type: Type of budget value - "ABSOLUTE" or "MULTIPLIER".
+        time_start: Unix timestamp for when the high demand period should start.
+        time_end: Unix timestamp for when the high demand period should end.
+        access_token: Meta API access token (optional - will use cached token if not provided).
+        
+    Returns:
+        A JSON string containing the ID of the created budget schedule or an error message.
+    """
+    if not campaign_id:
+        return json.dumps({"error": "Campaign ID is required"}, indent=2)
+    if budget_value is None: # Check for None explicitly
+        return json.dumps({"error": "Budget value is required"}, indent=2)
+    if not budget_value_type:
+        return json.dumps({"error": "Budget value type is required"}, indent=2)
+    if budget_value_type not in ["ABSOLUTE", "MULTIPLIER"]:
+        return json.dumps({"error": "Invalid budget_value_type. Must be ABSOLUTE or MULTIPLIER"}, indent=2)
+    if time_start is None: # Check for None explicitly to allow 0
+        return json.dumps({"error": "Time start is required"}, indent=2)
+    if time_end is None: # Check for None explicitly to allow 0
+        return json.dumps({"error": "Time end is required"}, indent=2)
+
+    endpoint = f"{campaign_id}/budget_schedules"
+
+    params = {
+        "budget_value": budget_value,
+        "budget_value_type": budget_value_type,
+        "time_start": time_start,
+        "time_end": time_end,
+    }
+
+    try:
+        data = await make_api_request(endpoint, access_token, params, method="POST")
+        return json.dumps(data, indent=2)
+    except Exception as e:
+        error_msg = str(e)
+        # Include details about the error and the parameters sent for easier debugging
+        return json.dumps({
+            "error": "Failed to create budget schedule",
+            "details": error_msg,
+            "campaign_id": campaign_id,
+            "params_sent": params
+        }, indent=2) 

meta_ads_mcp/core/callback_server.py

@@ -0,0 +1,256 @@
+"""Callback server for Meta Ads API authentication."""
+
+import threading
+import socket
+import asyncio
+import json
+import webbrowser
+import os
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from urllib.parse import urlparse, parse_qs, quote
+from typing import Dict, Any, Optional
+
+from .utils import logger
+
+# Global token container for communication between threads
+token_container = {"token": None, "expires_in": None, "user_id": None}
+
+# Global variables for server thread and state
+callback_server_thread = None
+callback_server_lock = threading.Lock()
+callback_server_running = False
+callback_server_port = None
+callback_server_instance = None
+server_shutdown_timer = None
+
+# Timeout in seconds before shutting down the callback server
+CALLBACK_SERVER_TIMEOUT = 180  # 3 minutes timeout
+
+
+class CallbackHandler(BaseHTTPRequestHandler):
+    def do_GET(self):
+        try:
+            # Print path for debugging
+            print(f"Callback server received request: {self.path}")
+            
+            if self.path.startswith("/callback"):
+                self._handle_oauth_callback()
+            elif self.path.startswith("/token"):
+                self._handle_token()
+            else:
+                # If no matching path, return a 404 error
+                self.send_response(404)
+                self.end_headers()
+        except Exception as e:
+            print(f"Error processing request: {e}")
+            self.send_response(500)
+            self.end_headers()
+    
+    def _handle_oauth_callback(self):
+        """Handle OAuth callback after user authorization"""
+        # Check if we're being redirected from Facebook with an authorization code
+        parsed_url = urlparse(self.path)
+        params = parse_qs(parsed_url.query)
+        
+        # Check for code parameter
+        code = params.get('code', [None])[0]
+        state = params.get('state', [None])[0]
+        error = params.get('error', [None])[0]
+        
+        # Send 200 OK response with a simple HTML page
+        self.send_response(200)
+        self.send_header("Content-type", "text/html")
+        self.end_headers()
+        
+        if error:
+            # User denied access or other error occurred
+            html = f"""
+            <html>
+            <head><title>Authorization Failed</title></head>
+            <body>
+                <h1>Authorization Failed</h1>
+                <p>Error: {error}</p>
+                <p>The authorization was cancelled or failed. You can close this window.</p>
+            </body>
+            </html>
+            """
+            logger.error(f"OAuth authorization failed: {error}")
+        elif code:
+            # Success case - we have the authorization code
+            logger.info(f"Received authorization code: {code[:10]}...")
+            
+            # Store the authorization code temporarily
+            # The auth module will exchange this for an access token
+            token_container.update({
+                "auth_code": code,
+                "state": state,
+                "timestamp": asyncio.get_event_loop().time()
+            })
+            
+            html = """
+            <html>
+            <head><title>Authorization Successful</title></head>
+            <body>
+                <h1> Authorization Successful!</h1>
+                <p>You have successfully authorized the Meta Ads MCP application.</p>
+                <p>You can now close this window and return to your application.</p>
+                <script>
+                    // Try to close the window automatically after 2 seconds
+                    setTimeout(function() {
+                        window.close();
+                    }, 2000);
+                </script>
+            </body>
+            </html>
+            """
+            logger.info("OAuth authorization successful")
+        else:
+            # No code or error - something unexpected happened
+            html = """
+            <html>
+            <head><title>Unexpected Response</title></head>
+            <body>
+                <h1>Unexpected Response</h1>
+                <p>No authorization code or error received. Please try again.</p>
+            </body>
+            </html>
+            """
+            logger.warning("OAuth callback received without code or error")
+        
+        self.wfile.write(html.encode())
+    
+    def _handle_token(self):
+        """Handle token endpoint for retrieving stored token data"""
+        # This endpoint allows other parts of the application to retrieve
+        # token information from the callback server
+        
+        self.send_response(200)
+        self.send_header("Content-type", "application/json")
+        self.end_headers()
+        
+        # Return current token container contents
+        response_data = {
+            "status": "success",
+            "data": token_container
+        }
+        
+        self.wfile.write(json.dumps(response_data).encode())
+        
+        # The actual token processing is now handled by the auth module
+        # that imports this module and accesses token_container
+    
+    # Silence server logs
+    def log_message(self, format, *args):
+        return
+
+
+def shutdown_callback_server():
+    """
+    Shutdown the callback server if it's running
+    """
+    global callback_server_thread, callback_server_running, callback_server_port, callback_server_instance, server_shutdown_timer
+    
+    with callback_server_lock:
+        if not callback_server_running:
+            print("Callback server is not running")
+            return
+        
+        if server_shutdown_timer is not None:
+            server_shutdown_timer.cancel()
+            server_shutdown_timer = None
+        
+        try:
+            if callback_server_instance:
+                print("Shutting down callback server...")
+                callback_server_instance.shutdown()
+                callback_server_instance.server_close()
+                print("Callback server shut down successfully")
+            
+            if callback_server_thread and callback_server_thread.is_alive():
+                callback_server_thread.join(timeout=5)
+                if callback_server_thread.is_alive():
+                    print("Warning: Callback server thread did not shut down cleanly")
+        except Exception as e:
+            print(f"Error during callback server shutdown: {e}")
+        finally:
+            callback_server_running = False
+            callback_server_thread = None
+            callback_server_port = None
+            callback_server_instance = None
+
+
+def start_callback_server() -> int:
+    """
+    Start the callback server and return the port number it's running on.
+    
+    Returns:
+        int: Port number the server is listening on
+        
+    Raises:
+        Exception: If the server fails to start
+    """
+    global callback_server_thread, callback_server_running, callback_server_port, callback_server_instance, server_shutdown_timer
+    
+    # Check if callback server is disabled
+    if os.environ.get("META_ADS_DISABLE_CALLBACK_SERVER"):
+        raise Exception("Callback server is disabled via META_ADS_DISABLE_CALLBACK_SERVER environment variable")
+    
+    with callback_server_lock:
+        if callback_server_running:
+            print(f"Callback server already running on port {callback_server_port}")
+            return callback_server_port
+        
+        # Find an available port
+        port = 8080
+        max_attempts = 10
+        for attempt in range(max_attempts):
+            try:
+                # Test if port is available
+                with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                    s.bind(('localhost', port))
+                break
+            except OSError:
+                port += 1
+        else:
+            raise Exception(f"Could not find an available port after {max_attempts} attempts")
+        
+        callback_server_port = port
+        
+        # Start the server in a separate thread
+        callback_server_thread = threading.Thread(target=server_thread, daemon=True)
+        callback_server_thread.start()
+        
+        # Wait a moment for the server to start
+        import time
+        time.sleep(0.5)
+        
+        if not callback_server_running:
+            raise Exception("Failed to start callback server")
+        
+        # Set up automatic shutdown timer
+        def auto_shutdown():
+            print(f"Callback server auto-shutdown after {CALLBACK_SERVER_TIMEOUT} seconds")
+            shutdown_callback_server()
+        
+        server_shutdown_timer = threading.Timer(CALLBACK_SERVER_TIMEOUT, auto_shutdown)
+        server_shutdown_timer.start()
+        
+        print(f"Callback server started on http://localhost:{port}")
+        return port
+
+
+def server_thread():
+    """Thread function to run the callback server"""
+    global callback_server_running, callback_server_instance
+    
+    try:
+        callback_server_instance = HTTPServer(('localhost', callback_server_port), CallbackHandler)
+        callback_server_running = True
+        print(f"Callback server thread started on port {callback_server_port}")
+        callback_server_instance.serve_forever()
+    except Exception as e:
+        print(f"Callback server error: {e}")
+        callback_server_running = False
+    finally:
+        print("Callback server thread finished")
+        callback_server_running = False