get_revenue

Instructions

Implementation Reference

• mcp-server.js:851-938 (registration)

  Registration of the 'get_revenue' MCP tool using server.tool(), including description, Zod input schema, and the complete inline async handler function that implements the revenue calculation logic.

  server.tool(
    "get_revenue",
    "Get the total revenue for a given date range",
    {
      date_range: z.string().describe("Date range expression (e.g., 'today', 'yesterday', 'last week', 'this month', 'YTD', or a specific date range like '2023-01-01 to 2023-01-31')"),
      status: z.string().optional().describe("Filter by order status (e.g., 'processing', 'complete', 'pending')"),
      include_tax: z.boolean().optional().describe("Whether to include tax in the revenue calculation (default: true)")
    },
    async ({ date_range, status, include_tax = true }) => {
      try {
        // Parse the date range expression
        const dateRange = parseDateExpression(date_range);
        
        // Build the search criteria for the date range
        let searchCriteria = buildDateRangeFilter('created_at', dateRange.startDate, dateRange.endDate);
        
        // Add status filter if provided
        if (status) {
          searchCriteria += `&searchCriteria[filter_groups][2][filters][0][field]=status&` +
                            `searchCriteria[filter_groups][2][filters][0][value]=${encodeURIComponent(status)}&` +
                            `searchCriteria[filter_groups][2][filters][0][condition_type]=eq`;
        }
        
        // Fetch all orders using the helper function
        const allOrders = await fetchAllPages('/orders', searchCriteria);
        
        // Calculate total revenue
        let totalRevenue = 0;
        let totalTax = 0;
        let orderCount = 0;
        
        if (allOrders && Array.isArray(allOrders)) {
          orderCount = allOrders.length;
          
          allOrders.forEach(order => {
            // Use grand_total which includes tax, shipping, etc.
            totalRevenue += parseFloat(order.grand_total || 0);
            
            // Track tax separately
            totalTax += parseFloat(order.tax_amount || 0);
          });
        }
        
        // Adjust revenue if tax should be excluded
        const revenueWithoutTax = totalRevenue - totalTax;
        const finalRevenue = include_tax ? totalRevenue : revenueWithoutTax;
        
        // Format the response
        const result = {
          query: {
            date_range: dateRange.description,
            status: status || 'All',
            include_tax: include_tax,
            period: {
              start_date: format(dateRange.startDate, 'yyyy-MM-dd'),
              end_date: format(dateRange.endDate, 'yyyy-MM-dd')
            }
          },
          result: {
            revenue: parseFloat(finalRevenue.toFixed(2)),
            currency: 'USD', // This should be dynamically determined from the store configuration
            order_count: orderCount,
            average_order_value: orderCount > 0 ? parseFloat((finalRevenue / orderCount).toFixed(2)) : 0,
            tax_amount: parseFloat(totalTax.toFixed(2))
          }
        };
        
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(result, null, 2)
            }
          ]
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error fetching revenue: ${error.message}`
            }
          ],
          isError: true
        };
      }
    }
  );

• mcp-server.js:859-937 (handler)

  The core handler function for the get_revenue tool. Parses date range, applies filters, fetches all orders via Magento API, computes total revenue (with optional tax exclusion), order count, average order value, and returns structured JSON response.

  async ({ date_range, status, include_tax = true }) => {
    try {
      // Parse the date range expression
      const dateRange = parseDateExpression(date_range);
      
      // Build the search criteria for the date range
      let searchCriteria = buildDateRangeFilter('created_at', dateRange.startDate, dateRange.endDate);
      
      // Add status filter if provided
      if (status) {
        searchCriteria += `&searchCriteria[filter_groups][2][filters][0][field]=status&` +
                          `searchCriteria[filter_groups][2][filters][0][value]=${encodeURIComponent(status)}&` +
                          `searchCriteria[filter_groups][2][filters][0][condition_type]=eq`;
      }
      
      // Fetch all orders using the helper function
      const allOrders = await fetchAllPages('/orders', searchCriteria);
      
      // Calculate total revenue
      let totalRevenue = 0;
      let totalTax = 0;
      let orderCount = 0;
      
      if (allOrders && Array.isArray(allOrders)) {
        orderCount = allOrders.length;
        
        allOrders.forEach(order => {
          // Use grand_total which includes tax, shipping, etc.
          totalRevenue += parseFloat(order.grand_total || 0);
          
          // Track tax separately
          totalTax += parseFloat(order.tax_amount || 0);
        });
      }
      
      // Adjust revenue if tax should be excluded
      const revenueWithoutTax = totalRevenue - totalTax;
      const finalRevenue = include_tax ? totalRevenue : revenueWithoutTax;
      
      // Format the response
      const result = {
        query: {
          date_range: dateRange.description,
          status: status || 'All',
          include_tax: include_tax,
          period: {
            start_date: format(dateRange.startDate, 'yyyy-MM-dd'),
            end_date: format(dateRange.endDate, 'yyyy-MM-dd')
          }
        },
        result: {
          revenue: parseFloat(finalRevenue.toFixed(2)),
          currency: 'USD', // This should be dynamically determined from the store configuration
          order_count: orderCount,
          average_order_value: orderCount > 0 ? parseFloat((finalRevenue / orderCount).toFixed(2)) : 0,
          tax_amount: parseFloat(totalTax.toFixed(2))
        }
      };
      
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2)
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error fetching revenue: ${error.message}`
          }
        ],
        isError: true
      };
    }
  }

