fin-app-mcp 2.1.0 → 2.3.0

package/docs/guia.md

@@ -61,27 +61,29 @@ Cada cartão de crédito tem:
 
 O ciclo de uma fatura vai do fechamento anterior até o fechamento atual. Transações dentro desse período pertencem a essa fatura.
 
-### `reference_month` — ATENÇÃO
+### `reference_month`
 
-O FIN usa `reference_month` baseado no **mês do vencimento**, NÃO no mês dos gastos.
+O FIN usa `reference_month` baseado no **mês dos gastos / mês de fechamento do ciclo**, NÃO no mês do vencimento. Geralmente coincide com o label que o banco usa para a fatura (quando o banco rotula pelo mês dos gastos).
 
-**Isso é diferente de como os bancos nomeiam faturas.**
-
-Exemplo concreto — cartão com `closing_day=1` e `due_day=9`:
+**Exemplo concreto — cartão com `closing_day=1` e `due_day=9`:**
 - Ciclo: 1 de março a 1 de abril
 - Vencimento: 9 de abril
-- **Banco chama:** "Fatura de Março" (mês dos gastos)
-- **FIN chama:** `reference_month: 2026-04` (mês do vencimento)
+- `reference_month: 2026-04` (o mês onde o ciclo fecha)
+
+**Exemplo concreto — cartão com `closing_day=19` e `due_day=26`:**
+- Ciclo: 20 de março a 19 de abril
+- Vencimento: 26 de abril
+- `reference_month: 2026-04` (o mês onde o ciclo fecha — abril)
 
-**Regra prática:** quando o banco diz "Fatura de Março", no FIN é `reference_month` do mês seguinte. Ou seja:
-- Fatura Março (banco) → `reference_month: 2026-04` (FIN)
-- Fatura Abril (banco) → `reference_month: 2026-05` (FIN)
+**Regra prática:** o `reference_month` é o mês em que a fatura **fecha** (atinge o `closing_day`). Não é o mês da compra mais antiga da fatura, e não é o mês do vencimento quando o cartão fecha e vence em meses diferentes.
+
+Se o banco rotula a fatura pelo mês de vencimento (raro), some -1 para chegar ao `reference_month`.
 
 ### Em qual fatura cai uma transação?
 
 Uma transação cai na fatura cujo ciclo contém a `tx_date`:
-- Compra em 15/03 com ciclo 01/03–01/04 → fatura de `reference_month: 2026-04`
-- Compra em 31/03 com ciclo 01/03–01/04 → fatura de `reference_month: 2026-04`
+- Cartão fecha dia 1: compra em 15/03 com ciclo 01/03–01/04 → fatura que fecha em abril → `reference_month: 2026-04`
+- Cartão fecha dia 19: compra em 25/03 com ciclo 20/03–19/04 → fatura que fecha em abril → `reference_month: 2026-04`
 
 **Detalhe:** transação feita exatamente no dia do fechamento (`closing_day`) é empurrada para o **próximo** ciclo.
 
@@ -221,8 +223,8 @@ Resultado: refund + ajuste se anulam → líquido bate com o banco.
 
 ### `cycle_end` vs `reference_month`
 
-- **`cycle_end`** é a data de fechamento do ciclo (ex: `2026-04-01` para um cartão que fecha dia 1). É o identificador usado internamente pelo FIN e na tool `fin_ajuste_fatura`.
-- **`reference_month`** é o mês do vencimento (ex: `2026-04` para uma fatura que vence em abril). É usado nas tools `fin_fatura_cartao` e `fin_fatura_transacoes`.
+- **`cycle_end`** é a data exata de fechamento do ciclo (ex: `2026-04-01` para um cartão que fecha dia 1). É o identificador usado internamente pelo FIN e na tool `fin_ajuste_fatura`.
+- **`reference_month`** é o mês em que o ciclo fecha (ex: `2026-04` para uma fatura com `cycle_end: 2026-04-01`). É usado nas tools `fin_fatura_cartao` e `fin_fatura_transacoes`. Ver seção 4 para a regra completa.
 
 Para descobrir o `cycle_end` de uma fatura, use `fin_fatura_transacoes` — a resposta inclui o `cycle_end`.
 
