advanced_product_search

Instructions

Implementation Reference

• mcp-server.js:740-773 (handler)

  The handler function for 'advanced_product_search' tool. It constructs search criteria for the Magento products API based on the provided field, value, condition, pagination, and sorting parameters, fetches the data, formats the results, and returns them in MCP format. Handles errors appropriately.

  async ({ field, value, condition_type = 'eq', page_size = 10, current_page = 1, sort_field = 'entity_id', sort_direction = 'DESC' }) => {
    try {
      // Build search criteria
      const searchCriteria = `searchCriteria[filter_groups][0][filters][0][field]=${encodeURIComponent(field)}&` +
                            `searchCriteria[filter_groups][0][filters][0][value]=${encodeURIComponent(value)}&` +
                            `searchCriteria[filter_groups][0][filters][0][condition_type]=${encodeURIComponent(condition_type)}&` +
                            `searchCriteria[pageSize]=${page_size}&` +
                            `searchCriteria[currentPage]=${current_page}&` +
                            `searchCriteria[sortOrders][0][field]=${encodeURIComponent(sort_field)}&` +
                            `searchCriteria[sortOrders][0][direction]=${encodeURIComponent(sort_direction)}`;
      
      const productData = await callMagentoApi(`/products?${searchCriteria}`);
      const formattedResults = formatSearchResults(productData);
      
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(formattedResults, null, 2)
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error performing advanced search: ${error.message}`
          }
        ],
        isError: true
      };
    }
  }

• mcp-server.js:731-739 (schema)

  Zod schema defining the input parameters for the advanced_product_search tool, including field, value, condition_type, pagination, and sorting options.

  {
    field: z.string().describe("Field to search on (e.g., name, sku, price, status)"),
    value: z.string().describe("Value to search for"),
    condition_type: z.string().optional().describe("Condition type (eq, like, gt, lt, etc.). Default: eq"),
    page_size: z.number().optional().describe("Number of results per page (default: 10)"),
    current_page: z.number().optional().describe("Page number (default: 1)"),
    sort_field: z.string().optional().describe("Field to sort by (default: entity_id)"),
    sort_direction: z.string().optional().describe("Sort direction (ASC or DESC, default: DESC)")
  },

• mcp-server.js:728-774 (registration)

  The registration of the 'advanced_product_search' tool using server.tool(), including name, description, input schema, and handler function.

  server.tool(
    "advanced_product_search",
    "Search for products with advanced filtering options",
    {
      field: z.string().describe("Field to search on (e.g., name, sku, price, status)"),
      value: z.string().describe("Value to search for"),
      condition_type: z.string().optional().describe("Condition type (eq, like, gt, lt, etc.). Default: eq"),
      page_size: z.number().optional().describe("Number of results per page (default: 10)"),
      current_page: z.number().optional().describe("Page number (default: 1)"),
      sort_field: z.string().optional().describe("Field to sort by (default: entity_id)"),
      sort_direction: z.string().optional().describe("Sort direction (ASC or DESC, default: DESC)")
    },
    async ({ field, value, condition_type = 'eq', page_size = 10, current_page = 1, sort_field = 'entity_id', sort_direction = 'DESC' }) => {
      try {
        // Build search criteria
        const searchCriteria = `searchCriteria[filter_groups][0][filters][0][field]=${encodeURIComponent(field)}&` +
                              `searchCriteria[filter_groups][0][filters][0][value]=${encodeURIComponent(value)}&` +
                              `searchCriteria[filter_groups][0][filters][0][condition_type]=${encodeURIComponent(condition_type)}&` +
                              `searchCriteria[pageSize]=${page_size}&` +
                              `searchCriteria[currentPage]=${current_page}&` +
                              `searchCriteria[sortOrders][0][field]=${encodeURIComponent(sort_field)}&` +
                              `searchCriteria[sortOrders][0][direction]=${encodeURIComponent(sort_direction)}`;
        
        const productData = await callMagentoApi(`/products?${searchCriteria}`);
        const formattedResults = formatSearchResults(productData);
        
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(formattedResults, null, 2)
            }
          ]
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error performing advanced search: ${error.message}`
            }
          ],
          isError: true
        };
      }
    }
  );

• mcp-server.js:363-380 (helper)

  Helper function used by the handler to format the raw Magento API search results into a structured, readable output with key product fields.

  // Format search results for better readability
  function formatSearchResults(results) {
    if (!results || !results.items || !Array.isArray(results.items)) {
      return "No products found";
    }
    
    return {
      total_count: results.total_count,
      items: results.items.map(item => ({
        id: item.id,
        sku: item.sku,
        name: item.name,
        price: item.price,
        status: item.status,
        type_id: item.type_id
      }))
    };
  }