Superprecio MCP Server

Instructions

Implementation Reference

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

  The executeGetBestDeals function is the core handler for the 'get_best_deals' tool. It queries the SuperPrecio API for products in a given category sorted by top sales, calculates discounts, sorts deals by discount percentage, generates a formatted text summary, and returns both text and JSON 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)

  Defines the tool schema for 'get_best_deals', including name, description, and inputSchema with required 'category' parameter and optional 'maxResults'.
  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:134-135 (registration)

  In the CallToolRequestSchema handler's switch statement, registers the execution dispatch for 'get_best_deals' by calling executeGetBestDeals.
  case 'get_best_deals': return await executeGetBestDeals(apiClient, args as any);
• src/index.ts:96-96 (registration)

  Includes getBestDealsTool in the array of tools returned by the ListToolsRequestSchema handler.
  getBestDealsTool,
• src/index.ts:32-32 (registration)

  Imports the getBestDealsTool schema and executeGetBestDeals handler from the tool module.
  import { getBestDealsTool, executeGetBestDeals } from './tools/getBestDeals.js';