fin-app-mcp 2.3.1 → 2.3.3

package/index.mjs

@@ -564,15 +564,16 @@ REGRAS DE NEGÓCIO:
   },
   {
     name: "fin_deletar_transacao",
-    description: `Deleta uma transação pelo ID.
+    description: `Deleta apenas a transação especificada pelo ID.
 
-QUANDO USAR: remover uma transação lançada por engano ou duplicada.
+QUANDO USAR: remover uma transação lançada por engano ou duplicada, ou remover uma parcela específica de um parcelamento sem afetar as outras.
 
 CAMPOS:
 - transaction_id: string UUID — ID da transação (obrigatório).
 
 REGRAS DE NEGÓCIO:
-- ATENÇÃO: se a transação faz parte de um parcelamento, deletar UMA parcela deleta TODAS as parcelas do grupo (todas com o mesmo installment_group_id).
+- **Deleta APENAS a transação especificada.** Se a transação faz parte de um parcelamento, as outras parcelas do mesmo installment_group_id permanecem intactas.
+- Para apagar um grupo inteiro de parcelamento, delete cada parcela individualmente usando os IDs retornados por fin_buscar_transacoes ou fin_todas_transacoes.
 - A operação é irreversível.`,
     inputSchema: {
       type: "object",
@@ -871,7 +872,8 @@ CAMPOS:
 - name: string — nome da conta (obrigatório, ex: "Nubank", "Inter", "Carteira").
 - institution: string — nome da instituição financeira.
 - type: string — 'cash' (corrente/carteira/poupança) ou 'credit' (cartão de crédito) (obrigatório).
-- initial_balance_cents: number — saldo inicial em centavos (default: 0). Para cartão credit, é o valor de uma fatura preexistente (use com initial_invoice_date).
+- currency: string — 'BRL' ou 'USD' (default: BRL). Apenas contas cash podem ser USD. Use USD para carteira em dólar, Wise, conta americana, etc. Cartão de crédito DEVE ser BRL.
+- initial_balance_cents: number — saldo inicial em centavos **da moeda da conta** (default: 0). Para conta USD, é em centavos de dólar (ex: $370 = 37000). Para cartão credit, é o valor de uma fatura preexistente (use com initial_invoice_date).
 - initial_invoice_date: string YYYY-MM-DD — data da fatura inicial (cutoff histórico). OMITIR é o comportamento recomendado para cartões novos — significa "sem cutoff", ou seja, transações com qualquer tx_date (inclusive anteriores à criação) contam no total da fatura.
 - initial_invoice_amount_cents: number — alias de initial_balance_cents quando se refere a fatura inicial de cartão. Use junto com initial_invoice_date.
 - closing_day: number — dia de fechamento da fatura, 1-28 (obrigatório para type 'credit').
@@ -881,21 +883,27 @@ CAMPOS:
 REGRAS DE NEGÓCIO:
 - Cartão de crédito (type 'credit') EXIGE closing_day e due_day.
 - closing_day e due_day devem estar entre 1 e 28.
-- Valores em centavos.
-- **Para cartão de crédito**: por padrão (quando initial_invoice_date é omitido), o cartão é criado SEM cutoff histórico. Transações com qualquer tx_date contam no total da fatura. Use initial_invoice_date + initial_invoice_amount_cents apenas se o usuário tem um saldo de fatura preexistente vindo de outro sistema.
+- **currency: 'USD' só é permitido para cash.** Tentar criar credit + USD retorna erro de validação.
+- Valores em centavos da moeda da conta (cents de BRL ou cents de USD, conforme currency).
+- **Para cartão de crédito**: por padrão (quando initial_invoice_date é omitido), o cartão é criado SEM cutoff histórico. Transações com qualquer tx_date contam no total da fatura.
 
-EXEMPLO — cartão novo (sem fatura preexistente):
+EXEMPLO — cartão novo BRL (sem fatura preexistente):
 { "name": "Nubank", "type": "credit", "closing_day": 19, "due_day": 26, "credit_limit_cents": 500000 }
 
 EXEMPLO — cartão migrado com fatura já aberta:
-{ "name": "Itaú", "type": "credit", "closing_day": 1, "due_day": 9, "initial_invoice_date": "2026-03-15", "initial_invoice_amount_cents": 350000 }`,
+{ "name": "Itaú", "type": "credit", "closing_day": 1, "due_day": 9, "initial_invoice_date": "2026-03-15", "initial_invoice_amount_cents": 350000 }
+
+EXEMPLO — conta USD (Wise, carteira em dólar):
+{ "name": "Wise USD", "institution": "Wise", "type": "cash", "currency": "USD", "initial_balance_cents": 20000 }
+// cria conta USD com saldo $200`,
     inputSchema: {
       type: "object",
       properties: {
         name: { type: "string", description: "Nome da conta (ex: Nubank, Inter)" },
         institution: { type: "string", description: "Nome da instituição financeira" },
         type: { type: "string", description: "'cash' ou 'credit'" },
-        initial_balance_cents: { type: "number", description: "Saldo inicial em centavos (default: 0)" },
+        currency: { type: "string", description: "'BRL' (default) ou 'USD'. USD só para cash." },
+        initial_balance_cents: { type: "number", description: "Saldo inicial em centavos da moeda da conta (default: 0)" },
         initial_invoice_date: { type: ["string", "null"], description: "YYYY-MM-DD — data da fatura inicial. Omitir ou passar null para cartão sem cutoff histórico (recomendado)." },
         initial_invoice_amount_cents: { type: "number", description: "Valor da fatura inicial em centavos. Use com initial_invoice_date." },
         closing_day: { type: "number", description: "Dia de fechamento da fatura (1-28, obrigatório para credit)" },
@@ -947,6 +955,40 @@ EXEMPLO — remover cutoff de um cartão criado errado:
       required: ["account_id"],
     },
   },
+  {
+    name: "fin_deletar_conta",
+    description: `Deleta uma conta bancária. Bloqueia a deleção se a conta tem transações vinculadas — não cascata.
+
+QUANDO USAR:
+- Remover uma conta criada por engano (nome errado, moeda errada, tipo errado).
+- Limpar contas duplicadas antes de importar histórico.
+
+NÃO USAR QUANDO:
+- A conta tem transações importantes. Se precisa remover uma conta em uso, delete as transações primeiro OU renomeie a conta via fin_editar_conta (soft-archive via renomear para "[ARQUIVADO] Nome").
+
+CAMPOS:
+- account_id: string UUID — ID da conta (obrigatório).
+
+REGRAS DE NEGÓCIO:
+- Se a conta tem qualquer transação vinculada (como account_from ou account_to), retorna erro 409 com a contagem de transações — a conta NÃO é deletada.
+- Sem cascata silenciosa: destruir histórico é pior que um erro claro.
+- Se precisar de hard-delete com histórico, delete as transações primeiro.
+
+EXEMPLO — deletar conta sem transações:
+{ "account_id": "uuid-da-conta" }
+→ retorna { ok: true, deleted: true }
+
+EXEMPLO — tentativa bloqueada:
+{ "account_id": "uuid-da-conta-com-transacoes" }
+→ retorna 409 { ok: false, error: "Conta X tem N transação(ões) vinculada(s)...", transactions_count: N }`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        account_id: { type: "string", description: "UUID da conta" },
+      },
+      required: ["account_id"],
+    },
+  },
   {
     name: "fin_criar_categoria",
     description: `Cria uma nova categoria de transação.
@@ -1199,6 +1241,9 @@ async function handleTool(name, args) {
       }
       return ok(await api("PATCH", `/api/genius/accounts/${account_id}`, body));
     }
+    case "fin_deletar_conta": {
+      return ok(await api("DELETE", `/api/genius/accounts/${args.account_id}`));
+    }
     case "fin_listar_categorias": {
       return ok(await api("GET", `/api/genius/categories`));
     }
@@ -1224,7 +1269,7 @@ async function handleTool(name, args) {
 // ── Server ──────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: "fin-app", version: "2.3.1" },
+  { name: "fin-app", version: "2.3.3" },
   { capabilities: { tools: {}, resources: {} } }
 );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fin-app-mcp",
-  "version": "2.3.1",
+  "version": "2.3.3",
   "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",