fin-app-mcp 2.0.0

package/README.md

@@ -0,0 +1,118 @@
+# FIN App — MCP Server
+
+MCP server que expõe as operações do FIN (finanças pessoais) para qualquer LLM agent via [Model Context Protocol](https://modelcontextprotocol.io/).
+
+## O que faz
+
+- **22 tools** para operar finanças: criar despesas, receitas, transferências, consultar saldos, faturas, relatórios, gerenciar contas e categorias.
+- **1 resource** (`fin://docs/guia`) com o guia completo de regras de negócio — ciclo de fatura, estorno, parcelamento, modelo de dados.
+- Descriptions ricas em cada tool: quando usar, quando NÃO usar, regras de negócio, armadilhas.
+
+## Pré-requisitos
+
+- Node.js 18+
+- Uma instância do FIN rodando (local ou na nuvem)
+- Service token configurado no FIN (endpoint `/api/genius/*`)
+
+## Setup
+
+### Opção A: via npx (recomendado — zero instalação)
+
+Não precisa clonar nem instalar nada. O `npx` baixa e executa automaticamente.
+
+#### Claude Code (settings.json)
+
+```json
+{
+  "mcpServers": {
+    "fin-app": {
+      "command": "npx",
+      "args": ["-y", "fin-app-mcp"],
+      "env": {
+        "FIN_BASE_URL": "https://fin.example.com",
+        "FIN_SERVICE_TOKEN": "seu-token-aqui",
+        "FIN_USER_ID": "seu-user-id-aqui"
+      }
+    }
+  }
+}
+```
+
+Reinicie o client MCP. O server deve aparecer com as tools disponíveis.
+
+### Opção B: instalação global
+
+```bash
+npm install -g fin-app-mcp
+```
+
+Claude Code (settings.json):
+```json
+{
+  "mcpServers": {
+    "fin-app": {
+      "command": "fin-app-mcp",
+      "env": {
+        "FIN_BASE_URL": "https://fin.example.com",
+        "FIN_SERVICE_TOKEN": "seu-token-aqui",
+        "FIN_USER_ID": "seu-user-id-aqui"
+      }
+    }
+  }
+}
+```
+
+### Opção C: clone local (para desenvolvimento)
+
+```bash
+git clone https://github.com/pe-menezes/fin-app.git
+cd fin-app/mcp-server
+npm install
+```
+
+Claude Code (settings.json):
+```json
+{
+  "mcpServers": {
+    "fin-app": {
+      "command": "node",
+      "args": ["/caminho/para/fin-app/mcp-server/index.mjs"],
+      "env": {
+        "FIN_BASE_URL": "https://fin.example.com",
+        "FIN_SERVICE_TOKEN": "seu-token-aqui",
+        "FIN_USER_ID": "seu-user-id-aqui"
+      }
+    }
+  }
+}
+```
+
+### Variáveis de ambiente
+
+| Variável | Descrição |
+|----------|-----------|
+| `FIN_BASE_URL` | URL base da instância do FIN (ex: `https://fin.example.com` ou `http://localhost:3000`) |
+| `FIN_SERVICE_TOKEN` | Service token para autenticação na API Genius |
+| `FIN_USER_ID` | UUID do usuário no FIN |
+
+## Resource: Guia do FIN
+
+O server expõe `fin://docs/guia` — um guia completo para agents operarem o FIN. Conteúdo:
+
+- Modelo de dados (contas, transações, categorias)
+- Valores em centavos
+- Ciclo de fatura de cartão (reference_month, closing_day, due_day)
+- Estorno / Reversal (como criar, armadilhas)
+- Parcelamento (geração automática, deleção em grupo)
+- Nomes vs IDs
+
+Agents devem ler este resource antes de iniciar operações financeiras.
+
+## Desenvolvimento
+
+O server é um proxy da API Genius do FIN — não contém lógica de negócio própria. Quando regras de negócio mudam no FIN, as descriptions e o guia devem ser atualizados aqui.
+
+```bash
+# Rodar direto (para debug)
+FIN_BASE_URL=http://localhost:3000 FIN_SERVICE_TOKEN=xxx FIN_USER_ID=xxx node index.mjs
+```

package/docs/guia.md

@@ -0,0 +1,271 @@
+# Guia do FIN — Regras de Negócio para Agents
+
+> Este documento é a referência completa para qualquer LLM agent que opera o FIN via MCP server.
+> Leia antes de executar qualquer operação financeira.
+
+## 1. Visão geral
+
+O FIN é um app de finanças pessoais. Registra despesas, receitas e transferências, com suporte a múltiplas contas bancárias, cartões de crédito com faturas, categorização, parcelamento, e estornos.
+
+Toda interação acontece via tools do MCP server. Os valores são sempre em **centavos** (ver seção 3). As tools aceitam nomes de contas e categorias (não IDs) e resolvem internamente.
+
+## 2. Modelo de dados
+
+### Contas (`accounts`)
+Dois tipos:
+- **`cash`** — conta corrente, carteira, poupança. Tem saldo calculado (saldo inicial + receitas - despesas).
+- **`credit`** — cartão de crédito. Tem `closing_day` (dia de fechamento), `due_day` (dia de vencimento), e `credit_limit`. Não tem "saldo" — tem faturas.
+
+### Transações (`transactions`)
+Três tipos:
+- **`expense`** — despesa. Debita de uma conta (cash ou credit).
+- **`income`** — receita. Credita numa conta cash.
+- **`transfer`** — transferência entre contas. Debita de uma e credita na outra.
+
+Campos principais:
+- `description` — texto livre
+- `amount` — valor em centavos (sempre positivo no banco; o tipo determina o sinal)
+- `tx_date` — data no formato YYYY-MM-DD
+- `account_from_id` — conta de origem (expense e transfer)
+- `account_to_id` — conta de destino (income e transfer)
+- `category_id` / `subcategory_id` — categorização
+- `essential` — booleano (despesa essencial vs supérflua)
+- `reversal_of_id` — se preenchido, esta transação é um estorno (ver seção 5)
+- `installment_group_id` — se preenchido, faz parte de um parcelamento (ver seção 6)
+
+### Categorias e subcategorias
+- Cada categoria tem um `flow`: `expense` ou `income`
+- Subcategorias pertencem a exatamente uma categoria
+- Categorias podem ser arquivadas (`is_active: false`)
+
+### Faturas de cartão de crédito
+- Uma fatura agrupa as transações de um cartão dentro de um ciclo de fechamento
+- Tem `reference_month`, `net_total`, `charges_total`, `refunds_total`, `due_date`
+- Ver seção 4 para detalhes do ciclo
+
+## 3. Valores em centavos
+
+**TODA a API trabalha em centavos.** R$10,50 = 1050 centavos.
+
+Ao criar transações, informar `amount_cents` (não reais). Ao ler respostas, todos os valores monetários estão em centavos.
+
+Conversão: `centavos = reais × 100`. Exemplo: R$1.234,56 = 123456 centavos.
+
+## 4. Ciclo de fatura de cartão
+
+### Como funciona
+
+Cada cartão de crédito tem:
+- `closing_day` — dia do mês em que a fatura fecha (1-28)
+- `due_day` — dia do mês em que a fatura vence (1-28)
+
+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
+
+O FIN usa `reference_month` baseado no **mês do vencimento**, NÃO no mês dos gastos.
+
+**Isso é diferente de como os bancos nomeiam faturas.**
+
+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)
+
+**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)
+
+### 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`
+
+**Detalhe:** transação feita exatamente no dia do fechamento (`closing_day`) é empurrada para o **próximo** ciclo.
+
+## 5. Estorno / Reversal
+
+### O que é
+
+Um estorno é um crédito que reduz o total de uma fatura (ou devolve dinheiro numa conta cash). No FIN, estornos são modelados como **despesas especiais** com `reversal_of_id`.
+
+### Como criar um estorno
+
+Usar a tool `fin_criar_despesa` com:
+
+| Campo | Valor |
+|-------|-------|
+| `reversal_of_id` | UUID da transação original sendo estornada |
+| `reversal_kind` | `'full'` (estorno total) ou `'partial'` (estorno parcial) |
+| `amount_cents` | valor do estorno em centavos (positivo — o sistema inverte) |
+| `account_name` | **mesmo** cartão/conta da transação original |
+| `description` | descrição do estorno |
+| `category_name` | mesma categoria da original |
+
+### Como funciona por dentro
+
+- O estorno é salvo como `tx_type: 'expense'` com `amount` positivo
+- Na hora de calcular a fatura, o sistema detecta `reversal_of_id != null` e **inverte o sinal** — o valor vira negativo e subtrai do total
+- Na listagem da fatura, o estorno aparece como `kind: 'refund'`
+
+### O que NÃO fazer
+
+- **NUNCA usar `fin_criar_receita` para estorno em cartão de crédito.** Receita soma na fatura em vez de subtrair. O resultado é o oposto do esperado.
+- **NUNCA** criar estorno de um estorno (a transação original não pode ter `reversal_of_id`)
+- **NUNCA** criar estorno em conta diferente da original
+
+### Validações automáticas
+
+O sistema valida:
+- A transação original deve existir
+- A original deve ser `expense` (não pode ser receita, transferência, ou outro estorno)
+- O `account_from_id` do estorno deve ser igual ao da original
+- O valor deve ser > R$0,01
+
+## 6. Parcelamento
+
+### Como funciona
+
+Ao criar uma despesa com `installments: N` (onde N é 2-48), o sistema gera **N transações separadas** automaticamente.
+
+### Distribuição
+
+- O `amount_cents` informado é o **TOTAL** (não o valor de cada parcela)
+- O sistema divide: `total / N`, distribuindo centavos restantes nas primeiras parcelas
+  - Exemplo: R$100,00 em 3x → [R$33,34 + R$33,33 + R$33,33]
+- Cada parcela ganha `tx_date` espaçada de 1 mês (+1 mês por parcela)
+  - Parcela 1: `tx_date` original
+  - Parcela 2: +1 mês
+  - Parcela 3: +2 meses
+  - Edge cases de fim de mês são tratados (31/jan → 28/fev)
+
+### Campos em cada transação gerada
+
+| Campo | Valor |
+|-------|-------|
+| `installment_group_id` | UUID compartilhado por todas as parcelas |
+| `installment_index` | 1, 2, 3, ... N (1-based) |
+| `installment_count` | N (total de parcelas) |
+| `tx_date` | offset de +1 mês por parcela |
+| `amount` | valor dividido (não o total) |
+
+### Fatura
+
+Cada parcela cai na fatura baseada na sua `tx_date` individual. Como cada parcela tem date offset de 1 mês, cada uma cai em uma fatura diferente automaticamente.
+
+### Entrar no meio do parcelamento
+
+O parâmetro `current_installment` permite começar de qualquer parcela. Se o parcelamento é de 10x e você está na parcela 3, passe `current_installment: 3, installments: 10` — o sistema gera 8 transações (3 a 10).
+
+### Deleção
+
+Ao deletar **qualquer** parcela de um grupo, **todas** as parcelas com o mesmo `installment_group_id` são deletadas juntas. Não é possível deletar uma parcela individual.
+
+## 7. Nomes vs IDs
+
+As tools do MCP aceitam **nomes** (não UUIDs) para contas e categorias:
+- `account_name` — nome da conta (match parcial, case-insensitive)
+- `category_name` — nome da categoria
+- `subcategory_name` — nome da subcategoria
+
+O servidor resolve o nome para o ID internamente. Se o nome for ambíguo ou não encontrado, a API retorna erro explicativo.
+
+Exceção: `reversal_of_id` e `transaction_id` são sempre UUIDs — transações são identificadas por ID, não por nome.
+
+## 8. Conciliação de faturas complexas
+
+Bancos às vezes tratam estornos e cancelamentos de formas que o modelo padrão de faturas não cobre diretamente. O FIN tem dois mecanismos para lidar com isso: **`invoice_cycle_end`** (forçar transação pra outro ciclo) e **ajustes de fatura** (tool `fin_ajuste_fatura`).
+
+### Cenário 1: Cancelamento cross-cycle
+
+**O que acontece:** o banco cancela uma compra do ciclo X, mas aplica o crédito como desconto no pagamento da fatura Y. Exemplo:
+
+- Compra GoDaddy R$593,22 em 18/03 → fatura Abr (ciclo 01/03–01/04)
+- Cancelamento GoDaddy -R$593,22 → banco lista na fatura **Mai** (ciclo 01/04–01/05)
+- Banco desconta os R$593,22 do pagamento da fatura Abr: total era R$11.368,91, Pedro pagou R$10.775,69
+
+**Como resolver:**
+
+1. Lançar o cancelamento como estorno (`fin_criar_despesa` com `reversal_of_id`) com `invoice_cycle_end` apontando pro ciclo de Mai (onde o banco listou):
+   ```json
+   { "description": "Cancelamento GoDaddy", "amount_cents": 59322, "account_name": "Latam Itaú", "reversal_of_id": "uuid-da-compra", "reversal_kind": "full", "invoice_cycle_end": "2026-05-01" }
+   ```
+
+2. Criar ajuste NEGATIVO na fatura Abr para representar o crédito que o banco aplicou no pagamento:
+   ```json
+   fin_ajuste_fatura({ "card_name": "Latam Itaú", "cycle_end": "2026-04-01", "amount_cents": -59322 })
+   ```
+
+Resultado: fatura Abr fecha com net_total = total - ajuste = pagamento. Fatura Mai mostra o refund.
+
+### Cenário 2: Estorno que não abate do total
+
+**O que acontece:** o banco lista um estorno na fatura, mas NÃO desconta do total. Exemplo:
+
+- Estorno GitHub -R$38,63 em 04/03 → aparece no CSV da fatura Abr
+- Total do banco: R$11.368,91 (não desconta os R$38,63)
+
+Se lançar como refund no FIN, o líquido fica R$38,63 menor que o banco mostra.
+
+**Como resolver:**
+
+1. Lançar o estorno como refund normalmente (ele vai descontar do líquido)
+2. Criar ajuste POSITIVO pra anular o efeito:
+   ```json
+   fin_ajuste_fatura({ "card_name": "Latam Itaú", "cycle_end": "2026-04-01", "amount_cents": 3863 })
+   ```
+
+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`.
+
+Para descobrir o `cycle_end` de uma fatura, use `fin_fatura_transacoes` — a resposta inclui o `cycle_end`.
+
+### Combinando ajustes
+
+Se uma fatura tem múltiplos ajustes necessários (ex: crédito cross-cycle + estorno que não abate), **some os valores** num único `fin_ajuste_fatura`:
+
+```json
+// Crédito GoDaddy (-R$593,22) + anular GitHub (+R$38,63) = -R$554,59
+fin_ajuste_fatura({ "card_name": "Latam Itaú", "cycle_end": "2026-04-01", "amount_cents": -55459 })
+```
+
+Um ajuste por (cartão, ciclo) — se chamar `fin_ajuste_fatura` duas vezes pro mesmo cartão/ciclo, o segundo valor sobrescreve o primeiro.
+
+## 9. Contas a pagar (bills)
+
+O FIN tem um sistema de contas a pagar recorrentes. Cada conta (Light, condomínio, internet, faxina) é cadastrada como **bill** com dia de vencimento e valor padrão.
+
+### Modelo
+
+- **Bill (template):** conta recorrente cadastrada. Campos: `name`, `due_day` (1-31), `amount_type` ('fixed' ou 'variable'), `default_amount`, conta/categoria default.
+- **Occurrence (instância mensal):** gerada automaticamente para cada mês consultado. Campos: `due_date`, `amount`, `status`, `transaction_id` (se paga).
+
+### Status
+
+| Status | Significado |
+|--------|------------|
+| `pending` | Aguardando vencimento — ainda não venceu e não foi paga |
+| `overdue` | Vencida e não paga |
+| `paid` | Paga no prazo |
+| `paid_late` | Paga em atraso (data de pagamento > data de vencimento) |
+
+### Fluxo típico
+
+1. **"O que falta pagar?"** → `fin_bills_do_mes` retorna lista com status de cada conta do mês.
+2. **Conciliando extrato:** encontrou pagamento de Light → `fin_pagar_bill` com o `occurrence_id` (do passo 1). O sistema cria a transação de despesa automaticamente e marca como paga.
+3. **Nova conta:** usuário contratou novo serviço → `fin_criar_bill` cadastra a recorrência.
+
+### Geração de ocorrências
+
+As ocorrências são geradas **lazily**: ao consultar um mês (`fin_bills_do_mes`), o sistema verifica se as ocorrências já existem e cria as que faltam. Não precisa gerar manualmente.
+
+### amount_type
+
+- `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.