@@ -269,3 +271,57 @@ As ocorrências são geradas **lazily**: ao consultar um mês (`fin_bills_do_mes
 
 - `fixed`: valor fixo todo mês (ex: condomínio R$1.383). O `amount` da ocorrência já vem preenchido.
 - `variable`: valor muda (ex: Light). O `amount` da ocorrência vem `null` até ser definido no momento do pagamento.
+
+## 10. Câmbio USD/BRL e ajuste de saldo
+
+O FIN tem suporte para contas cash em USD (carteira física, Wise, conta no exterior). No v0, contas em USD trabalham com **saldo manual** — você não lança despesas/receitas categorizadas em dólar. Em vez disso, usa duas operações:
+
+### `fin_cambio` — comprar ou vender dólar
+
+O FIN não usa cotação automática para câmbio — **você informa a taxa praticada** na operação, porque a taxa real varia por banco/spread/operação. A tool cria atomicamente 2 transações vinculadas (`exchange_pair_id` compartilhado):
+
+- **Vender dólar:** `from = conta USD`, `to = conta BRL`
+- **Comprar dólar:** `from = conta BRL`, `to = conta USD`
+
+Cada transação fica na sua conta respectiva, com a moeda da conta. A categoria "Câmbio" é criada automaticamente no primeiro uso.
+
+**Exemplo — vendi $100 e recebi R$540 no Itaú:**
+```json
+fin_cambio({
+  "from_account_name": "Wise USD",
+  "to_account_name": "Itaú",
+  "amount_from_cents": 10000,
+  "amount_to_cents": 54000,
+  "description": "Venda de dólar"
+})
+```
+
+Resultado: despesa de $100 na Wise USD + receita de R$540 no Itaú. Ambas com `exchange_pair_id` igual.
+
+### `fin_ajustar_saldo_conta` — atualizar saldo manualmente
+
+Para casos onde o saldo USD muda **sem motivo categórico** (ex: você achou mais $50 na carteira, ou simplesmente quer atualizar pra refletir o saldo real), use `fin_ajustar_saldo_conta`. Ele atualiza o `initial_balance` da conta diretamente, **sem criar transação**.
+
+**Importante:** o valor é o **saldo absoluto**, não um delta. Se a conta tinha $400 e você quer somar $50, passe `45000` (não `5000`).
+
+```json
+fin_ajustar_saldo_conta({
+  "account_name": "Wise USD",
+  "amount_cents": 45000
+})
+```
+
+Funciona para qualquer conta cash (BRL ou USD). Não funciona para cartão de crédito.
+
+### Restrições no v0
+
+- ❌ Lançar despesa/receita categorizada em USD via `fin_criar_despesa`/`fin_criar_receita` (continua bloqueado — mensagem: "use fin_cambio ou fin_ajustar_saldo_conta")
+- ❌ Cotação automática (você sempre informa a taxa)
+- ❌ Cartão de crédito em USD
+- ❌ Filtros nos relatórios mensais por moeda (transações de câmbio aparecem no relatório como categoria "Câmbio" — visualmente identificadas)
+
+### Para "comprei algo no exterior por $20"
+
+No v0, a recomendação é **registrar como ajuste de saldo**: subtrair $20 do saldo atual da conta USD via `fin_ajustar_saldo_conta`. A categorização (que tipo de gasto foi) pode ser feita depois manualmente pela UI, ou simplesmente ignorada se não for crítica para o seu controle.
+
+Lançar despesas categorizadas em USD pode entrar em uma versão futura se virar uma dor real.

package/index.mjs

@@ -182,17 +182,16 @@ CAMPOS:
 - reference_month: string YYYY-MM — mês de referência da fatura.
 
 REGRAS DE NEGÓCIO:
-- ATENÇÃO: reference_month = mês do VENCIMENTO da fatura, NÃO o mês dos gastos.
-- Bancos nomeiam faturas pelo mês dos gastos. O FIN nomeia pelo mês do vencimento. Há ~1 mês de diferença.
-- Exemplo: "Fatura de Março" do banco = reference_month 2026-04 no FIN (se vence em abril).
-- Regra prática: some +1 ao mês que o banco informa.
+- reference_month = mês dos GASTOS / mês de fechamento do ciclo da fatura (NÃO é o mês do vencimento).
+- Exemplo: uma fatura com ciclo 20/03–19/04 e vencimento 26/04 está em reference_month "2026-04". Normalmente coincide com o label que o banco usa (ex: "Fatura de Abril" quando o banco rotula pelo mês dos gastos).
+- Se o banco rotula pelo mês de vencimento, some -1 mês para chegar ao reference_month.
 - net_total já desconta estornos.
 - Valores em centavos.`,
     inputSchema: {
       type: "object",
       properties: {
         card_name: { type: "string", description: "Nome do cartão" },
-        reference_month: { type: "string", description: "YYYY-MM" },
+        reference_month: { type: "string", description: "YYYY-MM (mês dos gastos / fechamento)" },
       },
     },
   },
