fin-app-mcp 2.3.3 → 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,15 +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).
-
-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.
+- 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: 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.
@@ -385,17 +381,33 @@ REGRAS DE NEGÓCIO — CICLO DE FATURA:
 - invoice_cycle_end: força a transação a pertencer a um ciclo de fatura específico, independente da tx_date. Usar quando o banco lista um cancelamento/estorno em uma fatura diferente da compra original. O valor é a data de fechamento do ciclo (YYYY-MM-DD), NÃO o reference_month.
 - Ver seção 8 do guia (fin://docs/guia) para cenários de conciliação complexa.
 
+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 (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:
+- Pra lançar uma compra já em andamento (ex: "Ray-Ban 10x, estou na parcela 4"), passe original_purchase_date (data REAL da compra), installments (10), current_installment (4). O backend usa o cutoff/due_day do cartão pra colocar a parcela 4 na fatura corrente e as próximas nas faturas futuras. SEM esse campo, você precisa passar tx_date como "data da primeira parcela a cair" (anti-intuitivo).
+
 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": 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" }`,
     inputSchema: {
       type: "object",
       properties: {
@@ -414,20 +426,34 @@ EXEMPLO — forçar ciclo:
           type: "number",
           description: "Parcela inicial (default: 1). Usar para entrar no meio de parcelamento existente.",
         },
-        reversal_of_id: {
+        invoice_cycle_end: {
           type: "string",
-          description: "UUID da transação original — para estornos/créditos em cartão",
+          description: "YYYY-MM-DD — data de fechamento do ciclo. Força a transação pra uma fatura específica.",
+        },
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          description: "Tags livres pra cortes ortogonais (max 20).",
         },
-        reversal_kind: {
+        original_purchase_date: {
           type: "string",
-          description: "'full' ou 'partial' — obrigatório quando reversal_of_id é informado",
+          description: "YYYY-MM-DD — data REAL da compra. Use com installments>1 + current_installment>1 em cartão pra colocar cada parcela na fatura certa.",
         },
-        invoice_cycle_end: {
+        original_amount_cents: {
+          type: "number",
+          description: "Valor em centavos na moeda estrangeira (ex: 2000 = US$ 20,00).",
+        },
+        original_currency: {
           type: "string",
-          description: "YYYY-MM-DD — data de fechamento do ciclo. Força a transação pra uma fatura específica.",
+          enum: ["BRL", "USD"],
+          description: "Moeda de original_amount_cents. Use 'USD' pra despesas em dólar.",
+        },
+        exchange_rate: {
+          type: "number",
+          description: "Cotação em decimal: 5.1023 = R$ 5,1023 por 1 USD. Use quando NÃO passar amount_cents.",
         },
       },
-      required: ["description", "amount_cents"],
+      required: ["description"],
     },
   },
   {
@@ -436,7 +462,7 @@ EXEMPLO — forçar ciclo:
 
 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:
@@ -446,6 +472,7 @@ CAMPOS:
 - category_name: string — nome da categoria (deve ser flow 'income').
 - subcategory_name: string — subcategoria.
 - tx_date: string YYYY-MM-DD — data (default: hoje).
+- tags: string[] — tags livres pra cortes ortogonais.
 
 REGRAS DE NEGÓCIO:
 - Valores em centavos.
@@ -459,6 +486,11 @@ REGRAS DE NEGÓCIO:
         category_name: { type: "string" },
         subcategory_name: { type: "string" },
         tx_date: { type: "string", description: "YYYY-MM-DD (default: hoje)" },
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          description: "Tags livres pra cortes ortogonais (max 20).",
+        },
       },
       required: ["description", "amount_cents"],
     },
@@ -534,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"],
     },
@@ -592,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:
@@ -731,60 +763,85 @@ NÃO USAR QUANDO: quiser ver transações gerais (usar fin_todas_transacoes) ou
 
 CAMPOS:
 - month: string YYYY-MM — mês de referência (default: mês atual).
+- status: string — filtro opcional. Aceita um valor ('pending', 'overdue', 'paid', 'paid_late'), lista separada por vírgula ('pending,overdue'), ou o atalho 'unpaid' (= pending+overdue).
 
 REGRAS DE NEGÓCIO:
 - Status: 'pending' (aguardando vencimento), 'overdue' (vencida e não paga), 'paid' (paga no prazo), 'paid_late' (paga em atraso).
 - Ocorrências são geradas automaticamente para cada bill ativa no mês consultado.
 - amount_cents: valor definido para esta ocorrência (null se ainda não definido — usar default_amount_cents da bill).
 - transaction_id: preenchido quando a conta foi paga (link para a transação de despesa).
+- Ocorrências pagas vêm com account_name, category_name, subcategory_name, tx_description, invoice_cycle_end resolvidos via JOIN com a transação.
+- Resposta inclui summary com total_*_cents e count_* por status (agregado sobre o mês inteiro, ignorando status filter).
 - Valores em centavos.
 
 EXEMPLO:
 { "month": "2026-04" }
+{ "month": "2026-04", "status": "unpaid" }
 
-Retorno: [{ bill_name: "Light", status: "pending", due_date: "2026-04-01", amount_cents: null }, ...]`,
+Retorno: { summary: {...}, occurrences: [{ bill_name: "Light", status: "pending", due_date: "2026-04-01", amount_cents: null, account_name, category_name, notes }, ...] }`,
     inputSchema: {
       type: "object",
       properties: {
         month: { type: "string", description: "YYYY-MM (default: mês atual)" },
+        status: { type: "string", description: "Filtro opcional: 'pending', 'overdue', 'paid', 'paid_late', 'unpaid' (pending+overdue), ou lista separada por vírgula." },
       },
     },
   },
   {
     name: "fin_pagar_bill",
-    description: `Marca uma conta a pagar como paga e cria a transação de despesa automaticamente.
+    description: `Marca uma conta a pagar como paga. Dois modos:
+  (1) CRIAR nova transação de despesa (default); ou
+  (2) LINKAR a uma transação já existente no extrato (passando transaction_id) — útil quando você importou o OFX antes de cadastrar a bill.
 
-QUANDO USAR: ao conciliar extrato e encontrar pagamento de uma conta recorrente (Light, condomínio, faxina, etc.). Use fin_bills_do_mes primeiro para obter o occurrence_id.
+QUANDO USAR: ao conciliar extrato e encontrar pagamento de uma conta recorrente. Use fin_bills_do_mes primeiro para obter occurrence_id.
 NÃO USAR QUANDO: quiser lançar despesa avulsa que não é conta recorrente (usar fin_criar_despesa).
 
 CAMPOS:
-- occurrence_id: string UUID — ID da ocorrência (obrigatório, obter via fin_bills_do_mes).
-- amount_cents: number — valor pago em centavos (obrigatório).
-- account_name: string — conta de onde saiu o dinheiro (obrigatório, match parcial).
-- category_name: string — categoria da despesa (opcional, usa default da bill se omitido).
-- subcategory_name: string — subcategoria (opcional).
-- payment_date: string YYYY-MM-DD — data do pagamento (default: hoje).
+- occurrence_id: string UUID (obrigatório).
+- transaction_id: string UUID — se passado, LINKA em vez de criar. A transação é fonte da verdade (account/amount/date vêm dela). Zero duplicação. Não combina com amount_cents/account_name/fee_cents.
+- amount_cents: number — valor em centavos. Obrigatório quando transaction_id NÃO é passado.
+- account_name: string — obrigatório quando transaction_id NÃO é passado.
+- category_name / subcategory_name: opcionais (usa default da bill).
+- payment_date: YYYY-MM-DD (default: hoje).
+- fee_cents: number — multa/juros em centavos. Cria uma 2ª transação de despesa em "Taxas, Juros & Impostos > Multa" (ou na categoria que você especificar). Só funciona no modo CRIAR.
+- fee_category_name / fee_subcategory_name: sobrescreve a categoria default da multa.
+- is_catch_up: boolean — marca este pagamento como sendo de um mês PASSADO (ex: Vivo atrasada de março paga junto com abril). Exige catch_up_reference_month.
+- catch_up_reference_month: YYYY-MM — mês que esse pagamento referencia quando is_catch_up=true. Se já existe ocorrência pendente nesse mês, ela é paga; senão, uma nova é criada.
 
 REGRAS DE NEGÓCIO:
-- Se a ocorrência já foi paga, retorna erro.
-- Cria transação de despesa automaticamente (não precisa chamar fin_criar_despesa).
-- Se category_name não for informado, usa a categoria default cadastrada na bill.
+- Modo LINK (transaction_id): valida ownership, exige tipo expense, bloqueia se transação já está linkada a outra ocorrência. Retorna warning 'transaction_date_outside_occurrence_month' se tx.date não cair no mês da ocorrência.
+- Modo CRIAR: se occurrence já foi paga, retorna erro (a menos que is_catch_up=true pra um mês diferente).
+- Catch-up: cria/reaproveita uma ocorrência do mês catch_up_reference_month, deixando a ocorrência corrente intacta.
 - Valores em centavos.
-- Não suporta multa/juros no momento.
 
-EXEMPLO:
-{ "occurrence_id": "uuid-da-ocorrencia", "amount_cents": 35000, "account_name": "Itaú", "payment_date": "2026-04-01" }`,
+EXEMPLO — criar nova tx:
+{ "occurrence_id": "uuid", "amount_cents": 35000, "account_name": "Itaú", "payment_date": "2026-04-01" }
+
+EXEMPLO — linkar a tx já importada do OFX:
+{ "occurrence_id": "uuid", "transaction_id": "uuid-da-tx-do-extrato" }
+
+EXEMPLO — pagar com multa:
+{ "occurrence_id": "uuid", "amount_cents": 10000, "account_name": "C6", "fee_cents": 500 }
+
+EXEMPLO — catch-up (pagou março junto com abril):
+{ "occurrence_id": "uuid-de-abril-qualquer", "amount_cents": 8000, "account_name": "C6", "is_catch_up": true, "catch_up_reference_month": "2026-03" }`,
     inputSchema: {
       type: "object",
       properties: {
         occurrence_id: { type: "string", description: "UUID da ocorrência (de fin_bills_do_mes)" },
-        amount_cents: { type: "number", description: "Valor pago em centavos" },
-        account_name: { type: "string", description: "Nome da conta" },
+        transaction_id: { type: "string", description: "UUID de uma transação já existente pra LINKAR em vez de criar nova." },
+        amount_cents: { type: "number", description: "Valor pago em centavos (obrigatório sem transaction_id)" },
+        account_name: { type: "string", description: "Nome da conta (obrigatório sem transaction_id)" },
         category_name: { type: "string", description: "Categoria (opcional, usa default da bill)" },
         subcategory_name: { type: "string", description: "Subcategoria (opcional)" },
         payment_date: { type: "string", description: "YYYY-MM-DD (default: hoje)" },
+        fee_cents: { type: "number", description: "Multa/juros em centavos. Cria 2ª transação em 'Taxas, Juros & Impostos > Multa'. Só no modo CRIAR." },
+        fee_category_name: { type: "string", description: "Sobrescreve categoria default da multa." },
+        fee_subcategory_name: { type: "string", description: "Sobrescreve subcategoria default da multa." },
+        is_catch_up: { type: "boolean", description: "True quando pagando ref. a um mês passado (precisa catch_up_reference_month)." },
+        catch_up_reference_month: { type: "string", description: "YYYY-MM — mês referência quando is_catch_up=true." },
       },
-      required: ["occurrence_id", "amount_cents", "account_name"],
+      required: ["occurrence_id"],
     },
   },
   {
@@ -802,14 +859,21 @@ CAMPOS:
 - account_name: string — conta default de pagamento (match parcial).
 - category_name: string — categoria default.
 - subcategory_name: string — subcategoria default.
+- notes: string — contexto livre (ex: "reajusta em janeiro", "plano expira dez/2026").
+- tags: string[] — tags pra cortes ortogonais.
+- review_after: YYYY-MM-DD — lembrete pra revisar essa bill depois dessa data.
+- end_date: YYYY-MM-DD — último mês (inclusive) que gera ocorrência (ex: IPTU 10x até out/2026).
+- max_occurrences: number — alternativa a end_date: para depois de N ocorrências geradas.
 
 REGRAS DE NEGÓCIO:
 - amount_type 'fixed' = valor fixo todo mês (ex: condomínio R$1.383).
 - amount_type 'variable' = valor muda (ex: Light). Definido no momento do pagamento.
+- POST de bill já cria a ocorrência do mês atual e retorna em current_month_occurrence.
 - Valores em centavos.
 
 EXEMPLO:
-{ "name": "Light", "due_day": 1, "amount_type": "variable", "category_name": "Moradia", "account_name": "Itaú" }`,
+{ "name": "Light", "due_day": 1, "amount_type": "variable", "category_name": "Moradia", "account_name": "Itaú" }
+{ "name": "IPTU", "due_day": 10, "amount_type": "fixed", "default_amount_cents": 38000, "end_date": "2026-10-10", "notes": "10x jan-out/2026" }`,
     inputSchema: {
       type: "object",
       properties: {
@@ -820,6 +884,11 @@ EXEMPLO:
         account_name: { type: "string", description: "Conta default de pagamento" },
         category_name: { type: "string", description: "Categoria default" },
         subcategory_name: { type: "string", description: "Subcategoria default" },
+        notes: { type: "string", description: "Contexto livre (max 2000 chars)." },
+        tags: { type: "array", items: { type: "string" }, description: "Tags livres (max 20)." },
+        review_after: { type: "string", description: "YYYY-MM-DD — lembrete pra revisar a bill." },
+        end_date: { type: "string", description: "YYYY-MM-DD — último mês que gera ocorrência." },
+        max_occurrences: { type: "number", description: "Para depois de N ocorrências geradas." },
       },
       required: ["name", "due_day"],
     },
@@ -832,18 +901,14 @@ QUANDO USAR: mudar configurações de uma conta existente ou desativar.
 
 CAMPOS:
 - bill_id: string UUID — ID da bill (obrigatório, obter via fin_listar_bills).
-- name: string — novo nome.
-- due_day: number — novo dia de vencimento (1-31).
-- amount_type: string — 'fixed' ou 'variable'.
-- default_amount_cents: number — novo valor padrão em centavos.
-- account_name: string — nova conta default.
-- category_name: string — nova categoria default.
-- subcategory_name: string — nova subcategoria default.
-- is_active: boolean — false para desativar (soft delete).
+- name / due_day / amount_type / default_amount_cents / account_name / category_name / subcategory_name — editáveis.
+- is_active: boolean — false para soft-delete (preserva histórico).
+- notes / tags / review_after / end_date / max_occurrences — editáveis (null pra limpar).
 
 REGRAS DE NEGÓCIO:
 - Campos omitidos não são alterados.
 - is_active: false desativa a bill (não gera novas ocorrências, mas mantém histórico).
+- Pra HARD-delete (apagar de verdade) a bill, use fin_deletar_bill — só funciona se nenhuma ocorrência foi paga ainda.
 - Valores em centavos.`,
     inputSchema: {
       type: "object",
@@ -857,6 +922,11 @@ REGRAS DE NEGÓCIO:
         category_name: { type: "string", description: "Nova categoria default" },
         subcategory_name: { type: "string", description: "Nova subcategoria default" },
         is_active: { type: "boolean", description: "false para desativar" },
+        notes: { type: "string", description: "Contexto livre (null pra limpar)." },
+        tags: { type: "array", items: { type: "string" }, description: "Tags livres (null pra limpar)." },
+        review_after: { type: "string", description: "YYYY-MM-DD (null pra limpar)." },
+        end_date: { type: "string", description: "YYYY-MM-DD (null pra limpar)." },
+        max_occurrences: { type: "number", description: "Máximo de ocorrências (null pra limpar)." },
       },
       required: ["bill_id"],
     },
