fin-app-mcp 2.2.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:** 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.
 
-**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)
+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`.
 

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).
 
@@ -872,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').
@@ -880,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: {
@@ -888,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)" },
@@ -899,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: {
@@ -922,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" },
@@ -1158,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": {
@@ -1189,7 +1224,7 @@ async function handleTool(name, args) {
 // ── Server ──────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: "fin-app", version: "2.2.0" },
+  { name: "fin-app", version: "2.3.0" },
   { capabilities: { tools: {}, resources: {} } }
 );
 

package/package.json

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