@marcelocorrea/mcp-safrapay 0.2.0

package/README.md

@@ -0,0 +1,335 @@
+# SafraPay MCP Server
+
+Servidor MCP (Model Context Protocol) para integração com a API SafraPay, permitindo que agentes de IA realizem operações completas de pagamento, gestão de clientes, recorrência e muito mais.
+
+## 🚀 Versão 0.2.0 - Arquitetura Agrupada com Autenticação Automática
+
+Esta versão implementa uma arquitetura agrupada onde **12 ferramentas** cobrem **110+ endpoints** da API SafraPay, ao invés de criar uma ferramenta por endpoint.
+
+### ⚡ Autenticação Automática
+
+O servidor gerencia a autenticação **completamente de forma automática**:
+- ✅ Gera token automaticamente na primeira requisição
+- ✅ Reautentica automaticamente quando o token expira (erro 401)
+- ✅ Usa as credenciais configuradas via variáveis de ambiente
+- ✅ **Você NUNCA precisa se preocupar com autenticação!**
+
+### Benefícios da Arquitetura Agrupada
+
+- ✅ **Escalável**: Não há limite de ferramentas para gerenciar
+- ✅ **Organizada**: Ferramentas agrupadas por contexto funcional
+- ✅ **Flexível**: Agente IA monta as requisições baseado na documentação
+- ✅ **Completa**: Acesso a toda a API SafraPay com documentação embarcada
+- ✅ **Automática**: Autenticação e renovação de token transparentes
+
+## 📦 Instalação
+
+```bash
+npm install
+npm run build
+```
+
+## ⚙️ Configuração
+
+Crie um arquivo `.env` na raiz do projeto:
+
+```env
+# Ambiente: HML ou PROD
+SAFRA_ENV=HML
+
+# Credenciais (obtenha no portal SafraPay)
+SAFRA_CLIENT_ID=seu-client-id
+SAFRA_CLIENT_SECRET=seu-merchant-token
+
+# Token (opcional - será gerado automaticamente)
+SAFRA_ACCESS_TOKEN=
+```
+
+## 🔧 Configuração no Claude Code
+
+Adicione ao arquivo de configuração do MCP:
+
+```json
+{
+  "mcpServers": {
+    "safrapay": {
+      "command": "node",
+      "args": ["/caminho/para/banco-safra-mcp/dist/index.js"],
+      "env": {
+        "SAFRA_ENV": "HML",
+        "SAFRA_CLIENT_SECRET": "seu-merchant-token"
+      }
+    }
+  }
+}
+```
+
+## 🛠️ Ferramentas Disponíveis
+
+O servidor expõe **12 ferramentas agrupadas** que cobrem toda a API SafraPay:
+
+### 1. `safrapay_authentication`
+Gestão de usuários SafraPay
+- CRUD de usuários
+- Listar merchants do usuário
+
+**IMPORTANTE**: A autenticação de token é **AUTOMÁTICA**. Não é necessário chamar endpoints de autenticação manualmente.
+
+### 2. `safrapay_payments`
+Processamento de pagamentos completo
+- Clientes (customers)
+- Cartão de crédito/débito
+- 3D Secure (3DS)
+- PIX
+- Boleto
+- Consulta de BIN
+- Produtos
+- Planos de taxas
+
+### 3. `safrapay_charges`
+Gestão de cobranças
+- Buscar cobrança
+- Capturar pré-autorização
+- Cancelar/estornar
+
+### 4. `safrapay_vault`
+Tokenização de cartões (Cartão Protegido)
+- Salvar cartão
+- Atualizar cartão
+- Buscar cartões
+- Cartão temporário
+- Validação zero dollar
+
+### 5. `safrapay_recurrence`
+Planos e assinaturas recorrentes
+- CRUD de planos
+- CRUD de assinaturas
+- Assinaturas em lote
+- Relatórios
+
+### 6. `safrapay_payment_link`
+Links de pagamento (SmartCheckout)
+- Criar link
+- Listar links
+- Detalhes e exclusão
+
+### 7. `safrapay_checkout`
+Sessões de checkout
+- Checkout Redirect
+- Checkout Lightbox
+- Checkout Transparente
+
+### 8. `safrapay_split`
+Split de pagamentos
+- Gestão de recebedores
+- Configuração de split
+- Extrato digital
+- Saldo disponível
+
+### 9. `safrapay_accreditation`
+Credenciamento
+- Gestão de merchants
+- Sub-merchants
+- Taxas e produtos
+- Upload de documentos
+- Reconciliação
+- Adquirentes virtuais
+
+### 10. `safrapay_webhook`
+Webhooks para eventos
+- Criar webhooks
+- Listar webhooks
+- Cancelar webhook
+
+### 11. `safrapay_chargeback`
+Gestão de disputas
+- Resumo de disputas
+- Detalhes de disputa
+- Aceitar débito
+- Representação secundária
+
+### 12. `safrapay_tef`
+Integração com PinPads
+- Fluxo transacional completo
+- Funções auxiliares
+
+## 💡 Exemplos de Uso
+
+### Exemplo 1: Criar uma transação de crédito
+
+```
+Usuário: "Crie uma transação de crédito de R$ 100,00"
+
+Agente IA usa: safrapay_payments
+{
+  "api": "GATEWAY",
+  "method": "POST",
+  "path": "/v2/charge/authorization",
+  "body": {
+    "charge": {
+      "merchantChargeId": "ORDER-123",
+      "transactions": [{
+        "card": {
+          "cardholderName": "JOAO SILVA",
+          "cardNumber": "4111111111111111",
+          "expirationMonth": 12,
+          "expirationYear": 2025,
+          "securityCode": "123"
+        },
+        "paymentType": 2,
+        "amount": 10000,
+        "installmentNumber": 1,
+        "installmentType": 0,
+        "autoCapture": true
+      }],
+      "source": 1
+    }
+  }
+}
+```
+
+### Exemplo 2: Criar cobrança PIX
+
+```
+Usuário: "Crie uma cobrança PIX de R$ 50,00"
+
+Agente IA usa: safrapay_payments
+{
+  "api": "GATEWAY",
+  "method": "POST",
+  "path": "/v2/charge/pix",
+  "body": {
+    "charge": {
+      "merchantChargeId": "PIX-456",
+      "transactions": [{
+        "amount": 5000,
+        "paymentType": "Pix"
+      }],
+      "source": 1
+    }
+  }
+}
+```
+
+### Exemplo 3: Criar assinatura recorrente
+
+```
+Usuário: "Crie uma assinatura mensal de R$ 99,90"
+
+Passo 1 - Criar plano (safrapay_recurrence):
+{
+  "api": "PORTAL",
+  "method": "POST",
+  "path": "/plan",
+  "body": {
+    "name": "Plano Premium",
+    "amount": 9990,
+    "interval": 3,
+    "intervalCount": 1
+  }
+}
+
+Passo 2 - Criar assinatura (safrapay_recurrence):
+{
+  "api": "GATEWAY",
+  "method": "POST",
+  "path": "/subscription",
+  "body": {
+    "planId": "plan-123",
+    "customerId": "customer-456",
+    "cardToken": "token-abc"
+  }
+}
+```
+
+## 📚 Documentação Completa
+
+Consulte os arquivos na raiz do projeto:
+
+- **`SAFRAPAY_API_MAPPING.md`**: Mapeamento completo de todas as rotas organizadas por grupo
+- **`API_DOCUMENTATION.md`**: Documentação técnica detalhada com exemplos de request/response
+
+## 🔑 Enumeradores Importantes
+
+### Status de Transação
+- `1` - Pendente
+- `2` - Autorizada
+- `3` - Capturada
+- `4` - Cancelada
+- `5` - Negada
+- `6` - Estornada
+
+### Tipos de Pagamento
+- `2` - Crédito
+- `3` - Débito
+- `4` - Boleto
+- `5` - PIX
+- `"Pix"` - PIX (string)
+- `"Boleto"` - Boleto (string)
+
+### Tipos de Parcelamento
+- `0` - À vista
+- `2` - Emissor (com juros)
+- `3` - Lojista (sem juros)
+
+### Intervalos de Recorrência
+- `1` - Diário
+- `2` - Semanal
+- `3` - Mensal
+- `4` - Anual
+
+### Source (Origem)
+- `1` - E-commerce/API
+- `2` - Mobile
+- `3` - Recorrência
+- `4` - Telefone
+
+## 🌐 Ambientes
+
+### Homologação (HML)
+- Portal API: `https://portal-api-hml.safrapay.com.br`
+- Gateway API: `https://payment-hml.safrapay.com.br`
+- Reconciliation API: `https://reconciliation-api-hml.safrapay.com.br`
+
+### Produção (PROD)
+- Portal API: `https://portal-api.safrapay.com.br`
+- Gateway API: `https://payment.safrapay.com.br`
+- Reconciliation API: `https://reconciliation-api.safrapay.com.br`
+
+## ⚡ Desenvolvimento
+
+```bash
+# Compilar
+npm run build
+
+# Modo watch (desenvolvimento)
+npm run dev
+
+# Executar
+npm start
+```
+
+## 🔒 Segurança
+
+- NUNCA armazene dados de cartão completos
+- Use tokenização sempre que possível
+- Implemente validação zero dollar antes de cobranças recorrentes
+- Utilize HTTPS em todos os endpoints
+- Monitore transações suspeitas
+
+## 🤝 Contribuindo
+
+Este é um projeto em desenvolvimento ativo. Sugestões e melhorias são bem-vindas!
+
+## 📄 Licença
+
+ISC
+
+## 👤 Autor
+
+Marcelo Correa
+
+---
+
+**Versão**: 0.2.0
+**Última atualização**: Janeiro 2026