@@ -930,14 +1000,19 @@ CAMPOS:
 - closing_day: number — novo dia de fechamento (1-28).
 - due_day: number — novo dia de vencimento (1-28).
 - credit_limit_cents: number — novo limite de crédito em centavos.
+- currency: string — 'BRL' ou 'USD'. SÓ FUNCIONA quando a conta não tem nenhuma transação vinculada. Se tiver, retorna 409 com transactions_count — caller deve deletar/mover as transações antes.
 
 REGRAS DE NEGÓCIO:
 - Valores em centavos.
 - Campos omitidos não são alterados.
 - Use initial_invoice_date: null para remover o cutoff histórico de um cartão (caso transações antigas estejam aparecendo fora da fatura no app).
+- currency é imutável quando há transações.
 
 EXEMPLO — remover cutoff de um cartão criado errado:
-{ "account_id": "uuid-do-cartao", "initial_invoice_date": null, "initial_invoice_amount_cents": 0 }`,
+{ "account_id": "uuid-do-cartao", "initial_invoice_date": null, "initial_invoice_amount_cents": 0 }
+
+EXEMPLO — corrigir moeda de uma conta recém-criada (sem transações):
+{ "account_id": "uuid-da-conta", "currency": "USD" }`,
     inputSchema: {
       type: "object",
       properties: {
@@ -951,6 +1026,7 @@ EXEMPLO — remover cutoff de um cartão criado errado:
         closing_day: { type: "number", description: "Novo dia de fechamento (1-28)" },
         due_day: { type: "number", description: "Novo dia de vencimento (1-28)" },
         credit_limit_cents: { type: "number", description: "Novo limite de crédito em centavos" },
+        currency: { type: "string", description: "'BRL' ou 'USD'. Só funciona se a conta não tem transações." },
       },
       required: ["account_id"],
     },
