Интеграция API Drops Commerce и MCP

Надежное решение для интеграции криптовалютных платежей с использованием протокола MCP (Model Context Protocol), позволяющее помощникам на основе искусственного интеллекта, таким как Клод, создавать и проверять транзакции USDT через API Gotas Commerce.

🚀 Обзор

Этот проект является связующим звеном между помощниками на базе искусственного интеллекта и сервисами криптовалютных платежей. Благодаря внедрению сервера MCP помощники могут генерировать платежные ссылки, проверять статус транзакций и получать подробную информацию о платежах USDT, не требуя при этом специальных технических знаний в области блокчейна.

Related MCP server: MCP Coinbase Commerce Server

✨ Ресурсы

Инструменты МКП

create-payment

Создает новую платежную транзакцию USDT и возвращает все необходимые данные, включая URL-адрес платежа и адрес кошелька.

Параметры:

• amount : Сумма платежа (например: 100,50)

• currency : Код валюты (в настоящее время просто «USDT»)

• return_url : URL для перенаправления клиента после оплаты

• description : Необязательное описание платежа

Возвращаться:

• Полный объект JSON со всеми платежными реквизитами:

  • Уникальный идентификатор платежа

  • URL-адрес платежа

  • Адрес кошелька

  • Статус (ожидание, завершено, неудача, просрочен)

  • Даты создания и истечения срока действия

  • Другие соответствующие метаданные

check-payment-status

Он проверяет текущий статус существующего платежа по его уникальному идентификатору.

Параметры:

• payment_id : Уникальный идентификатор платежа, который необходимо проверить

Возвращаться:

• Полный объект JSON с текущим статусом платежа

• Информация о временной метке для создания, истечения срока действия и завершения (где применимо)

• Хэш транзакции блокчейна (при подтверждении платежа)

Ресурсы МКП

payment-status://{payment_id}

Он предоставляет форматированную и упрощенную версию статуса платежа в качестве ресурса MCP.

Возвращаться:

• Форматированный текст с наиболее актуальной платежной информацией

• Идентификатор, статус, значение, временные метки и описание

Подсказки MCP

create-payment-prompt

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

🔧 Архитектура

Сервер MCP действует как уровень абстракции над API Drops Commerce, преобразуя возможности API в инструменты, ресурсы и подсказки, которые легко использовать помощникам на основе искусственного интеллекта, таким как Клод.

┌────────────────┐    ┌───────────────┐    ┌──────────────────┐
│                │    │               │    │                  │
│  Assistente IA ├────┤  Servidor MCP ├────┤  API Gotas       │
│  (Claude)      │    │  (FastAPI)    │    │  Commerce        │
│                │    │               │    │                  │
└────────────────┘    └───────────────┘    └──────────────────┘

📋 Предварительные условия

• Python 3.8 или выше

• Ключ API Gotas Commerce (получить его можно на сайте: commerce.gotas.com )

• Доступ к помощнику, совместимому с MCP (например, Клоду)

🔌 Установка

1. Клонируйте этот репозиторий:

   git clone https://github.com/caiovicentino/mcpGOTAS.git
   cd mcpGOTAS

2. Установите зависимости:

   pip install -r requirements.txt

   Или воспользуйтесь скриптом автоматической настройки:

   ./setup.bat

3. Настройте переменные среды:

   • Создайте файл .env со следующими значениями:

     GOTAS_API_KEY=sua_chave_api_aqui
     GOTAS_BASE_URL=https://commerce.gotas.com

🏃‍♂️ Исполнение

MCP-сервер

Запустите сервер, чтобы сделать инструменты доступными через MCP:

uvicorn src.gotas_mcp_server:app --host 0.0.0.0 --port 8000

Интеграция с Claude Desktop

Для использования напрямую с Claude Desktop:

python install_claude.py

Либо установите вручную:

mcp install src.gotas_mcp_server.py

Прямое использование API (тестовые скрипты)

Для прямого тестирования без мастера:

• Создать платеж : python test_client.py

• Проверить статус : python check_payment.py

📊 Поток платежей

