Gotas Commerce MCP Server

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