PropellerAds MCP Server

Instructions

Implementation Reference

• src/propellerads_mcp/server.py:642-674 (handler)

  The `get_zone_performance` tool handler, which retrieves zone statistics from the client, calculates performance metrics, and formats the output as a Markdown table.

  elif name == "get_zone_performance":
      zones = client.get_zone_statistics(
          campaign_id=args.get("campaign_id"),
          date_from=args.get("date_from"),
          date_to=args.get("date_to"),
          limit=args.get("limit", 100),
      )
  
      if not zones:
          return "No zone statistics found."
  
      enriched = [calculate_metrics(z) for z in zones]
  
      # Sort if requested
      sort_by = args.get("sort_by", "spend")
      enriched.sort(key=lambda x: x.get(sort_by, 0), reverse=True)
  
      lines = ["# Zone Performance\n\n"]
      lines.append("| Zone ID | Impressions | Clicks | CTR | Conv | Spend | ROI |\n")
      lines.append("|---------|-------------|--------|-----|------|-------|-----|\n")
  
      for z in enriched[:args.get("limit", 100)]:
          lines.append(
              f"| {z.get('zone_id', 'N/A')} | "
              f"{z.get('impressions', 0):,} | "
              f"{z.get('clicks', 0):,} | "
              f"{format_percentage(z.get('ctr'))} | "
              f"{z.get('conversions', 0)} | "
              f"{format_currency(z.get('spend', z.get('cost', 0)))} | "
              f"{format_percentage(z.get('roi'))} |\n"
          )
  
      return "".join(lines)

• src/propellerads_mcp/server.py:284-306 (schema)

  The `Tool` registration for `get_zone_performance`, defining the tool name, description, and input schema.

      name="get_zone_performance",
      description="Get performance statistics grouped by zone/placement. Useful for whitelist/blacklist optimization.",
      inputSchema={
          "type": "object",
          "properties": {
              "campaign_id": {
                  "type": "integer",
                  "description": "Filter by campaign ID",
              },
              "date_from": {"type": "string", "description": "Start date (YYYY-MM-DD)"},
              "date_to": {"type": "string", "description": "End date (YYYY-MM-DD)"},
              "limit": {
                  "type": "integer",
                  "description": "Max number of zones to return (default: 100)",
              },
              "sort_by": {
                  "type": "string",
                  "description": "Sort by: spend, conversions, roi, ctr",
                  "enum": ["spend", "conversions", "roi", "ctr"],
              },
          },
      },
  ),