@@ -303,14 +302,14 @@ CAMPOS:
 - reference_month: string YYYY-MM — mês de referência (default: mês atual).
 
 REGRAS DE NEGÓCIO:
-- ATENÇÃO: reference_month segue a mesma regra de fin_fatura_cartao — é o mês do VENCIMENTO, não dos gastos. Some +1 ao mês que o banco informa.
+- reference_month = mês dos GASTOS / mês de fechamento do ciclo (NÃO é o mês do vencimento). Ver fin_fatura_cartao para exemplos.
 - Estornos aparecem com kind: 'refund' e signedAmount negativo.
 - Valores em centavos.`,
     inputSchema: {
       type: "object",
       properties: {
         card_name: { type: "string", description: "Nome do cartão (obrigatório)" },
-        reference_month: { type: "string", description: "YYYY-MM (default: mês atual)" },
+        reference_month: { type: "string", description: "YYYY-MM (mês dos gastos / fechamento; default: mês atual)" },
       },
       required: ["card_name"],
     },
@@ -365,7 +364,7 @@ CAMPOS:
 - tx_date: string YYYY-MM-DD — data (default: hoje, timezone America/Sao_Paulo).
 - 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). Útil para entrar no meio de um parcelamento.
+- 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).
 
@@ -621,6 +620,92 @@ EXEMPLO — anular estorno que não abate (GitHub R$38,63):
       required: ["card_name", "cycle_end", "amount_cents"],
     },
   },
+  // ── Câmbio USD/BRL e ajuste manual de saldo ─────────────────────
+  {
+    name: "fin_cambio",
+    description: `Registra uma operação de câmbio (compra ou venda de dólar) entre uma conta BRL e uma conta USD. Cria 2 transações vinculadas com a categoria "Câmbio".
+
+QUANDO USAR:
+- Vender dólar: from = conta USD, to = conta BRL. Ex: "vendi $100 por R$540".
+- Comprar dólar: from = conta BRL, to = conta USD. Ex: "comprei $50 por R$280".
+
+NÃO USAR QUANDO:
+- Quiser apenas atualizar o saldo de uma conta sem registrar a operação (use fin_ajustar_saldo_conta).
+- Quiser lançar despesa em USD (não suportado no v0 — só câmbio).
+- Quiser transferir entre contas da mesma moeda (use fin_criar_transferencia).
+
+CAMPOS:
+- from_account_name: string — conta de origem (a que fica negativa). Match parcial.
+- to_account_name: string — conta de destino (a que fica positiva). Match parcial.
+- amount_from_cents: number — valor que SAI da from_account, em centavos da moeda da conta. Ex: $100 = 10000 (centavos USD).
+- amount_to_cents: number — valor que ENTRA na to_account, em centavos da moeda da conta. Ex: R$540 = 54000 (centavos BRL).
+- tx_date: string YYYY-MM-DD — data (default: hoje).
+- description: string — descrição livre (opcional).
+
+REGRAS DE NEGÓCIO:
+- As contas DEVEM ter moedas diferentes (uma BRL, outra USD).
+- Cria 2 transações: uma despesa na from_account, uma receita na to_account.
+- Ambas transações ficam linkadas via exchange_pair_id.
+- A categoria "Câmbio" é criada automaticamente no primeiro uso.
+- A taxa de câmbio é INFORMADA por você — não usa cotação automática.
+- Operação atômica: se uma transação falhar, a outra é desfeita.
+
+EXEMPLO — vender $100 por R$540:
+{ "from_account_name": "Wise USD", "to_account_name": "Itaú", "amount_from_cents": 10000, "amount_to_cents": 54000, "description": "Venda de dólar" }
+
+EXEMPLO — comprar $50 por R$280:
+{ "from_account_name": "Itaú", "to_account_name": "Wise USD", "amount_from_cents": 28000, "amount_to_cents": 5000 }`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        from_account_name: { type: "string", description: "Nome da conta de origem" },
+        to_account_name: { type: "string", description: "Nome da conta de destino" },
+        amount_from_cents: { type: "number", description: "Valor que SAI da origem, em centavos da moeda da conta" },
+        amount_to_cents: { type: "number", description: "Valor que ENTRA no destino, em centavos da moeda da conta" },
+        tx_date: { type: "string", description: "YYYY-MM-DD (default: hoje)" },
+        description: { type: "string", description: "Descrição livre (opcional)" },
+      },
+      required: ["from_account_name", "to_account_name", "amount_from_cents", "amount_to_cents"],
+    },
+  },
+  {
+    name: "fin_ajustar_saldo_conta",
+    description: `Atualiza o saldo de uma conta cash (BRL ou USD) diretamente, sem criar transação. Útil para correções e contas em USD que mudam sem motivo categórico.
+
+QUANDO USAR:
+- Conta USD: registrar quanto dólar você tem agora (ex: "achei mais $50 na carteira", "agora tenho $537").
+- Conta BRL: corrigir saldo inicial após verificar extrato bancário.
+- Onboarding: definir saldo inicial de uma conta recém-criada.
+
+NÃO USAR QUANDO:
+- Quiser registrar uma despesa ou receita categorizada (use fin_criar_despesa / fin_criar_receita).
+- Quiser registrar câmbio entre contas (use fin_cambio).
+- For uma conta de cartão de crédito (não suportado — cartão tem fatura).
+
+CAMPOS:
+- account_name: string — nome da conta (match parcial).
+- amount_cents: number — novo saldo ABSOLUTO, em centavos da moeda da conta. Ex: $487 = 48700 (centavos USD); R$1.234,00 = 123400 (centavos BRL).
+
+REGRAS DE NEGÓCIO:
+- O valor é o SALDO ABSOLUTO, não um delta. Se a conta tinha $400 e você quer somar $50, passe 45000 (não 5000).
+- Funciona para qualquer conta cash (BRL ou USD).
+- Não cria transação — atualiza diretamente o initial_balance da conta.
+- Não suportado para cartão de crédito.
+
+EXEMPLO — atualizar saldo USD pra $537:
+{ "account_name": "Wise USD", "amount_cents": 53700 }
+
+EXEMPLO — corrigir saldo BRL pra R$1.234,56:
+{ "account_name": "Itaú", "amount_cents": 123456 }`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        account_name: { type: "string", description: "Nome da conta (match parcial)" },
+        amount_cents: { type: "number", description: "Novo saldo absoluto em centavos da moeda da conta" },
+      },
+      required: ["account_name", "amount_cents"],
+    },
+  },
   // ── Bills (Contas a Pagar) ──────────────────────────────────────
   {
     name: "fin_listar_bills",
@@ -786,7 +871,9 @@ 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).
+- 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).
+- 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').
 - due_day: number — dia de vencimento da fatura, 1-28 (obrigatório para type 'credit').
 - credit_limit_cents: number — limite de crédito em centavos (para type 'credit').
@@ -794,7 +881,14 @@ 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.`,
+- 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.
+
+EXEMPLO — cartão novo (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 }`,
     inputSchema: {
       type: "object",
       properties: {
@@ -802,6 +896,8 @@ REGRAS DE NEGÓCIO:
         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)" },
+        initial_invoice_date: { type: "string", description: "YYYY-MM-DD — data da fatura inicial. Omitir 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)" },
         due_day: { type: "number", description: "Dia de vencimento da fatura (1-28, obrigatório para credit)" },
         credit_limit_cents: { type: "number", description: "Limite de crédito em centavos (para credit)" },
@@ -813,21 +909,27 @@ REGRAS DE NEGÓCIO:
     name: "fin_editar_conta",
     description: `Edita uma conta bancária existente. Campos omitidos permanecem inalterados.
 
