MCP Server (deprecated)

MCP 服务（已弃用）

一个模型上下文协议（MCP）服务，可全面集成 PayPal 的 API。该服务通过标准化接口，实现与 PayPal 支付处理、开具发票、订阅管理和业务运营功能的无缝交互。

功能

支付处理

• 订单管理：创建、更新和跟踪订单
• 支付处理：使用多种方式处理支付
• 支付令牌：创建和管理供日后使用的支付令牌
• 争议管理：处理支付争议及其解决事宜

业务运营

• 产品管理：创建和管理产品目录
• 开具发票：生成并发送专业发票
• 付款：向多个收款方批量付款
• 订阅管理：创建和管理定期计费

用户管理

• 身份验证：验证用户身份
• 用户信息：检索和管理用户数据
• Web 配置文件管理：自定义结账体验

架构

graph TB
    subgraph "MCP Environment"
        Client[MCP Client]
        Server[PayPal MCP Server]
        Validation[Input Validation]
        Auth[OAuth Authentication]
        Cache[Token Cache]
        ErrorHandler[Error Handler]
    end

    subgraph "PayPal APIs"
        Orders[Orders API]
        Payments[Payments API]
        Payouts[Payouts API]
        Invoicing[Invoicing API]
        Products[Products API]
        Subscriptions[Subscriptions API]
        Disputes[Disputes API]
        Identity[Identity API]
    end

    Client --> |Request| Server
    Server --> |Response| Client
    Server --> Validation
    Server --> Auth
    Auth --> Cache
    Auth --> |Access Token| PayPal
    Server --> ErrorHandler

    Server --> Orders
    Server --> Payments
    Server --> Payouts
    Server --> Invoicing
    Server --> Products
    Server --> Subscriptions
    Server --> Disputes
    Server --> Identity

    style Client fill:#f9f,stroke:#333,stroke-width:2px
    style Server fill:#bbf,stroke:#333,stroke-width:2px
    style Auth fill:#bfb,stroke:#333,stroke-width:2px
    style Validation fill:#bfb,stroke:#333,stroke-width:2px
    style Cache fill:#fbb,stroke:#333,stroke-width:2px
    style ErrorHandler fill:#fbb,stroke:#333,stroke-width:2px

安装

前提条件

• Node.js 16.x 或更高版本
• 拥有 API 凭据的 PayPal 开发者账户

手动安装

1. 克隆仓库

   git clone https://github.com/arbuthnot-eth/PayPal-MCP.git
   cd PayPal-MCP
   

2. 安装依赖项

   npm install
   

3. 构建项目

   npm run build
   

4. 在 MCP 设置文件中配置 PayPal 凭据：

   {
     "mcpServers": {
       "paypal": {
         "command": "node",
         "args": ["path/to/paypal-mcp/build/index.js"],
         "env": {
           "PAYPAL_CLIENT_ID": "your_client_id",
           "PAYPAL_CLIENT_SECRET": "your_client_secret",
           "PAYPAL_ENVIRONMENT": "sandbox" // or "live"
         },
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

可用工具

支付操作

create_payment_token

创建供日后使用的支付令牌。

{
  customer: {
    id: string;
    email_address?: string;
  };
  payment_source: {
    card?: {
      name: string;
      number: string;
      expiry: string;
      security_code: string;
    };
    paypal?: {
      email_address: string;
    };
  };
}

create_order

在 PayPal 中创建新订单。

{
  intent: 'CAPTURE' | 'AUTHORIZE';
  purchase_units: Array<{
    amount: {
      currency_code: string;
      value: string;
    };
    description?: string;
    reference_id?: string;
    items?: Array<{
      name: string;
      quantity: string;
      unit_amount: {
        currency_code: string;
        value: string;
      };
    }>;
  }>;
  application_context?: {
    brand_name?: string;
    shipping_preference?: 'GET_FROM_FILE' | 'NO_SHIPPING' | 'SET_PROVIDED_ADDRESS';
    user_action?: 'CONTINUE' | 'PAY_NOW';
  };
}

capture_order

捕获已授权订单的款项。

{
  order_id: string;
  payment_source?: {
    token?: {
      id: string;
      type: string;
    };
  };
}

create_subscription

创建定期计费订阅。

{
  plan_id: string;
  subscriber: {
    name: {
      given_name: string;
      surname: string;
    };
    email_address: string;
  };
  application_context?: {
    brand_name?: string;
    shipping_preference?: 'GET_FROM_FILE' | 'NO_SHIPPING' | 'SET_PROVIDED_ADDRESS';
    user_action?: 'CONTINUE' | 'SUBSCRIBE_NOW';
    payment_method?: {
      payer_selected?: string;
      payee_preferred?: string;
    };
  };
}

业务操作

create_product

在目录中创建新产品。

{
  name: string;
  description: string;
  type: 'PHYSICAL' | 'DIGITAL' | 'SERVICE';
  category: string;
  image_url?: string;
  home_url?: string;
}

create_invoice

生成新发票。

{
  invoice_number: string;
  reference: string;
  currency_code: string;
  recipient_email: string;
  items: Array<{
    name: string;
    quantity: string;
    unit_amount: {
      currency_code: string;
      value: string;
    };
    description?: string;
    tax?: {
      name: string;
      percent: string;
    };
  }>;
  note?: string;
  terms_and_conditions?: string;
  memo?: string;
  payment_term?: {
    term_type: 'DUE_ON_RECEIPT' | 'DUE_ON_DATE' | 'NET_10' | 'NET_15' | 'NET_30' | 'NET_45' | 'NET_60' | 'NET_90';
    due_date?: string;
  };
}

create_payout

处理批量付款。

{
  sender_batch_header: {
    sender_batch_id: string;
    email_subject?: string;
    recipient_type?: string;
  };
  items: Array<{
    recipient_type: string;
    amount: {
      value: string;
      currency: string;
    };
    receiver: string;
    note?: string;
  }>;
}

错误处理

该服务实现了全面的错误处理：

• 输入验证：提供详细的验证错误及具体说明
• PayPal API 错误：返回包含 PayPal 错误详情的结构化错误响应
• 网络错误：针对暂时性网络问题实现重试逻辑
• 身份验证错误：自动刷新令牌并提供清晰的错误消息
• 速率限制：针对 API 速率限制采用退避策略

安全注意事项

• 验证并清理所有敏感数据
• 使用 PayPal OAuth 2.0 进行身份验证
• 通过环境变量安全地管理凭据
• 验证所有 API 参数
• 错误消息不会泄露敏感信息

开发

构建

npm run build

在开发模式下运行

npm run dev

测试

npm test

代码检查

npm run lint

格式化

npm run format

贡献

1. Fork 仓库
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

许可证

MIT 许可证