Superprecio MCP Server

Instructions

Implementation Reference

• src/tools/getBestDeals.ts:37-124 (handler)

  The main handler function that executes the get_best_deals tool. It searches for products in the given category, calculates discounts, sorts by discount, formats a summary, and returns structured content.
  export async function executeGetBestDeals( client: SuperPrecioApiClient, args: { category: string; maxResults?: number } ) { if (!args) { throw new Error('Missing required arguments'); } const { category, maxResults = 10 } = args; // Search with TopSale sorting to get best deals const response = await client.searchProducts({ search: category, maxResults, order: 'OrderByTopSaleDESC', }); const deals: Array<{ supermarket: string; logo: string; product: string; price: number; discount?: number; link: string; image: string; }> = []; response.allData.forEach((marketProducts, idx) => { const market = response.markets[idx]; if (marketProducts && marketProducts.length > 0) { marketProducts.forEach((product) => { const discount = product.listPrice ? ((product.listPrice - product.price) / product.listPrice) * 100 : undefined; deals.push({ supermarket: market.name, logo: market.logo, product: product.desc, price: product.price, discount: discount ? parseFloat(discount.toFixed(1)) : undefined, link: product.link, image: product.img, }); }); } }); // Sort by discount percentage if available const dealsWithDiscount = deals.filter((d) => d.discount !== undefined); const dealsWithoutDiscount = deals.filter((d) => d.discount === undefined); const sortedDeals = [ ...dealsWithDiscount.sort((a, b) => (b.discount || 0) - (a.discount || 0)), ...dealsWithoutDiscount, ]; const summary = ` Best Deals in "${category}" ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Found ${deals.length} products across ${response.columns} supermarkets ${sortedDeals .slice(0, 15) .map( (deal, i) => `${i + 1}. ${deal.product} 🏪 ${deal.supermarket} 💵 $${deal.price.toLocaleString('es-AR')}${deal.discount ? ` (${deal.discount}% OFF)` : ''} 🔗 ${deal.link}` ) .join('\n\n')} `; return { content: [ { type: 'text', text: summary, }, { type: 'text', text: JSON.stringify({ category, totalDeals: deals.length, deals: sortedDeals }, null, 2), }, ], }; }
• src/tools/getBestDeals.ts:7-35 (schema)

  The tool definition object including name, description, and inputSchema for validation.
  export const getBestDealsTool = { name: 'get_best_deals', description: `Find the best deals and discounts currently available in supermarkets. This tool helps you discover: - Products on sale - Best price-to-value items - Popular deals - Discount opportunities Great for budget shopping and finding savings across all stores.`, inputSchema: { type: 'object', properties: { category: { type: 'string', description: 'Product category or type to find deals for (e.g., "lácteos", "cereales", "bebidas")', }, maxResults: { type: 'number', description: 'Number of deals per supermarket (default: 10)', minimum: 1, maximum: 30, default: 10, }, }, required: ['category'], }, };
• src/index.ts:89-116 (registration)

  Registration of getBestDealsTool in the MCP server's listTools handler.
  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:134-135 (registration)

  Handler dispatch for 'get_best_deals' tool call in the MCP server's CallToolRequestSchema.
  case 'get_best_deals': return await executeGetBestDeals(apiClient, args as any);
• src/index.ts:32-32 (registration)

  Import of the tool definition and handler function.
  import { getBestDealsTool, executeGetBestDeals } from './tools/getBestDeals.js';