@mupag/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# @mupag/mcp-server
+
+Identidade no MCP Registry: `br.com.mupag/mcp-server`.
+
+Servidor MCP oficial da MuPag para operar **somente no ambiente sandbox** por meio do SDK Node oficial.
+
+Ferramentas disponíveis:
+
+- criar cobrança PIX ou cartão B2B direto;
+- criar sessão real de checkout hospedado;
+- criar e cancelar assinatura;
+- solicitar estorno total explícito ou parcial;
+- listar cobranças e consultar estornos para reconciliação.
+
+Não existem fallback de chave, ambiente implícito, saldo fictício, cliente fictício nem URL de pagamento fabricada. Cada mutação exige `Idempotency-Key`, uma referência de aprovação e confirmação explícita do efeito financeiro. Toda cobrança envia identidade completa do customer (`id` quando existente, nome, email e CPF/CNPJ); cartão exige token opaco Asaas, `payer_ip` literal atestado pelo lojista e somente 1x. PAN/CVV e `soft_descriptor` não são aceitos.
+
+## Configuração
+
+Node.js 20 ou superior é obrigatório. Defina também:
+
+```env
+MUPAG_API_KEY=sk_test_sua_chave_aqui
+MUPAG_ENV=test
+```
+
+`MUPAG_API_URL` é opcional para desenvolvimento local. HTTPS é obrigatório fora de loopback; a URL não pode conter credenciais, path, query ou fragmento.
+
+Exemplo para clientes MCP baseados em JSON:
+
+```json
+{
+  "mcpServers": {
+    "mupag": {
+      "command": "npx",
+      "args": ["-y", "@mupag/mcp-server@0.1.0"],
+      "env": {
+        "MUPAG_API_KEY": "sk_test_sua_chave_aqui",
+        "MUPAG_ENV": "test"
+      }
+    }
+  }
+}
+```
+
+O processo falha fechado se uma variável obrigatória estiver ausente, se chave e ambiente divergirem ou se `prd` for selecionado. Nunca inclua chave, dados de cliente ou payload financeiro em `approval_reference`; use apenas um identificador interno não sensível do workflow aprovado.
+
+O pacote npm é a fonte imutável do release. A entrada no MCP Registry e os diretórios de terceiros devem apontar exatamente para `@mupag/mcp-server@0.1.0`; não use `latest` em automações financeiras.
+
+## Desenvolvimento local
+
+```bash
+npm install
+npm run check
+MUPAG_API_KEY=sk_test_sua_chave_aqui MUPAG_ENV=test npm start
+```
+
+O log de auditoria contém somente nome da ferramenta, referência de aprovação, hashes do payload/chave de idempotência e timestamp. Erros retornados ao agente não incluem mensagem bruta, stack trace, segredo, PII ou caminho local.