cobroya

Instructions

Implementation Reference

• src/actions.ts:59-75 (handler)

  The createRefund function that handles the actual refund logic. It validates the payment_id and optional amount parameters, then makes a POST request to the Mercado Pago API to create the refund (full or partial).

  export async function createRefund(
    client: MercadoPagoClient,
    params: CreateRefundParams
  ): Promise<unknown> {
    if (!params.payment_id || typeof params.payment_id !== "string") {
      throw new Error("payment_id is required and must be a string");
    }
    if (params.amount !== undefined && (typeof params.amount !== "number" || params.amount <= 0)) {
      throw new Error("amount must be a positive number when provided");
    }
  
    const body = params.amount !== undefined ? { amount: params.amount } : {};
    return client.post(
      `/v1/payments/${encodeURIComponent(params.payment_id)}/refunds`,
      body
    );
  }

• src/schemas.ts:20-23 (schema)

  TypeScript interface defining the CreateRefundParams with payment_id (required) and amount (optional) fields.

  export interface CreateRefundParams {
    payment_id: string;
    amount?: number;
  }

• src/schemas.ts:72-83 (schema)

  MCP schema definition for create_refund tool with name, description, and parameter validation using JSON Schema format.

  export const createRefundSchema = {
    name: "create_refund",
    description: "Refund a payment fully or partially. Omit amount for full refund.",
    parameters: {
      type: "object",
      required: ["payment_id"],
      properties: {
        payment_id: { type: "string", description: "The payment ID to refund" },
        amount: { type: "number", description: "Partial refund amount. Omit for full refund." },
      },
    },
  } as const;

• src/mcp-server.ts:58-74 (registration)

  MCP server tool registration for create_refund, defining zod schema validation and the async handler that calls the tool and returns formatted results.

  server.tool(
    "create_refund",
    "Refund a payment fully or partially. Omit amount for full refund.",
    {
      payment_id: z.string(),
      amount: z.number().optional(),
    },
    async (params) => {
      try {
        const result = await tools.create_refund(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:30-31 (registration)

  Tool export in createMercadoPagoTools function that connects the create_refund parameter to the createRefund handler with the Mercado Pago client.

  create_refund: (params: CreateRefundParams) =>
    createRefund(client, params),