create_partner_referral

Instructions

Implementation Reference

• src/index.ts:1229-1242 (handler)

  Executes the create_partner_referral tool by validating input parameters and sending a POST request to the PayPal partner-referrals API endpoint.

  case 'create_partner_referral': {
    const args = this.validatePartnerReferral(request.params.arguments);
    const response = await axios.post<PayPalPartnerReferral>(
      'https://api-m.sandbox.paypal.com/v2/customer/partner-referrals',
      args,
      { headers }
    );
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(response.data, null, 2)
      }]
    };
  }

• src/index.ts:977-1021 (registration)

  Registers the create_partner_referral tool with the MCP server, including its name, description, and JSON input schema.

  {
    name: 'create_partner_referral',
    description: 'Create a partner referral',
    inputSchema: {
      type: 'object',
      properties: {
        individual_owners: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              names: {
                type: 'array',
                items: {
                  type: 'object',
                  properties: {
                    given_name: { type: 'string' },
                    surname: { type: 'string' }
                  },
                  required: ['given_name', 'surname']
                }
              }
            },
            required: ['names']
          }
        },
        business_entity: {
          type: 'object',
          properties: {
            business_type: {
              type: 'object',
              properties: {
                type: { type: 'string' }
              },
              required: ['type']
            },
            business_name: { type: 'string' }
          },
          required: ['business_type', 'business_name']
        },
        email: { type: 'string' }
      },
      required: ['individual_owners', 'business_entity', 'email']
    }
  },

• src/index.ts:140-171 (schema)

  TypeScript interface defining the structure expected for PayPal partner referral data.

  interface PayPalPartnerReferral {
    individual_owners: Array<{
      names: Array<{
        prefix?: string;
        given_name: string;
        surname: string;
        middle_name?: string;
        suffix?: string;
      }>;
      citizenship?: string;
      addresses?: Array<{
        address_line_1: string;
        address_line_2?: string;
        admin_area_2: string;
        admin_area_1: string;
        postal_code: string;
        country_code: string;
      }>;
    }>;
    business_entity: {
      business_type: {
        type: string;
        subtype?: string;
      };
      business_name: string;
      business_phone?: {
        country_code: string;
        national_number: string;
      };
    };
    email: string;
  }

• src/index.ts:555-608 (helper)

  Validates and sanitizes the input arguments for the create_partner_referral tool according to the expected PayPal API structure.

  private validatePartnerReferral(args: unknown): PayPalPartnerReferral {
    if (typeof args !== 'object' || !args) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid partner referral data');
    }
  
    const referral = args as Record<string, unknown>;
    
    if (!Array.isArray(referral.individual_owners) ||
        !referral.business_entity ||
        typeof referral.email !== 'string') {
      throw new McpError(ErrorCode.InvalidParams, 'Missing required referral fields');
    }
  
    const individual_owners = referral.individual_owners.map(owner => {
      const ownerObj = owner as Record<string, unknown>;
      if (!Array.isArray(ownerObj.names) || ownerObj.names.length === 0) {
        throw new McpError(ErrorCode.InvalidParams, 'Invalid owner names');
      }
  
      const names = ownerObj.names.map(name => {
        const nameObj = name as Record<string, unknown>;
        if (typeof nameObj.given_name !== 'string' || typeof nameObj.surname !== 'string') {
          throw new McpError(ErrorCode.InvalidParams, 'Invalid name fields');
        }
        return {
          given_name: nameObj.given_name,
          surname: nameObj.surname
        };
      });
  
      return { names };
    });
  
    const business = referral.business_entity as Record<string, unknown>;
    if (!business.business_type || typeof business.business_name !== 'string') {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid business entity');
    }
  
    const business_type = business.business_type as Record<string, unknown>;
    if (typeof business_type.type !== 'string') {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid business type');
    }
  
    return {
      individual_owners,
      business_entity: {
        business_type: {
          type: business_type.type
        },
        business_name: business.business_name
      },
      email: referral.email
    };
  }