mercadolibre-mcp

Instructions

Implementation Reference

• src/actions.ts:27-32 (handler)

  The getItem function implements the core logic for the get_item tool. It takes a MercadoLibreClient and GetItemParams, then makes a GET request to the MercadoLibre API to retrieve item details using the item_id.

  export async function getItem(
    client: MercadoLibreClient,
    params: GetItemParams
  ): Promise<unknown> {
    return client.get(`/items/${encodeURIComponent(params.item_id)}`);
  }

• src/schemas.ts:11-13 (schema)

  GetItemParams interface defines the input schema for the get_item tool, requiring a single item_id parameter.

  export interface GetItemParams {
    item_id: string;
  }

• src/mcp-server.ts:36-51 (registration)

  The get_item tool is registered with the MCP server using server.tool(). It defines the tool name, description, Zod validation schema for the item_id parameter, and the handler that calls tools.get_item() and returns the result as formatted JSON.

  server.tool(
    "get_item",
    "Get full details of a MercadoLibre item including title, price, pictures, seller, condition, and stock.",
    {
      item_id: z.string().describe("Item ID (e.g. MLA1234567890)"),
    },
    async (params) => {
      try {
        const result = await tools.get_item(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:28-30 (helper)

  The createMercadoLibreTools function exports the get_item tool, creating an instance of MercadoLibreClient and returning a wrapper function that calls getItem with the client and params.

  search_items: (params: SearchItemsParams) => searchItems(client, params),
  get_item: (params: GetItemParams) => getItem(client, params),
  get_item_description: (params: GetItemDescriptionParams) => getItemDescription(client, params),

• src/client.ts:22-38 (helper)

  The MercadoLibreClient.get method is a helper utility used by getItem to make HTTP requests to the MercadoLibre API. It handles URL construction, headers including optional authorization, and error handling.

  async get<T = unknown>(path: string, params?: Record<string, string>): Promise<T> {
    let url = `${BASE_URL}${path}`;
    if (params) {
      const qs = new URLSearchParams(params).toString();
      if (qs) url += `?${qs}`;
    }
    const res = await fetch(url, {
      method: "GET",
      headers: this.headers(),
      signal: AbortSignal.timeout(30000),
    });
    if (!res.ok) {
      const body = await res.text();
      throw new MercadoLibreError("GET", path, res.status, body);
    }
    return res.json() as Promise<T>;
  }