Mercado Livre MCP Server

Instructions

Implementation Reference

• src/interface/controllers/MercadoLivreToolsController.ts:18-38 (registration)

  Registers the 'get-produtos' MCP tool with input schema (array of product names), description, and an inline handler that fetches product info via MercadoLivreService.getProducts and returns it as formatted JSON text.

  private registerGetStockToolHandler(): void {
    this.server.tool(
      'get-produtos',
      'Buscar informações básicas de produtos',
      {
        products: z.array(z.string()).describe('Array of product names'),
      },
      async ({ products }) => {
        const infos = await this.service.getProducts(products);
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(infos, null, 2),
            },
          ],
        };
      },
    );
  }

• src/interface/controllers/MercadoLivreToolsController.ts:22-24 (schema)

  Zod schema defining the input parameters for the 'get-produtos' tool: an array of product names.

  {
    products: z.array(z.string()).describe('Array of product names'),
  },

• src/application/services/MercadoLivreService.ts:17-29 (handler)

  Core implementation of product fetching: resets state, crawls Mercado Livre for the first product using getItems, computes lowest value items, and returns them.

  async getProducts(products: string[]) {
    // const data = [];
    // for (const product of products) {
    this.page = 1;
    this.products = [];
  
    await this.getItems(products[0]);
    const lowestValueItem = this.getLowestValueItem();
  
    // data.push(lowestValueItem);
    // }
    return lowestValueItem;
  }

• src/application/services/MercadoLivreService.ts:132-172 (helper)

  Parses HTML content from Mercado Livre search results using Cheerio, extracts product details (name, price, URL, shipping), matches against query with minimum 80% ratio, and collects matching products.

  private parseHTML = (product: string): void => {
    const $ = this.pageContent;
    if (!$) {
      console.error('Error parsing HTML: No content available');
      return;
    }
  
    const uiSearchLayoutItem = this.layoutItems();
  
    if (uiSearchLayoutItem) {
      uiSearchLayoutItem.each((_, element) => {
        const uiSearchItemTitle = $(element)
          .find('div[class="poly-card__content"] h3')
          .text();
        const productOriginalName = voca(uiSearchItemTitle).trim().value();
        const price = this.getPrice(element);
  
        const matching = wordsMatching({
          originalName: productOriginalName,
          querySearchByFilter: product,
          price,
          debug: false,
        });
  
        if (matching.queryMatchRatio >= 0.8) {
          if (price) {
            const productUrl = this.getUrl(element);
            const shippings = this.getShippings(element);
  
            this.products.push({
              name: productOriginalName,
              price,
              queryMatchRatio: matching.queryMatchRatio,
              url: productUrl,
              shippings,
            });
          }
        }
      });
    }
  };

• src/application/services/MercadoLivreService.ts:31-48 (helper)

  Filters products with free shipping, copies relevant fields, sorts by price ascending, and returns the list of lowest value items.

  private getLowestValueItem = (): MercadoLivreCrawlerOutput[] => {
    const items: MercadoLivreCrawlerOutput[] = [];
  
    this.getFreeShipping();
    for (const product of this.products) {
      items.push({
        name: product.name,
        price: product.price,
        queryMatchRatio: product.queryMatchRatio,
        url: product.url,
        shippings: product.shippings,
      });
    }
  
    items.sort((a, b) => a.price - b.price);
  
    return items;
  };