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

Clone este repositório:

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

Instale as dependências:
```
pip install -r requirements.txt
```
Ou use o script de configuração automatizado:
```
./setup.bat
```
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

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

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"
}

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:

Novas Funcionalidades: Adicione novas ferramentas MCP implementando funções decoradas com @mcp.tool() no servidor
Integração com Outros Serviços: A arquitetura permite integrar facilmente outros serviços além da Gotas Commerce
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