search_items

Instructions

Implementation Reference

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

  The actual implementation of the search_items tool. It builds query parameters (site_id, query, category, price_min, price_max, limit, offset) and calls the MercadoLibre API endpoint /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: query (required), site_id, category, price_min, price_max, limit, offset (all optional).

  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)

  Registration of the search_items tool with the MCP server. Defines the tool name, description, Zod schemas for input validation, and the handler that calls tools.search_items and formats the response.

  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:26-28 (helper)

  The createMercadoLibreTools factory creates a client and exposes a tools object where search_items is mapped to call the searchItems action with the client already bound.

  return {
    tools: {
      search_items: (params: SearchItemsParams) => searchItems(client, params),

• src/mcp-server.ts:16-24 (registration)

  Zod schema definitions for the search_items tool's input validation (query, site_id, category, price_min, price_max, limit, offset).

  {
    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"),
  },