Refgrow MCP Server

Instructions

Implementation Reference

• src/tools.ts:507-534 (handler)

  Handler function for 'create_conversion' tool - processes parameters, builds request body with optional fields, and makes POST request to /conversions API endpoint

  async (params) => {
    try {
      const body: Record<string, unknown> = { type: params.type };
      const optionalFields = [
        "value",
        "base_value",
        "affiliate_id",
        "referral_code",
        "referred_user_id",
        "email",
        "paid",
        "reference",
        "coupon_code_used",
        "base_value_currency",
      ] as const;
  
      for (const field of optionalFields) {
        if (params[field] !== undefined) {
          body[field] = params[field];
        }
      }
  
      const data = await apiRequest(config, "POST", "/conversions", body);
      return textResult(data);
    } catch (err) {
      return errorResult(err);
    }
  }

• src/tools.ts:452-535 (registration)

  Registration of 'create_conversion' tool using server.tool() with name, description, zod schema for input validation, and async handler function

  server.tool(
    "create_conversion",
    "Manually create a conversion (signup or purchase). For purchases, the commission is auto-calculated from project settings if value is not provided. You can identify the affiliate by ID or referral code.",
    {
      type: z
        .enum(["signup", "purchase"])
        .describe("Conversion type: signup or purchase"),
      value: z
        .number()
        .optional()
        .describe(
          "Commission value (auto-calculated from project settings if omitted)"
        ),
      base_value: z
        .number()
        .optional()
        .describe("Original transaction amount before commission"),
      affiliate_id: z
        .number()
        .int()
        .optional()
        .describe("ID of the referring affiliate"),
      referral_code: z
        .string()
        .optional()
        .describe(
          "Referral code to look up the affiliate (used if affiliate_id is not provided)"
        ),
      referred_user_id: z
        .number()
        .int()
        .optional()
        .describe("ID of the referred user"),
      email: z
        .string()
        .email()
        .optional()
        .describe("Email of the customer (for webhook payloads)"),
      paid: z
        .boolean()
        .optional()
        .describe("Whether the commission has been paid out (default false)"),
      reference: z
        .string()
        .optional()
        .describe("External reference ID (e.g. invoice number)"),
      coupon_code_used: z
        .string()
        .optional()
        .describe("Coupon code used in this conversion"),
      base_value_currency: z
        .string()
        .optional()
        .describe("Currency of the base value (e.g. USD, EUR)"),
    },
    async (params) => {
      try {
        const body: Record<string, unknown> = { type: params.type };
        const optionalFields = [
          "value",
          "base_value",
          "affiliate_id",
          "referral_code",
          "referred_user_id",
          "email",
          "paid",
          "reference",
          "coupon_code_used",
          "base_value_currency",
        ] as const;
  
        for (const field of optionalFields) {
          if (params[field] !== undefined) {
            body[field] = params[field];
          }
        }
  
        const data = await apiRequest(config, "POST", "/conversions", body);
        return textResult(data);
      } catch (err) {
        return errorResult(err);
      }
    }
  );

• src/tools.ts:456-506 (schema)

  Zod schema definition for create_conversion input parameters including type (signup/purchase), value, base_value, affiliate_id, referral_code, referred_user_id, email, paid, reference, coupon_code_used, and base_value_currency

    type: z
      .enum(["signup", "purchase"])
      .describe("Conversion type: signup or purchase"),
    value: z
      .number()
      .optional()
      .describe(
        "Commission value (auto-calculated from project settings if omitted)"
      ),
    base_value: z
      .number()
      .optional()
      .describe("Original transaction amount before commission"),
    affiliate_id: z
      .number()
      .int()
      .optional()
      .describe("ID of the referring affiliate"),
    referral_code: z
      .string()
      .optional()
      .describe(
        "Referral code to look up the affiliate (used if affiliate_id is not provided)"
      ),
    referred_user_id: z
      .number()
      .int()
      .optional()
      .describe("ID of the referred user"),
    email: z
      .string()
      .email()
      .optional()
      .describe("Email of the customer (for webhook payloads)"),
    paid: z
      .boolean()
      .optional()
      .describe("Whether the commission has been paid out (default false)"),
    reference: z
      .string()
      .optional()
      .describe("External reference ID (e.g. invoice number)"),
    coupon_code_used: z
      .string()
      .optional()
      .describe("Coupon code used in this conversion"),
    base_value_currency: z
      .string()
      .optional()
      .describe("Currency of the base value (e.g. USD, EUR)"),
  },

• src/types.ts:87-99 (schema)

  TypeScript interface CreateConversionInput defining the type structure for conversion creation with all optional fields

  export interface CreateConversionInput {
    type: "signup" | "purchase";
    value?: number;
    base_value?: number;
    affiliate_id?: number;
    referred_user_id?: number;
    referral_code?: string;
    paid?: boolean;
    reference?: string;
    coupon_code_used?: string;
    base_value_currency?: string;
    email?: string;
  }