meta-ads-mcp 0.7.8__tar.gz → 0.7.10__tar.gz

{meta_ads_mcp-0.7.8 → meta_ads_mcp-0.7.10}/PKG-INFO

@@ -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.10/RELEASE.md

@@ -0,0 +1,166 @@
+# Release Process
+
+This repository uses GitHub Actions to automatically publish releases to PyPI. Here's the optimized release process:
+
+## 🚀 Quick Release (Recommended)
+
+### Prerequisites
+- ✅ **Trusted Publishing Configured**: Repository uses PyPI trusted publishing with OIDC tokens
+- ✅ **GitHub CLI installed**: `gh` command available for streamlined releases
+- ✅ **Clean working directory**: No uncommitted changes
+
+### Optimal Release Process
+
+1. **Update version in both files** (use consistent versioning):
+   
+   ```bash
+   # Update pyproject.toml
+   sed -i '' 's/version = "0.7.7"/version = "0.7.8"/' pyproject.toml
+   
+   # Update __init__.py  
+   sed -i '' 's/__version__ = "0.7.7"/__version__ = "0.7.8"/' meta_ads_mcp/__init__.py
+   ```
+   
+   Or manually edit:
+   - `pyproject.toml`: `version = "0.7.8"`
+   - `meta_ads_mcp/__init__.py`: `__version__ = "0.7.8"`
+
+2. **Commit and push version changes**:
+   ```bash
+   git add pyproject.toml meta_ads_mcp/__init__.py
+   git commit -m "Bump version to 0.7.8"
+   git push origin main
+   ```
+
+3. **Create GitHub release** (triggers automatic PyPI publishing):
+   ```bash
+   # Use bash wrapper if gh has issues in Cursor
+   bash -c "gh release create 0.7.8 --title '0.7.8' --generate-notes"
+   ```
+
+4. **Verify release** (optional):
+   ```bash
+   # Check GitHub release
+   curl -s "https://api.github.com/repos/pipeboard-co/meta-ads-mcp/releases/latest" | grep -E '"tag_name"|"name"'
+   
+   # Check PyPI availability (wait 2-3 minutes)
+   curl -s "https://pypi.org/pypi/meta-ads-mcp/json" | grep -E '"version"|"0.7.8"'
+   ```
+
+## 📋 Detailed Release Process
+
+### Version Management Best Practices
+
+- **Semantic Versioning**: Follow `MAJOR.MINOR.PATCH` (e.g., 0.7.8)
+- **Synchronized Files**: Always update BOTH version files
+- **Commit Convention**: Use `"Bump version to X.Y.Z"` format
+- **Release Tag**: GitHub release tag matches version (no "v" prefix)
+
+### Pre-Release Checklist
+
+```bash
+# 1. Ensure clean working directory
+git status
+
+# 2. Run tests locally (optional but recommended)
+uv run python -m pytest tests/ -v
+
+# 3. Check current version
+grep -E "version =|__version__" pyproject.toml meta_ads_mcp/__init__.py
+```
+
+### Release Commands (One-liner)
+
+```bash
+# Complete release in one sequence
+VERSION="0.7.8" && \
+sed -i '' "s/version = \"0.7.7\"/version = \"$VERSION\"/" pyproject.toml && \
+sed -i '' "s/__version__ = \"0.7.7\"/__version__ = \"$VERSION\"/" meta_ads_mcp/__init__.py && \
+git add pyproject.toml meta_ads_mcp/__init__.py && \
+git commit -m "Bump version to $VERSION" && \
+git push origin main && \
+bash -c "gh release create $VERSION --title '$VERSION' --generate-notes"
+```
+
+## 🔄 Workflows
+
+### `publish.yml` (Automatic)
+- **Trigger**: GitHub release creation
+- **Purpose**: Build and publish to PyPI
+- **Security**: OIDC tokens (no API keys)
+- **Status**: ✅ Fully automated
+
+### `test.yml` (Validation)
+- **Trigger**: Push to main/master
+- **Purpose**: Package structure validation
+- **Matrix**: Python 3.10, 3.11, 3.12
+- **Note**: Build tests only, not pytest
+
+## 🛠️ Troubleshooting
+
+### Common Issues
+
+1. **gh command issues in Cursor**:
+   ```bash
+   # Use bash wrapper
+   bash -c "gh release create 0.7.8 --title '0.7.8' --generate-notes"
+   ```
+
+2. **Version mismatch**:
+   ```bash
+   # Verify both files have same version
+   grep -E "version =|__version__" pyproject.toml meta_ads_mcp/__init__.py
+   ```
+
+3. **PyPI not updated**:
+   ```bash
+   # Check if package is available (wait 2-3 minutes)
+   curl -s "https://pypi.org/pypi/meta-ads-mcp/json" | grep '"version"'
+   ```
+
+### Manual Deployment (Fallback)
+
+```bash
+# Install build tools
+pip install build twine
+
+# Build package
+python -m build
+
+# Upload to PyPI (requires API token)
+python -m twine upload dist/*
+```
+
+## 📊 Release Verification
+
+### GitHub Release
+- ✅ Release created with correct tag
+- ✅ Auto-generated notes from commits
+- ✅ Actions tab shows successful workflow
+
+### PyPI Package
+- ✅ Package available for installation
+- ✅ Correct version displayed
+- ✅ All dependencies listed
+
+### Installation Test
+```bash
+# Test new version installation
+pip install meta-ads-mcp==0.7.8
+# or
+uvx meta-ads-mcp@0.7.8
+```
+
+## 🔒 Security Notes
+
+- **Trusted Publishing**: Uses GitHub OIDC tokens (no API keys needed)
+- **Isolated Builds**: All builds run in GitHub-hosted runners
+- **Access Control**: Only maintainers can create releases
+- **Audit Trail**: All releases tracked in GitHub Actions
+
+## 📈 Release Metrics
+
+Track successful releases:
+- **GitHub Releases**: https://github.com/pipeboard-co/meta-ads-mcp/releases
+- **PyPI Package**: https://pypi.org/project/meta-ads-mcp/
+- **Actions History**: https://github.com/pipeboard-co/meta-ads-mcp/actions 

{meta_ads_mcp-0.7.8 → meta_ads_mcp-0.7.10}/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-0.7.8 → meta_ads_mcp-0.7.10}/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-0.7.8 → meta_ads_mcp-0.7.10}/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 → meta_ads_mcp-0.7.10}/pyproject.toml

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

{meta_ads_mcp-0.7.8 → meta_ads_mcp-0.7.10}/tests/test_get_ad_creatives_fix.py

@@ -90,11 +90,11 @@ class TestGetAdCreativesBugFix:
         
         urls = extract_creative_image_urls(test_creative)
         
-        # Should extract URLs in order: image_url, thumbnail_url, picture
+        # Should extract URLs in order: image_url, picture, thumbnail_url (new priority order)
         expected_urls = [
             "https://example.com/image.jpg",
-            "https://example.com/thumb.jpg", 
-            "https://example.com/picture.jpg"
+            "https://example.com/picture.jpg",
+            "https://example.com/thumb.jpg"
         ]
         
         assert urls == expected_urls