get_best_deals

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';