fin-app-mcp 2.3.4 → 3.0.0

package/index.mjs

@@ -343,14 +343,14 @@ REGRAS DE NEGÓCIO:
   // ── Mutações ──────────────────────────────────────────────────────
   {
     name: "fin_criar_despesa",
-    description: `Cria uma despesa. Também usada para lançar ESTORNOS em cartão de crédito (via reversal_of_id). Suporta parcelamento automático.
+    description: `Cria uma despesa. Suporta parcelamento automático e multi-moeda.
 
 QUANDO USAR:
 - Lançar uma despesa normal (compra, conta, assinatura).
-- Lançar um ESTORNO/CANCELAMENTO em cartão de crédito — usar com reversal_of_id.
 - Lançar uma compra parcelada — usar com installments.
 
 NÃO USAR QUANDO:
+- Quiser lançar ESTORNO/CANCELAMENTO em cartão — usar fin_criar_estorno (rota dedicada, valida ownership e invariants atomicamente).
 - Quiser lançar receita (usar fin_criar_receita).
 - Quiser registrar pagamento de fatura de cartão (usar fin_pagar_fatura).
 - Quiser transferir entre contas (usar fin_criar_transferencia).
@@ -365,20 +365,11 @@ CAMPOS:
 - essential: boolean — se é despesa essencial.
 - installments: number — número de parcelas (2-48). Gera N transações separadas automaticamente.
 - current_installment: number — parcela inicial (default: 1). Passar 1 é equivalente ao default — o sistema cria todas as N parcelas começando da primeira. Use valores > 1 APENAS quando registrando uma compra parcelada que já está em andamento e você quer criar apenas as parcelas futuras (ex: installments=10, current_installment=3 cria 8 transações, da parcela 3 à 10).
-- reversal_of_id: string UUID — ID da transação original para estorno.
-- reversal_kind: string — 'full' ou 'partial' (obrigatório quando reversal_of_id é informado).
 - tags: string[] — tags livres pra cortes ortogonais (ex: ["TDAH-tracking", "Lou-shared"]).
 - original_purchase_date: string YYYY-MM-DD — data REAL da compra (use junto com installments>1 e current_installment>1 em cartão para o FIN colocar cada parcela na fatura certa a partir do cutoff do cartão).
 - original_amount_cents: number — valor na moeda estrangeira (ex: 2000 = US$ 20,00). Use quando a despesa foi em USD.
 - original_currency: 'BRL' | 'USD' — moeda de original_amount_cents.
-- exchange_rate_cents_per_unit: number — cotação em 1/10000 (51023 = R$ 5,1023 por 1 USD). Opcional; use quando NÃO passar amount_cents (backend deriva BRL).
-
-REGRAS DE NEGÓCIO — ESTORNO:
-- Para estorno em cartão: criar despesa com reversal_of_id = UUID da transação original.
-- O amount_cents é POSITIVO — o sistema inverte automaticamente na fatura.
-- O account_name DEVE ser o mesmo cartão da transação original.
-- NUNCA usar fin_criar_receita para estorno em cartão — receita SOMA na fatura em vez de subtrair.
-- A transação original deve existir, ser expense, e não ser outro estorno.
+- exchange_rate: number — cotação em decimal (5.1023 = R$ 5,1023 por 1 USD). Opcional; use quando NÃO passar amount_cents (backend deriva BRL).
 
 REGRAS DE NEGÓCIO — PARCELAMENTO:
 - installments: N gera N transações separadas, cada uma em um mês consecutivo.
@@ -394,7 +385,7 @@ REGRAS DE NEGÓCIO — MULTI-MOEDA (USD):
 - amount_cents é SEMPRE em BRL. Para despesas em USD, pergunte à pessoa: "cotação automática ou valor exato em BRL que saiu?".
 - Conta USD EXIGE original_amount_cents + original_currency: "USD". Passar só amount_cents numa conta USD retorna 422.
 - Modo (a) — pessoa informa o BRL exato: passar amount_cents (BRL) + original_amount_cents + original_currency. O backend grava BRL como fonte da verdade e deriva exchange_rate.
-- Modo (b) — pessoa só sabe a cotação: passar original_amount_cents + original_currency + exchange_rate_cents_per_unit (sem amount_cents). Backend calcula amount_cents = original_amount * rate.
+- Modo (b) — pessoa só sabe a cotação: passar original_amount_cents + original_currency + exchange_rate (sem amount_cents). Backend calcula amount_cents = original_amount * rate.
 - Modo (c) — despesa BRL normal: só passar amount_cents.
 
 REGRAS DE NEGÓCIO — PARCELAMENTO DE COMPRA ANTIGA:
@@ -403,20 +394,17 @@ REGRAS DE NEGÓCIO — PARCELAMENTO DE COMPRA ANTIGA:
 EXEMPLO — despesa simples:
 { "description": "Almoço", "amount_cents": 3500, "account_name": "Nubank", "category_name": "Alimentação" }
 
-EXEMPLO — estorno:
-{ "description": "Cancelamento Rappi", "amount_cents": 1474, "account_name": "Latam Itaú", "category_name": "Alimentação", "reversal_of_id": "uuid-da-transacao-original", "reversal_kind": "partial" }
-
 EXEMPLO — parcelamento:
 { "description": "Óculos Fozoco", "amount_cents": 36792, "account_name": "Nubank", "category_name": "Saúde", "installments": 4 }
 
-EXEMPLO — forçar ciclo:
-{ "description": "Cancelamento GoDaddy", "amount_cents": 59322, "account_name": "Latam Itaú", "category_name": "Tecnologia", "reversal_of_id": "uuid-original", "reversal_kind": "full", "invoice_cycle_end": "2026-05-01" }
+EXEMPLO — forçar ciclo (caso raro — banco lista compra em fatura diferente do esperado pela data):
+{ "description": "Compra retroativa", "amount_cents": 59322, "account_name": "Latam Itaú", "category_name": "Tecnologia", "invoice_cycle_end": "2026-05-01" }
 
 EXEMPLO — compra USD com BRL exato (modo a):
 { "description": "Camiseta NY", "amount_cents": 10200, "original_amount_cents": 2000, "original_currency": "USD", "account_name": "Wise USD", "category_name": "Pessoal", "subcategory_name": "Vestuário" }
 
 EXEMPLO — compra USD via cotação (modo b):
-{ "description": "Café", "original_amount_cents": 500, "original_currency": "USD", "exchange_rate_cents_per_unit": 52000, "account_name": "Wise USD", "category_name": "Alimentação" }
+{ "description": "Café", "original_amount_cents": 500, "original_currency": "USD", "exchange_rate": 5.20, "account_name": "Wise USD", "category_name": "Alimentação" }
 
 EXEMPLO — Ray-Ban 10x, parcela 4 em cartão Caixa (compra dez/2025, hoje abril/2026):
 { "description": "Ray-Ban", "amount_cents": 137000, "account_name": "Caixa Cartão", "category_name": "Pessoal", "subcategory_name": "Acessórios", "installments": 10, "current_installment": 4, "original_purchase_date": "2025-12-23" }`,
@@ -438,14 +426,6 @@ EXEMPLO — Ray-Ban 10x, parcela 4 em cartão Caixa (compra dez/2025, hoje abril
           type: "number",
           description: "Parcela inicial (default: 1). Usar para entrar no meio de parcelamento existente.",
         },
-        reversal_of_id: {
-          type: "string",
-          description: "UUID da transação original — para estornos/créditos em cartão",
-        },
-        reversal_kind: {
-          type: "string",
-          description: "'full' ou 'partial' — obrigatório quando reversal_of_id é informado",
-        },
         invoice_cycle_end: {
           type: "string",
           description: "YYYY-MM-DD — data de fechamento do ciclo. Força a transação pra uma fatura específica.",
@@ -468,9 +448,9 @@ EXEMPLO — Ray-Ban 10x, parcela 4 em cartão Caixa (compra dez/2025, hoje abril
           enum: ["BRL", "USD"],
           description: "Moeda de original_amount_cents. Use 'USD' pra despesas em dólar.",
         },
-        exchange_rate_cents_per_unit: {
+        exchange_rate: {
           type: "number",
-          description: "Cotação em 1/10000: 51023 = R$ 5,1023 por 1 USD. Use quando NÃO passar amount_cents.",
+          description: "Cotação em decimal: 5.1023 = R$ 5,1023 por 1 USD. Use quando NÃO passar amount_cents.",
         },
       },
       required: ["description"],
@@ -482,7 +462,7 @@ EXEMPLO — Ray-Ban 10x, parcela 4 em cartão Caixa (compra dez/2025, hoje abril
 
 QUANDO USAR: lançar salário, freelance, dividendos, reembolso em conta corrente.
 NÃO USAR QUANDO:
-- Quiser lançar estorno em cartão de crédito — usar fin_criar_despesa com reversal_of_id.
+- Quiser lançar estorno em cartão de crédito — usar fin_criar_estorno.
 - Quiser transferir entre contas — usar fin_criar_transferencia.
 
 CAMPOS:
@@ -586,30 +566,30 @@ NÃO USAR QUANDO: quiser deletar (usar fin_deletar_transacao) ou criar nova (usa
 
 CAMPOS:
 - transaction_id: string UUID — ID da transação (obrigatório).
-- new_amount_cents: number — novo valor em centavos.
-- new_description: string — nova descrição.
-- new_category_name: string — nova categoria (por nome).
-- new_subcategory_name: string — nova subcategoria (por nome).
-- new_account_name: string — nova conta (por nome).
-- new_date: string YYYY-MM-DD — nova data.
-- new_invoice_cycle_end: string YYYY-MM-DD — força a transação pra uma fatura específica (data de fechamento do ciclo).
+- amount_cents: number — novo valor em centavos.
+- description: string — nova descrição.
+- category_name: string — nova categoria (por nome).
+- subcategory_name: string — nova subcategoria (por nome).
+- account_name: string — nova conta (por nome).
+- tx_date: string YYYY-MM-DD — nova data.
+- invoice_cycle_end: string YYYY-MM-DD — força a transação pra uma fatura específica (data de fechamento do ciclo).
 
 REGRAS DE NEGÓCIO:
 - Valores em centavos.
 - Campos omitidos não são alterados.
 - O transaction_id é um UUID (usar fin_buscar_transacoes ou fin_todas_transacoes para encontrar).
-- new_invoice_cycle_end: usar para mover uma transação entre faturas (ex: estorno que o banco listou em fatura diferente da compra).`,
+- invoice_cycle_end: usar para mover uma transação entre faturas (ex: estorno que o banco listou em fatura diferente da compra).`,
     inputSchema: {
       type: "object",
       properties: {
         transaction_id: { type: "string", description: "UUID da transação" },
-        new_amount_cents: { type: "number" },
-        new_description: { type: "string" },
-        new_category_name: { type: "string" },
-        new_subcategory_name: { type: "string" },
-        new_account_name: { type: "string" },
-        new_date: { type: "string", description: "YYYY-MM-DD" },
-        new_invoice_cycle_end: { type: "string", description: "YYYY-MM-DD — data de fechamento do ciclo da fatura" },
+        amount_cents: { type: "number" },
+        description: { type: "string" },
+        category_name: { type: "string" },
+        subcategory_name: { type: "string" },
+        account_name: { type: "string" },
+        tx_date: { type: "string", description: "YYYY-MM-DD" },
+        invoice_cycle_end: { type: "string", description: "YYYY-MM-DD — data de fechamento do ciclo da fatura" },
       },
       required: ["transaction_id"],
     },
@@ -644,7 +624,7 @@ QUANDO USAR:
 - O banco lista um estorno na fatura mas NÃO desconta do total. Criar ajuste POSITIVO pra anular o efeito do refund no net_total.
 
 NÃO USAR QUANDO:
-- O estorno/crédito se comporta normalmente (abate do total na mesma fatura que a compra). Nesse caso, basta lançar o estorno com fin_criar_despesa + reversal_of_id.
+- O estorno/crédito se comporta normalmente (abate do total na mesma fatura que a compra). Nesse caso, basta lançar o estorno com fin_criar_estorno.
 - Quiser mover uma transação entre faturas (usar invoice_cycle_end em fin_criar_despesa ou fin_editar_transacao).
 
 CAMPOS:
@@ -1209,7 +1189,7 @@ REGRAS DE NEGÓCIO:
   },
   {
     name: "fin_criar_estorno",
-    description: `Cria um estorno atômico de uma despesa — versão simplificada de fin_criar_despesa com reversal_of_id.
+    description: `Cria um estorno atômico de uma despesa. Rota canônica — chama POST /api/genius/reversals, que valida ownership e invariants atomicamente.
 
 QUANDO USAR: quando já sabe o UUID da transação original que quer estornar (ex: achou via fin_buscar_transacoes ou fin_fatura_transacoes). A tool herda account/category/subcategory da original automaticamente.
 NÃO USAR QUANDO: quiser fazer uma nova despesa sem relação com estorno (usar fin_criar_despesa).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fin-app-mcp",
-  "version": "2.3.4",
+  "version": "3.0.0",
   "description": "MCP server para o FIN App — finanças pessoais. Expõe tools para agents LLM operarem contas, despesas, faturas de cartão, bills recorrentes e mais.",
   "type": "module",
   "main": "index.mjs",