modus_get_sales_breakdown

Instructions

Implementation Reference

• modus-mcp-server.js:157-191 (registration)

  Tool registration with name, description, and input/output schema definition

  {
    name: "modus_get_sales_breakdown",
    description:
      "Get comprehensive sales breakdown with hiring/capacity analysis including targets, capacity, attrition impact, and quarterly waterfall metrics. Returns month-by-month capacity projections with revenue gaps and hiring needs. The period type is auto-detected: use quarter for quarterly analysis, year for annual, or startDate/endDate for custom ranges.",
    inputSchema: {
      type: "object",
      properties: {
        period: {
          type: "string",
          description: "Period type (optional - auto-detected): YTD, QUARTER, YEAR, CUSTOM_RANGE, LAST_12_MONTHS, NEXT_12_MONTHS",
          enum: ["YTD", "QUARTER", "YEAR", "CUSTOM_RANGE", "LAST_12_MONTHS", "NEXT_12_MONTHS"],
        },
        year: {
          type: "number",
          description: "Year to analyze (e.g., 2025). Required for QUARTER, YEAR, or YTD periods.",
        },
        quarter: {
          type: "number",
          description: "Quarter number (1-4). When specified, automatically uses QUARTER period.",
        },
        startDate: {
          type: "string",
          description: "Start date (YYYY-MM-DD). When specified with endDate, automatically uses CUSTOM_RANGE period.",
        },
        endDate: {
          type: "string",
          description: "End date (YYYY-MM-DD). When specified with startDate, automatically uses CUSTOM_RANGE period.",
        },
        scenarioId: {
          type: "number",
          description: "Optional scenario ID to analyze",
        },
      },
    },
  },

• modus-mcp-server.js:162-191 (schema)

  Input schema defining parameters: period type, year, quarter, startDate, endDate, scenarioId

      type: "object",
      properties: {
        period: {
          type: "string",
          description: "Period type (optional - auto-detected): YTD, QUARTER, YEAR, CUSTOM_RANGE, LAST_12_MONTHS, NEXT_12_MONTHS",
          enum: ["YTD", "QUARTER", "YEAR", "CUSTOM_RANGE", "LAST_12_MONTHS", "NEXT_12_MONTHS"],
        },
        year: {
          type: "number",
          description: "Year to analyze (e.g., 2025). Required for QUARTER, YEAR, or YTD periods.",
        },
        quarter: {
          type: "number",
          description: "Quarter number (1-4). When specified, automatically uses QUARTER period.",
        },
        startDate: {
          type: "string",
          description: "Start date (YYYY-MM-DD). When specified with endDate, automatically uses CUSTOM_RANGE period.",
        },
        endDate: {
          type: "string",
          description: "End date (YYYY-MM-DD). When specified with startDate, automatically uses CUSTOM_RANGE period.",
        },
        scenarioId: {
          type: "number",
          description: "Optional scenario ID to analyze",
        },
      },
    },
  },

• modus-mcp-server.js:680-726 (handler)

  Handler function that executes 'modus_get_sales_breakdown': parses args, auto-detects period type, calls API, computes summary, returns response

  case "modus_get_sales_breakdown": {
    const { period, year, quarter, startDate, endDate, scenarioId } = args || {};
    const params = new URLSearchParams();
  
    // Auto-detect period type based on provided parameters if not explicitly set
    let finalPeriod = period;
    if (!finalPeriod) {
      if (startDate && endDate) {
        finalPeriod = "CUSTOM_RANGE";
      } else if (quarter) {
        finalPeriod = "QUARTER";
      } else if (year) {
        finalPeriod = "YEAR";
      } else {
        finalPeriod = "YTD";
      }
    }
  
    params.append("period", finalPeriod);
    if (year) params.append("year", year.toString());
    if (quarter) params.append("quarter", quarter.toString());
    if (startDate) params.append("startDate", startDate);
    if (endDate) params.append("endDate", endDate);
    if (scenarioId) params.append("scenarioId", scenarioId.toString());
  
    response = await modusApi.get(`/api/sales/sales-breakdown?${params.toString()}`);
    const data = response.data;
  
    // Add summary statistics
    const summary = {
      totalRevenueGap: calculateTotalGap(data.quarterlyCapacityDetails),
      totalHeadcount: (data.totalHeadcount?.current || 0) + (data.totalHeadcount?.tbh || 0),
      currentHeadcount: data.totalHeadcount?.current || 0,
      plannedHires: data.totalHeadcount?.tbh || 0,
      averageAttritionImpact: calculateAvgAttrition(data),
      quartersAtRisk: countQuartersAtRisk(data.quarterlyCapacityDetails),
    };
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({ summary, data }, null, 2),
        },
      ],
    };
  }

• modus-mcp-server.js:1143-1146 (helper)

  Helper function calculateTotalGap: sums gap values from quarterlyCapacityDetails

  function calculateTotalGap(quarterlyDetails) {
    if (!quarterlyDetails || !Array.isArray(quarterlyDetails)) return 0;
    return quarterlyDetails.reduce((sum, q) => sum + (q.gap || 0), 0);
  }

• modus-mcp-server.js:1148-1154 (helper)

  Helper function calculateAvgAttrition: averages non-zero attrition impacts across quarters

  function calculateAvgAttrition(data) {
    if (!data.quarterlyCapacityDetails || !Array.isArray(data.quarterlyCapacityDetails)) return 0;
    const impacts = data.quarterlyCapacityDetails
      .map((q) => q.attritionImpact || 0)
      .filter((impact) => impact > 0);
    return impacts.length > 0 ? impacts.reduce((sum, i) => sum + i, 0) / impacts.length : 0;
  }