meta-ads-mcp 0.10.6__tar.gz → 0.10.9__tar.gz

{meta_ads_mcp-0.10.6 → meta_ads_mcp-0.10.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.10.6
+Version: 0.10.9
 Summary: Model Context Protocol (MCP) server 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
@@ -176,13 +176,43 @@ For local installation configuration, authentication options, and advanced techn
      - `access_token` (optional): Meta API access token (will use cached token if not provided)
      - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
      - `name`: Campaign name
-     - `objective`: Campaign objective (AWARENESS, TRAFFIC, ENGAGEMENT, etc.)
+     - `objective`: Campaign objective (ODAX, outcome-based). Must be one of:
+       - `OUTCOME_AWARENESS`
+       - `OUTCOME_TRAFFIC`
+       - `OUTCOME_ENGAGEMENT`
+       - `OUTCOME_LEADS`
+       - `OUTCOME_SALES`
+       - `OUTCOME_APP_PROMOTION`
+       
+       Note: Legacy objectives such as `BRAND_AWARENESS`, `LINK_CLICKS`, `CONVERSIONS`, `APP_INSTALLS`, etc. are no longer valid for new campaigns and will cause a 400 error. Use the outcome-based values above. Common mappings:
+       - `BRAND_AWARENESS` → `OUTCOME_AWARENESS`
+       - `REACH` → `OUTCOME_AWARENESS`
+       - `LINK_CLICKS`, `TRAFFIC` → `OUTCOME_TRAFFIC`
+       - `POST_ENGAGEMENT`, `PAGE_LIKES`, `EVENT_RESPONSES`, `VIDEO_VIEWS` → `OUTCOME_ENGAGEMENT`
+       - `LEAD_GENERATION` → `OUTCOME_LEADS`
+       - `CONVERSIONS`, `CATALOG_SALES`, `MESSAGES` (sales-focused flows) → `OUTCOME_SALES`
+       - `APP_INSTALLS` → `OUTCOME_APP_PROMOTION`
      - `status`: Initial campaign status (default: PAUSED)
      - `special_ad_categories`: List of special ad categories if applicable
      - `daily_budget`: Daily budget in account currency (in cents)
      - `lifetime_budget`: Lifetime budget in account currency (in cents)
+     - `bid_strategy`: Bid strategy. Must be one of: `LOWEST_COST_WITHOUT_CAP`, `LOWEST_COST_WITH_BID_CAP`, `COST_CAP`, `LOWEST_COST_WITH_MIN_ROAS`.
    - Returns: Confirmation with new campaign details
 
+   - Example:
+     ```json
+     {
+       "name": "2025 - Bedroom Furniture - Awareness",
+       "account_id": "act_123456789012345",
+       "objective": "OUTCOME_AWARENESS",
+       "special_ad_categories": [],
+       "status": "PAUSED",
+       "buying_type": "AUCTION",
+       "bid_strategy": "LOWEST_COST_WITHOUT_CAP",
+       "daily_budget": 10000
+     }
+     ```
+
 7. `mcp_meta_ads_get_adsets`
    - Get ad sets for a Meta Ads account with optional filtering by campaign
    - Inputs:

{meta_ads_mcp-0.10.6 → meta_ads_mcp-0.10.9}/README.md

@@ -151,13 +151,43 @@ For local installation configuration, authentication options, and advanced techn
      - `access_token` (optional): Meta API access token (will use cached token if not provided)
      - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
      - `name`: Campaign name
-     - `objective`: Campaign objective (AWARENESS, TRAFFIC, ENGAGEMENT, etc.)
+     - `objective`: Campaign objective (ODAX, outcome-based). Must be one of:
+       - `OUTCOME_AWARENESS`
+       - `OUTCOME_TRAFFIC`
+       - `OUTCOME_ENGAGEMENT`
+       - `OUTCOME_LEADS`
+       - `OUTCOME_SALES`
+       - `OUTCOME_APP_PROMOTION`
+       
+       Note: Legacy objectives such as `BRAND_AWARENESS`, `LINK_CLICKS`, `CONVERSIONS`, `APP_INSTALLS`, etc. are no longer valid for new campaigns and will cause a 400 error. Use the outcome-based values above. Common mappings:
+       - `BRAND_AWARENESS` → `OUTCOME_AWARENESS`
+       - `REACH` → `OUTCOME_AWARENESS`
+       - `LINK_CLICKS`, `TRAFFIC` → `OUTCOME_TRAFFIC`
+       - `POST_ENGAGEMENT`, `PAGE_LIKES`, `EVENT_RESPONSES`, `VIDEO_VIEWS` → `OUTCOME_ENGAGEMENT`
+       - `LEAD_GENERATION` → `OUTCOME_LEADS`
+       - `CONVERSIONS`, `CATALOG_SALES`, `MESSAGES` (sales-focused flows) → `OUTCOME_SALES`
+       - `APP_INSTALLS` → `OUTCOME_APP_PROMOTION`
      - `status`: Initial campaign status (default: PAUSED)
      - `special_ad_categories`: List of special ad categories if applicable
      - `daily_budget`: Daily budget in account currency (in cents)
      - `lifetime_budget`: Lifetime budget in account currency (in cents)
+     - `bid_strategy`: Bid strategy. Must be one of: `LOWEST_COST_WITHOUT_CAP`, `LOWEST_COST_WITH_BID_CAP`, `COST_CAP`, `LOWEST_COST_WITH_MIN_ROAS`.
    - Returns: Confirmation with new campaign details
 
+   - Example:
+     ```json
+     {
+       "name": "2025 - Bedroom Furniture - Awareness",
+       "account_id": "act_123456789012345",
+       "objective": "OUTCOME_AWARENESS",
+       "special_ad_categories": [],
+       "status": "PAUSED",
+       "buying_type": "AUCTION",
+       "bid_strategy": "LOWEST_COST_WITHOUT_CAP",
+       "daily_budget": 10000
+     }
+     ```
+
 7. `mcp_meta_ads_get_adsets`
    - Get ad sets for a Meta Ads account with optional filtering by campaign
    - Inputs:

{meta_ads_mcp-0.10.6 → meta_ads_mcp-0.10.9}/meta_ads_mcp/__init__.py

@@ -1,13 +1,12 @@
 """
 Meta Ads MCP - Python Package
 
-This package provides a Meta Ads Marketing Cloud Platform (MCP) integration
-with the Claude LLM.
+This package provides a Meta Ads MCP integration
 """
 
 from meta_ads_mcp.core.server import main
 
-__version__ = "0.10.6"
+__version__ = "0.10.9"
 
 __all__ = [
     'get_ad_accounts',

{meta_ads_mcp-0.10.6 → meta_ads_mcp-0.10.9}/meta_ads_mcp/core/ads.py

@@ -671,7 +671,55 @@ async def upload_ad_image(
         print(f"Uploading image to Facebook Ad Account {account_id}")
         data = await make_api_request(endpoint, access_token, params, method="POST")
 
-        return json.dumps(data, indent=2)
+        # Normalize/structure the response for callers (e.g., to easily grab image_hash)
+        # Typical Graph API response shape:
+        # { "images": { "<hash>": { "hash": "<hash>", "url": "...", "width": ..., "height": ..., "name": "...", "status": 1 } } }
+        if isinstance(data, dict) and "images" in data and isinstance(data["images"], dict) and data["images"]:
+            images_dict = data["images"]
+            images_list = []
+            for hash_key, info in images_dict.items():
+                # Some responses may omit the nested hash, so ensure it's present
+                normalized = {
+                    "hash": (info.get("hash") or hash_key),
+                    "url": info.get("url"),
+                    "width": info.get("width"),
+                    "height": info.get("height"),
+                    "name": info.get("name"),
+                }
+                # Drop null/None values
+                normalized = {k: v for k, v in normalized.items() if v is not None}
+                images_list.append(normalized)
+
+            # Sort deterministically by hash
+            images_list.sort(key=lambda i: i.get("hash", ""))
+            primary_hash = images_list[0].get("hash") if images_list else None
+
+            result = {
+                "success": True,
+                "account_id": account_id,
+                "name": final_name,
+                "image_hash": primary_hash,
+                "images_count": len(images_list),
+                "images": images_list
+            }
+            return json.dumps(result, indent=2)
+
+        # If the API returned an error-like structure, surface it consistently
+        if isinstance(data, dict) and "error" in data:
+            return json.dumps({
+                "error": "Failed to upload image",
+                "details": data.get("error"),
+                "account_id": account_id,
+                "name": final_name
+            }, indent=2)
+
+        # Fallback: return a wrapped raw response to avoid breaking callers
+        return json.dumps({
+            "success": True,
+            "account_id": account_id,
+            "name": final_name,
+            "raw_response": data
+        }, indent=2)
 
     except Exception as e:
         return json.dumps({

{meta_ads_mcp-0.10.6 → meta_ads_mcp-0.10.9}/meta_ads_mcp/core/campaigns.py

@@ -109,13 +109,19 @@ async def create_campaign(
         access_token: Meta API access token (optional - will use cached token if not provided)
         account_id: Meta Ads account ID (format: act_XXXXXXXXX)
         name: Campaign name
-        objective: Campaign objective. Validates ad objectives. enum{BRAND_AWARENESS, LEAD_GENERATION, LINK_CLICKS, CONVERSIONS, OUTCOME_TRAFFIC, etc.}.
+        objective: Campaign objective (ODAX, outcome-based). Must be one of:
+                   OUTCOME_AWARENESS, OUTCOME_TRAFFIC, OUTCOME_ENGAGEMENT,
+                   OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_APP_PROMOTION.
+                   Note: Legacy objectives like BRAND_AWARENESS, LINK_CLICKS,
+                   CONVERSIONS, APP_INSTALLS, etc. are not valid for new
+                   campaigns and will cause a 400 error. Use the outcome-based
+                   values above (e.g., BRAND_AWARENESS → OUTCOME_AWARENESS).
         status: Initial campaign status (default: PAUSED)
         special_ad_categories: List of special ad categories if applicable
         daily_budget: Daily budget in account currency (in cents) as a string (only used if use_adset_level_budgets=False)
         lifetime_budget: Lifetime budget in account currency (in cents) as a string (only used if use_adset_level_budgets=False)
         buying_type: Buying type (e.g., 'AUCTION')
-        bid_strategy: Bid strategy (e.g., 'LOWEST_COST', 'LOWEST_COST_WITH_BID_CAP', 'COST_CAP')
+        bid_strategy: Bid strategy. Must be one of: 'LOWEST_COST_WITHOUT_CAP', 'LOWEST_COST_WITH_BID_CAP', 'COST_CAP', 'LOWEST_COST_WITH_MIN_ROAS'.
         bid_cap: Bid cap in account currency (in cents) as a string
         spend_cap: Spending limit for the campaign in account currency (in cents) as a string
         campaign_budget_optimization: Whether to enable campaign budget optimization (only used if use_adset_level_budgets=False)

{meta_ads_mcp-0.10.6 → meta_ads_mcp-0.10.9}/pyproject.toml

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

meta_ads_mcp-0.10.9/tests/test_upload_ad_image.py

@@ -0,0 +1,134 @@
+import json
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from meta_ads_mcp.core.ads import upload_ad_image
+
+
+@pytest.mark.asyncio
+async def test_upload_ad_image_normalizes_images_dict():
+    mock_response = {
+        "images": {
+            "abc123": {
+                "hash": "abc123",
+                "url": "https://example.com/image.jpg",
+                "width": 1200,
+                "height": 628,
+                "name": "image.jpg",
+                "status": 1,
+            }
+        }
+    }
+
+    with patch("meta_ads_mcp.core.ads.make_api_request", new_callable=AsyncMock) as mock_api:
+        mock_api.return_value = mock_response
+
+        # Use a data URL input to exercise that branch
+        file_data_url = "data:image/png;base64,QUJDREVGRw=="  # 'ABCDEFG' base64
+        result_json = await upload_ad_image(
+            access_token="test",
+            account_id="act_123",
+            file=file_data_url,
+            name="my-upload.png",
+        )
+
+        result = json.loads(result_json)
+
+        assert result.get("success") is True
+        assert result.get("account_id") == "act_123"
+        assert result.get("name") == "my-upload.png"
+        assert result.get("image_hash") == "abc123"
+        assert result.get("images_count") == 1
+        assert isinstance(result.get("images"), list) and result["images"][0]["hash"] == "abc123"
+
+
+@pytest.mark.asyncio
+async def test_upload_ad_image_error_structure_is_surfaced():
+    mock_response = {"error": {"message": "Something went wrong", "code": 400}}
+
+    with patch("meta_ads_mcp.core.ads.make_api_request", new_callable=AsyncMock) as mock_api:
+        mock_api.return_value = mock_response
+
+        result_json = await upload_ad_image(
+            access_token="test",
+            account_id="act_123",
+            file="data:image/png;base64,QUJD",
+        )
+
+        # Error responses from MCP functions may be wrapped multiple times under a data field
+        payload = result_json
+        for _ in range(5):
+            # If it's a JSON string, parse it
+            if isinstance(payload, str):
+                try:
+                    payload = json.loads(payload)
+                    continue
+                except Exception:
+                    break
+            # If it's a dict containing a JSON string in data, unwrap once
+            if isinstance(payload, dict) and "data" in payload:
+                payload = payload["data"]
+                continue
+            break
+        error_payload = payload if isinstance(payload, dict) else json.loads(payload)
+
+        assert "error" in error_payload
+        assert error_payload["error"] == "Failed to upload image"
+        assert isinstance(error_payload.get("details"), dict)
+        assert error_payload.get("account_id") == "act_123"
+
+
+@pytest.mark.asyncio
+async def test_upload_ad_image_fallback_wraps_raw_response():
+    mock_response = {"unexpected": "shape"}
+
+    with patch("meta_ads_mcp.core.ads.make_api_request", new_callable=AsyncMock) as mock_api:
+        mock_api.return_value = mock_response
+
+        result_json = await upload_ad_image(
+            access_token="test",
+            account_id="act_123",
+            file="data:image/png;base64,QUJD",
+        )
+
+        result = json.loads(result_json)
+        assert result.get("success") is True
+        assert result.get("raw_response") == mock_response
+
+
+@pytest.mark.asyncio
+async def test_upload_ad_image_from_url_infers_name_and_prefixes_account_id():
+    mock_response = {
+        "images": {
+            "hash999": {
+                "url": "https://example.com/img.jpg",
+                "width": 800,
+                "height": 600,
+                # omit nested hash intentionally to test normalization fallback
+            }
+        }
+    }
+
+    with patch("meta_ads_mcp.core.ads.try_multiple_download_methods", new_callable=AsyncMock) as mock_dl, \
+         patch("meta_ads_mcp.core.ads.make_api_request", new_callable=AsyncMock) as mock_api:
+        mock_dl.return_value = b"\xff\xd8\xff"  # minimal JPEG header bytes
+        mock_api.return_value = mock_response
+
+        # Provide raw account id (without act_) and ensure it is prefixed in the result
+        result_json = await upload_ad_image(
+            access_token="test",
+            account_id="701351919139047",
+            image_url="https://cdn.example.com/path/photo.jpg?x=1",
+        )
+
+        result = json.loads(result_json)
+        assert result.get("success") is True
+        assert result.get("account_id") == "act_701351919139047"
+        # Name should be inferred from URL
+        assert result.get("name") == "photo.jpg"
+        # Primary hash should be derived from key when nested hash missing
+        assert result.get("image_hash") == "hash999"
+        assert result.get("images_count") == 1
+
+