1. Инициализация платежа :

   • Дежурный получает от пользователя сумму и другие реквизиты платежа.

   • Мастер вызывает инструмент create-payment с требуемыми параметрами

   • В Gotas Commerce создан новый платеж

   • Ссылка на оплату возвращается пользователю.

2. Процесс оплаты :

   • Пользователь переходит по предоставленной ссылке на оплату.

   • Пользователь переводит USDT на указанный адрес кошелька

   • Gotas Commerce отслеживает блокчейн для подтверждения транзакций

3. Проверка статуса :

   • Помощник может проверить статус платежа, позвонив по номеру check-payment-status status.

   • Статус может быть следующим: ожидание, завершено, просрочено или неудача.

   • После подтверждения платежа становится доступен хэш транзакции в блокчейне.

🔍 Технические характеристики

Подробности API

Конечные точки API Drops Commerce :

1. Создать платеж

   • POST /api/v1/payments

   • Текст запроса:

     {
       "amount": "100.00",
       "currency": "USDT",
       "return_url": "https://exemplo.com/retorno",
       "description": "Descrição do pagamento"
     }

2. Проверить статус платежа

   • GET /api/v1/payments/{payment_id}

МКП-коммуникация

• Транспорт : SSE (события, отправленные сервером)

• Формат : JSON для связи между помощником и сервером MCP

• Аутентификация : ключ API хранится как переменная среды

📂 Структура проекта

├── src/
│   └── gotas_mcp_server.py  # Implementação principal do servidor MCP
├── .env                     # Variáveis de ambiente (API key, etc.)
├── .smithery.json           # Configuração para Smithery CLI
├── check_payment.py         # Utilitário para verificar status de pagamentos
├── docsdaapigotas.md        # Documentação detalhada da API
├── install_claude.py        # Script para instalação no Claude Desktop
├── mcp.md                   # Documentação do servidor MCP
├── MCPPROTOCOLpython.MD     # Documentação do protocolo MCP em Python
├── requirements.txt         # Dependências do projeto
├── setup.bat                # Script de configuração para Windows
├── smithery.json            # Schema para integração com Smithery
└── test_client.py           # Cliente de teste para criação de pagamentos

🔒 Безопасность

• Ключ API хранится как переменная среды, а не в исходном коде.

• Связь с API Gotas Commerce осуществляется через HTTPS.

• Сервер MCP проверяет все параметры перед отправкой в API.

• Правильная обработка ошибок во избежание раскрытия конфиденциальной информации

🧩 Расширяемость

Проект спроектирован с возможностью легкого расширения:

1. Новые функции : добавление новых инструментов MCP, реализующих функции, декорированные @mcp.tool() на сервере.

2. Интеграция с другими сервисами : Архитектура позволяет легко интегрировать другие сервисы помимо Gotas Commerce.

3. Поддержка новых монет : платформа готова поддерживать другие криптовалюты помимо USDT в будущем.

📚 Примеры использования

Создание платежа (через Клода)

Usuário: Preciso gerar um link de pagamento de 50 USDT.

Claude: Vou gerar um link de pagamento para você. Para qual URL devo configurar o redirecionamento após o pagamento?

Usuário: https://meusite.com.br/obrigado

Claude: [Utilizando ferramenta create-payment]
Criando pagamento de 50 USDT com redirecionamento para https://meusite.com.br/obrigado...

Pronto! Criei um link de pagamento para 50 USDT.

Link de pagamento: [URL gerado pela API]
Este link expirará em 30 minutos. O cliente deve transferir exatamente 50 USDT para o endereço da carteira mostrado na página de pagamento.

Проверка статуса (через Клода)

Usuário: Verifique o status do meu pagamento com ID xyz123.

Claude: [Utilizando ferramenta check-payment-status]
Verificando o status do pagamento ID xyz123...

O status atual do pagamento é: PENDENTE
- Valor: 50.00 USDT
- Criado em: [timestamp]
- Expira em: [timestamp]

O pagamento ainda não foi confirmado na blockchain. Você pode acompanhar usando o link de pagamento ou me pedir para verificar novamente mais tarde.

📞 Поддержка и контакты

Для получения поддержки или дополнительной информации свяжитесь с командой разработчиков Gotas или создайте проблему в репозитории GitHub.

📜 Лицензия

Лицензия Массачусетского технологического института