fix(insights): keep leads/CPL on platform_position breakdown (#141)

* fix(insights): keep action data on platform_position breakdown (bump 1.0.117)

get_insights with breakdown=platform_position was dropping the action-typed fields (actions, action_values, conversions, cost_per_action_type), so placement-level reports lost leads, CPL, and conversions while spend/clicks/impressions came through.

Root cause: the Meta (#100) "(action_type, platform_position) is invalid" error is caused solely by platform_position not being paired with publisher_platform. The tool already auto-adds publisher_platform; once paired, Meta returns the action-typed fields per placement (verified live against the Graph API with action_breakdowns default, [], and [action_type]). Stripping the fields was an unnecessary over-correction.

Removes the field-stripping path and its constants; adds regression tests.

* chore: sync server.json version to 1.0.117

Author: nictuku

meta_ads_mcp/__init__.py

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

meta_ads_mcp/core/insights.py

@@ -28,14 +28,6 @@
 )
 
 
-# Breakdowns Meta rejects when combined with the default action_breakdowns
-# (which is [action_type]). Picking any of these auto-drops the action-typed
-# fields below so the request still succeeds. Meta error path is
-# "(#100) Current combination of data breakdown columns (action_type, X) is invalid".
-_BREAKDOWNS_INCOMPATIBLE_WITH_ACTION_TYPE = frozenset({
-    "platform_position",
-})
-
 # Breakdowns that collide with the default action_breakdowns=[action_type] but
 # are real Meta fields (so we explicitly clear action_breakdowns instead of
 # dropping the action-typed response fields). For non-DCO ads this returns
@@ -44,13 +36,6 @@
     "media_type",
 })
 
-_ACTION_TYPED_FIELDS = frozenset({
-    "actions",
-    "action_values",
-    "cost_per_action_type",
-    "conversions",
-})
-
 
 def _strip_redundant_actions(row: dict) -> dict:
     """Remove redundant action-type entries from a single insight row."""
