PayPal MCP

Instructions

Implementation Reference

• src/index.ts:1325-1351 (handler)

  Handler for 'create_invoice' tool: validates arguments using validatePayPalInvoice, constructs the invoice data, sends POST to PayPal invoicing API, and returns the response.

  case 'create_invoice': {
    const args = this.validatePayPalInvoice(request.params.arguments);
    const invoiceData: PayPalInvoice = {
      detail: {
        invoice_number: args.detail.invoice_number,
        reference: args.detail.reference,
        currency_code: args.detail.currency_code
      },
      primary_recipients: [{
        billing_info: {
          email_address: args.primary_recipients[0].billing_info.email_address
        }
      }],
      items: args.items
    };
    const response = await axios.post<PayPalInvoice>(
      'https://api-m.sandbox.paypal.com/v2/invoicing/invoices',
      invoiceData,
      { headers }
    );
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(response.data, null, 2)
      }]
    };
  }

• src/index.ts:1108-1137 (registration)

  Registration of the 'create_invoice' tool in the ListTools response, including name, description, and input schema definition.

    name: 'create_invoice',
    description: 'Create a new invoice',
    inputSchema: {
      type: 'object',
      properties: {
        invoice_number: { type: 'string' },
        reference: { type: 'string' },
        currency_code: { type: 'string' },
        recipient_email: { type: 'string' },
        items: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              name: { type: 'string' },
              quantity: { type: 'string' },
              unit_amount: {
                type: 'object',
                properties: {
                  currency_code: { type: 'string' },
                  value: { type: 'string' }
                }
              }
            }
          }
        }
      },
      required: ['invoice_number', 'reference', 'currency_code', 'recipient_email', 'items']
    }
  }

• src/index.ts:713-775 (helper)

  Helper function validatePayPalInvoice that validates and structures the input arguments for creating an invoice according to PayPalInvoice interface.

  private validatePayPalInvoice(args: unknown): PayPalInvoice {
    if (typeof args !== 'object' || !args) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid invoice data');
    }
  
    const invoice = args as Record<string, unknown>;
    
    if (!invoice.detail || typeof invoice.detail !== 'object' ||
        !Array.isArray(invoice.primary_recipients) || invoice.primary_recipients.length === 0 ||
        !Array.isArray(invoice.items) || invoice.items.length === 0) {
      throw new McpError(ErrorCode.InvalidParams, 'Missing required invoice fields');
    }
  
    const detail = invoice.detail as Record<string, unknown>;
    if (typeof detail.invoice_number !== 'string' ||
        typeof detail.reference !== 'string' ||
        typeof detail.currency_code !== 'string') {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid invoice detail fields');
    }
  
    const recipient = invoice.primary_recipients[0] as Record<string, unknown>;
    if (!recipient.billing_info || typeof recipient.billing_info !== 'object' ||
        typeof (recipient.billing_info as any).email_address !== 'string') {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid recipient information');
    }
  
    const items = invoice.items as Array<Record<string, unknown>>;
    const validatedItems = items.map(item => {
      if (typeof item.name !== 'string' ||
          typeof item.quantity !== 'string' ||
          !item.unit_amount || typeof item.unit_amount !== 'object') {
        throw new McpError(ErrorCode.InvalidParams, 'Invalid invoice item');
      }
  
      const amount = item.unit_amount as Record<string, unknown>;
      if (typeof amount.currency_code !== 'string' || typeof amount.value !== 'string') {
        throw new McpError(ErrorCode.InvalidParams, 'Invalid item amount');
      }
  
      return {
        name: item.name,
        quantity: item.quantity,
        unit_amount: {
          currency_code: amount.currency_code,
          value: amount.value
        }
      };
    });
  
    return {
      detail: {
        invoice_number: detail.invoice_number,
        reference: detail.reference,
        currency_code: detail.currency_code
      },
      primary_recipients: [{
        billing_info: {
          email_address: (recipient.billing_info as any).email_address
        }
      }],
      items: validatedItems
    };
  }

• src/index.ts:214-234 (schema)

  TypeScript interface defining the structure of a PayPalInvoice, used for type safety in validation and API calls.

  interface PayPalInvoice {
    id?: string;
    detail: {
      invoice_number: string;
      reference: string;
      currency_code: string;
    };
    primary_recipients: Array<{
      billing_info: {
        email_address: string;
      };
    }>;
    items: Array<{
      name: string;
      quantity: string;
      unit_amount: {
        currency_code: string;
        value: string;
      };
    }>;
  }