chore: merge upstream/main (PM-Labs changes preserved)

Author: mdrokon-dev

README.md

@@ -1,6 +1,8 @@
 # Meta Ads MCP
 
-A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for interacting with Meta Ads. Analyze, manage and optimize Meta advertising campaigns through an AI interface. Use an LLM to retrieve performance data, visualize ad creatives, and provide strategic insights for your ads on Facebook, Instagram, and other Meta platforms.
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that lets AI assistants run your Meta Ads end to end — launch campaigns, upload creatives, update budgets, and dig into performance through natural conversation. Works across Facebook, Instagram, and other Meta surfaces.
+
+Part of the [Pipeboard](https://pipeboard.co) family of ad connectors — sibling remote MCP servers cover **Google Ads**, **TikTok Ads**, **Snap Ads**, and **Reddit Ads** with the same setup (see [Also Available](#also-available-google-ads-tiktok-ads-snap-ads-and-reddit-ads) below).
 
 > **Note:** This is an independent open-source project that uses Meta's public APIs. If you're looking for an officially approved Meta app, check out [Pipeboard](https://pipeboard.co). Meta, Facebook, Instagram, and other Meta brand names are trademarks of their respective owners.
 
@@ -30,14 +32,14 @@ mcp-name: co.pipeboard/meta-ads-mcp
 
 ## 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)**. 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!
+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 your Meta Ads account. No technical setup required — just connect and start launching, updating, and analyzing campaigns with AI!
 
 ### For Claude Pro/Max Users
 
 1. Go to [claude.ai/settings/integrations](https://claude.ai/settings/integrations) (requires Claude Pro or Max)
 2. Click "Add Integration" and enter:
    - **Name**: "Pipeboard Meta Ads" (or any name you prefer)
-   - **Integration URL**: `https://mcp.pipeboard.co/meta-ads-mcp`
+   - **Integration URL**: `https://meta-ads.mcp.pipeboard.co/`
 3. Click "Connect" next to the integration and follow the prompts to:
    - Login to Pipeboard
    - Connect your Facebook Ads account
@@ -49,7 +51,7 @@ That's it! You can now ask Claude to analyze your Meta ad campaigns, get perform
 For direct token-based authentication without the interactive flow, use this URL format when adding the integration:
 
 ```
-https://mcp.pipeboard.co/meta-ads-mcp?token=YOUR_PIPEBOARD_TOKEN
+https://meta-ads.mcp.pipeboard.co/?token=YOUR_PIPEBOARD_TOKEN
 ```
 
 Get your token at [pipeboard.co/api-tokens](https://pipeboard.co/api-tokens).
@@ -63,7 +65,7 @@ Add the following to your `~/.cursor/mcp.json`. Once you enable the remote MCP,
 {
   "mcpServers": {
     "meta-ads-remote": {
-      "url": "https://mcp.pipeboard.co/meta-ads-mcp"
+      "url": "https://meta-ads.mcp.pipeboard.co/"
     }
   }
 }
@@ -77,7 +79,7 @@ If you prefer to authenticate without the interactive login flow, you can includ
 {
   "mcpServers": {
     "meta-ads-remote": {
-      "url": "https://mcp.pipeboard.co/meta-ads-mcp?token=YOUR_PIPEBOARD_TOKEN"
+      "url": "https://meta-ads.mcp.pipeboard.co/?token=YOUR_PIPEBOARD_TOKEN"
     }
   }
 }
@@ -87,7 +89,7 @@ Get your token at [pipeboard.co/api-tokens](https://pipeboard.co/api-tokens).
 
 ### For Other MCP Clients
 
-Use the Remote MCP URL: `https://mcp.pipeboard.co/meta-ads-mcp`
+Use the Remote MCP URL: `https://meta-ads.mcp.pipeboard.co/`
 
 **[📖 Get detailed setup instructions for your AI client here](https://pipeboard.co)**
 
@@ -96,22 +98,24 @@ Use the Remote MCP URL: `https://mcp.pipeboard.co/meta-ads-mcp`
 For MCP clients that support token-based authentication, you can append your Pipeboard API token to the URL:
 
 ```
-https://mcp.pipeboard.co/meta-ads-mcp?token=YOUR_PIPEBOARD_TOKEN
+https://meta-ads.mcp.pipeboard.co/?token=YOUR_PIPEBOARD_TOKEN
 ```
 
 This bypasses the interactive login flow and authenticates immediately. Get your token at [pipeboard.co/api-tokens](https://pipeboard.co/api-tokens).
 
-### Also Available: Google Ads and TikTok Ads
+### Also Available: Google Ads, TikTok Ads, Snap Ads, and Reddit Ads
 
-Pipeboard also offers remote MCP servers for **Google Ads** and **TikTok Ads**, set up the same way:
+Pipeboard offers remote MCP servers for every major ad platform — all set up the same way and all built for the full launch/manage/analyze loop:
 
 | Platform | Remote MCP URL |
 |---|---|
-| Meta Ads | `https://mcp.pipeboard.co/meta-ads-mcp` |
-| Google Ads | `https://mcp.pipeboard.co/google-ads-mcp` |
-| TikTok Ads | `https://mcp.pipeboard.co/tiktok-ads-mcp` |
+| Meta Ads | `https://meta-ads.mcp.pipeboard.co/` |
+| Google Ads | `https://google-ads.mcp.pipeboard.co/` |
+| TikTok Ads | `https://tiktok-ads.mcp.pipeboard.co/` |
+| Snap Ads | `https://snap-ads.mcp.pipeboard.co/` |
+| Reddit Ads | `https://reddit-ads.mcp.pipeboard.co/` |
 
-Connect your ad accounts at [pipeboard.co](https://pipeboard.co) and use any of them with Claude, Cursor, or any MCP client.
+Connect your ad accounts at [pipeboard.co](https://pipeboard.co) and use any of them with Claude, Cursor, or any MCP-compatible assistant.
 
 ## Pipeboard CLI (Alternative to MCP)
 
@@ -147,14 +151,15 @@ Meta Ads MCP also supports a local streamable HTTP transport, allowing you to ru
 
 ## Features
 
-- **AI-Powered Campaign Analysis**: Let your favorite LLM analyze your campaigns and provide actionable insights on performance
+- **Campaign Management**: Launch campaigns, ad sets, and ads, update budgets, pause and resume, and apply targeting changes — all from a conversation, with explicit confirmation on every write
+- **Creative Operations**: Upload images, build creatives, and update copy, headlines, descriptions, and CTAs without leaving your AI client
+- **Dynamic Creative Testing**: One API for both simple ads (single headline/description) and full A/B testing (multiple headlines/descriptions)
+- **AI-Powered Campaign Analysis**: Let your favorite LLM analyze performance and surface actionable insights
 - **Strategic Recommendations**: Receive data-backed suggestions for optimizing ad spend, targeting, and creative content
-- **Automated Monitoring**: Ask any MCP-compatible LLM to track performance metrics and alert you about significant changes
 - **Budget Optimization**: Get recommendations for reallocating budget to better-performing ad sets
 - **Creative Improvement**: Receive feedback on ad copy, imagery, and calls-to-action
-- **Dynamic Creative Testing**: Easy API for both simple ads (single headline/description) and advanced A/B testing (multiple headlines/descriptions)
-- **Campaign Management**: Request changes to campaigns, ad sets, and ads (all changes require explicit confirmation)
-- **Cross-Platform Integration**: Works with Facebook, Instagram, and all Meta ad platforms
+- **Automated Monitoring**: Ask any MCP-compatible LLM to track performance metrics and alert you about significant changes
+- **Cross-Platform Integration**: Works with Facebook, Instagram, and all Meta ad surfaces
 - **Universal LLM Support**: Compatible with any MCP client including Claude Desktop, Cursor, Cherry Studio, and more
 - **Enhanced Search**: Generic search function includes page searching when queries mention "page" or "pages"
 - **Simple Authentication**: Easy setup with secure OAuth authentication

SECURITY.md

@@ -0,0 +1,46 @@
+# Security
+
+## Reporting a vulnerability
+
+Please report security issues privately via GitHub: open a draft advisory
+from the [Security tab](https://github.com/pipeboard-co/meta-ads-mcp/security/advisories/new)
+("Report a vulnerability"). Do not file public issues for unpatched
+vulnerabilities.
+
+## Advisories
+
+### GHSA-9gw6-46qc-99vr — Unauthenticated HTTP MCP tool execution leaks operator Meta access token
+
+- **Severity:** Critical (CVSS 3.1 9.1 — `AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:N`)
+- **Affected versions:** `<= 1.0.108` when run with `--transport streamable-http`
+  and a `META_ACCESS_TOKEN` environment variable.
+- **Fixed in:** `1.0.109`
+- **Affected configurations:** Self-hosted deployments that expose the
+  streamable-HTTP port on a reachable network interface. The hosted MCP at
+  `*.mcp.pipeboard.co` was not affected — it sits behind an authenticating
+  proxy and the Python process is bound to localhost.
+
+**What went wrong.** `AuthInjectionMiddleware.dispatch()` logged a warning when
+a request arrived with no `Authorization: Bearer` / `X-PIPEBOARD-API-TOKEN`
+header and then forwarded the request to the tool handler anyway. Tool handlers
+fall back to `META_ACCESS_TOKEN` when no per-request token is set, so any
+network-reachable caller could invoke any MCP tool as the operator. When the
+downstream Graph API call returned a 4xx, `make_api_request()` serialized
+`e.request.url` — including `access_token` as a query parameter — verbatim into
+the JSON-RPC error payload, exposing the long-lived operator credential.
+
+**Fix.**
+1. `AuthInjectionMiddleware` now returns `401 Unauthorized` with
+   `WWW-Authenticate: Bearer` when neither token header is present.
+2. `make_api_request()` redacts `access_token` and `appsecret_proof` from any
+   URLs returned in error payloads (`_redact_url` helper).
+
+**Action for operators.**
+- Upgrade to `1.0.109` or later.
+- HTTP clients must send `Authorization: Bearer <meta-access-token>` (or the
+  legacy `X-PIPEBOARD-API-TOKEN` header) on every request. The
+  `META_ACCESS_TOKEN` env var is no longer used as an implicit fallback for
+  HTTP transport.
+- If you exposed an earlier version to an untrusted network, rotate the Meta
+  access token (`https://developers.facebook.com/tools/debug/accesstoken/`)
+  and review Graph API access logs for unexpected calls.

meta_ads_mcp/__init__.py

@@ -6,7 +6,7 @@
 
 from meta_ads_mcp.core.server import main
 
-__version__ = "1.0.104"
+__version__ = "1.0.110"
 
 __all__ = [
     'get_ad_accounts',

meta_ads_mcp/core/ads.py

@@ -717,12 +717,15 @@ async def get_ad_creatives(ad_id: str, access_token: Optional[str] = None) -> st
 @meta_api_tool
 async def get_ad_image(ad_id: str, access_token: Optional[str] = None) -> Image:
     """
-    Get, download, and visualize a Meta ad image in one step. Useful to see the image in the LLM.
-    
+    Get, download, and visualize the image attached to an existing Meta ad.
+
+    Takes a Meta ad ID and returns the image the ad is currently serving.
+    If all you have is an image hash (no ad), use get_image_by_hash instead.
+
     Args:
         ad_id: Meta Ads ad ID
         access_token: Meta API access token (optional - will use cached token if not provided)
-    
+
     Returns:
         The ad image ready for direct visual analysis
     """
@@ -859,58 +862,89 @@ async def get_ad_image(ad_id: str, access_token: Optional[str] = None) -> Image:
                 return f"Error processing image from direct URL: {str(e)}"
 
     print(f"Found image hashes: {image_hashes}")
-    
-    # Now fetch image data using adimages endpoint with specific format
+
+    return await _fetch_image_by_hash(account_id, image_hashes[0], access_token)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def get_image_by_hash(
+    account_id: str,
+    image_hash: str,
+    access_token: Optional[str] = None,
+) -> Image:
+    """
+    Get, download, and visualize a Meta ad image by its hash.
+
+    Use this when you have an image_hash without an ad — e.g. the hash
+    returned by upload_ad_image / bulk_upload_ad_images, or one referenced
+    in a creative (object_story_spec.link_data.image_hash, asset_feed_spec
+    images[].hash, etc.). To view the image of an existing ad, prefer
+    get_ad_image(ad_id).
+
+    Args:
+        account_id: Meta Ads account ID (act_XXXXXXXXX or bare numeric — both accepted)
+        image_hash: Meta image hash
+        access_token: Meta API access token (optional - will use cached token if not provided)
+
+    Returns:
+        The image ready for direct visual analysis
+    """
+    if not account_id:
+        return "Error: No account ID provided"
+    if not image_hash:
+        return "Error: No image hash provided"
+    normalized_account = ensure_act_prefix(account_id).removeprefix("act_")
+    return await _fetch_image_by_hash(normalized_account, image_hash, access_token)
+
+
+async def _fetch_image_by_hash(
+    account_id: str,
+    image_hash: str,
+    access_token: Optional[str],
+) -> Union[Image, str]:
+    """Fetch a single image from act_{account_id}/adimages by hash and return it as a PIL Image.
+
+    account_id is the bare numeric part (without the "act_" prefix). Returns
+    an "Error: ..." string on failure so the @meta_api_tool wrapper can
+    serialize it.
+    """
     image_endpoint = f"act_{account_id}/adimages"
-    
-    # Format the hashes parameter exactly as in our successful curl test
-    hashes_str = f'["{image_hashes[0]}"]'  # Format first hash only, as JSON string array
-    
+    hashes_str = f'["{image_hash}"]'
     image_params = {
         "fields": "hash,url,width,height,name,status",
-        "hashes": hashes_str
+        "hashes": hashes_str,
     }
-    
+
     print(f"Requesting image data with params: {image_params}")
     image_data = await make_api_request(image_endpoint, access_token, image_params)
-    
+
     if "error" in image_data:
         return f"Error: Failed to get image data - {json.dumps(image_data)}"
-    
+
     if "data" not in image_data or not image_data["data"]:
-        return "Error: No image data returned from API"
-    
-    # Get the first image URL
-    first_image = image_data["data"][0]
-    image_url = first_image.get("url")
-    
+        return (
+            f"Error: No image found for hash {image_hash} in account "
+            f"act_{account_id}. Confirm the hash and that the account matches "
+            "the one used to upload (image hashes are scoped per ad account)."
+        )
+
+    image_url = image_data["data"][0].get("url")
     if not image_url:
         return "Error: No valid image URL found"
-    
+
     print(f"Downloading image from URL: {image_url}")
-    
-    # Download the image
     image_bytes = await download_image(image_url)
-    
     if not image_bytes:
         return "Error: Failed to download image"
-    
+
     try:
-        # Convert bytes to PIL Image
         img = PILImage.open(io.BytesIO(image_bytes))
-        
-        # Convert to RGB if needed
         if img.mode != "RGB":
             img = img.convert("RGB")
-            
-        # Create a byte stream of the image data
         byte_arr = io.BytesIO()
         img.save(byte_arr, format="JPEG")
-        img_bytes = byte_arr.getvalue()
-        
-        # Return as an Image object that LLM can directly analyze
-        return Image(data=img_bytes, format="jpeg")
-        
+        return Image(data=byte_arr.getvalue(), format="jpeg")
     except Exception as e:
         return f"Error processing image: {str(e)}"
 
@@ -1250,16 +1284,21 @@ async def upload_ad_image(
 ) -> str:
     """
     Upload an image to use in Meta Ads creatives.
-    
+
     Args:
         account_id: Meta Ads account ID (format: act_XXXXXXXXX)
         access_token: Meta API access token (optional - will use cached token if not provided)
         file: Data URL or raw base64 string of the image (e.g., "data:image/png;base64,iVBORw0KG...")
         image_url: Direct URL to an image to fetch and upload
         name: Optional name for the image (default: filename)
-    
+
     Returns:
-        JSON response with image details including hash for creative creation
+        JSON object with:
+          - image_hash: Pass this to create_ad_creative when building the ad,
+            or to get_image_by_hash to view the image later.
+          - images: List of {hash, url, width, height, name}. The url is a
+            Meta CDN link you can fetch directly to view the image — no need
+            to call any other tool right after upload.
     """
     # Check required parameters
     if not account_id:
@@ -1832,13 +1871,19 @@ async def create_ad_creative(
     """
     Create a new ad creative using an uploaded image hash, video ID, or an existing post.
 
-    Supports five creative modes:
+    Supports six creative modes:
     - **Existing post**: Provide object_story_id (format: {page_id}_{post_id}) to promote an existing
       organic or published post. No image_hash or video_id required. Optionally combine with
       asset_customization_rules to attach a 9:16 video for Story/Reels placements.
     - **Simple image/video**: Single image_hash or video_id with object_story_spec
     - **Multi-variant copy**: Use plural text params (messages[], headlines[], descriptions[]) to test
       multiple text variants with a single image/video. No optimization_type or is_dynamic_creative needed.
+    - **Placement Asset Customization (dual-aspect, non-DC)**: Serve different aspect ratios per placement
+      on a STANDARD ad set without is_dynamic_creative and without the one-ad-per-ad-set cap. Set
+      optimization_type="PLACEMENT" and pass videos=[{video_id, label}, ...] (or images=[{image_hash,
+      label}, ...]) together with asset_customization_rules whose customization_spec references those
+      labels via video_label/image_label. Every label in the rules MUST appear on a videos[]/images[]
+      entry, or Meta returns error_subcode=1487390 ("Adcreative Create Failed").
     - **Dynamic Creative**: Multiple variants with dynamic_creative_spec (requires is_dynamic_creative on ad set)
     - **FLEX/DOF (Advantage+)**: Set optimization_type="DEGREES_OF_FREEDOM" for Meta to auto-optimize
       across all asset combinations without requiring is_dynamic_creative on the ad set