• mcp-server.js:854-858 (schema)

  Zod schema defining input parameters for the get_revenue tool: required date_range string, optional status and include_tax.

  {
    date_range: z.string().describe("Date range expression (e.g., 'today', 'yesterday', 'last week', 'this month', 'YTD', or a specific date range like '2023-01-01 to 2023-01-31')"),
    status: z.string().optional().describe("Filter by order status (e.g., 'processing', 'complete', 'pending')"),
    include_tax: z.boolean().optional().describe("Whether to include tax in the revenue calculation (default: true)")
  },

• mcp-server.js:23-124 (helper)

  Helper function to parse natural language date range expressions into startDate, endDate (Date objects) and a human-readable description, used by get_revenue and similar tools.

  function parseDateExpression(dateExpression) {
    const now = new Date();
    const currentYear = now.getFullYear();
    const currentMonth = now.getMonth();
    const currentDay = now.getDate();
    
    // Normalize the date expression
    const normalizedExpression = dateExpression.toLowerCase().trim();
    
    // Handle relative date expressions
    switch (normalizedExpression) {
      case 'today':
        return {
          startDate: startOfDay(now),
          endDate: endOfDay(now),
          description: 'Today'
        };
      case 'yesterday':
        const yesterday = subDays(now, 1);
        return {
          startDate: startOfDay(yesterday),
          endDate: endOfDay(yesterday),
          description: 'Yesterday'
        };
      case 'this week':
        return {
          startDate: startOfWeek(now, { weekStartsOn: 1 }), // Week starts on Monday
          endDate: endOfDay(now),
          description: 'This week'
        };
      case 'last week':
        const lastWeekStart = subDays(startOfWeek(now, { weekStartsOn: 1 }), 7);
        const lastWeekEnd = subDays(endOfWeek(now, { weekStartsOn: 1 }), 7);
        return {
          startDate: lastWeekStart,
          endDate: lastWeekEnd,
          description: 'Last week'
        };
      case 'this month':
        return {
          startDate: startOfMonth(now),
          endDate: endOfDay(now),
          description: 'This month'
        };
      case 'last month':
        const lastMonth = new Date(currentYear, currentMonth - 1, 1);
        return {
          startDate: startOfMonth(lastMonth),
          endDate: endOfMonth(lastMonth),
          description: 'Last month'
        };
      case 'ytd':
      case 'this ytd':
      case 'this year to date':
      case 'year to date':
        return {
          startDate: startOfYear(now),
          endDate: endOfDay(now),
          description: 'Year to date'
        };
      case 'last year':
        const lastYear = new Date(currentYear - 1, 0, 1);
        return {
          startDate: startOfYear(lastYear),
          endDate: endOfYear(lastYear),
          description: 'Last year'
        };
      default:
        // Try to parse as ISO date or other common formats
        try {
          // Check if it's a single date (not a range)
          const parsedDate = parseISO(normalizedExpression);
          if (isValid(parsedDate)) {
            return {
              startDate: startOfDay(parsedDate),
              endDate: endOfDay(parsedDate),
              description: format(parsedDate, 'yyyy-MM-dd')
            };
          }
          
          // Check if it's a date range in format "YYYY-MM-DD to YYYY-MM-DD"
          const rangeParts = normalizedExpression.split(' to ');
          if (rangeParts.length === 2) {
            const startDate = parseISO(rangeParts[0]);
            const endDate = parseISO(rangeParts[1]);
            
            if (isValid(startDate) && isValid(endDate)) {
              return {
                startDate: startOfDay(startDate),
                endDate: endOfDay(endDate),
                description: `${format(startDate, 'yyyy-MM-dd')} to ${format(endDate, 'yyyy-MM-dd')}`
              };
            }
          }
          
          // If we can't parse it, throw an error
          throw new Error(`Unable to parse date expression: ${dateExpression}`);
        } catch (error) {
          throw new Error(`Invalid date expression: ${dateExpression}. ${error.message}`);
        }
    }
  }