package/dist/index.js

@@ -0,0 +1,564 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const axios_1 = __importDefault(require("axios"));
+const zod_to_json_schema_1 = require("zod-to-json-schema");
+const dotenv_1 = __importDefault(require("dotenv"));
+const zod_1 = require("zod");
+dotenv_1.default.config();
+// --- Configuração de Constantes e Tipos ---
+const API_ENVS = {
+    HML: {
+        PORTAL: "https://portal-api-hml.safrapay.com.br",
+        GATEWAY: "https://payment-hml.safrapay.com.br",
+        RECONCILIATION: "https://reconciliation-api-hml.safrapay.com.br"
+    },
+    PROD: {
+        PORTAL: "https://portal-api.safrapay.com.br",
+        GATEWAY: "https://payment.safrapay.com.br",
+        RECONCILIATION: "https://reconciliation-api.safrapay.com.br"
+    }
+};
+class SafraPayServer {
+    server;
+    env;
+    axiosInstances;
+    token = null;
+    merchantToken;
+    isAuthenticating = false;
+    constructor() {
+        this.server = new index_js_1.Server({
+            name: "@marcelocorrea/mcp-safrapay",
+            version: "0.2.0",
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        // Determina ambiente (Default: HML para segurança)
+        this.env = (process.env.SAFRA_ENV === "PROD") ? "PROD" : "HML";
+        this.token = process.env.SAFRA_ACCESS_TOKEN || null;
+        // Valida se o MerchantToken está configurado
+        const merchantToken = process.env.SAFRA_CLIENT_SECRET;
+        if (!merchantToken) {
+            throw new Error("SAFRA_CLIENT_SECRET (MerchantToken) não configurado. " +
+                "Por favor, configure a variável de ambiente antes de iniciar o servidor.");
+        }
+        this.merchantToken = merchantToken;
+        console.error(`[SafraPay MCP] Ambiente: ${this.env}`);
+        console.error(`[SafraPay MCP] Token configurado: ${this.token ? "Sim" : "Não (será gerado automaticamente)"}`);
+        console.error(`[SafraPay MCP] MerchantToken presente: Sim`);
+        // Inicializa instâncias Axios para cada serviço base
+        this.axiosInstances = {
+            PORTAL: this.createAxiosInstance(API_ENVS[this.env].PORTAL),
+            GATEWAY: this.createAxiosInstance(API_ENVS[this.env].GATEWAY),
+            RECONCILIATION: this.createAxiosInstance(API_ENVS[this.env].RECONCILIATION),
+        };
+        this.setupToolHandlers();
+        // Error handling
+        this.server.onerror = (error) => console.error("[MCP Error]", error);
+        process.on("SIGINT", async () => {
+            await this.server.close();
+            process.exit(0);
+        });
+    }
+    createAxiosInstance(baseURL) {
+        const instance = axios_1.default.create({
+            baseURL,
+            headers: {
+                "Content-Type": "application/json",
+            },
+        });
+        // Interceptor de requisição: adiciona token
+        instance.interceptors.request.use((config) => {
+            if (this.token) {
+                config.headers.Authorization = `Bearer ${this.token}`;
+            }
+            return config;
+        });
+        // Interceptor de resposta: reautentica automaticamente em caso de 401
+        instance.interceptors.response.use((response) => response, async (error) => {
+            const originalRequest = error.config;
+            // Se recebeu 401 e ainda não tentou reautenticar
+            if (error.response?.status === 401 && !originalRequest._retry) {
+                originalRequest._retry = true;
+                try {
+                    // Reautentica automaticamente
+                    await this.autoAuthenticate();
+                    // Atualiza o header com o novo token
+                    originalRequest.headers.Authorization = `Bearer ${this.token}`;
+                    // Retenta a requisição original
+                    return instance(originalRequest);
+                }
+                catch (authError) {
+                    console.error("[SafraPay MCP] Falha na reautenticação automática:", authError);
+                    return Promise.reject(error);
+                }
+            }
+            return Promise.reject(error);
+        });
+        return instance;
+    }
+    /**
+     * Autentica automaticamente usando as credenciais configuradas
+     */
+    async autoAuthenticate() {
+        // Evita múltiplas chamadas simultâneas de autenticação
+        if (this.isAuthenticating) {
+            await new Promise(resolve => setTimeout(resolve, 1000));
+            return;
+        }
+        this.isAuthenticating = true;
+        try {
+            console.error("[SafraPay MCP] Gerando novo token automaticamente...");
+            const response = await axios_1.default.post(`${API_ENVS[this.env].PORTAL}/v1/Login/GenerateToken`, {}, {
+                headers: {
+                    "MerchantToken": this.merchantToken,
+                    "Content-Type": "application/json"
+                }
+            });
+            if (response.data && response.data.generatedToken) {
+                this.token = response.data.generatedToken;
+                console.error("[SafraPay MCP] Token gerado com sucesso!");
+            }
+            else {
+                throw new Error("Token não retornado pela API");
+            }
+        }
+        finally {
+            this.isAuthenticating = false;
+        }
+    }
+    setupToolHandlers() {
+        this.server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+            tools: [
+                {
+                    name: "safrapay_authentication",
+                    description: `Gestão de usuários SafraPay.
+
+NOTA: A autenticação de token é AUTOMÁTICA. O servidor reautentica automaticamente quando necessário usando as credenciais configuradas via variáveis de ambiente. Você NÃO precisa chamar os endpoints de autenticação manualmente.
+
+GESTÃO DE USUÁRIOS:
+- POST /v1/User - Criar: { name, email, password, phone?, role? }
+- GET /v1/User - Buscar: query { userId? }
+- PUT /v1/User - Atualizar: { userId, name?, email?, phone? }
+- GET /v1/User/Merchants - Listar merchants: query { currentPage?, pageSize?, sortDirection? }
+- DELETE /v1/User/{userId} - Deletar
+
+Use 'api' para especificar PORTAL ou GATEWAY, 'method' para o verbo HTTP, 'path' para o endpoint e 'body' para dados.`,
+                    inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(zod_1.z.object({
+                        api: zod_1.z.enum(["PORTAL", "GATEWAY"]).describe("API base (PORTAL ou GATEWAY)"),
+                        method: zod_1.z.enum(["GET", "POST", "PUT", "DELETE"]).describe("Método HTTP"),
+                        path: zod_1.z.string().describe("Caminho do endpoint"),
+                        body: zod_1.z.record(zod_1.z.any()).optional().describe("Corpo da requisição JSON"),
+                        params: zod_1.z.record(zod_1.z.any()).optional().describe("Query parameters"),
+                    })),
+                },
+                {
+                    name: "safrapay_payments",
+                    description: `Processamento de pagamentos: cartão, PIX, boleto, produtos e taxas.
+
+CLIENTES (Customers):
+- POST /customer - Criar: { merchantCustomerId, name, email?, birthDate?, phone?, document?, address? }
+- PUT /customer - Atualizar: mesma estrutura
+- GET /customer - Buscar: query { customerId?, merchantCustomerId? }
+
+CARTÃO DE CRÉDITO:
+- POST /v2/charge/authorization - Transação: { charge: { merchantChargeId, customer?, transactions: [{ card: { cardholderName, cardNumber, expirationMonth, expirationYear, securityCode }, paymentType: 2, amount, installmentNumber, installmentType, autoCapture?, softDescriptor? }], source: 1 } }
+- POST /v2/charge/preauthorization - Pré-autorização
+- POST /v2/charge/preauthorization/incremental - Incremental: { chargeId, transactionId, incrementalAmount }
+- POST /v2/charge/capture - Captura: { chargeId, transactionId?, amount? }
+
+3DS (3D Secure):
+- POST /v2/charge/ecommerce/3ds/setup - Setup
+- PUT /v2/charge/ecommerce/3ds/enrollment - Enrollment
+- PUT /v2/charge/ecommerce - Transação 3DS
+
+PIX:
+- POST /v2/charge/pix - Criar: { charge: { merchantChargeId, transactions: [{ amount, paymentType: "Pix", expirationDate? }], source: 1 } }
+  Response: { chargeId, transactions: [{ qrCode, qrCodeText }] }
+
+BOLETO:
+- POST /v2/charge/boleto - Criar: { charge: { merchantChargeId, customer, transactions: [{ amount, paymentType: "Boleto", dueDate, instructions?, fine?, interest?, discount? }] } }
+- GET /v2/charge/{chargeId}/boleto/{transactionId} - Consultar
+
+BIN:
+- GET /Card/Bin/Brand/{bin} - Consultar bandeira
+
+PRODUTOS:
+- POST /v1/product - Criar: { name, description?, price, sku?, active? }
+- GET /v1/product - Listar: query { currentPage?, pageSize?, active? }
+- PUT /v1/product/{productId} - Atualizar
+- GET /v1/product/{productId} - Buscar
+
+TAXAS:
+- POST /tax - Criar: { name, description?, fees: [{ paymentType, installmentNumber, fee, fixedFee? }] }
+- GET /tax - Listar
+- PUT /tax - Atualizar
+- DELETE /tax/{taxPlanId} - Deletar
+- PUT /tax/Activate/{taxPlanId} - Ativar
+
+VALORES: em centavos (1000 = R$ 10,00)
+paymentType: 2=Crédito, 3=Débito
+installmentType: 0=À vista, 2=Com juros, 3=Sem juros`,
+                    inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(zod_1.z.object({
+                        api: zod_1.z.enum(["PORTAL", "GATEWAY"]).describe("API base"),
+                        method: zod_1.z.enum(["GET", "POST", "PUT", "DELETE"]).describe("Método HTTP"),
+                        path: zod_1.z.string().describe("Caminho do endpoint"),
+                        body: zod_1.z.record(zod_1.z.any()).optional().describe("Corpo JSON"),
+                        params: zod_1.z.record(zod_1.z.any()).optional().describe("Query parameters"),
+                    })),
+                },
+                {
+                    name: "safrapay_charges",
+                    description: `Gestão de cobranças: buscar, capturar e cancelar.
+
+ENDPOINTS:
+- GET /v2/charge/{chargeId} - Buscar cobrança
+  Response: { chargeId, merchantChargeId, status, amount, transactions: [...] }
+
+- POST /v2/charge/capture - Capturar cobrança pré-autorizada
+  Body: { chargeId, transactionId?, amount? }
+
+- POST /v2/charge/cancelation - Cancelar/Estornar cobrança
+  Body: { chargeId, transactionId?, amount? }
+
+STATUS: 1=Pendente, 2=Autorizada, 3=Capturada, 4=Cancelada, 5=Negada, 6=Estornada`,
+                    inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(zod_1.z.object({
+                        method: zod_1.z.enum(["GET", "POST"]).describe("Método HTTP"),
+                        path: zod_1.z.string().describe("Caminho do endpoint (ex: /v2/charge/{chargeId})"),
+                        body: zod_1.z.record(zod_1.z.any()).optional().describe("Corpo JSON"),
+                    })),
+                },
+                {
+                    name: "safrapay_vault",
+                    description: `Tokenização e armazenamento seguro de cartões (Cartão Protegido).
+
+CARTÃO:
+- POST /card - Salvar: { customerId, card: { cardholderName, cardNumber, expirationMonth, expirationYear, securityCode }, alias? }
+  Response: { cardToken, maskedCardNumber, cardBrand }
+
+- PUT /card - Atualizar: { cardToken, expirationMonth?, expirationYear?, alias? }
+
+- GET /card - Buscar: query { cardToken }
+
+- GET /card/byCustomer - Por cliente: query { customerId }
+
+- DELETE /card/{cardId} - Deletar
+
+CARTÃO TEMPORÁRIO:
+- POST /temporary/card - Criar: { card: {...} }
+  Response: { temporaryToken, expiresIn }
+
+VALIDAÇÃO ZERO DOLLAR:
+- POST /card/validation/zerodollar - Validar: { customerId, card: {...} }
+  Response: { cardToken, validationResult, transactionId }
+
+Use cardToken nas transações ao invés dos dados completos do cartão.`,
+                    inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(zod_1.z.object({
+                        method: zod_1.z.enum(["GET", "POST", "PUT", "DELETE"]).describe("Método HTTP"),
+                        path: zod_1.z.string().describe("Caminho do endpoint"),
+                        body: zod_1.z.record(zod_1.z.any()).optional().describe("Corpo JSON"),
+                        params: zod_1.z.record(zod_1.z.any()).optional().describe("Query parameters"),
+                    })),
+                },
+                {
+                    name: "safrapay_recurrence",
+                    description: `Gestão de planos e assinaturas recorrentes.
+
+PLANOS:
+- POST /plan - Criar: { name, description?, amount, interval: 1-4 (1=Diário, 2=Semanal, 3=Mensal, 4=Anual), intervalCount, trialDays?, cycles?, active? }
+- PUT /plan - Atualizar: { planId, ... }
+- GET /plan/all - Listar: query { currentPage?, pageSize?, active? }
+- DELETE /plan - Deletar: query { planId }
+
+ASSINATURAS:
+- POST /subscription - Criar: { planId, customerId, cardToken?, startDate?, description?, metadata? }
+- POST /subscription/bulk - Em lote: { subscriptions: [{...}] }
+- PUT /subscription/cancelation/{subscriptionId} - Cancelar: { cancelReason? }
+- GET /subscription/{subscriptionId} - Buscar
+- GET /subscription - Listar: query { currentPage?, pageSize?, status?, customerId? }
+- GET /subscription/report - Relatório: query { startDate, endDate, format? }
+- PATCH /subscription/{subscriptionId} - Atualizar: { cardToken?, metadata? }
+
+VALORES: amount em centavos
+cycles: null = infinito`,
+                    inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(zod_1.z.object({
+                        api: zod_1.z.enum(["PORTAL", "GATEWAY"]).describe("API base"),
+                        method: zod_1.z.enum(["GET", "POST", "PUT", "DELETE", "PATCH"]).describe("Método HTTP"),
+                        path: zod_1.z.string().describe("Caminho do endpoint"),
+                        body: zod_1.z.record(zod_1.z.any()).optional().describe("Corpo JSON"),
+                        params: zod_1.z.record(zod_1.z.any()).optional().describe("Query parameters"),
+                    })),
+                },
+                {
+                    name: "safrapay_payment_link",
+                    description: `Links de pagamento (SmartCheckout).
+
+ENDPOINTS:
+- POST /paymentlink - Criar: { name, description?, amount, maxInstallments?, expirationDate?, paymentTypes?, metadata? }
+  Response: { smartcheckoutId, url }
+
+- GET /smartcheckout/{smartcheckoutId}/detail - Detalhes
+
+- DELETE /smartcheckout/{smartcheckoutId} - Deletar
+
+- GET /smartcheckout - Listar: query { currentPage?, pageSize?, status? }
+
+paymentTypes: 2=Crédito, 3=Débito, 4=Boleto, 5=Pix`,
+                    inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(zod_1.z.object({
+                        method: zod_1.z.enum(["GET", "POST", "DELETE"]).describe("Método HTTP"),
+                        path: zod_1.z.string().describe("Caminho do endpoint"),
+                        body: zod_1.z.record(zod_1.z.any()).optional().describe("Corpo JSON"),
+                        params: zod_1.z.record(zod_1.z.any()).optional().describe("Query parameters"),
+                    })),
+                },
+                {
+                    name: "safrapay_checkout",
+                    description: `Criação de sessões de checkout com SDK.
+
+ENDPOINTS:
+- POST /smartcheckout - Criar: { charge: { merchantChargeId, amount, customer?, source: 1 }, settings: { type: 1-3 (1=Redirect, 2=Lightbox, 3=Transparente), paymentTypes?, maxInstallments?, returnUrl?, callbackUrl? } }
+  Response: { smartcheckoutId, url?, token? }
+
+- GET /smartcheckout/{smartcheckoutId}/detail - Detalhes
+
+SDKs disponíveis para integração frontend.`,
+                    inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(zod_1.z.object({
+                        method: zod_1.z.enum(["GET", "POST"]).describe("Método HTTP"),
+                        path: zod_1.z.string().describe("Caminho do endpoint"),
+                        body: zod_1.z.record(zod_1.z.any()).optional().describe("Corpo JSON"),
+                    })),
+                },
+                {
+                    name: "safrapay_split",
+                    description: `Split de pagamentos entre múltiplos recebedores.
+
+RECEBEDORES:
+- POST /receiver - Criar: { name, document: { type: 1-2 (1=CPF, 2=CNPJ), number }, bankAccount: { bank, agency, agencyDigit?, account, accountDigit, accountType: 1-2 (1=Corrente, 2=Poupança) }, email?, phone? }
+  Response: { receiverId }
+- PUT /receiver - Atualizar: { receiverId, ... }
+- GET /receiver/{receiverId} - Buscar
+
+SPLIT:
+- PUT /charge/split/ - Configurar: { chargeId, splits: [{ receiverId, type: 1-2 (1=Percentual, 2=Fixo), value, feeResponsible }] }
+
+EXTRATO (Reconciliation API):
+- GET /Account/Movement/Extract - query { startDate, endDate, receiverId?, currentPage?, pageSize? }
+- GET /Future/Movement/Resume - query { receiverId? }
+- GET /Account/Movement/Amount/Available - query { receiverId? }`,
+                    inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(zod_1.z.object({
+                        api: zod_1.z.enum(["PORTAL", "GATEWAY", "RECONCILIATION"]).describe("API base"),
+                        method: zod_1.z.enum(["GET", "POST", "PUT"]).describe("Método HTTP"),
+                        path: zod_1.z.string().describe("Caminho do endpoint"),
+                        body: zod_1.z.record(zod_1.z.any()).optional().describe("Corpo JSON"),
+                        params: zod_1.z.record(zod_1.z.any()).optional().describe("Query parameters"),
+                    })),
+                },
+                {
+                    name: "safrapay_accreditation",
+                    description: `Credenciamento: gestão de estabelecimentos (merchants) e adquirentes virtuais.
+
+ESTABELECIMENTO:
+- POST /v1/Merchant - Criar: { name, tradeName, document: { type, number }, email, phone, address, businessCategory, mcc, parentMerchantId? }
+- PUT /v1/Merchant - Atualizar: { merchantId, ... }
+- DELETE /v1/Merchant - Deletar: query { merchantId }
+- GET /v1/Merchant - Listar: query { currentPage?, pageSize? }
+- GET /v1/Merchant/{merchantId} - Buscar
+- GET /v1/Merchant/GetChildMerchantsByParentId - Sub-merchants: query { parentMerchantId }
+- GET /v1/Merchant/GetByUserId - Por usuário: query { userId }
+- GET /v1/Merchant/{merchantId}/Taxes - Taxas
+- GET /v1/Merchant/Mcc - Listar MCCs
+- GET /v1/Merchant/Terminal - Terminais: query { merchantId? }
+- GET /v1/Merchant/{merchantId}/BankSlipTaxesPlan - Taxas boleto
+- GET /v1/Merchant/Taxes/Products - Produtos de taxas
+- PUT /v1/Merchant/{merchantId}/Taxes/Products - Atualizar produtos: { products: [{ productId, active }] }
+- PUT /v1/Merchant/UploadDocuments - Upload docs (multipart/form-data)
+- POST /v1/Merchant/{merchantId}/Reconciliation - Criar reconciliação: { acquirerId, clientId, clientSecret }
+- DELETE /v1/Merchant/{merchantId}/Reconciliation/{acquirerId}/{clientId} - Deletar
+- PATCH /v1/Merchant/{merchantId}/Reconciliation/{acquirerId}/{clientId} - Atualizar: { clientSecret?, active? }
+
+ADQUIRENTE VIRTUAL:
+- POST /VirtualAcquirer - Criar: { name, cnpj, active? }
+- GET /VirtualAcquirer - Listar
+- PUT /VirtualAcquirer/{virtualAcquirerId} - Atualizar
+- DELETE /VirtualAcquirer/{virtualAcquirerId} - Deletar`,
+                    inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(zod_1.z.object({
+                        method: zod_1.z.enum(["GET", "POST", "PUT", "DELETE", "PATCH"]).describe("Método HTTP"),
+                        path: zod_1.z.string().describe("Caminho do endpoint"),
+                        body: zod_1.z.record(zod_1.z.any()).optional().describe("Corpo JSON"),
+                        params: zod_1.z.record(zod_1.z.any()).optional().describe("Query parameters"),
+                        isMultipart: zod_1.z.boolean().optional().describe("true para upload de arquivos"),
+                    })),
+                },
+                {
+                    name: "safrapay_webhook",
+                    description: `Configuração de webhooks para notificações de eventos.
+
+ENDPOINTS:
+- POST /webhook/bulk - Criar: { url, events: ["CHARGE_PAID", "CHARGE_REFUNDED", "CHARGE_CANCELED", "CHARGE_CHARGEBACK", "SUBSCRIPTION_CREATED", "SUBSCRIPTION_CANCELED", "SUBSCRIPTION_PAYMENT_SUCCESS", "SUBSCRIPTION_PAYMENT_FAILED"], active?, headers? }
+
+- GET /webhook - Listar: query { currentPage?, pageSize? }
+
+- PUT /Webhook/Cancel/{webhookId} - Cancelar
+
+EVENTOS:
+- CHARGE_PAID: Cobrança paga
+- CHARGE_REFUNDED: Estornada
+- CHARGE_CANCELED: Cancelada
+- CHARGE_CHARGEBACK: Chargeback
+- SUBSCRIPTION_*: Eventos de assinatura`,
+                    inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(zod_1.z.object({
+                        method: zod_1.z.enum(["GET", "POST", "PUT"]).describe("Método HTTP"),
+                        path: zod_1.z.string().describe("Caminho do endpoint"),
+                        body: zod_1.z.record(zod_1.z.any()).optional().describe("Corpo JSON"),
+                        params: zod_1.z.record(zod_1.z.any()).optional().describe("Query parameters"),
+                    })),
+                },
+                {
+                    name: "safrapay_chargeback",
+                    description: `Gestão de disputas e chargebacks.
+
+ENDPOINTS:
+- GET /v1/disputes/summary - Resumo: query { startDate?, endDate? }
+
+- GET /v1/disputes/total - Total: query { status? }
+
+- GET /v1/disputes/{disputeId} - Detalhes
+
+- POST /v1/disputes/{disputeId}/debts/accept - Aceitar débito: { acceptReason? }
+
+- POST /v1/disputes/second-presentment - Representação (multipart): { disputeId, documents: File[], description }`,
+                    inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(zod_1.z.object({
+                        method: zod_1.z.enum(["GET", "POST"]).describe("Método HTTP"),
+                        path: zod_1.z.string().describe("Caminho do endpoint"),
+                        body: zod_1.z.record(zod_1.z.any()).optional().describe("Corpo JSON"),
+                        params: zod_1.z.record(zod_1.z.any()).optional().describe("Query parameters"),
+                        isMultipart: zod_1.z.boolean().optional().describe("true para upload de documentos"),
+                    })),
+                },
+                {
+                    name: "safrapay_tef",
+                    description: `Integração com PinPads via protocolo TEF.
+
+FLUXO TRANSACIONAL:
+- POST /Init - Inicializar: { terminalId, softwareVersion }
+- POST /Payment - Pagamento: { amount, installments, transactionType }
+- GET /Abort - Abortar
+- GET /Cancelation - Cancelar: query { transactionId, amount? }
+- GET /Reversal - Estornar: query { transactionId }
+- GET /GetPending - Buscar pendências
+- GET /Confirm - Confirmar: query { transactionId }
+
+FUNÇÕES AUXILIARES:
+- GET /Display - Display
+- POST /DataPicker - Seletor: { options: string[], message }
+- GET /WaitEvent - Aguardar evento
+- GET /Status - Status
+- GET /RemoveCard - Remover cartão`,
+                    inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(zod_1.z.object({
+                        method: zod_1.z.enum(["GET", "POST"]).describe("Método HTTP"),
+                        path: zod_1.z.string().describe("Caminho do endpoint"),
+                        body: zod_1.z.record(zod_1.z.any()).optional().describe("Corpo JSON"),
+                        params: zod_1.z.record(zod_1.z.any()).optional().describe("Query parameters"),
+                    })),
+                },
+            ],
+        }));
+        this.server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+            try {
+                const toolName = request.params.name;
+                const args = request.params.arguments;
+                // Todas as ferramentas agrupadas usam o mesmo handler genérico
+                if (toolName.startsWith("safrapay_")) {
+                    return await this.handleGroupedTool(toolName, args);
+                }
+                throw new types_js_1.McpError(types_js_1.ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
+            }
+            catch (error) {
+                const errorMessage = error.response?.data
+                    ? JSON.stringify(error.response.data)
+                    : error.message;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Erro na execução: ${errorMessage}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+    }
+    async handleGroupedTool(toolName, args) {
+        const { api, method, path, body, params, headers, isMultipart } = args;
+        // Determina qual API usar baseado no contexto
+        let apiType;
+        if (toolName === "safrapay_authentication") {
+            apiType = api || "PORTAL";
+        }
+        else if (toolName === "safrapay_payments") {
+            apiType = api || "GATEWAY";
+        }
+        else if (toolName === "safrapay_charges" || toolName === "safrapay_vault" || toolName === "safrapay_checkout" || toolName === "safrapay_tef") {
+            apiType = "GATEWAY";
+        }
+        else if (toolName === "safrapay_recurrence") {
+            apiType = api || (path.includes("/plan") ? "PORTAL" : "GATEWAY");
+        }
+        else if (toolName === "safrapay_payment_link") {
+            apiType = "PORTAL";
+        }
+        else if (toolName === "safrapay_split") {
+            apiType = api || (path.includes("/Account") || path.includes("/Future") ? "RECONCILIATION" : "PORTAL");
+        }
+        else if (toolName === "safrapay_accreditation" || toolName === "safrapay_webhook" || toolName === "safrapay_chargeback") {
+            apiType = "PORTAL";
+        }
+        else {
+            apiType = api || "GATEWAY";
+        }
+        const instance = this.axiosInstances[apiType];
+        const config = {
+            method,
+            url: path,
+            data: body,
+            params,
+            headers: headers || {},
+        };
+        if (isMultipart) {
+            config.headers = {
+                ...config.headers,
+                "Content-Type": "multipart/form-data",
+            };
+        }
+        // Se não há token, autentica antes da primeira requisição
+        if (!this.token) {
+            await this.autoAuthenticate();
+        }
+        // Executa a requisição (o interceptor cuida da reautenticação automática se necessário)
+        const response = await instance.request(config);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    async run() {
+        const transport = new stdio_js_1.StdioServerTransport();
+        await this.server.connect(transport);
+        console.error(`SafraPay MCP Server v0.2.0 running on stdio [Env: ${this.env}]`);
+    }
+}
+const server = new SafraPayServer();
+server.run().catch(console.error);

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@marcelocorrea/mcp-safrapay",
+  "version": "0.2.0",
+  "description": "MCP Server for SafraPay Integration",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "mcp-safrapay": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "safrapay",
+    "safra",
+    "model-context-protocol",
+    "payment",
+    "payment-gateway",
+    "pix",
+    "boleto",
+    "credit-card",
+    "brasil",
+    "brazil"
+  ],
+  "author": "Marcelo Correa",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marcelocorrea/mcp-safrapay.git"
+  },
+  "homepage": "https://github.com/marcelocorrea/mcp-safrapay#readme",
+  "bugs": {
+    "url": "https://github.com/marcelocorrea/mcp-safrapay/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.1",
+    "axios": "^1.6.0",
+    "dotenv": "^16.0.0",
+    "zod": "^3.22.0",
+    "zod-to-json-schema": "^3.25.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}