meta-ads-mcp 0.4.3__tar.gz → 0.4.5__tar.gz

{meta_ads_mcp-0.4.3 → meta_ads_mcp-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.4.3
+Version: 0.4.5
 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
@@ -49,7 +49,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for in
 
 ## Getting started with Remote MCP (Recommended)
 
-The fastest and most reliable way to get started is to **[🚀 Get started with our Meta Ads Remote MCP](https://pipeboard.co)**. No technical setup required - just connect and start analyzing your ad campaigns with AI!
+The fastest and most reliable way to get started is to **[🚀 Get started with our Meta Ads Remote MCP](https://pipeboard.co)**. Our cloud service uses streamable HTTP transport for reliable, scalable access to Meta Ads data. No technical setup required - just connect and start analyzing your ad campaigns with AI!
 
 ### For Claude Pro/Max Users
 
@@ -88,6 +88,8 @@ Use the Remote MCP URL: `https://mcp.pipeboard.co/meta-ads-mcp`
 
 If you're a developer or need to customize the installation, you can run Meta Ads MCP locally. **Most marketers should use the Remote MCP above instead!** For complete technical setup instructions, see our **[Local Installation Guide](LOCAL_INSTALLATION.md)**.
 
+Meta Ads MCP also supports **streamable HTTP transport**, allowing you to run it as a standalone HTTP API for web applications and custom integrations. See **[Streamable HTTP Setup Guide](STREAMABLE_HTTP_SETUP.md)** for complete instructions.
+
 ### Quick Local Setup
 
 ```bash

{meta_ads_mcp-0.4.3 → meta_ads_mcp-0.4.5}/README.md

@@ -24,7 +24,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for in
 
 ## Getting started with Remote MCP (Recommended)
 
-The fastest and most reliable way to get started is to **[🚀 Get started with our Meta Ads Remote MCP](https://pipeboard.co)**. No technical setup required - just connect and start analyzing your ad campaigns with AI!
+The fastest and most reliable way to get started is to **[🚀 Get started with our Meta Ads Remote MCP](https://pipeboard.co)**. Our cloud service uses streamable HTTP transport for reliable, scalable access to Meta Ads data. No technical setup required - just connect and start analyzing your ad campaigns with AI!
 
 ### For Claude Pro/Max Users
 
@@ -63,6 +63,8 @@ Use the Remote MCP URL: `https://mcp.pipeboard.co/meta-ads-mcp`
 
 If you're a developer or need to customize the installation, you can run Meta Ads MCP locally. **Most marketers should use the Remote MCP above instead!** For complete technical setup instructions, see our **[Local Installation Guide](LOCAL_INSTALLATION.md)**.
 
+Meta Ads MCP also supports **streamable HTTP transport**, allowing you to run it as a standalone HTTP API for web applications and custom integrations. See **[Streamable HTTP Setup Guide](STREAMABLE_HTTP_SETUP.md)** for complete instructions.
+
 ### Quick Local Setup
 
 ```bash

{meta_ads_mcp-0.4.3 → meta_ads_mcp-0.4.5}/STREAMABLE_HTTP_SETUP.md

@@ -26,10 +26,10 @@ export PIPEBOARD_API_TOKEN=your_pipeboard_token
 
 ### 3. Make HTTP Requests
 
-The server accepts JSON-RPC 2.0 requests at the `/mcp/` endpoint. Use the `Authorization` header to provide your token.
+The server accepts JSON-RPC 2.0 requests at the `/mcp` endpoint. Use the `Authorization` header to provide your token.
 
 ```bash
-curl -X POST http://localhost:8080/mcp/ \
+curl -X POST http://localhost:8080/mcp \
   -H "Content-Type: application/json" \
   -H "Accept: application/json, text/event-stream" \
   -H "Authorization: Bearer your_pipeboard_token" \
@@ -77,7 +77,7 @@ python -m meta_ads_mcp --transport streamable-http --port 9000
 
 ```bash
 curl -H "Authorization: Bearer your_pipeboard_token" \
-     -X POST http://localhost:8080/mcp/ \
+     -X POST http://localhost:8080/mcp \
      -H "Content-Type: application/json" \
      -H "Accept: application/json, text/event-stream" \
      -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
@@ -89,7 +89,7 @@ If you have a Meta Developer App, you can use a direct access token via the `X-M
 
 ```bash
 curl -H "X-META-ACCESS-TOKEN: your_meta_access_token" \
-     -X POST http://localhost:8080/mcp/ \
+     -X POST http://localhost:8080/mcp \
      -H "Content-Type: application/json" \
      -H "Accept: application/json, text/event-stream" \
      -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
@@ -100,7 +100,7 @@ curl -H "X-META-ACCESS-TOKEN: your_meta_access_token" \
 ### Server URL Structure
 
 **Base URL**: `http://localhost:8080`  
-**MCP Endpoint**: `/mcp/`
+**MCP Endpoint**: `/mcp`
 
 ### MCP Protocol Methods
 
@@ -129,7 +129,7 @@ All responses follow JSON-RPC 2.0 format:
 ### 1. Initialize Session
 
 ```bash
-curl -X POST http://localhost:8080/mcp/ \
+curl -X POST http://localhost:8080/mcp \
   -H "Content-Type: application/json" \
   -H "Accept: application/json, text/event-stream" \
   -H "Authorization: Bearer your_token" \
@@ -148,7 +148,7 @@ curl -X POST http://localhost:8080/mcp/ \
 ### 2. List Available Tools
 
 ```bash
-curl -X POST http://localhost:8080/mcp/ \
+curl -X POST http://localhost:8080/mcp \
   -H "Content-Type: application/json" \
   -H "Accept: application/json, text/event-stream" \
   -H "Authorization: Bearer your_token" \
@@ -162,7 +162,7 @@ curl -X POST http://localhost:8080/mcp/ \
 ### 3. Get Ad Accounts
 
 ```bash
-curl -X POST http://localhost:8080/mcp/ \
+curl -X POST http://localhost:8080/mcp \
   -H "Content-Type: application/json" \
   -H "Accept: application/json, text/event-stream" \
   -H "Authorization: Bearer your_token" \
@@ -180,7 +180,7 @@ curl -X POST http://localhost:8080/mcp/ \
 ### 4. Get Campaign Performance
 
 ```bash
-curl -X POST http://localhost:8080/mcp/ \
+curl -X POST http://localhost:8080/mcp \
   -H "Content-Type: application/json" \
   -H "Accept: application/json, text/event-stream" \
   -H "Authorization: Bearer your_token" \
@@ -210,7 +210,7 @@ import json
 class MetaAdsMCPClient:
     def __init__(self, base_url="http://localhost:8080", token=None):
         self.base_url = base_url
-        self.endpoint = f"{base_url}/mcp/"
+        self.endpoint = f"{base_url}/mcp"
         self.headers = {
             "Content-Type": "application/json",
             "Accept": "application/json, text/event-stream"
@@ -245,7 +245,7 @@ const axios = require('axios');
 class MetaAdsMCPClient {
     constructor(baseUrl = 'http://localhost:8080', token = null) {
         this.baseUrl = baseUrl;
-        this.endpoint = `${baseUrl}/mcp/`;
+        this.endpoint = `${baseUrl}/mcp`;
         this.headers = {
             'Content-Type': 'application/json',
             'Accept': 'application/json, text/event-stream'
@@ -325,7 +325,7 @@ export META_ACCESS_TOKEN=your_access_token
 
 1. **Connection Refused**: Ensure the server is running and accessible on the specified port.
 2. **Authentication Failed**: Verify your Bearer token is valid and included in the `Authorization` header.
-3. **404 Not Found**: Make sure you're using the correct endpoint (`/mcp/`).
+3. **404 Not Found**: Make sure you're using the correct endpoint (`/mcp`).
 4. **JSON-RPC Errors**: Check that your request follows the JSON-RPC 2.0 format.
 
 ### Debug Mode
@@ -337,7 +337,7 @@ Enable verbose logging by setting the log level in your environment if the appli
 Test if the server is running by sending a `tools/list` request:
 
 ```bash
-curl -X POST http://localhost:8080/mcp/ \
+curl -X POST http://localhost:8080/mcp \
   -H "Content-Type: application/json" \
   -H "Accept: application/json, text/event-stream" \
   -H "Authorization: Bearer your_token" \

{meta_ads_mcp-0.4.3 → meta_ads_mcp-0.4.5}/meta_ads_mcp/__init__.py

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

{meta_ads_mcp-0.4.3 → meta_ads_mcp-0.4.5}/meta_ads_mcp/core/adsets.py

@@ -5,9 +5,6 @@ from typing import Optional, Dict, Any, List
 from .api import meta_api_tool, make_api_request
 from .accounts import get_ad_accounts
 from .server import mcp_server
-import asyncio
-from .callback_server import start_callback_server, shutdown_callback_server, update_confirmation
-import urllib.parse
 
 
 @mcp_server.tool()
@@ -211,94 +208,52 @@ 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}})
+        targeting: Complete targeting specifications (will replace existing targeting)
+                  (e.g. {"targeting_automation":{"advantage_audience":1}, "geo_locations": {"countries": ["US"]}})
         optimization_goal: Conversion optimization goal (e.g., 'LINK_CLICKS', 'CONVERSIONS', 'APP_INSTALLS', etc.)
         access_token: Meta API access token (optional - will use cached token if not provided)
     """
     if not adset_id:
         return json.dumps({"error": "No ad set ID provided"}, indent=2)
     
-    changes = {}
+    params = {}
     
     if frequency_control_specs is not None:
-        changes['frequency_control_specs'] = frequency_control_specs
+        params['frequency_control_specs'] = frequency_control_specs
     
     if bid_strategy is not None:
-        changes['bid_strategy'] = bid_strategy
+        params['bid_strategy'] = bid_strategy
         
     if bid_amount is not None:
-        changes['bid_amount'] = bid_amount
+        params['bid_amount'] = str(bid_amount)
         
     if status is not None:
-        changes['status'] = status
+        params['status'] = status
         
     if optimization_goal is not None:
-        changes['optimization_goal'] = optimization_goal
+        params['optimization_goal'] = optimization_goal
         
     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
+        # Ensure proper JSON encoding for targeting
+        if isinstance(targeting, dict):
+            params['targeting'] = json.dumps(targeting)
         else:
-            # Full targeting replacement
-            changes['targeting'] = targeting
+            params['targeting'] = targeting  # Already a string
     
-    if not changes:
+    if not params:
         return json.dumps({"error": "No update parameters provided"}, indent=2)
+
+    endpoint = f"{adset_id}"
     
-    # Get current ad set details for comparison
-    current_details_json = await get_adset_details(adset_id=adset_id, access_token=access_token)
-    current_details = json.loads(current_details_json)
-    
-    # Start the callback server if not already running
     try:
-        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?adset_id={adset_id}&token={access_token}&changes={encoded_changes}"
+        # Use POST method for updates as per Meta API documentation
+        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 adset_id in error for better context
         return json.dumps({
-            "error": "Callback server disabled",
-            "message": f"Cannot create confirmation URL: {str(e)}",
-            "suggestion": "Manual update confirmation not available when META_ADS_DISABLE_CALLBACK_SERVER is set",
-            "adset_id": adset_id,
-            "proposed_changes": changes
-        }, indent=2)
-    
-    # Reset the update confirmation
-    update_confirmation.clear()
-    update_confirmation.update({"approved": False})
-    
-    # Return the confirmation link
-    response = {
-        "message": "Please confirm the ad set update",
-        "confirmation_url": confirmation_url,
-        "markdown_link": f"[Click here to confirm ad set 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": "Click the link to confirm and apply your ad set updates. Refresh the browser page if it doesn't load immediately."
-    }
-    
-    return json.dumps(response, indent=2) 
+            "error": f"Failed to update ad set {adset_id}",
+            "details": error_msg,
+            "params_sent": params
+        }, indent=2) 

{meta_ads_mcp-0.4.3 → meta_ads_mcp-0.4.5}/meta_ads_mcp/core/auth.py

@@ -23,7 +23,9 @@ from .callback_server import (
 from .pipeboard_auth import pipeboard_auth_manager
 
 # Auth constants
-AUTH_SCOPE = "ads_management,ads_read,business_management,public_profile"
+# Scope includes pages_show_list and pages_read_engagement to fix issue #16
+# where get_account_pages failed for regular users due to missing page permissions
+AUTH_SCOPE = "ads_management,ads_read,business_management,public_profile,pages_show_list,pages_read_engagement"
 AUTH_REDIRECT_URI = "http://localhost:8888/callback"
 AUTH_RESPONSE_TYPE = "token"
 

meta_ads_mcp-0.4.5/meta_ads_mcp/core/callback_server.py

@@ -0,0 +1,257 @@
+"""Callback server for Meta Ads API authentication."""
+
+import threading
+import socket
+import asyncio
+import json
+import logging
+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 

{meta_ads_mcp-0.4.3 → meta_ads_mcp-0.4.5}/pyproject.toml

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