Integración de API y MCP de Drops Commerce

Una solución robusta para la integración de pagos de criptomonedas utilizando el MCP (Protocolo de contexto de modelo), que permite a los asistentes de IA como Claude crear y verificar transacciones USDT a través de la API de Gotas Commerce.

🚀 Descripción general

Este proyecto proporciona un puente entre los asistentes de IA y los servicios de pago de criptomonedas. Con el servidor MCP implementado, los asistentes pueden generar enlaces de pago, verificar el estado de las transacciones y obtener información detallada sobre los pagos USDT sin requerir conocimientos técnicos especializados en blockchain.

Related MCP server: MCP Coinbase Commerce Server

✨ Recursos

Herramientas MCP

create-payment

Crea una nueva transacción de pago USDT y devuelve todos los detalles requeridos, incluida la URL de pago y la dirección de la billetera.

Parámetros:

• amount : Importe del pago (ej: 100,50)

• currency : Código de moneda (actualmente solo "USDT")

• return_url : URL para redirigir al cliente después del pago

• description : Descripción de pago opcional

Devolver:

• Objeto JSON completo con todos los detalles de pago:

  • ID de pago único

  • URL de pago

  • Dirección de la billetera

  • Estado (pendiente, completado, fallido, expirado)

  • Fechas de creación y caducidad

  • Otros metadatos relevantes

check-payment-status

Comprueba el estado actual de un pago existente a través de su identificador único.

Parámetros:

• payment_id : ID único del pago a verificar

Devolver:

• Objeto JSON completo con el estado de pago actual

• Información de marca de tiempo para creación, vencimiento y finalización (cuando corresponda)

• Hash de transacción de blockchain (cuando se confirma el pago)

Recursos de MCP

payment-status://{payment_id}

Proporciona una versión formateada y simplificada del estado de pago como un recurso de MCP.

Devolver:

• Texto formateado con la información de pago más relevante

• Identificador, estado, valor, marcas de tiempo y descripción

Indicaciones de MCP

create-payment-prompt

Una solicitud guiada para ayudar al usuario a proporcionar la información necesaria para crear un nuevo pago.

🔧 Arquitectura

El servidor MCP actúa como una capa de abstracción sobre la API de Drops Commerce, traduciendo las capacidades de la API en herramientas, recursos y avisos que los asistentes de IA como Claude pueden utilizar fácilmente.

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

📋 Requisitos previos

• Python 3.8 o superior

• Clave API de Gotas Commerce (consíguela en: commerce.gotas.com )

• Acceso a un asistente compatible con MCP (como Claude)

🔌 Instalación

1. Clonar este repositorio:

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

2. Instalar dependencias:

   pip install -r requirements.txt

   O utilice el script de configuración automatizada:

   ./setup.bat

3. Configurar variables de entorno:

   • Crea un archivo .env con los siguientes valores:

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

🏃‍♂️ Ejecución

Servidor MCP

Ejecute el servidor para que las herramientas estén disponibles a través de MCP:

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

Integración con Claude Desktop

Para utilizar directamente con Claude Desktop:

python install_claude.py

Alternativamente, instálelo manualmente:

mcp install src.gotas_mcp_server.py

Uso directo de la API (scripts de prueba)

Para realizar pruebas directas sin un asistente:

• Crear pago : python test_client.py

• Comprobar estado : python check_payment.py

📊 Flujo de pago

1. Inicialización de pago :

   • El asistente obtiene el importe y otros detalles de pago del usuario.

   • El asistente llama a la herramienta create-payment con los parámetros requeridos

   • Se crea un nuevo pago en Gotas Commerce

   • El enlace de pago se devuelve al usuario.

2. Proceso de pago :

   • El usuario accede al enlace de pago proporcionado

   • El usuario transfiere USDT a la dirección de billetera mostrada

   • Gotas Commerce monitorea blockchain para confirmar transacciones

3. Comprobación de estado :

   • El asistente puede verificar el estado del pago llamando a check-payment-status estado

   • El estado puede ser: pendiente, completado, expirado o fallido.

   • Cuando se confirma el pago, el hash de la transacción de blockchain queda disponible.

🔍 Especificaciones técnicas

Detalles de la API

Puntos finales de la API de Drops Commerce :

1. Crear pago

   • POST /api/v1/payments

   • Cuerpo de la solicitud:

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

2. Verificar el estado del pago

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

Comunicación MCP

• Transporte : SSE (Eventos enviados por el servidor)

• Formato : JSON para la comunicación entre el asistente y el servidor MCP

• Autenticación : clave API almacenada como variable de entorno

📂 Estructura del proyecto

├── 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

🔒 Seguridad

• La clave API se almacena como una variable de entorno, no en el código fuente

• La comunicación con la API de Gotas Commerce se realiza mediante HTTPS

• El servidor MCP valida todos los parámetros antes de enviarlos a la API

• Manejo adecuado de errores para evitar exponer información confidencial

🧩 Extensibilidad

El proyecto está diseñado para ampliarse fácilmente:

1. Nuevas funciones : agregue nuevas herramientas MCP que implementan funciones decoradas con @mcp.tool() en el servidor

2. Integración con otros servicios : La arquitectura le permite integrar fácilmente otros servicios además de Gotas Commerce

3. Compatibilidad con nuevas monedas : el marco está preparado para admitir otras criptomonedas además de USDT en el futuro.

Ejemplos de uso

Creando un pago (a través de Claude)

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.

Comprobando el estado (vía Claude)

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.

📞 Soporte y Contacto

Para obtener ayuda o información adicional, comuníquese con el equipo de desarrollo de Gotas o abra un problema en el repositorio de GitHub.

📜 Licencia

Licencia MIT