-QUANDO USAR: corrigir nome, instituição, limites ou dias de fechamento/vencimento.
+QUANDO USAR: corrigir nome, instituição, limites, dias de fechamento/vencimento, OU corrigir a data/valor da fatura inicial em cartões criados com cutoff errado.
 
 CAMPOS:
 - account_id: string UUID — ID da conta (obrigatório).
 - name: string — novo nome.
 - institution: string — nova instituição.
 - type: string — 'cash' ou 'credit'.
-- initial_balance_cents: number — novo saldo inicial em centavos.
+- initial_balance_cents: number — novo saldo inicial / fatura inicial em centavos.
+- initial_invoice_date: string YYYY-MM-DD ou null — data da fatura inicial (cutoff histórico). Passe null para remover o cutoff (transações antigas voltam a contar no total).
+- initial_invoice_amount_cents: number — alias de initial_balance_cents quando se refere a fatura inicial de cartão.
 - 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.
 
 REGRAS DE NEGÓCIO:
 - Valores em centavos.
-- Campos omitidos não são alterados.`,
+- 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).
+
+EXEMPLO — remover cutoff de um cartão criado errado:
+{ "account_id": "uuid-do-cartao", "initial_invoice_date": null, "initial_invoice_amount_cents": 0 }`,
     inputSchema: {
       type: "object",
       properties: {
@@ -836,6 +938,8 @@ REGRAS DE NEGÓCIO:
         institution: { type: "string", description: "Nova instituição" },
         type: { type: "string", description: "'cash' ou 'credit'" },
         initial_balance_cents: { type: "number", description: "Novo saldo inicial em centavos" },
+        initial_invoice_date: { type: "string", description: "YYYY-MM-DD ou null — data da fatura inicial (cutoff histórico)" },
+        initial_invoice_amount_cents: { type: "number", description: "Valor da fatura inicial em centavos" },
         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" },
@@ -1041,6 +1145,15 @@ async function handleTool(name, args) {
     case "fin_ajuste_fatura": {
       return ok(await api("POST", `/api/genius/card-invoice-adjustments`, args));
     }
+    case "fin_cambio": {
+      return ok(await api("POST", `/api/genius/exchange`, args));
+    }
+    case "fin_ajustar_saldo_conta": {
+      const { account_name, amount_cents } = args;
+      return ok(
+        await api("POST", `/api/genius/accounts/${encodeURIComponent(account_name)}/balance`, { amount_cents })
+      );
+    }
     case "fin_listar_bills": {
       return ok(await api("GET", `/api/genius/bills`));
     }
@@ -1063,10 +1176,27 @@ async function handleTool(name, args) {
       return ok(await api("GET", `/api/genius/accounts`));
     }
     case "fin_criar_conta": {
-      return ok(await api("POST", `/api/genius/accounts`, args));
+      // Map user-friendly names to Genius API field names.
+      // initial_invoice_date / initial_invoice_amount_cents → initial_balance_date / initial_balance_cents
+      const { initial_invoice_date, initial_invoice_amount_cents, ...rest } = args;
+      const mapped = { ...rest };
+      if (initial_invoice_date !== undefined) {
+        mapped.initial_balance_date = initial_invoice_date;
+      }
+      if (initial_invoice_amount_cents !== undefined) {
+        mapped.initial_balance_cents = initial_invoice_amount_cents;
+      }
+      return ok(await api("POST", `/api/genius/accounts`, mapped));
     }
     case "fin_editar_conta": {
-      const { account_id, ...body } = args;
+      const { account_id, initial_invoice_date, initial_invoice_amount_cents, ...rest } = args;
+      const body = { ...rest };
+      if (initial_invoice_date !== undefined) {
+        body.initial_balance_date = initial_invoice_date;
+      }
+      if (initial_invoice_amount_cents !== undefined) {
+        body.initial_balance_cents = initial_invoice_amount_cents;
+      }
       return ok(await api("PATCH", `/api/genius/accounts/${account_id}`, body));
     }
     case "fin_listar_categorias": {
@@ -1094,7 +1224,7 @@ async function handleTool(name, args) {
 // ── Server ──────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: "fin-app", version: "2.0.0" },
+  { name: "fin-app", version: "2.3.0" },
   { capabilities: { tools: {}, resources: {} } }
 );
 

package/package.json

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