PayPal MCP

Instructions

Implementation Reference

• src/index.ts:1214-1227 (handler)

  The handler logic for the 'create_order' tool within the CallToolRequestSchema handler. It validates the arguments using validatePayPalOrder, makes a POST request to PayPal's orders endpoint, and returns the JSON response.

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

• src/index.ts:944-976 (registration)

  Tool registration for 'create_order' in the ListToolsRequestSchema handler, defining the tool's name, description, and input schema.

  {
    name: 'create_order',
    description: 'Create a new order in PayPal',
    inputSchema: {
      type: 'object',
      properties: {
        intent: { 
          type: 'string',
          enum: ['CAPTURE', 'AUTHORIZE']
        },
        purchase_units: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              amount: {
                type: 'object',
                properties: {
                  currency_code: { type: 'string' },
                  value: { type: 'string' }
                },
                required: ['currency_code', 'value']
              },
              description: { type: 'string' },
              reference_id: { type: 'string' }
            },
            required: ['amount']
          }
        }
      },
      required: ['intent', 'purchase_units']
    }
  },

• src/index.ts:508-553 (schema)

  validatePayPalOrder: Schema validation function that parses and validates the input arguments for the create_order tool, ensuring correct structure and types matching PayPalOrder interface.

  private validatePayPalOrder(args: unknown): PayPalOrder {
    if (typeof args !== 'object' || !args) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid order data');
    }
  
    const order = args as Record<string, unknown>;
    
    if (!['CAPTURE', 'AUTHORIZE'].includes(order.intent as string) ||
        !Array.isArray(order.purchase_units) ||
        order.purchase_units.length === 0) {
      throw new McpError(ErrorCode.InvalidParams, 'Missing required order fields');
    }
  
    const purchase_units = order.purchase_units.map(unit => {
      const unitObj = unit as Record<string, unknown>;
      if (!unitObj.amount || typeof unitObj.amount !== 'object') {
        throw new McpError(ErrorCode.InvalidParams, 'Invalid purchase unit amount');
      }
  
      const amount = unitObj.amount as Record<string, unknown>;
      if (typeof amount.currency_code !== 'string' || typeof amount.value !== 'string') {
        throw new McpError(ErrorCode.InvalidParams, 'Invalid amount fields');
      }
  
      const validatedUnit: PayPalOrder['purchase_units'][0] = {
        amount: {
          currency_code: amount.currency_code,
          value: amount.value
        }
      };
  
      if (typeof unitObj.description === 'string') {
        validatedUnit.description = unitObj.description;
      }
      if (typeof unitObj.reference_id === 'string') {
        validatedUnit.reference_id = unitObj.reference_id;
      }
  
      return validatedUnit;
    });
  
    return {
      intent: order.intent as 'CAPTURE' | 'AUTHORIZE',
      purchase_units
    };
  }

• src/index.ts:127-138 (schema)

  PayPalOrder TypeScript interface defining the expected structure for order data used in create_order tool.

  interface PayPalOrder {
    id?: string;
    intent: 'CAPTURE' | 'AUTHORIZE';
    purchase_units: Array<{
      amount: {
        currency_code: string;
        value: string;
      };
      description?: string;
      reference_id?: string;
    }>;
  }