@@ -97,10 +82,10 @@ async def get_insights(object_id: str = "", access_token: Optional[str] = None,
                    Demographic: age, gender, country, region, dma
                    Platform/Device: device_platform, platform_position, publisher_platform, impression_device
                    NOTE: platform_position is a Meta-restricted breakdown — Meta requires it to be paired
-                   with publisher_platform and is incompatible with the default action_breakdowns=[action_type].
-                   When you pass platform_position, this tool auto-adds publisher_platform and drops the
-                   action-typed fields (actions, action_values, conversions, cost_per_action_type) from the
-                   response. Use publisher_platform alone if you need action data alongside placement.
+                   with publisher_platform (otherwise "(#100) ... (action_type, platform_position) is invalid").
+                   When you pass platform_position, this tool auto-adds publisher_platform, and the
+                   action-typed fields (actions, action_values, conversions, cost_per_action_type) are
+                   returned per placement, so you get leads/CPL/conversions broken down by placement.
                    Creative Assets: ad_format_asset, body_asset, call_to_action_asset, description_asset,
                                   image_asset, link_url_asset, title_asset, video_asset, media_type,
                                   creative_relaxation_asset_type, flexible_format_asset_type,
@@ -168,17 +153,17 @@ async def get_insights(object_id: str = "", access_token: Optional[str] = None,
         "unique_clicks", "cost_per_action_type",
     ]
 
-    # Meta rejects platform_position alone or with the default
-    # action_breakdowns=[action_type]: it must be paired with publisher_platform,
-    # and the action-typed fields must be dropped. Auto-fix both so the request
-    # succeeds with placement-level metrics.
+    # Meta rejects platform_position on its own: it must be paired with
+    # publisher_platform, otherwise "(#100) Current combination of data breakdown
+    # columns (action_type, platform_position) is invalid". Auto-add
+    # publisher_platform so the request succeeds with placement-level metrics —
+    # including the action-typed fields (actions, cost_per_action_type, etc.),
+    # which Meta returns per placement once the pairing is in place.
     breakdown_values = [b.strip() for b in breakdown.split(",") if b.strip()] if breakdown else []
     breakdown_set = set(breakdown_values)
     if "platform_position" in breakdown_set and "publisher_platform" not in breakdown_set:
         breakdown_values = ["publisher_platform", *breakdown_values]
         breakdown_set.add("publisher_platform")
-    if breakdown_set & _BREAKDOWNS_INCOMPATIBLE_WITH_ACTION_TYPE:
-        fields = [f for f in fields if f not in _ACTION_TYPED_FIELDS]
     # media_type collides with action_breakdowns=[action_type] but is a real
     # field — override action_breakdowns to empty so the request succeeds with
     # the action-typed metrics intact.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "meta-ads-mcp"
-version = "1.0.116"
+version = "1.0.117"
 description = "Model Context Protocol (MCP) server for Meta Ads - Use Remote MCP at pipeboard.co for easiest setup"
 readme = "README.md"
 requires-python = ">=3.10"

server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "co.pipeboard/meta-ads-mcp",
   "description": "Facebook / Meta Ads automation with AI: analyze performance, test creatives, optimize spend.",
-  "version": "1.0.116",
+  "version": "1.0.117",
   "remotes": [
     {
       "type": "streamable-http",

tests/test_insights_platform_position_breakdown.py

@@ -0,0 +1,82 @@
+"""Regression tests for get_insights breakdown=platform_position.
+
+platform_position is a Meta-restricted breakdown: it must be paired with
+publisher_platform or Meta returns "(#100) Current combination of data
+breakdown columns (action_type, platform_position) is invalid". Once paired,
+Meta DOES return the action-typed fields (actions, cost_per_action_type,
+conversions) per placement.
+
+A previous version of get_insights worked around the (#100) error by dropping
+the action-typed fields entirely, which made leads/CPL/conversions disappear
+from placement-level reports. These tests pin the corrected behavior: auto-pair
+publisher_platform AND keep the action-typed fields.
+"""
+
+import json
+import pytest
+from unittest.mock import AsyncMock, patch
+from meta_ads_mcp.core.insights import get_insights
+
+
+@pytest.fixture
+def mock_auth_manager():
+    with patch('meta_ads_mcp.core.api.auth_manager') as mock, \
+         patch('meta_ads_mcp.core.auth.get_current_access_token') as mock_get_token:
+        mock.get_current_access_token.return_value = "test_access_token"
+        mock.is_token_valid.return_value = True
+        mock.app_id = "test_app_id"
+        mock_get_token.return_value = "test_access_token"
+        yield mock
+
+
+async def _call_and_get_params(breakdown, **kwargs):
+    """Invoke get_insights with a mocked API and return the params dict sent to Meta."""
+    with patch('meta_ads_mcp.core.insights.make_api_request', new_callable=AsyncMock) as mock_api:
+        mock_api.return_value = {"data": []}
+        await get_insights(
+            object_id="act_701351919139047",
+            level="account",
+            time_range="last_30d",
+            breakdown=breakdown,
+            **kwargs,
+        )
+        mock_api.assert_called_once()
+        return mock_api.call_args[0][2]
+
+
+class TestPlatformPositionBreakdown:
+    @pytest.mark.asyncio
+    async def test_platform_position_keeps_action_typed_fields(self, mock_auth_manager):
+        """The core regression: action-typed fields must NOT be stripped."""
+        params = await _call_and_get_params("platform_position")
+        fields = params["fields"].split(",")
+        for f in ("actions", "action_values", "conversions", "cost_per_action_type"):
+            assert f in fields, f"{f} was stripped from fields for platform_position"
+
+    @pytest.mark.asyncio
+    async def test_platform_position_auto_pairs_publisher_platform(self, mock_auth_manager):
+        """publisher_platform is auto-prepended so Meta does not reject the request."""
+        params = await _call_and_get_params("platform_position")
+        breakdowns = params["breakdowns"].split(",")
+        assert "publisher_platform" in breakdowns
+        assert "platform_position" in breakdowns
+
+    @pytest.mark.asyncio
+    async def test_platform_position_does_not_force_action_breakdowns(self, mock_auth_manager):
+        """No explicit action_breakdowns is sent — Meta's default action_type slicing
+        applies, which returns actions per placement (verified live against Meta)."""
+        params = await _call_and_get_params("platform_position")
+        assert "action_breakdowns" not in params
+
+    @pytest.mark.asyncio
+    async def test_caller_action_breakdowns_still_wins(self, mock_auth_manager):
+        """An explicit action_breakdowns from the caller is still respected."""
+        params = await _call_and_get_params("platform_position", action_breakdowns=[])
+        assert params["action_breakdowns"] == "[]"
+
+    @pytest.mark.asyncio
+    async def test_already_paired_breakdown_is_not_duplicated(self, mock_auth_manager):
+        """Passing publisher_platform,platform_position does not duplicate publisher_platform."""
+        params = await _call_and_get_params("publisher_platform,platform_position")
+        breakdowns = params["breakdowns"].split(",")
+        assert breakdowns.count("publisher_platform") == 1