PropellerAds MCP Server

Instructions

Implementation Reference

• src/propellerads_mcp/server.py:606-645 (handler)

  The handler logic for 'compare_periods' which fetches statistics for two periods and generates a Markdown comparison table.

  elif name == "compare_periods":
      stats1 = client.get_statistics(
          date_from=args["period1_from"],
          date_to=args["period1_to"],
          campaign_id=args.get("campaign_id"),
      )
      stats2 = client.get_statistics(
          date_from=args["period2_from"],
          date_to=args["period2_to"],
          campaign_id=args.get("campaign_id"),
      )
  
      m1 = calculate_metrics(stats1[0] if stats1 else {})
      m2 = calculate_metrics(stats2[0] if stats2 else {})
  
      def change(v1: float, v2: float) -> str:
          if v1 == 0:
              return "N/A"
          pct = ((v2 - v1) / v1) * 100
          arrow = "📈" if pct > 0 else "📉" if pct < 0 else "➡️"
          return f"{arrow} {pct:+.1f}%"
  
      return (
          f"# Period Comparison\n\n"
          f"**Period 1:** {args['period1_from']} to {args['period1_to']}\n"
          f"**Period 2:** {args['period2_from']} to {args['period2_to']}\n\n"
          f"| Metric | Period 1 | Period 2 | Change |\n"
          f"|--------|----------|----------|--------|\n"
          f"| Impressions | {m1.get('impressions', 0):,} | {m2.get('impressions', 0):,} | {change(m1.get('impressions', 0), m2.get('impressions', 0))} |\n"
          f"| Clicks | {m1.get('clicks', 0):,} | {m2.get('clicks', 0):,} | {change(m1.get('clicks', 0), m2.get('clicks', 0))} |\n"
          f"| CTR | {format_percentage(m1.get('ctr'))} | {format_percentage(m2.get('ctr'))} | {change(m1.get('ctr', 0), m2.get('ctr', 0))} |\n"
          f"| Conversions | {m1.get('conversions', 0):,} | {m2.get('conversions', 0):,} | {change(m1.get('conversions', 0), m2.get('conversions', 0))} |\n"
          f"| Spend | {format_currency(m1.get('spend', 0))} | {format_currency(m2.get('spend', 0))} | {change(m1.get('spend', 0), m2.get('spend', 0))} |\n"
          f"| ROI | {format_percentage(m1.get('roi'))} | {format_percentage(m2.get('roi'))} | {change(m1.get('roi', 0), m2.get('roi', 0))} |\n"
      )
  
  elif name == "get_zone_performance":
      zones = client.get_zone_statistics(
          campaign_id=args.get("campaign_id"),
          date_from=args.get("date_from"),

• src/propellerads_mcp/server.py:253-276 (registration)

  Registration of the 'compare_periods' tool with its schema definition in the server tool list.

  Tool(
      name="compare_periods",
      description="Compare performance between two time periods.",
      inputSchema={
          "type": "object",
          "properties": {
              "period1_from": {
                  "type": "string",
                  "description": "Period 1 start date (YYYY-MM-DD)",
              },
              "period1_to": {
                  "type": "string",
                  "description": "Period 1 end date (YYYY-MM-DD)",
              },
              "period2_from": {
                  "type": "string",
                  "description": "Period 2 start date (YYYY-MM-DD)",
              },
              "period2_to": {
                  "type": "string",
                  "description": "Period 2 end date (YYYY-MM-DD)",
              },
              "campaign_id": {
                  "type": "integer",