fin-app-mcp 2.1.0 → 2.2.0

package/docs/guia.md

@@ -269,3 +269,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

@@ -621,6 +621,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",
@@ -1041,6 +1127,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`));
     }
@@ -1094,7 +1189,7 @@ async function handleTool(name, args) {
 // ── Server ──────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: "fin-app", version: "2.0.0" },
+  { name: "fin-app", version: "2.2.0" },
   { capabilities: { tools: {}, resources: {} } }
 );
 

package/package.json

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