Magento 2 MCP Server

Instructions

Implementation Reference

• mcp-server.js:941-1004 (handler)

  Full tool registration including handler function. The handler parses the date range, constructs Magento API search criteria for orders filtered by date and optional status, calls the API with pagination set to get total_count without fetching all orders, formats the result with query details and order count, and returns it as text content.

  server.tool(
    "get_order_count",
    "Get the number of orders 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')")
    },
    async ({ date_range, status }) => {
      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`;
        }
        
        // Add pagination to get all results
        searchCriteria += `&searchCriteria[pageSize]=1&searchCriteria[currentPage]=1`;
        
        // Make the API call to get orders
        const ordersData = await callMagentoApi(`/orders?${searchCriteria}`);
        
        // Format the response
        const result = {
          query: {
            date_range: dateRange.description,
            status: status || 'All',
            period: {
              start_date: format(dateRange.startDate, 'yyyy-MM-dd'),
              end_date: format(dateRange.endDate, 'yyyy-MM-dd')
            }
          },
          result: {
            order_count: ordersData.total_count || 0
          }
        };
        
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(result, null, 2)
            }
          ]
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error fetching order count: ${error.message}`
            }
          ],
          isError: true
        };
      }
    }
  );

• mcp-server.js:944-947 (schema)

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

  {
    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')")
  },

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

  Helper function used by get_order_count to parse flexible date range expressions into startDate, endDate, and description.

  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:137-149 (helper)

  Helper function used to construct the date range filter parameters for the Magento orders API search criteria.

  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('&');
  }

• mcp-server.js:941-942 (registration)

  Tool registration call for get_order_count using McpServer.tool method.

  server.tool(
    "get_order_count",