cobroya

Instructions

Implementation Reference

• src/actions.ts:9-47 (handler)

  The main handler function createPaymentPreference that validates input parameters, constructs the payload with items array (title, quantity, currency_id, unit_price), optionally adds back_urls and notification_url, and makes a POST request to Mercado Pago's /checkout/preferences endpoint.

  export async function createPaymentPreference(
    client: MercadoPagoClient,
    params: CreatePaymentPreferenceParams
  ): Promise<unknown> {
    if (!params.title || typeof params.title !== "string") {
      throw new Error("title is required and must be a string");
    }
    if (typeof params.quantity !== "number" || params.quantity < 1) {
      throw new Error("quantity must be a positive number");
    }
    if (!params.currency || typeof params.currency !== "string") {
      throw new Error("currency is required and must be a string");
    }
    if (typeof params.unit_price !== "number" || params.unit_price <= 0) {
      throw new Error("unit_price must be a positive number");
    }
  
    const payload: Record<string, unknown> = {
      items: [
        {
          title: params.title,
          quantity: params.quantity,
          currency_id: params.currency,
          unit_price: params.unit_price,
        },
      ],
    };
  
    if (params.back_urls) {
      payload.back_urls = params.back_urls;
      payload.auto_return = "approved";
    }
  
    if (params.notification_url) {
      payload.notification_url = params.notification_url;
    }
  
    return client.post("/checkout/preferences", payload);
  }

• src/schemas.ts:7-58 (schema)

  TypeScript interface CreatePaymentPreferenceParams defining the input type (title, quantity, currency, unit_price, back_urls, notification_url) and the createPaymentPreferenceSchema object with the tool's name, description, and parameter structure for MCP registration.

  export interface CreatePaymentPreferenceParams {
    title: string;
    quantity: number;
    currency: string;
    unit_price: number;
    back_urls?: BackUrls;
    notification_url?: string;
  }
  
  export interface GetPaymentParams {
    payment_id: string;
  }
  
  export interface CreateRefundParams {
    payment_id: string;
    amount?: number;
  }
  
  export interface SearchPaymentsParams {
    status?: string;
    sort?: string;
    criteria?: string;
    limit?: number;
    offset?: number;
  }
  
  export type GetMerchantInfoParams = Record<string, never>;
  
  export const createPaymentPreferenceSchema = {
    name: "create_payment_preference",
    description: "Creates a Mercado Pago checkout payment preference (payment link). Returns init_point URL for redirecting buyers.",
    parameters: {
      type: "object",
      required: ["title", "quantity", "currency", "unit_price"],
      properties: {
        title: { type: "string", description: "Product or service title" },
        quantity: { type: "number", description: "Quantity of items" },
        currency: { type: "string", description: "Currency ID (e.g. ARS, BRL, MXN, CLP, COP, UYU, PEN)" },
        unit_price: { type: "number", description: "Unit price of the item" },
        back_urls: {
          type: "object",
          description: "URLs to redirect the buyer after payment",
          properties: {
            success: { type: "string", description: "URL on approved payment" },
            failure: { type: "string", description: "URL on rejected payment" },
            pending: { type: "string", description: "URL on pending payment" },
          },
        },
        notification_url: { type: "string", description: "Webhook URL for payment notifications (IPN)" },
      },
    },
  } as const;

• src/mcp-server.ts:15-39 (registration)

  MCP tool registration using server.tool() with Zod schema validation, defining the tool name, description, input schema, and the async handler that calls tools.create_payment_preference and formats the response.

  server.tool(
    "create_payment_preference",
    "Creates a Mercado Pago checkout payment preference (payment link). Returns init_point URL for redirecting buyers.",
    {
      title: z.string(),
      quantity: z.number(),
      currency: z.string(),
      unit_price: z.number(),
      back_urls: z.object({
        success: z.string().optional(),
        failure: z.string().optional(),
        pending: z.string().optional(),
      }).optional(),
      notification_url: z.string().optional(),
    },
    async (params) => {
      try {
        const result = await tools.create_payment_preference(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:17-40 (helper)

  The createMercadoPagoTools factory function that creates a MercadoPagoClient instance and exports the tools object containing create_payment_preference wrapper that calls the handler with the client.

  export function createMercadoPagoTools(accessToken: string) {
    const client = new MercadoPagoClient(accessToken);
  
    return {
      schemas: allSchemas,
  
      tools: {
        create_payment_preference: (params: CreatePaymentPreferenceParams) =>
          createPaymentPreference(client, params),
  
        get_payment: (params: GetPaymentParams) =>
          getPayment(client, params),
  
        create_refund: (params: CreateRefundParams) =>
          createRefund(client, params),
  
        search_payments: (params?: SearchPaymentsParams) =>
          searchPayments(client, params),
  
        get_merchant_info: () =>
          getMerchantInfo(client),
      },
    };
  }

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

  BackUrls interface defining optional success, failure, and pending redirect URLs used in CreatePaymentPreferenceParams.

  export interface BackUrls {
    success?: string;
    failure?: string;
    pending?: string;
  }