mercadolibre-mcp

Instructions

Implementation Reference

• src/actions.ts:13-25 (handler)

  The searchItems handler function that executes the search logic. It takes a client and SearchItemsParams, builds query parameters with optional filters (site_id, category, price range, limit, offset), and calls the MercadoLibre API at /sites/{siteId}/search.

  export async function searchItems(
    client: MercadoLibreClient,
    params: SearchItemsParams
  ): Promise<unknown> {
    const siteId = params.site_id ?? "MLA";
    const qp: Record<string, string> = { q: params.query };
    if (params.category) qp.category = params.category;
    if (params.price_min !== undefined) qp.price_min = String(params.price_min);
    if (params.price_max !== undefined) qp.price_max = String(params.price_max);
    qp.limit = String(Math.min(params.limit ?? 10, 50));
    if (params.offset !== undefined) qp.offset = String(params.offset);
    return client.get(`/sites/${encodeURIComponent(siteId)}/search`, qp);
  }

• src/schemas.ts:1-9 (schema)

  TypeScript interface defining the input parameters for search_items including required query field and optional filters (site_id, category, price_min, price_max, limit, offset).

  export interface SearchItemsParams {
    query: string;
    site_id?: string;
    category?: string;
    price_min?: number;
    price_max?: number;
    limit?: number;
    offset?: number;
  }

• src/mcp-server.ts:13-34 (registration)

  MCP tool registration for search_items with Zod schema validation. Defines the tool name, description, input schema with field descriptions, and the async handler that calls tools.search_items and returns formatted JSON results.

  server.tool(
    "search_items",
    "Search products on MercadoLibre by keyword. Supports filtering by category, price range, and site (MLA=Argentina, MLB=Brazil, MLM=Mexico, etc.)",
    {
      query: z.string().describe("Search query"),
      site_id: z.string().optional().describe("Site ID (default: MLA). MLA=Argentina, MLB=Brazil, MLM=Mexico, MLC=Chile, MCO=Colombia"),
      category: z.string().optional().describe("Category ID to filter"),
      price_min: z.number().optional().describe("Minimum price"),
      price_max: z.number().optional().describe("Maximum price"),
      limit: z.number().optional().describe("Max results (default 10, max 50)"),
      offset: z.number().optional().describe("Pagination offset"),
    },
    async (params) => {
      try {
        const result = await tools.search_items(params);
        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
      } catch (error) {
        const message = error instanceof Error ? error.message : String(error);
        return { content: [{ type: "text", text: message }], isError: true };
      }
    },
  );

• src/index.ts:23-37 (registration)

  Factory function that creates the MercadoLibre tools object. Line 28 wraps the searchItems handler with the client instance and exports it as search_items.

  export function createMercadoLibreTools(accessToken?: string) {
    const client = new MercadoLibreClient(accessToken);
  
    return {
      tools: {
        search_items: (params: SearchItemsParams) => searchItems(client, params),
        get_item: (params: GetItemParams) => getItem(client, params),
        get_item_description: (params: GetItemDescriptionParams) => getItemDescription(client, params),
        get_categories: (params?: GetCategoriesParams) => getCategories(client, params),
        get_category: (params: GetCategoryParams) => getCategory(client, params),
        get_seller_info: (params: GetSellerInfoParams) => getSellerInfo(client, params),
        get_trends: (params?: GetTrendsParams) => getTrends(client, params),
        get_currency_conversion: (params: GetCurrencyConversionParams) => getCurrencyConversion(client, params),
      },
    };