Agent Toolkit

Apache License 2.0

PayPal 代理工具包

PayPal 代理工具包使流行的代理框架（包括 OpenAI 的 Agent SDK、LangChain、Vercel 的 AI SDK 和 Model Context Protocol (MCP)）能够通过函数调用与 PayPal API 集成。它支持 TypeScript，并基于 PayPal API 和 PayPal SDK 构建。

可用工具

PayPal 代理工具包提供以下工具：

发票

create_invoice：在 PayPal 系统中创建新发票
list_invoices：列出带有可选分页和过滤的发票
get_invoice：检索特定发票的详细信息
send_invoice：将发票发送给收件人
send_invoice_reminder：发送现有发票的提醒
cancel_sent_invoice：取消已发送的发票
generate_invoice_qr_code：为发票生成二维码

订单

create_order：根据提供的详细信息在 PayPal 系统中创建订单
get_order：检索订单的详细信息
capture_order：捕获授权订单的付款

争议

list_disputes：检索所有未解决争议的摘要
get_dispute：检索特定争议的详细信息
accept_dispute_claim：接受争议索赔

发货

create_shipment：创建发货跟踪记录
get_shipment_tracking：检索发货跟踪信息

产品

create_product：在 PayPal 目录中创建新产品
list_products：列出带有可选分页和过滤的产品
show_product_details：检索特定产品的详细信息
update_product：更新现有产品

订阅计划

create_subscription_plan：创建新的订阅计划
list_subscription_plans：列出订阅计划
show_subscription_plan_details：检索特定订阅计划的详细信息

create_subscription：创建新的订阅
show_subscription_details：检索特定订阅的详细信息
cancel_subscription：取消活动订阅

交易

list_transactions：列出带有可选分页和过滤的交易

TypeScript

安装

除非你想修改包，否则你不需要这个源代码。如果你想使用该包，请运行：

sh 复制代码

npm install @paypal/agent-toolkit

要求

Node 18+

使用

库需要配置你的帐户的客户端 ID 和密钥，这些可以在你的 PayPal 开发者仪表板中找到。

该工具包与 Vercel 的 AI SDK 兼容，并可以作为工具列表传递。有关更多详细信息，请参阅我们的示例

typescript 复制代码

import { PayPalAgentToolkit } from '@paypal/agent-toolkit/ai-sdk';
const paypalToolkit = new PayPalAgentToolkit({
  clientId: process.env.PAYPAL_CLIENT_ID,
  clientSecret: process.env.PAYPAL_CLIENT_SECRET,
  configuration: {
    actions: {
      invoices: {
        create: true,
        list: true,
        send: true,
        sendReminder: true,
        cancel: true,
        generateQRC: true,
      },
      products: { create: true, list: true, update: true },
      subscriptionPlans: { create: true, list: true, show: true },
      shipment: { create: true, show: true, cancel: true },
      orders: { create: true, get: true },
      disputes: { list: true, get: true },
    },
  },
});

初始化工作流

typescript 复制代码

import { PayPalWorkflows, ALL_TOOLS_ENABLED } from '@paypal/agent-toolkit/ai-sdk';
const paypalWorkflows = new PayPalWorkflows({
  clientId: process.env.PAYPAL_CLIENT_ID,
  clientSecret: process.env.PAYPAL_CLIENT_SECRET,
  configuration: {
    actions: ALL_TOOLS_ENABLED,
  },
});

使用

使用工具包

typescript 复制代码

const llm: LanguageModelV1 = getModel(); // 用于 ai-sdk 的模型
const { text: response } = await generateText({
  model: llm,
  tools: paypalToolkit.getTools(),
  maxSteps: 10,
  prompt: `创建一个价值 50 美元的手工艺品订单并获取付款链接。`,
});

PayPal 模型上下文协议

PayPal 模型上下文协议服务器允许你通过函数调用与 PayPal API 集成。此协议支持各种工具以与不同的 PayPal 服务交互。

运行 MCP 检查器

要使用 npx 运行 PayPal MCP 服务器，请使用以下命令：

bash 复制代码

npx -y @paypal/mcp --tools=all PAYPAL_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PAYPAL_ENVIRONMENT="SANDBOX"

将 YOUR_ACCESS_TOKEN 替换为你使用这些步骤生成的有效访问令牌：生成访问令牌。或者，你可以将 PAYPAL_ACCESS_TOKEN 设置为环境变量。

自定义 MCP 服务器

你可以设置自己的 MCP 服务器。例如：

typescript 复制代码

import { PayPalAgentToolkit } from “@paypal/agent-toolkit/modelcontextprotocol";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const orderSummary = await paypalWorkflows.generateOrder(
  llm,
  transactionInfo,
  merchantInfo,
);

