PayPal MCP Server

официальный

Сервер протокола контекста модели PayPal позволяет интегрироваться с API PayPal через вызов функций. Этот протокол поддерживает различные инструменты для взаимодействия с разными сервисами PayPal.

GitHub
187

Документация

PayPal Agent Toolkit

PayPal Agent Toolkit позволяет популярным агентским фреймворкам, включая OpenAI Agent SDK, LangChain, Vercel AI SDK и Model Context Protocol (MCP), интегрироваться с API PayPal через вызов функций. Он включает поддержку TypeScript и построен на основе API PayPal и PayPal SDK.

Доступные инструменты

PayPal Agent Toolkit предоставляет следующие инструменты:

Счета

  • create_invoice: Создать новый счет в системе PayPal
  • list_invoices: Получить список счетов с возможностью пагинации и фильтрации
  • get_invoice: Получить детали конкретного счета
  • send_invoice: Отправить счет получателям
  • send_invoice_reminder: Отправить напоминание по существующему счету
  • cancel_sent_invoice: Отменить отправленный счет
  • generate_invoice_qr_code: Сгенерировать QR-код для счета

Платежи

  • create_order: Создать заказ в системе PayPal на основе предоставленных данных
  • get_order: Получить детали заказа
  • pay_order: Обработать платеж по авторизованному заказу
  • create_refund: Оформить возврат по захваченному платежу
  • get_refund: Получить детали конкретного возврата

Управление спорами

  • list_disputes: Получить сводку всех открытых споров
  • get_dispute: Получить подробную информацию о конкретном споре
  • accept_dispute_claim: Принять претензию по спору

Отслеживание отправлений

  • create_shipment_tracking: Создать запись отслеживания отправления
  • get_shipment_tracking: Получить информацию об отслеживании отправления
  • update_shipment_tracking: Обновить информацию об отслеживании отправления

Управление каталогом

  • create_product: Создать новый продукт в каталоге PayPal
  • list_products: Получить список продуктов с возможностью пагинации и фильтрации
  • show_product_details: Получить детали конкретного продукта

Управление подписками

  • create_subscription_plan: Создать новый план подписки
  • list_subscription_plans: Получить список планов подписки
  • show_subscription_plan_details: Получить детали конкретного плана подписки
  • create_subscription: Создать новую подписку
  • show_subscription_details: Получить детали конкретной подписки
  • update_subscription: Обновить существующую подписку
  • cancel_subscription: Отменить активную подписку

Отчетность и аналитика

  • list_transactions: Получить список транзакций с возможностью пагинации и фильтрации
  • get_merchant_insights: Получить бизнес-аналитику и метрики для продавца

TypeScript

Установка

Вам не нужен этот исходный код, если вы не хотите изменять пакет. Если вы просто хотите использовать пакет, выполните:

npm install @paypal/agent-toolkit

Требования

  • Node 18+

Использование

Библиотеку необходимо настроить с использованием client id и secret вашего аккаунта, которые доступны в PayPal Developer Dashboard.

Инструментарий работает с Vercel AI SDK и может быть передан в виде списка инструментов. Для получения дополнительной информации обратитесь к нашим примерам.

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 },
    },
  },
});

Чтобы использовать режим песочницы, добавьте контекст в вашу конфигурацию.

configuration: {
  context: {
    sandbox: true,
  }
}

Инициализация рабочих процессов

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,
  },
});

Использование

Использование инструментария

const llm: LanguageModelV1 = getModel(); // The model to be used with ai-sdk
const { text: response } = await generateText({
  model: llm,
  tools: paypalToolkit.getTools(),
  maxSteps: 10,
  prompt: `Create an order for $50 for custom handcrafted item and get the payment link.`,
});

Переменные окружения

Можно использовать следующие переменные окружения:

  • PAYPAL_ACCESS_TOKEN: Ваш токен доступа PayPal
  • PAYPAL_ENVIRONMENT: Установите SANDBOX для режима песочницы, PRODUCTION для production (по умолчанию используется режим SANDBOX)

В этом руководстве объясняется, как сгенерировать токен доступа для интеграции с API PayPal, включая поиск вашего client ID и client secret.

Предварительные требования

  • Аккаунт разработчика PayPal (для песочницы)
  • Бизнес-аккаунт PayPal (для production)

Поиск вашего Client ID и Client Secret

  1. Создайте аккаунт разработчика PayPal:

    • Перейдите в PayPal Developer Dashboard
    • Зарегистрируйтесь или войдите, используя свои учетные данные PayPal

  2. Получите доступ к учетным данным:

    • В Developer Dashboard нажмите Apps & Credentials в меню
    • Переключайтесь между режимами Sandbox и Live в зависимости от ваших потребностей

  3. Создайте или просмотрите приложение:

    • Чтобы создать новое приложение, нажмите Create App
    • Дайте приложению имя и выберите бизнес-аккаунт для связи с ним
    • Для существующих приложений нажмите на имя приложения, чтобы просмотреть детали

  4. Получите учетные данные:

    • После создания или выбора приложения вы увидите экран с:
      • Client ID: Публичный идентификатор вашего приложения
      • Client Secret: Приватный ключ (отображается после нажатия "Show")
    • Сохраните эти учетные данные в безопасном месте, так как они необходимы для генерации токенов доступа

Генерация токена доступа

Использование cURL

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 на ваши реальные учетные данные. Для production используйте https://api-m.paypal.com вместо URL песочницы.

Использование Postman

  1. Создайте новый запрос к https://api-m.sandbox.paypal.com/v1/oauth2/token
  2. Установите метод POST
  3. В разделе Authorization выберите Basic Auth и введите ваш Client ID и Client Secret
  4. В разделе Body выберите x-www-form-urlencoded и добавьте ключ grant_type со значением client_credentials
  5. Отправьте запрос

Ответ

Успешный ответ будет выглядеть так:

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

Скопируйте значение access_token для использования в интеграции с Claude Desktop.

Детали токена

  • Токены песочницы: Действительны 3-8 часов
  • Production токены: Действительны 8 часов
  • Рекомендуется реализовать логику обновления токена до истечения срока действия

Использование токена с Claude Desktop

Получив токен доступа, обновите значение PAYPAL_ACCESS_TOKEN в конфигурации вашего коннектора Claude Desktop:

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

Лучшие практики

  1. Храните client ID и client secret в безопасности
  2. Реализуйте логику обновления токена для обработки истечения срока действия
  3. Используйте токены, специфичные для окружения (песочница для тестирования, production для реальных транзакций)
  4. Избегайте жесткого кодирования токенов в коде приложения

Отказ от ответственности

Контент, сгенерированный ИИ, может быть неточным или неполным. Пользователи несут ответственность за независимую проверку любой информации, прежде чем полагаться на нее. PayPal не дает никаких гарантий относительно точности вывода и не несет ответственности за любые решения, действия или последствия, возникшие в результате его использования.