PropellerAds MCP Server

Instructions

Implementation Reference

• src/propellerads_mcp/server.py:787-821 (handler)

  The handler logic for 'find_scaling_opportunities' retrieves active campaigns, fetches statistics, calculates ROI/conversions, and filters campaigns based on the provided criteria.

  elif name == "find_scaling_opportunities":
      campaigns = client.list_campaigns(status="active")
      if not campaigns:
          return "No active campaigns found."
  
      min_roi = args.get("min_roi", 50)
      min_conv = args.get("min_conversions", 10)
  
      opportunities = []
      for c in campaigns:
          stats = client.get_campaign_statistics(
              c["id"],
              date_from=args.get("date_from"),
              date_to=args.get("date_to"),
          )
          if stats:
              metrics = calculate_metrics(stats)
              conv = metrics.get("conversions", 0) or 0
              roi = metrics.get("roi", 0) or 0
              if conv >= min_conv and roi >= min_roi:
                  opportunities.append({**c, **metrics})
  
      if not opportunities:
          return f"No scaling opportunities found (min ROI: {min_roi}%, min conversions: {min_conv})."
  
      opportunities.sort(key=lambda x: x.get("roi", 0), reverse=True)
  
      lines = ["# Scaling Opportunities\n\n"]
      lines.append(f"Criteria: ROI >= {min_roi}%, Conversions >= {min_conv}\n\n")
  
      for c in opportunities:
          lines.append(
              f"### {c.get('name')} (ID: {c.get('id')})\n"
              f"- ROI: {format_percentage(c.get('roi'))}\n"
              f"- Conversions: {c.get('conversions', 0)}\n"

• src/propellerads_mcp/server.py:366-384 (schema)

  The Tool definition and schema for 'find_scaling_opportunities' specifying input parameters (min_roi, min_conversions, date_from, date_to).

  Tool(
      name="find_scaling_opportunities",
      description="Find campaigns ready for scaling based on ROI and conversion volume.",
      inputSchema={
          "type": "object",
          "properties": {
              "min_roi": {
                  "type": "number",
                  "description": "Minimum ROI percentage (default: 50)",
              },
              "min_conversions": {
                  "type": "integer",
                  "description": "Minimum conversions (default: 10)",
              },
              "date_from": {"type": "string", "description": "Start date"},
              "date_to": {"type": "string", "description": "End date"},
          },
      },
  ),