@@ -1087,6 +1163,199 @@ REGRAS DE NEGÓCIO:
       required: ["subcategory_id"],
     },
   },
+  // ── Bugs #17/#15/#16/#18-34 — new tools ───────────────────────────
+  {
+    name: "fin_patrimonio",
+    description: `Retorna patrimônio consolidado multi-moeda (cash + checking) em uma moeda de exibição.
+
+QUANDO USAR: responder "quanto eu tenho hoje no total em reais?" — pergunta básica de dashboard.
+NÃO USAR QUANDO: quiser ver saldos nativos por conta (usar fin_saldos).
+
+CAMPOS:
+- display_currency: 'BRL' | 'USD' — moeda em que o total é exibido (default: BRL).
+
+REGRAS DE NEGÓCIO:
+- Usa getBalanceService (mesmo dado de fin_saldos).
+- Converte USD→BRL via cotação 1h-cached (AwesomeAPI / exchangerate.host).
+- Se a cotação está off: retorna total BRL PARCIAL + partial: true + warning 'partial_total_exchange_rate_unavailable'.
+- Retorno: { as_of, display_currency, exchange_rates, total_cents, partial, breakdown_by_currency: { BRL: {...}, USD: {...} }, breakdown_by_account: [{ account_id, account_name, currency, balance_cents, balance_in_display_cents }] }
+- ATENÇÃO: essa tool usa cotação DINÂMICA. Pra transações individuais (gastos em dólar), o caller deve informar a cotação real paga — ver fin_criar_despesa.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        display_currency: { type: "string", description: "'BRL' (default) ou 'USD'." },
+      },
+    },
+  },
+  {
+    name: "fin_criar_estorno",
+    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).
+
+CAMPOS:
+- original_transaction_id: string UUID (obrigatório) — transação original.
+- amount_cents: number (obrigatório) — valor em centavos. Pode ser parcial (ex: 7216 de uma compra de 10000).
+- tx_date: YYYY-MM-DD — data do estorno (default: hoje).
+- description: string — descrição custom (default: "Estorno: <descrição original>").
+
+REGRAS DE NEGÓCIO:
+- A original precisa ser tipo 'expense'. Retorna 422 senão.
+- amount_cents não pode exceder o valor da original. Retorna 422 se exceder.
+- reversal_kind é derivado: 'full' se amount == original, 'partial' senão.
+- account/category/subcategory são HERDADOS da original — sem precisar informar.
+- Retorna o mesmo shape de fin_criar_despesa.
+
+EXEMPLO — estorno parcial:
+{ "original_transaction_id": "uuid-original", "amount_cents": 7216, "description": "Devolução parcial defeito" }
+
+EXEMPLO — estorno total:
+{ "original_transaction_id": "uuid-original", "amount_cents": 10000 }`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        original_transaction_id: { type: "string", description: "UUID da transação original" },
+        amount_cents: { type: "number", description: "Valor do estorno em centavos (pode ser parcial)" },
+        tx_date: { type: "string", description: "YYYY-MM-DD (default: hoje)" },
+        description: { type: "string", description: "Descrição custom (default: 'Estorno: ...')" },
+      },
+      required: ["original_transaction_id", "amount_cents"],
+    },
+  },
+  {
+    name: "fin_classificar_linha_extrato",
+    description: `Classifica uma linha de extrato bancário em uma das 5 categorias semânticas.
+
+QUANDO USAR: em skills que importam OFX/CNAB/CSV e precisam decidir se cada linha é despesa, receita, transfer, pagamento de fatura, ou saque ATM. Evita reinventar heurística cliente-side.
+NÃO USAR QUANDO: a skill já sabe o tipo (ex: acabou de chamar fin_criar_despesa).
+
+CAMPOS:
+- description: string (obrigatório) — descrição da linha do extrato.
+- amount_cents: number (obrigatório) — valor em centavos. Negativo = débito, positivo = crédito.
+- account_id: string UUID (obrigatório) — conta do extrato que está sendo importado.
+- trntype: string — hint OFX (ATM, XFER, PAYMENT, DEBIT, CREDIT). Opcional.
+- fitid: string — FITID OFX, pass-through no retorno pra idempotência.
+
+REGRAS DE NEGÓCIO:
+- Retorna { type, confidence, reason, details, from_account_id, from_account_name, fitid }
+- type ∈ { 'expense', 'income', 'transfer', 'payment_invoice', 'atm_withdrawal' }
+- details:
+  - atm_withdrawal → { suggested_cash_account_id: UUID pra conta "Dinheiro" se existir }
+  - payment_invoice → { suggested_card_account_id: UUID do cartão se der pra adivinhar pelo nome na descrição }
+  - transfer → { suggested_counterparty_account_id: UUID da outra conta do user se bateu pelo nome }
+  - expense/income → {}
+- O caller orquestra: recebe a classificação e chama fin_criar_despesa / fin_criar_transferencia / fin_pagar_fatura conforme.
+- Matching de nomes de conta tem blocklist de palavras genéricas (PIX, TED, DOC, etc) pra evitar falso positivo.
+
+EXEMPLO:
+{ "description": "SAQUE 24H BANCO X", "amount_cents": -20000, "account_id": "uuid-c6", "trntype": "ATM" }
+→ { type: "atm_withdrawal", confidence: "high", details: { suggested_cash_account_id: "uuid-dinheiro" } }`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        description: { type: "string" },
+        amount_cents: { type: "number", description: "Centavos (negativo = débito, positivo = crédito)" },
+        account_id: { type: "string", description: "UUID da conta sendo importada" },
+        trntype: { type: "string", description: "Hint OFX (ATM, XFER, PAYMENT, DEBIT, CREDIT)" },
+        fitid: { type: "string", description: "FITID OFX, pass-through no retorno" },
+      },
+      required: ["description", "amount_cents", "account_id"],
+    },
+  },
+  {
+    name: "fin_criar_transacoes_batch",
+    description: `Cria múltiplas transações (despesa/receita/transferência) em uma única chamada. Max 100 por batch.
+
+QUANDO USAR:
+- Conciliação de extrato com várias transações que não passaram pelo parser automático.
+- Lançamento em lote de parcelas avulsas (ex: várias compras parceladas antigas).
+- Qualquer cenário que geraria N chamadas individuais de criar_despesa/criar_receita/criar_transferencia.
+NÃO USAR QUANDO: uma única transação atômica com rollback é necessária (essa tool é "partial success by design").
+
+CAMPOS:
+- transactions: array — cada item é um objeto com type + campos do tipo correspondente. Discriminated union:
+  - { type: "expense", amount_cents, description, account_name?, category_name?, subcategory_name?, tx_date?, essential?, invoice_cycle_end?, tags? }
+  - { type: "income", amount_cents, description, account_name?, category_name?, subcategory_name?, tx_date?, tags? }
+  - { type: "transfer", amount_cents, description, account_from, account_to, tx_date? }
+
+REGRAS DE NEGÓCIO:
+- Loop sequencial (não-transacional). Falha no meio NÃO reverte as anteriores.
+- Resposta: { ok: true, total, created: [{ index, transaction_id, type }], failed: [{ index, error }] }.
+- Caller decide o que fazer com 'failed' (retry, logar, abortar).
+- Max 100 rows por chamada pra limitar memória de request.
+
+EXEMPLO:
+{
+  "transactions": [
+    { "type": "expense", "amount_cents": 5000, "description": "Almoço", "account_name": "C6" },
+    { "type": "income", "amount_cents": 500000, "description": "Salário", "account_name": "Itaú" },
+    { "type": "transfer", "amount_cents": 10000, "description": "pra poupança", "account_from": "C6", "account_to": "Poupança" }
+  ]
+}`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        transactions: {
+          type: "array",
+          description: "Lista de transações a criar (max 100)",
+          items: { type: "object" },
+        },
+      },
+      required: ["transactions"],
+    },
+  },
+  {
+    name: "fin_deletar_bill",
+    description: `Hard-delete de uma bill recorrente. Só funciona se NENHUMA ocorrência foi paga.
+
+QUANDO USAR: remover bill criada por engano (nome/categoria errada) antes de qualquer pagamento.
+NÃO USAR QUANDO: a bill já tem ocorrências pagas — use fin_editar_bill com is_active: false (soft-delete, preserva histórico).
+
+CAMPOS:
+- bill_id: string UUID (obrigatório).
+
+REGRAS DE NEGÓCIO:
+- Se a bill tem ≥1 ocorrência com transaction_id != null, retorna 409 com soft_delete_hint.
+- Ocorrências NÃO pagas são deletadas em cascata (FK ON DELETE CASCADE).`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        bill_id: { type: "string", description: "UUID da bill" },
+      },
+      required: ["bill_id"],
+    },
+  },
+  {
+    name: "fin_editar_occurrence",
+    description: `Edita uma ocorrência específica de bill (amount_cents, due_date, notes) sem alterar o template mãe.
+
+QUANDO USAR:
+- Bill 'fixed' teve valor diferente em UM mês (multa, reajuste retroativo).
+- Data de vencimento mudou num mês específico (feriado, dia não-útil).
+- Anotar contexto local (ex: "pago com desconto pontual").
+NÃO USAR QUANDO: quiser mudar o default permanente da bill (usar fin_editar_bill).
+
+CAMPOS:
+- occurrence_id: string UUID (obrigatório).
+- amount_cents: number — novo valor em centavos.
+- due_date: string YYYY-MM-DD — novo dia de vencimento.
+- notes: string | null — anotação livre (null pra limpar).
+
+REGRAS DE NEGÓCIO:
+- Se a ocorrência já foi paga (tem transaction_id) e você tenta editar amount_cents: retorna 409 (a transação é a fonte da verdade; use fin_editar_transacao).
+- Outros campos podem ser editados mesmo em ocorrência paga.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        occurrence_id: { type: "string", description: "UUID da ocorrência" },
+        amount_cents: { type: "number", description: "Novo valor em centavos" },
+        due_date: { type: "string", description: "YYYY-MM-DD" },
+        notes: { type: ["string", "null"], description: "Anotação livre (null pra limpar)" },
+      },
+      required: ["occurrence_id"],
+    },
+  },
 ];
 
 // ── Tool handlers ───────────────────────────────────────────────────
@@ -1200,7 +1469,10 @@ async function handleTool(name, args) {
       return ok(await api("GET", `/api/genius/bills`));
     }
     case "fin_bills_do_mes": {
-      const qs = args.month ? `?month=${args.month}` : "";
+      const params = new URLSearchParams();
+      if (args.month) params.set("month", args.month);
+      if (args.status) params.set("status", args.status);
+      const qs = params.toString() ? `?${params}` : "";
       return ok(await api("GET", `/api/genius/bills/occurrences${qs}`));
     }
     case "fin_pagar_bill": {
@@ -1261,6 +1533,27 @@ async function handleTool(name, args) {
       const { subcategory_id, ...body } = args;
       return ok(await api("PATCH", `/api/genius/subcategories/${subcategory_id}`, body));
     }
+    // ── Bugs #17/#15/#16/#18-34 — new tool handlers ───────────────
+    case "fin_patrimonio": {
+      const qs = args.display_currency ? `?display_currency=${args.display_currency}` : "";
+      return ok(await api("GET", `/api/genius/patrimony${qs}`));
+    }
+    case "fin_criar_estorno": {
+      return ok(await api("POST", `/api/genius/reversals`, args));
+    }
+    case "fin_classificar_linha_extrato": {
+      return ok(await api("POST", `/api/genius/classify-statement-line`, args));
+    }
+    case "fin_criar_transacoes_batch": {
+      return ok(await api("POST", `/api/genius/transactions/batch`, args));
+    }
+    case "fin_deletar_bill": {
+      return ok(await api("DELETE", `/api/genius/bills/${args.bill_id}`));
+    }
+    case "fin_editar_occurrence": {
+      const { occurrence_id, ...body } = args;
+      return ok(await api("PATCH", `/api/genius/bills/occurrences/${occurrence_id}`, body));
+    }
     default:
       return err(`Tool desconhecida: ${name}`);
   }

package/package.json

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