Revenue Server

Overview

The Revenue Server specializes in revenue attribution and conversion analysis. It helps you track and analyze how marketing efforts contribute to revenue generation through various milestones like MQL, SQL, and Conversions.

Server Details

• Server Name: revenue-server
• Version: 0.0.1
• Endpoint: /mcp/revenue
• Authentication: Organization-level required

Purpose

Analyze revenue attribution, milestone conversions, and marketing influence on revenue generation. This server is ideal for understanding which marketing activities drive the most valuable outcomes.

Available Tools

1. milestones-tool

Purpose: Retrieve configured milestones for your organization

When to use:

• At the start of any revenue analysis conversation
• To validate milestone names before querying
• To identify which milestones are configured as MQL, SQL, or Conversion

Returns: A table of available milestones with their flags (MQL, SQL, Conversion)

Example Response:

| Milestone | MQL | SQL | Conversion |
|-----------|-----|-----|------------|
| Signup    | ✓   |     |            |
| Demo Request |  | ✓   |            |
| Paid Conversion | | | ✓          |

2. terminology-tool

Purpose: Translate abbreviations and business terms

When to use:

• User mentions abbreviations (MQL, SQL, PTC, etc.)
• Need to understand attribution model types
• Clarify business metrics terminology

Returns: Comprehensive guide of terminologies and their meanings

3. system-report-schema-tool

Purpose: Get field mappings for the SystemReport index

When to use:

• Before constructing any query
• To discover available fields and their types
• To validate field names

Returns: Elasticsearch mapping with field names, types, and descriptions

4. system-report-compute-tool

Purpose: Execute Elasticsearch queries against the SystemReport index

Input: Elasticsearch query JSON Returns: Query results with matching documents and aggregations

Example Query:

{
  "query": {
    "bool": {
      "filter": [
        {"exists": {"field": "Signup"}},
        {"range": {"First Touch Date": {"gte": "now-30d/d"}}}
      ]
    }
  },
  "size": 100
}

5. chart-format-tool

Purpose: Generate Chart.js configurations for data visualization

Supported chart types: line, pie, doughnut, bar, horizontalBar

Example Usage:

{
  "type": "line",
  "title": "Revenue Trend",
  "height": 400,
  "unit": "day"
}

Key Concepts

Milestones

Milestones represent key conversion points in your customer journey:

• MQL (Marketing Qualified Lead): A lead qualified by marketing
• SQL (Sales Qualified Lead): A lead qualified by sales
• Conversion: Final conversion event (purchase, signup, etc.)

Milestone to Query Field Mapping

When filtering by milestones, use the milestone's exact name as the field name in queries.

Example:

• If MQL milestone is "Signup" → Use {"exists": {"field": "Signup"}}
• If SQL milestone is "Demo Request" → Use {"exists": {"field": "Demo Request"}}
• If Conversion milestone is "Paid Conversion" → Use {"exists": {"field": "Paid Conversion"}}

Date Filtering

IMPORTANT: Always apply date filters to queries for accurate and performant results.

Example date filters:

{
  "range": {
    "First Touch Date": {
      "gte": "now-30d/d",
      "lte": "now/d"
    }
  }
}

Common Use Cases

1. MQL Count for Last 30 Days

Workflow:

1. Call milestones-tool to find MQL milestone name (e.g., "Signup")
2. Call system-report-compute-tool with query:

{
  "query": {
    "bool": {
      "filter": [
        {"exists": {"field": "Signup"}},
        {"range": {"Signup": {"gte": "now-30d/d"}}}
      ]
    }
  },
  "size": 0,
  "aggs": {
    "total_mqls": {
      "value_count": {"field": "Signup"}
    }
  }
}

2. Conversion Rate by Channel

Workflow:

1. Call milestones-tool to identify MQL and Conversion milestones
2. Call system-report-compute-tool:

{
  "query": {
    "range": {"First Touch Date": {"gte": "now-90d/d"}}
  },
  "size": 0,
  "aggs": {
    "by_channel": {
      "terms": {"field": "First Touch Channel.keyword", "size": 20},
      "aggs": {
        "mqls": {
          "filter": {"exists": {"field": "Signup"}}
        },
        "conversions": {
          "filter": {"exists": {"field": "Paid Conversion"}}
        }
      }
    }
  }
}

3. Revenue Trend Over Time

{
  "query": {
    "range": {"Paid Conversion": {"gte": "now-90d/d"}}
  },
  "size": 0,
  "aggs": {
    "revenue_by_day": {
      "date_histogram": {
        "field": "Paid Conversion",
        "calendar_interval": "day"
      },
      "aggs": {
        "total_revenue": {
          "sum": {"field": "Revenue"}
        }
      }
    }
  }
}

4. Top Performing Campaigns

{
  "query": {
    "bool": {
      "filter": [
        {"exists": {"field": "Paid Conversion"}},
        {"range": {"Paid Conversion": {"gte": "now-30d/d"}}}
      ]
    }
  },
  "size": 0,
  "aggs": {
    "by_campaign": {
      "terms": {
        "field": "First Touch UTM Campaign.keyword",
        "size": 10,
        "order": {"total_revenue": "desc"}
      },
      "aggs": {
        "total_revenue": {
          "sum": {"field": "Revenue"}
        },
        "conversion_count": {
          "value_count": {"field": "Paid Conversion"}
        }
      }
    }
  }
}

Best Practices

1. Always Call milestones-tool First

Before any revenue analysis, call the milestones tool to get the correct milestone names and their configurations.

2. Use Exact Milestone Names

When filtering by milestones, use the exact name (including casing and spacing) from the milestones tool.

3. Apply Date Filters

Always include date range filters to improve query performance and ensure relevant results.

4. Text Search with Wildcards

Use wildcard matching for text searches unless exact match is explicitly requested:

{"wildcard": {"First Touch UTM Campaign": "*brand*"}}

5. Handle Missing Milestones

If a user asks about MQL/SQL/Conversion and no milestone is configured with that flag, inform them to configure it at: https://platform.sonalabs.com/setup/profile/milestones

Query Tips

Filtering by Multiple Conditions

{
  "query": {
    "bool": {
      "filter": [
        {"exists": {"field": "Signup"}},
        {"term": {"First Touch Channel.keyword": "Paid Search"}},
        {"range": {"Signup": {"gte": "now-30d/d"}}}
      ]
    }
  }
}

Excluding Null Values

{
  "query": {
    "bool": {
      "must": [
        {"exists": {"field": "Revenue"}},
        {"range": {"Revenue": {"gt": 0}}}
      ]
    }
  }
}

Calculating Conversion Rates

Use bucket_script in aggregations:

{
  "aggs": {
    "by_source": {
      "terms": {"field": "First Touch Utm Source.keyword"},
      "aggs": {
        "mqls": {"filter": {"exists": {"field": "Signup"}}},
        "conversions": {"filter": {"exists": {"field": "Paid Conversion"}}},
        "conversion_rate": {
          "bucket_script": {
            "buckets_path": {
              "mqls": "mqls>_count",
              "conversions": "conversions>_count"
            },
            "script": "params.mqls > 0 ? (params.conversions / params.mqls) * 100 : 0"
          }
        }
      }
    }
  }
}