fin-app-mcp 2.0.0 → 2.2.0

package/README.md

@@ -14,13 +14,31 @@ MCP server que expõe as operações do FIN (finanças pessoais) para qualquer L
 - Uma instância do FIN rodando (local ou na nuvem)
 - Service token configurado no FIN (endpoint `/api/genius/*`)
 
-## Setup
+## Setup (recomendado) — com API Key
 
-### Opção A: via npx (recomendado — zero instalação)
+Cada usuário gera sua própria chave no app FIN. Zero fricção, nada de tokens compartilhados.
 
-Não precisa clonar nem instalar nada. O `npx` baixa e executa automaticamente.
+### Passo 1: Gerar uma API Key
 
-#### Claude Code (settings.json)
+1. Acesse o app FIN (web ou mobile)
+2. Vá em **Configurações → Chaves de API**
+3. Clique em **"Nova chave"**
+4. Dê um nome (ex: "Claude Code", "Personal Genius")
+5. Copie a chave gerada (`fin_live_xxx`) — **ela só é mostrada uma vez**
+
+### Passo 2: Configurar o Claude Code
+
+Um único comando:
+
+```bash
+claude mcp add fin-app \
+  -s user \
+  -e FIN_BASE_URL=https://fin-app-wine.vercel.app \
+  -e FIN_API_KEY=fin_live_xxx \
+  -- npx -y fin-app-mcp
+```
+
+Ou edite manualmente o `settings.json` do Claude Code:
 
 ```json
 {
@@ -29,40 +47,74 @@ Não precisa clonar nem instalar nada. O `npx` baixa e executa automaticamente.
       "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"
+        "FIN_BASE_URL": "https://fin-app-wine.vercel.app",
+        "FIN_API_KEY": "fin_live_xxx"
       }
     }
   }
 }
 ```
 
-Reinicie o client MCP. O server deve aparecer com as tools disponíveis.
+### Passo 3: Testar
 
-### Opção B: instalação global
+Reinicie o Claude Code. Rode `claude mcp list` — o `fin-app` deve aparecer como conectado. As tools do FIN ficam disponíveis automaticamente.
 
-```bash
-npm install -g fin-app-mcp
-```
+### Variáveis de ambiente
+
+| Variável | Descrição |
+|----------|-----------|
+| `FIN_BASE_URL` | URL base da instância do FIN (ex: `https://fin-app-wine.vercel.app`) |
+| `FIN_API_KEY` | API key pessoal (`fin_live_xxx`) gerada em `/settings/api-keys` |
+
+---
+
+## Setup legado — com Service Token (backward-compat)
+
+Modo antigo, ainda suportado. Requer conhecer o `FIN_SERVICE_TOKEN` (env var do deploy) e o UUID do usuário no Supabase.
 
-Claude Code (settings.json):
 ```json
 {
   "mcpServers": {
     "fin-app": {
-      "command": "fin-app-mcp",
+      "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"
+        "FIN_BASE_URL": "https://fin-app-wine.vercel.app",
+        "FIN_SERVICE_TOKEN": "shared-secret",
+        "FIN_USER_ID": "uuid-do-usuario"
       }
     }
   }
 }
 ```
 
-### Opção C: clone local (para desenvolvimento)
+Variáveis:
+
+| Variável | Descrição |
+|----------|-----------|
+| `FIN_BASE_URL` | URL base da instância do FIN |
+| `FIN_SERVICE_TOKEN` | Service token compartilhado |
+| `FIN_USER_ID` | UUID do usuário no Supabase |
+
+Se `FIN_API_KEY` e as variáveis legadas estiverem setadas juntas, `FIN_API_KEY` tem precedência.
+
+---
+
+## Opções de instalação
+
+### Via npx (padrão)
+
+O `npx -y fin-app-mcp` baixa e executa automaticamente. Updates automáticos na próxima invocação.
+
+### Instalação global
+
+```bash
+npm install -g fin-app-mcp
+```
+
+Depois use `"command": "fin-app-mcp"` na config (sem `npx`).
+
+### Clone local (desenvolvimento)
 
 ```bash
 git clone https://github.com/pe-menezes/fin-app.git
@@ -70,30 +122,7 @@ 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 |
+Aponte o `command` pro `index.mjs` local.
 
 ## Resource: Guia do FIN
 

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

@@ -12,20 +12,47 @@ import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 
 // ── Config ──────────────────────────────────────────────────────────
+//
+// Auth modes (in order of preference):
+//
+// 1. Per-user API key (recommended):
+//    FIN_BASE_URL=https://fin-app-wine.vercel.app
+//    FIN_API_KEY=fin_live_xxx   ← gerada em /settings/api-keys no app
+//
+// 2. Legacy shared service token (backward-compat):
+//    FIN_BASE_URL=https://fin-app-wine.vercel.app
+//    FIN_SERVICE_TOKEN=<shared secret>
+//    FIN_USER_ID=<supabase uuid>
+//
 const BASE_URL = process.env.FIN_BASE_URL;
-const TOKEN = process.env.FIN_SERVICE_TOKEN;
-const USER_ID = process.env.FIN_USER_ID;
+const API_KEY = process.env.FIN_API_KEY;
+const LEGACY_TOKEN = process.env.FIN_SERVICE_TOKEN;
+const LEGACY_USER_ID = process.env.FIN_USER_ID;
 
-if (!BASE_URL || !TOKEN || !USER_ID) {
-  console.error("Missing env: FIN_BASE_URL, FIN_SERVICE_TOKEN, FIN_USER_ID");
+if (!BASE_URL) {
+  console.error("Missing env: FIN_BASE_URL");
   process.exit(1);
 }
 
-const headers = {
-  Authorization: `Bearer ${TOKEN}`,
-  "X-Genius-User-Id": USER_ID,
-  "Content-Type": "application/json",
-};
+if (!API_KEY && !(LEGACY_TOKEN && LEGACY_USER_ID)) {
+  console.error(
+    "Missing auth config. Set FIN_API_KEY (recomendado) ou " +
+      "FIN_SERVICE_TOKEN + FIN_USER_ID (legado).\n" +
+      "Gere uma API key em: " + BASE_URL + "/settings/api-keys"
+  );
+  process.exit(1);
+}
+
+const headers = API_KEY
+  ? {
+      Authorization: `Bearer ${API_KEY}`,
+      "Content-Type": "application/json",
+    }
+  : {
+      Authorization: `Bearer ${LEGACY_TOKEN}`,
+      "X-Genius-User-Id": LEGACY_USER_ID,
+      "Content-Type": "application/json",
+    };
 
 // ── Resource content ────────────────────────────────────────────────
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -594,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",
@@ -1014,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`));
     }
@@ -1067,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.0.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",