Интеграция API Drops Commerce и MCP
Надежное решение для интеграции криптовалютных платежей с использованием протокола MCP (Model Context Protocol), позволяющее помощникам на основе искусственного интеллекта, таким как Клод, создавать и проверять транзакции USDT через API Gotas Commerce.
🚀 Обзор
Этот проект является связующим звеном между помощниками на базе искусственного интеллекта и сервисами криптовалютных платежей. Благодаря внедрению сервера MCP помощники могут генерировать платежные ссылки, проверять статус транзакций и получать подробную информацию о платежах USDT, не требуя при этом специальных технических знаний в области блокчейна.
✨ Ресурсы
Инструменты МКП
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 (например, Клоду)
🔌 Установка
- Клонируйте этот репозиторий:
git clone https://github.com/caiovicentino/mcpGOTAS.git
cd mcpGOTAS
- Установите зависимости:
pip install -r requirements.txt
- Настройте переменные среды:
- Создайте файл
.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:
Либо установите вручную:
mcp install src.gotas_mcp_server.py
Прямое использование API (тестовые скрипты)
Для прямого тестирования без мастера:
- Создать платеж :
python test_client.py - Проверить статус :
python check_payment.py
📊 Поток платежей
- Инициализация платежа :
- Дежурный получает от пользователя сумму и другие реквизиты платежа.
- Мастер вызывает инструмент
create-payment с требуемыми параметрами - В Gotas Commerce создан новый платеж
- Ссылка на оплату возвращается пользователю.
- Процесс оплаты :
- Пользователь переходит по предоставленной ссылке на оплату.
- Пользователь переводит USDT на указанный адрес кошелька
- Gotas Commerce отслеживает блокчейн для подтверждения транзакций
- Проверка статуса :
- Помощник может проверить статус платежа, позвонив по номеру
check-payment-status status. - Статус может быть следующим: ожидание, завершено, просрочено или неудача.
- После подтверждения платежа становится доступен хэш транзакции в блокчейне.
🔍 Технические характеристики
Подробности API
Конечные точки API Drops Commerce :
- Создать платеж
POST /api/v1/payments- Текст запроса:
{
"amount": "100.00",
"currency": "USDT",
"return_url": "https://exemplo.com/retorno",
"description": "Descrição do pagamento"
}
- Проверить статус платежа
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.
- Правильная обработка ошибок во избежание раскрытия конфиденциальной информации
🧩 Расширяемость
Проект спроектирован с возможностью легкого расширения:
- Новые функции : добавление новых инструментов MCP, реализующих функции, декорированные
@mcp.tool() на сервере. - Интеграция с другими сервисами : Архитектура позволяет легко интегрировать другие сервисы помимо Gotas Commerce.
- Поддержка новых монет : платформа готова поддерживать другие криптовалюты помимо 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.
📜 Лицензия
Лицензия Массачусетского технологического института