PropellerAds MCP Server

Instructions

Implementation Reference

• src/propellerads_mcp/server.py:748-785 (handler)

  The logic for the 'find_top_zones' tool handler, which fetches zone statistics, calculates metrics, filters by conversion and ROI thresholds, and formats the output.

  elif name == "find_top_zones":
      zones = client.get_zone_statistics(
          campaign_id=args["campaign_id"],
          date_from=args.get("date_from"),
          date_to=args.get("date_to"),
      )
  
      min_conv = args.get("min_conversions", 1)
      min_roi = args.get("min_roi", 0)
      limit = args.get("limit", 20)
  
      enriched = [calculate_metrics(z) for z in zones]
      top_zones = [
          z for z in enriched
          if (z.get("conversions", 0) or 0) >= min_conv and (z.get("roi", 0) or 0) >= min_roi
      ]
      top_zones.sort(key=lambda x: x.get("roi", 0), reverse=True)
  
      if not top_zones:
          return f"No zones found matching criteria (min conversions: {min_conv}, min ROI: {min_roi}%)."
  
      lines = [f"# Top Performing Zones (Campaign {args['campaign_id']})\n\n"]
      lines.append("| Zone ID | Conversions | Spend | Revenue | ROI |\n")
      lines.append("|---------|-------------|-------|---------|-----|\n")
  
      for z in top_zones[:limit]:
          lines.append(
              f"| {z.get('zone_id')} | "
              f"{z.get('conversions', 0)} | "
              f"{format_currency(z.get('spend', z.get('cost', 0)))} | "
              f"{format_currency(z.get('revenue', 0))} | "
              f"{format_percentage(z.get('roi'))} |\n"
          )
  
      zone_ids = [z.get("zone_id") for z in top_zones[:limit] if z.get("zone_id")]
      lines.append(f"\nZone IDs for whitelist: `{zone_ids}`")
  
      return "".join(lines)

• src/propellerads_mcp/server.py:344-362 (registration)

  The definition and registration of the 'find_top_zones' tool, including its input schema.

  Tool(
      name="find_top_zones",
      description="Find best performing zones. Useful for whitelist candidates.",
      inputSchema={
          "type": "object",
          "properties": {
              "campaign_id": {"type": "integer", "description": "Campaign ID"},
              "min_conversions": {
                  "type": "integer",
                  "description": "Minimum conversions (default: 1)",
              },
              "min_roi": {
                  "type": "number",
                  "description": "Minimum ROI percentage (default: 0)",
              },
              "limit": {"type": "integer", "description": "Max results (default: 20)"},
              "date_from": {"type": "string", "description": "Start date"},
              "date_to": {"type": "string", "description": "End date"},
          },