Gotas Commerce API & MCP Integration

Uma solução robusta para integração de pagamentos em criptomoeda usando o protocolo MCP (Model Context Protocol), permitindo que assistentes de IA como Claude possam criar e verificar transações USDT através da API Gotas Commerce.

🚀 Visão Geral

Este projeto fornece uma ponte entre assistentes de IA e serviços de pagamento em criptomoeda. Com o servidor MCP implementado, assistentes podem gerar links de pagamento, verificar status de transações e obter informações detalhadas sobre pagamentos USDT sem necessidade de conhecimento técnico especializado em blockchain.

✨ Recursos

Ferramentas MCP

create-payment

Cria uma nova transação de pagamento em USDT e retorna todos os detalhes necessários, incluindo URL para pagamento e endereço da carteira.

Parâmetros:

• amount: Valor do pagamento (ex: 100.50)

• currency: Código da moeda (atualmente apenas "USDT")

• return_url: URL para redirecionamento do cliente após o pagamento

• description: Descrição opcional do pagamento

Retorno:

• Objeto JSON completo com todos os detalhes do pagamento:

  • ID único do pagamento

  • URL para pagamento

  • Endereço da carteira

  • Status (pending, completed, failed, expired)

  • Datas de criação e expiração

  • Outros metadados relevantes

check-payment-status

Verifica o status atual de um pagamento existente através de seu identificador único.

Parâmetros:

• payment_id: ID único do pagamento a ser verificado

Retorno:

• Objeto JSON completo com o estado atual do pagamento

• Informações de timestamp para criação, expiração e conclusão (quando aplicável)

• Hash da transação blockchain (quando o pagamento for confirmado)

Recursos MCP

payment-status://{payment_id}

Fornece uma versão formatada e simplificada do status do pagamento como um recurso MCP.

Retorno:

• Texto formatado com as informações mais relevantes do pagamento

• Identificador, status, valor, timestamps e descrição

Prompts MCP

create-payment-prompt

Um prompt guiado para auxiliar o usuário a fornecer as informações necessárias para criar um novo pagamento.

🔧 Arquitetura

O servidor MCP atua como uma camada de abstração sobre a API Gotas Commerce, traduzindo as capacidades da API em ferramentas, recursos e prompts facilmente utilizáveis por assistentes de IA como o Claude.

📋 Pré-requisitos

• Python 3.8 ou superior

• Chave de API da Gotas Commerce (obtenha em: commerce.gotas.com)

• Acesso a um assistente compatível com MCP (como Claude)

🔌 Instalação

1. Clone este repositório:

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

2. Instale as dependências:

   pip install -r requirements.txt

   Ou use o script de configuração automatizado:

   ./setup.bat

3. Configure as variáveis de ambiente:

   • Crie um arquivo .env com os seguintes valores:

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

🏃‍♂️ Execução

Servidor MCP

Execute o servidor para disponibilizar as ferramentas via MCP:

Integração com Claude Desktop

Para usar diretamente com o Claude Desktop:

Alternativamente, instale manualmente:

Uso Direto da API (Scripts de Teste)

Para testes diretos sem um assistente:

• Criar pagamento: python test_client.py

• Verificar status: python check_payment.py

📊 Fluxo de Pagamento

1. Inicialização do Pagamento:

   • O assistente obtém do usuário o valor e outros detalhes do pagamento

   • O assistente chama a ferramenta create-payment com os parâmetros necessários

   • Um novo pagamento é criado na Gotas Commerce

   • O link de pagamento é retornado ao usuário

2. Processo de Pagamento:

   • O usuário acessa o link de pagamento fornecido

   • O usuário transfere USDT para o endereço de carteira exibido

   • A Gotas Commerce monitora a blockchain para confirmar a transação

3. Verificação de Status:

   • O assistente pode verificar o status do pagamento chamando check-payment-status

   • O status pode ser: pending (pendente), completed (concluído), expired (expirado) ou failed (falhou)

   • Quando o pagamento é confirmado, o hash da transação blockchain é disponibilizado

🔍 Especificações Técnicas

Detalhes da API

Endpoints da API Gotas Commerce:

1. Criar Pagamento

   • POST /api/v1/payments

   • Corpo da requisição:

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

2. Verificar Status do Pagamento

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

Comunicação MCP

• Transporte: SSE (Server-Sent Events)

• Formato: JSON para comunicação entre assistente e servidor MCP

• Autenticação: Chave de API armazenada como variável de ambiente

📂 Estrutura do Projeto

🔒 Segurança

• A chave de API é armazenada como variável de ambiente, não no código-fonte

• Comunicação com a API da Gotas Commerce é feita via HTTPS

• O servidor MCP valida todos os parâmetros antes de enviar para a API

• Tratamento de erros adequado para evitar exposição de informações sensíveis

🧩 Extensibilidade

O projeto foi projetado para ser facilmente extensível:

1. Novas Funcionalidades: Adicione novas ferramentas MCP implementando funções decoradas com @mcp.tool() no servidor

2. Integração com Outros Serviços: A arquitetura permite integrar facilmente outros serviços além da Gotas Commerce

3. Suporte a Novas Moedas: A estrutura está preparada para suportar outras criptomoedas além de USDT no futuro

📚 Exemplos de Uso

Criando um Pagamento (via Claude)

Verificando Status (via Claude)

📞 Suporte e Contato

Para suporte ou informações adicionais, entre em contato com a equipe de desenvolvimento da Gotas ou abra uma issue no repositório GitHub.

📜 Licença

MIT License