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.

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

📋 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:

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

Integração com Claude Desktop

Para usar diretamente com o Claude Desktop:

python install_claude.py

Alternativamente, instale manualmente:

mcp install src.gotas_mcp_server.py

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

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

🔒 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)

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.

Verificando Status (via 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.

📞 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