Superprecio MCP Server

Instructions

Implementation Reference

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

  The executeSearchProducts function is the main handler that executes the tool logic: validates input, calls the SuperPrecio API's searchProducts method, formats the results with supermarket and product details, and returns structured 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/tools/searchProducts.ts:7-49 (schema)

  The searchProductsTool object defines the tool's metadata including name, detailed description, and inputSchema for parameter validation (query required, optional maxResults and sortBy).
  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/index.ts:89-116 (registration)

  The searchProductsTool is registered in the MCP server's ListToolsRequestSchema handler, making it discoverable by clients.
  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)

  Dispatch logic in the MCP server's CallToolRequestSchema handler routes 'search_products' calls to the executeSearchProducts function.
  case 'search_products': return await executeSearchProducts(apiClient, args as any);