const server = new PayPalAgentToolkit({
	accessToken: process.env.PAYPAL_ACCESS_TOKEN
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("PayPal MCP Server running on stdio");
}

main().catch((error) => {
  console.error("Fatal error in main():", error);
  process.exit(1);
});

与 MCP 主机（Claude Desktop/Cline/Cursor/Github Co-Pilot）一起使用

本指南解释了如何将 PayPal 连接器与 Claude Desktop 集成。

前提条件

安装了 Claude Desktop 应用程序
本地安装 Node.js

安装步骤

1. 安装 Node.js

Node.js 是 PayPal 连接器正常工作的必要条件：

访问 Node.js 官方网站，下载并安装。
要求：Node 18+

2. 使用 MCP 主机（Claude Desktop / Cursor / Cline）配置 PayPal 连接器

我们将展示与 Claude Desktop 的集成。你可以使用你喜欢的 MCP 主机。

打开 Claude Desktop
导航到设置
找到开发者或高级设置部分
定位外部工具或连接器配置区域
将以下 PayPal 连接器配置添加到 ~/Claude/claude_desktop_config.json：

json 复制代码

{
   "mcpServers": {
     "paypal": {
       "command": "npx",
       "args": [
         "-y",
         "@paypal/mcp",
         "--tools=all"
       ],
       "env": {
         "PAYPAL_ACCESS_TOKEN": "YOUR_PAYPAL_ACCESS_TOKEN",
         "PAYPAL_ENVIRONMENT": "SANDBOX"
       }
     }
   }
}

确保将 YOUR_PAYPAL_ACCESS_TOKEN 替换为你的实际 PayPal 访问令牌。或者，你可以将 PAYPAL_ACCESS_TOKEN 设置为环境变量。你也可以使用 --access-token 在 "args" 中传递它。
将 PAYPAL_ENVIRONMENT 值设置为 SANDBOX 用于阶段测试，PRODUCTION 用于生产环境。

保存配置更改

3. 测试集成

退出并重新启动 Claude Desktop 以应用更改
通过要求 Claude 执行 PayPal 相关任务来测试连接
- 示例："列出我的 PayPal 发票"

环境变量

可以使用以下环境变量：

PAYPAL_ACCESS_TOKEN：你的 PayPal 访问令牌
PAYPAL_ENVIRONMENT：设置为 SANDBOX 用于沙箱模式，PRODUCTION 用于生产模式（默认为 SANDBOX 模式）

本指南解释了如何生成 PayPal API 集成的访问令牌，包括如何查找你的客户端 ID 和客户端密钥。

前提条件

PayPal 开发者帐户（用于沙箱）
PayPal 商业帐户（用于生产）

查找你的客户端 ID 和客户端密钥

创建 PayPal 开发者帐户：
- 前往 PayPal 开发者仪表板
- 使用你的 PayPal 凭证注册或登录
访问你的凭据：
- 在开发者仪表板中，点击菜单中的 Apps & Credentials
- 根据需要在 Sandbox 和 Live 模式之间切换
创建或查看应用程序：
- 要创建新应用程序，请点击 Create App
- 为你的应用程序命名并选择要关联的商业帐户
- 对于现有应用程序，点击应用程序名称以查看详细信息
检索凭据：
- 一旦你的应用程序被创建或选择，你会看到一个屏幕，其中包含你的：
  - Client ID：应用程序的公共标识符
  - Client Secret：私钥（点击“显示”后可见）
- 安全地保存这些凭据，因为它们是生成访问令牌所必需的

生成访问令牌

使用 cURL

bash 复制代码

curl -v https://api-m.sandbox.paypal.com/v1/oauth2/token \\
  -H \"Accept: application/json\" \\
  -H \"Accept-Language: en_US\" \\
  -u \"CLIENT_ID:CLIENT_SECRET\" \\
  -d \"grant_type=client_credentials\"

将 CLIENT_ID 和 CLIENT_SECRET 替换为你的实际凭据。对于生产环境，请使用 https://api-m.paypal.com 而不是沙箱 URL。

使用 Postman

创建一个新的请求到 https://api-m.sandbox.paypal.com/v1/oauth2/token
将方法设置为 POST
在 Authorization 下，选择 Basic Auth 并输入你的客户端 ID 和客户端密钥
在 Body 下，选择 x-www-form-urlencoded 并添加键 grant_type 且值为 client_credentials
发送请求

响应

成功的响应如下所示：

json 复制代码

{
  "scope": "...",
  "access_token": "Your Access Token",
  "token_type": "Bearer",
  "app_id": "APP-80W284485P519543T",
  "expires_in": 32400,
  "nonce": "..."
}

复制 access_token 值以用于 Claude Desktop 集成。

令牌详情

沙箱令牌：有效期 3-8 小时
生产令牌：有效期 8 小时
建议在令牌过期前实现令牌刷新逻辑

使用 Claude Desktop 的令牌

一旦你有了访问令牌，请在 Claude Desktop 连接器配置中更新 PAYPAL_ACCESS_TOKEN 值：

json 复制代码

{
  "env": {
    "PAYPAL_ACCESS_TOKEN": "YOUR_NEW_ACCESS_TOKEN",
    "PAYPAL_ENVIRONMENT": "SANDBOX"
  }
}

最佳实践

安全存储客户端 ID 和客户端密钥
实现令牌刷新逻辑以处理令牌过期
使用环境特定的令牌（沙箱用于测试，生产用于实际交易）
避免在应用程序代码中硬编码令牌

免责声明

AI 生成的内容可能不准确或不完整。用户负责独立验证任何信息，然后再依赖它。PayPal 不保证输出的准确性，也不对由此产生的任何决策、行动或后果负责。