search_products

Instructions

Implementation Reference

• src/tools/searchProducts.ts:7-49 (schema)

  Defines the tool schema for 'search_products' including name, description, and inputSchema for MCP tool listing.

  export const searchProductsTool = {
    name: 'search_products',
    description: `Search for products by name or description across all Argentina supermarkets.
  
  This tool searches multiple supermarkets simultaneously and returns price comparisons.
  It's perfect for finding the best deals and comparing prices across different stores.
  
  The search is smart and handles:
  - Spanish characters and accents (café, leche, etc.)
  - Partial matches
  - Common product names
  - Brand names
  
  Results include:
  - Product images
  - Prices
  - Direct links to products
  - Supermarket information
  - Availability across stores`,
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Product name or description to search for (e.g., "leche descremada", "arroz integral", "coca cola")',
        },
        maxResults: {
          type: 'number',
          description: 'Maximum number of results per supermarket (1-50, default: 9)',
          minimum: 1,
          maximum: 50,
          default: 9,
        },
        sortBy: {
          type: 'string',
          description: 'How to sort the results',
          enum: ['OrderByTopSaleDESC', 'OrderByPriceASC', 'OrderByPriceDESC'],
          default: 'OrderByTopSaleDESC',
        },
      },
      required: ['query'],
    },
  };

• src/tools/searchProducts.ts:51-112 (handler)

  Executes the search_products tool: validates args, calls SuperPrecioApiClient.searchProducts, formats results, and returns MCP content.

  export async function executeSearchProducts(
    client: SuperPrecioApiClient,
    args: {
      query: string;
      maxResults?: number;
      sortBy?: 'OrderByTopSaleDESC' | 'OrderByPriceASC' | 'OrderByPriceDESC';
    }
  ) {
    if (!args) {
      throw new Error('Missing required arguments');
    }
  
    if (!args.query) {
      throw new Error('Missing required parameter: query');
    }
  
    if (!client) {
      throw new Error('API client is not initialized');
    }
  
    const { query, maxResults = 9, sortBy = 'OrderByTopSaleDESC' } = args;
  
    const response = await client.searchProducts({
      search: query,
      maxResults,
      order: sortBy,
    });
  
    // Format response for better readability
    const results = {
      summary: {
        query: response.searched.search,
        totalSupermarkets: response.columns,
        totalProducts: response.allData.reduce((sum, market) => sum + market.length, 0),
      },
      supermarkets: response.markets.map((market) => ({
        name: market.name,
        logo: market.logo,
      })),
      products: response.allData.map((marketProducts, idx) => ({
        supermarket: response.markets[idx] ? response.markets[idx].name : 'Unknown',
        logo: response.markets[idx] ? response.markets[idx].logo : '',
        products: marketProducts.map((product) => ({
          name: product.desc,
          price: product.price,
          image: product.img,
          link: product.link,
          code: product.code,
          barcode: product.barcode,
        })),
      })),
    };
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(results, null, 2),
        },
      ],
    };
  }

• src/index.ts:89-116 (registration)

  Registers the searchProductsTool (line 93) in the MCP server's listTools handler, making it discoverable.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        // V1 Tools
        searchProductsTool,
        searchByCodeTool,
        comparePriceTool,
        getBestDealsTool,
        sendNotificationTool,
        subscribeDeviceTool,
  
        // V2 Tools - Shopping Lists
        createShoppingListTool,
        addItemsToListTool,
        getShoppingListsTool,
        optimizeShoppingListTool,
        removeShoppingListTool,
  
        // V2 Tools - Price Alerts
        setPriceAlertTool,
        getMyAlertsTool,
        removePriceAlertTool,
  
        // V2 Tools - Location
        findNearbySupermarketsTool,
      ],
    };
  });

• src/index.ts:125-126 (registration)

  Dispatches execution of search_products tool in the MCP server's CallToolRequestSchema handler.

  case 'search_products':
    return await executeSearchProducts(apiClient, args as any);