• mcp-server.js:259-300 (helper)

  Helper to fetch and concatenate all paginated results from a Magento API endpoint, handling dynamic pagination based on total_count.

  async function fetchAllPages(endpoint, baseSearchCriteria) {
    const pageSize = 100; // Or make this configurable if needed
    let currentPage = 1;
    let allItems = [];
    let totalCount = 0;
    
    do {
      // Build search criteria for the current page, ensuring baseSearchCriteria doesn't already have pagination
      let currentPageSearchCriteria = baseSearchCriteria;
      if (!currentPageSearchCriteria.includes('searchCriteria[pageSize]')) {
        currentPageSearchCriteria += `&searchCriteria[pageSize]=${pageSize}`;
      }
      if (!currentPageSearchCriteria.includes('searchCriteria[currentPage]')) {
        currentPageSearchCriteria += `&searchCriteria[currentPage]=${currentPage}`;
      } else {
        // If currentPage is already there, replace it (less common case)
        currentPageSearchCriteria = currentPageSearchCriteria.replace(/searchCriteria\[currentPage\]=\d+/, `searchCriteria[currentPage]=${currentPage}`);
      }
  
      // Make the API call for the current page
      const responseData = await callMagentoApi(`${endpoint}?${currentPageSearchCriteria}`);
      
      if (responseData.items && Array.isArray(responseData.items)) {
        allItems = allItems.concat(responseData.items);
      }
      
      // Update total count (only needs to be set once)
      if (currentPage === 1) {
        totalCount = responseData.total_count || 0;
      }
      
      // Check if we need to fetch more pages
      if (totalCount <= allItems.length || !responseData.items || responseData.items.length < pageSize) {
        break; // Exit loop if all items are fetched or last page had less than pageSize items
      }
      
      currentPage++;
      
    } while (true); // Loop continues until break
    
    return allItems; // Return the aggregated list of items
  }

• mcp-server.js:137-149 (helper)

  Helper to construct Magento API searchCriteria query string for filtering records by date range on a given field.

  function buildDateRangeFilter(field, startDate, endDate) {
    const formattedStartDate = formatDateForMagento(startDate);
    const formattedEndDate = formatDateForMagento(endDate);
    
    return [
      `searchCriteria[filter_groups][0][filters][0][field]=${field}`,
      `searchCriteria[filter_groups][0][filters][0][value]=${encodeURIComponent(formattedStartDate)}`,
      `searchCriteria[filter_groups][0][filters][0][condition_type]=gteq`,
      `searchCriteria[filter_groups][1][filters][0][field]=${field}`,
      `searchCriteria[filter_groups][1][filters][0][value]=${encodeURIComponent(formattedEndDate)}`,
      `searchCriteria[filter_groups][1][filters][0][condition_type]=lteq`
    ].join('&');
  }