cobroya

Instructions

Implementation Reference

• src/actions.ts:77-91 (handler)

  The main handler function that implements searchPayments logic. It accepts optional SearchPaymentsParams (status, sort, criteria, limit, offset), validates the limit (max 100), builds URL query parameters, and makes a GET request to the Mercado Pago API endpoint /v1/payments/search.

  export async function searchPayments(
    client: MercadoPagoClient,
    params?: SearchPaymentsParams
  ): Promise<unknown> {
    const safeLimit = Math.min(params?.limit ?? 30, 100);
    const query = new URLSearchParams();
    if (params?.status) query.set("status", params.status);
    if (params?.sort) query.set("sort", params.sort);
    if (params?.criteria) query.set("criteria", params.criteria);
    if (params?.limit) query.set("limit", String(safeLimit));
    if (params?.offset) query.set("offset", String(params.offset));
  
    const qs = query.toString();
    return client.get(`/v1/payments/search${qs ? `?${qs}` : ""}`);
  }

• src/schemas.ts:25-31 (schema)

  TypeScript interface defining the input parameters for searchPayments, including optional fields: status, sort, criteria, limit, and offset.

  export interface SearchPaymentsParams {
    status?: string;
    sort?: string;
    criteria?: string;
    limit?: number;
    offset?: number;
  }

• src/schemas.ts:85-98 (schema)

  JSON Schema definition for the search_payments tool, describing the tool name, description, and parameter structure with optional fields for filtering and pagination.

  export const searchPaymentsSchema = {
    name: "search_payments",
    description: "Search recent payments for the authenticated merchant. Supports filtering by status.",
    parameters: {
      type: "object",
      properties: {
        status: { type: "string", description: "Filter by status: approved, pending, rejected, refunded, cancelled" },
        sort: { type: "string", description: "Sort field (e.g. date_created)" },
        criteria: { type: "string", description: "Sort order: asc or desc" },
        limit: { type: "number", description: "Max results (default 30, max 100)" },
        offset: { type: "number", description: "Pagination offset" },
      },
    },
  } as const;

• src/mcp-server.ts:76-93 (registration)

  MCP server tool registration for search_payments. Defines the tool with Zod schema for parameters (status, limit, offset), and implements the handler that calls tools.search_payments and formats the response.

  server.tool(
    "search_payments",
    "Search recent payments for the authenticated merchant. Supports filtering by status.",
    {
      status: z.string().optional(),
      limit: z.number().optional(),
      offset: z.number().optional(),
    },
    async (params) => {
      try {
        const result = await tools.search_payments(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:33-34 (registration)

  Tool export in the createMercadoPagoTools function that wraps the searchPayments handler with the MercadoPagoClient instance and exposes it as search_payments.

  search_payments: (params?: SearchPaymentsParams) =>
    searchPayments(client, params),