fin-app-mcp 2.0.0

package/index.mjs

@@ -0,0 +1,1111 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+// ── Config ──────────────────────────────────────────────────────────
+const BASE_URL = process.env.FIN_BASE_URL;
+const TOKEN = process.env.FIN_SERVICE_TOKEN;
+const 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");
+  process.exit(1);
+}
+
+const headers = {
+  Authorization: `Bearer ${TOKEN}`,
+  "X-Genius-User-Id": USER_ID,
+  "Content-Type": "application/json",
+};
+
+// ── Resource content ────────────────────────────────────────────────
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const guiaContent = readFileSync(join(__dirname, "docs", "guia.md"), "utf-8");
+
+// ── API helpers ─────────────────────────────────────────────────────
+
+async function api(method, path, body) {
+  const url = `${BASE_URL}${path}`;
+  const opts = { method, headers };
+  if (body) opts.body = JSON.stringify(body);
+  const res = await fetch(url, opts);
+  const data = await res.json();
+  if (!res.ok) return { ok: false, status: res.status, ...data };
+  return data;
+}
+
+function ok(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+
+function err(msg) {
+  return { content: [{ type: "text", text: `Erro: ${msg}` }], isError: true };
+}
+
+// ── Tool definitions ────────────────────────────────────────────────
+
+const tools = [
+  // ── Consultas ─────────────────────────────────────────────────────
+  {
+    name: "fin_resumo_mensal",
+    description: `Retorna o resumo financeiro do mês: receitas totais, despesas totais, saldo, taxa de poupança (%) e top categorias de gasto.
+
+QUANDO USAR: para ter uma visão geral de como foi o mês financeiramente.
+NÃO USAR QUANDO: precisar de detalhes por transação (usar fin_todas_transacoes) ou breakdown por categoria (usar fin_gastos_por_categoria).
+
+CAMPOS:
+- month: string YYYY-MM — mês de referência. Default: mês atual (timezone America/Sao_Paulo).
+
+REGRAS DE NEGÓCIO:
+- Todos os valores retornados estão em centavos.
+- savings_rate é percentual (0-100), não decimal.
+- Inclui apenas transações do mês solicitado.`,
+    inputSchema: {
+      type: "object",
+      properties: { month: { type: "string", description: "YYYY-MM" } },
+    },
+  },
+  {
+    name: "fin_gastos_por_categoria",
+    description: `Retorna o breakdown de gastos agrupados por categoria e subcategoria no mês.
+
+QUANDO USAR: para entender onde o dinheiro foi gasto no mês, comparar categorias.
+NÃO USAR QUANDO: quiser o resumo geral (usar fin_resumo_mensal) ou transações individuais.
+
+CAMPOS:
+- month: string YYYY-MM — mês de referência.
+
+REGRAS DE NEGÓCIO:
+- Valores em centavos.
+- Inclui apenas despesas (expenses) — receitas não aparecem.
+- Agrupa por categoria + subcategoria.`,
+    inputSchema: {
+      type: "object",
+      properties: { month: { type: "string", description: "YYYY-MM" } },
+    },
+  },
+  {
+    name: "fin_saldos",
+    description: `Retorna os saldos das contas bancárias (tipo cash). Cartões de crédito não têm "saldo" — têm faturas.
+
+QUANDO USAR: para saber quanto tem em cada conta corrente/carteira/poupança.
+NÃO USAR QUANDO: quiser ver fatura de cartão de crédito (usar fin_fatura_cartao).
+
+CAMPOS:
+- account_name: string — filtro por nome da conta (match parcial, case-insensitive). Opcional.
+
+REGRAS DE NEGÓCIO:
+- Saldo = saldo_inicial + receitas - despesas (calculado pelo sistema).
+- Valores em centavos.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        account_name: { type: "string", description: "Nome parcial da conta" },
+      },
+    },
+  },
+  {
+    name: "fin_buscar_transacoes",
+    description: `Busca transações por texto na descrição, data, categoria ou conta. Retorna até 20 resultados.
+
+QUANDO USAR: para encontrar transações específicas por descrição ou filtros simples. Bom para verificar se algo já foi lançado.
+NÃO USAR QUANDO: precisar listar TODAS as transações de um período (usar fin_todas_transacoes) ou transações de uma fatura específica (usar fin_fatura_transacoes).
+
+CAMPOS:
+- q: string — busca por texto na descrição.
+- date_from / date_to: string YYYY-MM-DD — filtro de período.
+- category: string — nome da categoria.
+- account: string — nome da conta.
+- limit: number — max resultados (default 5, max 20).
+
+REGRAS DE NEGÓCIO:
+- Valores em centavos.
+- Compras de supermercado/delivery (ex: Rappi, iFood) podem estar divididas em múltiplos lançamentos por categoria (alimentação, limpeza, higiene) na mesma data, somando o valor total do extrato bancário. Na conciliação por valor, considere somar itens do mesmo estabelecimento/data.
+- Parcelas aparecem como transações separadas com installment_index e installment_count.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        q: { type: "string", description: "Texto na descrição" },
+        date_from: { type: "string", description: "YYYY-MM-DD" },
+        date_to: { type: "string", description: "YYYY-MM-DD" },
+        category: { type: "string", description: "Nome da categoria" },
+        account: { type: "string", description: "Nome da conta" },
+        limit: { type: "number", description: "Max resultados (default 5, max 20)" },
+      },
+    },
+  },
+  {
+    name: "fin_fatura_cartao",
+    description: `Retorna o resumo de uma fatura de cartão de crédito: total bruto, estornos, total líquido, vencimento, e top categorias.
+
+QUANDO USAR: para ver o total de uma fatura e quando vence.
+NÃO USAR QUANDO: precisar ver as transações individuais da fatura (usar fin_fatura_transacoes).
+
+CAMPOS:
+- card_name: string — nome do cartão (match parcial).
+- 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.
+- 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" },
+      },
+    },
+  },
+  {
+    name: "fin_contexto",
+    description: `Retorna o contexto financeiro completo: contas, categorias, transações recentes, saldos e resumo do mês atual.
+
+QUANDO USAR: no início de uma sessão financeira, para entender a situação geral antes de fazer qualquer operação. Útil para saber quais contas/categorias existem.
+NÃO USAR QUANDO: já souber as contas e categorias e quiser ir direto para operações específicas.
+
+REGRAS DE NEGÓCIO:
+- Valores em centavos.
+- Retorna dados do mês atual (timezone America/Sao_Paulo).
+- É uma visão consolidada — para detalhes, use as tools específicas.`,
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "fin_todas_transacoes",
+    description: `Lista TODAS as transações com paginação (até 200 por página). Ideal para conciliação em lote.
+
+QUANDO USAR: para listar todas as transações de um período, conta ou tipo. Ideal para conciliação com extrato bancário.
+NÃO USAR QUANDO: quiser buscar por texto na descrição (usar fin_buscar_transacoes) ou ver transações de uma fatura de cartão (usar fin_fatura_transacoes).
+
+CAMPOS:
+- account: string — nome da conta (match parcial).
+- date_from / date_to: string YYYY-MM-DD — filtro de período.
+- tx_type: string — 'expense', 'income', ou 'transfer'.
+- category: string — nome da categoria.
+- page: number — página (default 1).
+- per_page: number — itens por página (default 50, max 200).
+
+REGRAS DE NEGÓCIO:
+- Retorna total_count para saber o total de resultados.
+- Valores em centavos.
+- Paginação: se total_count > per_page, há mais páginas.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        account: { type: "string", description: "Nome da conta" },
+        date_from: { type: "string", description: "YYYY-MM-DD" },
+        date_to: { type: "string", description: "YYYY-MM-DD" },
+        tx_type: { type: "string", description: "expense | income | transfer" },
+        category: { type: "string", description: "Nome da categoria" },
+        page: { type: "number", description: "Página (default 1)" },
+        per_page: { type: "number", description: "Itens por página (default 50, max 200)" },
+      },
+    },
+  },
+  {
+    name: "fin_relatorio",
+    description: `Relatório financeiro multi-mês: receitas, despesas, saldo e categorias por mês.
+
+QUANDO USAR: para análise trimestral, semestral ou anual — comparar meses entre si.
+NÃO USAR QUANDO: quiser apenas um mês (usar fin_resumo_mensal).
+
+CAMPOS:
+- from_month: string YYYY-MM — mês inicial (obrigatório).
+- to_month: string YYYY-MM — mês final (obrigatório).
+
+REGRAS DE NEGÓCIO:
+- Valores em centavos.
+- Range máximo: 24 meses.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        from_month: { type: "string", description: "YYYY-MM (obrigatório)" },
+        to_month: { type: "string", description: "YYYY-MM (obrigatório)" },
+      },
+      required: ["from_month", "to_month"],
+    },
+  },
+  {
+    name: "fin_receitas",
+    description: `Lista receitas (income) detalhadas com paginação (até 100 por página).
+
+QUANDO USAR: para ver receitas de um período ou conta específica.
+NÃO USAR QUANDO: quiser ver todas as transações incluindo despesas (usar fin_todas_transacoes).
+
+CAMPOS:
+- account: string — nome da conta (match parcial).
+- date_from / date_to: string YYYY-MM-DD — filtro de período.
+- page: number — página (default 1).
+- per_page: number — itens por página (default 50, max 100).
+
+REGRAS DE NEGÓCIO:
+- Retorna apenas receitas (tx_type = income).
+- Valores em centavos.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        account: { type: "string", description: "Nome da conta" },
+        date_from: { type: "string", description: "YYYY-MM-DD" },
+        date_to: { type: "string", description: "YYYY-MM-DD" },
+        page: { type: "number", description: "Página (default 1)" },
+        per_page: { type: "number", description: "Itens por página (default 50, max 100)" },
+      },
+    },
+  },
+  {
+    name: "fin_fatura_transacoes",
+    description: `Lista TODAS as transações de uma fatura de cartão: cobranças, estornos (kind: refund) e pagamentos. Retorna totais e líquido.
+
+QUANDO USAR: para ver o detalhamento completo de uma fatura — cada transação, estornos, e o total líquido.
+NÃO USAR QUANDO: quiser apenas o resumo da fatura (usar fin_fatura_cartao).
+
+CAMPOS:
+- card_name: string — nome do cartão (obrigatório, match parcial).
+- 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.
+- 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)" },
+      },
+      required: ["card_name"],
+    },
+  },
+  {
+    name: "fin_listar_contas",
+    description: `Lista todas as contas bancárias com detalhes: nome, instituição, tipo (cash/credit), saldo inicial, e dados do cartão (closing_day, due_day, credit_limit) quando aplicável.
+
+QUANDO USAR: para saber quais contas e cartões existem, seus nomes e configurações.
+NÃO USAR QUANDO: quiser saber os saldos atuais (usar fin_saldos) ou faturas (usar fin_fatura_cartao).
+
+REGRAS DE NEGÓCIO:
+- Contas cash: corrente, carteira, poupança.
+- Contas credit: cartões de crédito — incluem closing_day (fechamento) e due_day (vencimento).
+- Valores em centavos.`,
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "fin_listar_categorias",
+    description: `Lista todas as categorias de transação com suas subcategorias. Inclui id, nome, flow (expense/income), status ativo, e subcategorias.
+
+QUANDO USAR: para saber quais categorias existem antes de criar transações, ou para encontrar o nome exato de uma categoria/subcategoria.
+NÃO USAR QUANDO: já souber os nomes das categorias.
+
+REGRAS DE NEGÓCIO:
+- flow 'expense' = categoria de despesa; flow 'income' = categoria de receita.
+- Categorias inativas (is_active: false) estão arquivadas.
+- Subcategorias herdam o flow da categoria pai.`,
+    inputSchema: { type: "object", properties: {} },
+  },
+  // ── Mutações ──────────────────────────────────────────────────────
+  {
+    name: "fin_criar_despesa",
+    description: `Cria uma despesa. Também usada para lançar ESTORNOS em cartão de crédito (via reversal_of_id). Suporta parcelamento automático.
+
+QUANDO USAR:
+- Lançar uma despesa normal (compra, conta, assinatura).
+- Lançar um ESTORNO/CANCELAMENTO em cartão de crédito — usar com reversal_of_id.
+- Lançar uma compra parcelada — usar com installments.
+
+NÃO USAR QUANDO:
+- Quiser lançar receita (usar fin_criar_receita).
+- Quiser registrar pagamento de fatura de cartão (usar fin_pagar_fatura).
+- Quiser transferir entre contas (usar fin_criar_transferencia).
+
+CAMPOS:
+- description: string — descrição da despesa (obrigatório).
+- amount_cents: number — valor em centavos (obrigatório). Para parcelamento, informar o TOTAL.
+- account_name: string — nome da conta/cartão (match parcial).
+- category_name: string — nome da categoria (deve ser flow 'expense').
+- subcategory_name: string — nome da subcategoria.
+- 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.
+- 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).
+
+REGRAS DE NEGÓCIO — ESTORNO:
+- Para estorno em cartão: criar despesa com reversal_of_id = UUID da transação original.
+- O amount_cents é POSITIVO — o sistema inverte automaticamente na fatura.
+- O account_name DEVE ser o mesmo cartão da transação original.
+- NUNCA usar fin_criar_receita para estorno em cartão — receita SOMA na fatura em vez de subtrair.
+- A transação original deve existir, ser expense, e não ser outro estorno.
+
+REGRAS DE NEGÓCIO — PARCELAMENTO:
+- installments: N gera N transações separadas, cada uma em um mês consecutivo.
+- O amount_cents informado é o TOTAL — o sistema divide entre as parcelas.
+- Cada parcela cai numa fatura diferente automaticamente.
+- Deletar qualquer parcela deleta TODAS do grupo.
+
+REGRAS DE NEGÓCIO — CICLO DE FATURA:
+- invoice_cycle_end: força a transação a pertencer a um ciclo de fatura específico, independente da tx_date. Usar quando o banco lista um cancelamento/estorno em uma fatura diferente da compra original. O valor é a data de fechamento do ciclo (YYYY-MM-DD), NÃO o reference_month.
+- Ver seção 8 do guia (fin://docs/guia) para cenários de conciliação complexa.
+
+EXEMPLO — despesa simples:
+{ "description": "Almoço", "amount_cents": 3500, "account_name": "Nubank", "category_name": "Alimentação" }
+
+EXEMPLO — estorno:
+{ "description": "Cancelamento Rappi", "amount_cents": 1474, "account_name": "Latam Itaú", "category_name": "Alimentação", "reversal_of_id": "uuid-da-transacao-original", "reversal_kind": "partial" }
+
+EXEMPLO — parcelamento:
+{ "description": "Óculos Fozoco", "amount_cents": 36792, "account_name": "Nubank", "category_name": "Saúde", "installments": 4 }
+
+EXEMPLO — forçar ciclo:
+{ "description": "Cancelamento GoDaddy", "amount_cents": 59322, "account_name": "Latam Itaú", "category_name": "Tecnologia", "reversal_of_id": "uuid-original", "reversal_kind": "full", "invoice_cycle_end": "2026-05-01" }`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        description: { type: "string" },
+        amount_cents: { type: "number", description: "Valor em centavos" },
+        account_name: { type: "string" },
+        category_name: { type: "string" },
+        subcategory_name: { type: "string" },
+        tx_date: { type: "string", description: "YYYY-MM-DD (default: hoje)" },
+        essential: { type: "boolean" },
+        installments: {
+          type: "number",
+          description: "Número de parcelas (2-48)",
+        },
+        current_installment: {
+          type: "number",
+          description: "Parcela inicial (default: 1). Usar para entrar no meio de parcelamento existente.",
+        },
+        reversal_of_id: {
+          type: "string",
+          description: "UUID da transação original — para estornos/créditos em cartão",
+        },
+        reversal_kind: {
+          type: "string",
+          description: "'full' ou 'partial' — obrigatório quando reversal_of_id é informado",
+        },
+        invoice_cycle_end: {
+          type: "string",
+          description: "YYYY-MM-DD — data de fechamento do ciclo. Força a transação pra uma fatura específica.",
+        },
+      },
+      required: ["description", "amount_cents"],
+    },
+  },
+  {
+    name: "fin_criar_receita",
+    description: `Cria uma receita (income). Credita numa conta cash.
+
+QUANDO USAR: lançar salário, freelance, dividendos, reembolso em conta corrente.
+NÃO USAR QUANDO:
+- Quiser lançar estorno em cartão de crédito — usar fin_criar_despesa com reversal_of_id.
+- Quiser transferir entre contas — usar fin_criar_transferencia.
+
+CAMPOS:
+- description: string — descrição (obrigatório).
+- amount_cents: number — valor em centavos (obrigatório).
+- account_name: string — nome da conta destino (match parcial). Deve ser conta cash.
+- category_name: string — nome da categoria (deve ser flow 'income').
+- subcategory_name: string — subcategoria.
+- tx_date: string YYYY-MM-DD — data (default: hoje).
+
+REGRAS DE NEGÓCIO:
+- Valores em centavos.
+- NUNCA usar para estorno em cartão de crédito. Receita em cartão SOMA na fatura em vez de subtrair.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        description: { type: "string" },
+        amount_cents: { type: "number", description: "Valor em centavos" },
+        account_name: { type: "string" },
+        category_name: { type: "string" },
+        subcategory_name: { type: "string" },
+        tx_date: { type: "string", description: "YYYY-MM-DD (default: hoje)" },
+      },
+      required: ["description", "amount_cents"],
+    },
+  },
+  {
+    name: "fin_criar_transferencia",
+    description: `Cria uma transferência entre duas contas. Move dinheiro da conta origem para a conta destino.
+
+QUANDO USAR: transferência entre contas (ex: da corrente para poupança, de um banco para outro).
+NÃO USAR QUANDO:
+- Quiser registrar pagamento de fatura de cartão — usar fin_pagar_fatura.
+- Quiser lançar despesa ou receita — usar as tools específicas.
+
+CAMPOS:
+- amount_cents: number — valor em centavos (obrigatório).
+- from_account_name: string — conta de origem (obrigatório, match parcial).
+- to_account_name: string — conta de destino (obrigatório, match parcial).
+- description: string — descrição.
+- tx_date: string YYYY-MM-DD — data (default: hoje).
+
+REGRAS DE NEGÓCIO:
+- Valores em centavos.
+- Ambas as contas devem existir.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        amount_cents: { type: "number", description: "Valor em centavos" },
+        from_account_name: { type: "string" },
+        to_account_name: { type: "string" },
+        description: { type: "string" },
+        tx_date: { type: "string", description: "YYYY-MM-DD (default: hoje)" },
+      },
+      required: ["amount_cents", "from_account_name", "to_account_name"],
+    },
+  },
+  {
+    name: "fin_pagar_fatura",
+    description: `Registra o pagamento de uma fatura de cartão de crédito. Debita da conta origem e credita no cartão.
+
+QUANDO USAR: quando o usuário pagou a fatura do cartão e quer registrar.
+NÃO USAR QUANDO:
+- Quiser transferir entre contas normais — usar fin_criar_transferencia.
+- Quiser lançar despesa no cartão — usar fin_criar_despesa.
+
+CAMPOS:
+- amount_cents: number — valor pago em centavos (obrigatório).
+- card_name: string — nome do cartão (obrigatório, match parcial).
+- from_account_name: string — conta de onde saiu o dinheiro (obrigatório, match parcial).
+- tx_date: string YYYY-MM-DD — data do pagamento.
+- installments: number — parcelas do pagamento (2-48), se a fatura for parcelada.
+
+REGRAS DE NEGÓCIO:
+- Valores em centavos.
+- Suporta parcelamento do pagamento da fatura (não confundir com parcelamento de compras).`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        amount_cents: { type: "number", description: "Valor em centavos" },
+        card_name: { type: "string" },
+        from_account_name: { type: "string" },
+        tx_date: { type: "string", description: "YYYY-MM-DD" },
+        installments: { type: "number", description: "Parcelas (2-48)" },
+      },
+      required: ["amount_cents", "card_name", "from_account_name"],
+    },
+  },
+  {
+    name: "fin_editar_transacao",
+    description: `Edita uma transação existente. Apenas os campos informados são alterados — campos omitidos permanecem inalterados.
+
+QUANDO USAR: corrigir valor, descrição, categoria, conta ou data de uma transação.
+NÃO USAR QUANDO: quiser deletar (usar fin_deletar_transacao) ou criar nova (usar tools de criação).
+
+CAMPOS:
+- transaction_id: string UUID — ID da transação (obrigatório).
+- new_amount_cents: number — novo valor em centavos.
+- new_description: string — nova descrição.
+- new_category_name: string — nova categoria (por nome).
+- new_subcategory_name: string — nova subcategoria (por nome).
+- new_account_name: string — nova conta (por nome).
+- new_date: string YYYY-MM-DD — nova data.
+- new_invoice_cycle_end: string YYYY-MM-DD — força a transação pra uma fatura específica (data de fechamento do ciclo).
+
+REGRAS DE NEGÓCIO:
+- Valores em centavos.
+- Campos omitidos não são alterados.
+- O transaction_id é um UUID (usar fin_buscar_transacoes ou fin_todas_transacoes para encontrar).
+- new_invoice_cycle_end: usar para mover uma transação entre faturas (ex: estorno que o banco listou em fatura diferente da compra).`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        transaction_id: { type: "string", description: "UUID da transação" },
+        new_amount_cents: { type: "number" },
+        new_description: { type: "string" },
+        new_category_name: { type: "string" },
+        new_subcategory_name: { type: "string" },
+        new_account_name: { type: "string" },
+        new_date: { type: "string", description: "YYYY-MM-DD" },
+        new_invoice_cycle_end: { type: "string", description: "YYYY-MM-DD — data de fechamento do ciclo da fatura" },
+      },
+      required: ["transaction_id"],
+    },
+  },
+  {
+    name: "fin_deletar_transacao",
+    description: `Deleta uma transação pelo ID.
+
+QUANDO USAR: remover uma transação lançada por engano ou duplicada.
+
+CAMPOS:
+- transaction_id: string UUID — ID da transação (obrigatório).
+
+REGRAS DE NEGÓCIO:
+- ATENÇÃO: se a transação faz parte de um parcelamento, deletar UMA parcela deleta TODAS as parcelas do grupo (todas com o mesmo installment_group_id).
+- A operação é irreversível.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        transaction_id: { type: "string", description: "UUID da transação" },
+      },
+      required: ["transaction_id"],
+    },
+  },
+  {
+    name: "fin_ajuste_fatura",
+    description: `Cria ou atualiza um ajuste manual no total de uma fatura de cartão de crédito. Ajustes somam (positivo) ou subtraem (negativo) do net_total da fatura.
+
+QUANDO USAR:
+- O banco aplicou um crédito/cancelamento de outro ciclo como desconto no pagamento da fatura (cross-cycle credit). Criar ajuste NEGATIVO na fatura que recebeu o crédito.
+- O banco lista um estorno na fatura mas NÃO desconta do total. Criar ajuste POSITIVO pra anular o efeito do refund no net_total.
+
+NÃO USAR QUANDO:
+- O estorno/crédito se comporta normalmente (abate do total na mesma fatura que a compra). Nesse caso, basta lançar o estorno com fin_criar_despesa + reversal_of_id.
+- Quiser mover uma transação entre faturas (usar invoice_cycle_end em fin_criar_despesa ou fin_editar_transacao).
+
+CAMPOS:
+- card_name: string — nome do cartão de crédito (obrigatório, match parcial).
+- cycle_end: string YYYY-MM-DD — data de fechamento do ciclo da fatura (obrigatório). ATENÇÃO: é a data de fechamento (closing_day), NÃO o reference_month. Use fin_fatura_transacoes pra descobrir o cycle_end de uma fatura.
+- amount_cents: number — valor do ajuste em centavos (obrigatório). Positivo = aumenta o total, Negativo = reduz o total.
+
+REGRAS DE NEGÓCIO:
+- Só funciona para cartões de crédito (type: credit).
+- Um ajuste por (cartão, ciclo). Se já existe, o valor é sobrescrito.
+- Ajustes aparecem como kind: 'adjustment' na listagem da fatura.
+- Valores em centavos.
+
+EXEMPLO — crédito cross-cycle (GoDaddy R$593,22 aplicado na fatura Abr):
+{ "card_name": "Latam Itaú", "cycle_end": "2026-04-01", "amount_cents": -59322 }
+
+EXEMPLO — anular estorno que não abate (GitHub R$38,63):
+{ "card_name": "Latam Itaú", "cycle_end": "2026-04-01", "amount_cents": 3863 }`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        card_name: { type: "string", description: "Nome do cartão de crédito" },
+        cycle_end: { type: "string", description: "YYYY-MM-DD — data de fechamento do ciclo da fatura" },
+        amount_cents: { type: "number", description: "Valor em centavos (positivo ou negativo)" },
+      },
+      required: ["card_name", "cycle_end", "amount_cents"],
+    },
+  },
+  // ── Bills (Contas a Pagar) ──────────────────────────────────────
+  {
+    name: "fin_listar_bills",
+    description: `Lista todas as contas a pagar recorrentes ativas (Light, condomínio, internet, etc.).
+
+QUANDO USAR: para ver quais contas recorrentes estão cadastradas, seus valores default e dia de vencimento.
+NÃO USAR QUANDO: quiser saber o que falta pagar no mês (usar fin_bills_do_mes).
+
+REGRAS DE NEGÓCIO:
+- Retorna apenas bills ativas (is_active: true).
+- amount_type 'fixed' = valor fixo todo mês; 'variable' = valor muda.
+- default_amount_cents: valor padrão da conta (pode ser null se variable).
+- Valores em centavos.`,
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "fin_bills_do_mes",
+    description: `Lista as contas a pagar do mês com status: pendente, atrasada, paga, ou paga em atraso. Responde "o que falta pagar este mês?".
+
+QUANDO USAR: no início de sessão financeira para saber quais contas recorrentes já foram pagas e quais estão pendentes/atrasadas.
+NÃO USAR QUANDO: quiser ver transações gerais (usar fin_todas_transacoes) ou faturas de cartão (usar fin_fatura_cartao).
+
+CAMPOS:
+- month: string YYYY-MM — mês de referência (default: mês atual).
+
+REGRAS DE NEGÓCIO:
+- Status: 'pending' (aguardando vencimento), 'overdue' (vencida e não paga), 'paid' (paga no prazo), 'paid_late' (paga em atraso).
+- Ocorrências são geradas automaticamente para cada bill ativa no mês consultado.
+- amount_cents: valor definido para esta ocorrência (null se ainda não definido — usar default_amount_cents da bill).
+- transaction_id: preenchido quando a conta foi paga (link para a transação de despesa).
+- Valores em centavos.
+
+EXEMPLO:
+{ "month": "2026-04" }
+
+Retorno: [{ bill_name: "Light", status: "pending", due_date: "2026-04-01", amount_cents: null }, ...]`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        month: { type: "string", description: "YYYY-MM (default: mês atual)" },
+      },
+    },
+  },
+  {
+    name: "fin_pagar_bill",
+    description: `Marca uma conta a pagar como paga e cria a transação de despesa automaticamente.
+
+QUANDO USAR: ao conciliar extrato e encontrar pagamento de uma conta recorrente (Light, condomínio, faxina, etc.). Use fin_bills_do_mes primeiro para obter o occurrence_id.
+NÃO USAR QUANDO: quiser lançar despesa avulsa que não é conta recorrente (usar fin_criar_despesa).
+
+CAMPOS:
+- occurrence_id: string UUID — ID da ocorrência (obrigatório, obter via fin_bills_do_mes).
+- amount_cents: number — valor pago em centavos (obrigatório).
+- account_name: string — conta de onde saiu o dinheiro (obrigatório, match parcial).
+- category_name: string — categoria da despesa (opcional, usa default da bill se omitido).
+- subcategory_name: string — subcategoria (opcional).
+- payment_date: string YYYY-MM-DD — data do pagamento (default: hoje).
+
+REGRAS DE NEGÓCIO:
+- Se a ocorrência já foi paga, retorna erro.
+- Cria transação de despesa automaticamente (não precisa chamar fin_criar_despesa).
+- Se category_name não for informado, usa a categoria default cadastrada na bill.
+- Valores em centavos.
+- Não suporta multa/juros no momento.
+
+EXEMPLO:
+{ "occurrence_id": "uuid-da-ocorrencia", "amount_cents": 35000, "account_name": "Itaú", "payment_date": "2026-04-01" }`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        occurrence_id: { type: "string", description: "UUID da ocorrência (de fin_bills_do_mes)" },
+        amount_cents: { type: "number", description: "Valor pago em centavos" },
+        account_name: { type: "string", description: "Nome da conta" },
+        category_name: { type: "string", description: "Categoria (opcional, usa default da bill)" },
+        subcategory_name: { type: "string", description: "Subcategoria (opcional)" },
+        payment_date: { type: "string", description: "YYYY-MM-DD (default: hoje)" },
+      },
+      required: ["occurrence_id", "amount_cents", "account_name"],
+    },
+  },
+  {
+    name: "fin_criar_bill",
+    description: `Cria uma nova conta a pagar recorrente (ex: Light, condomínio, streaming).
+
+QUANDO USAR: o usuário contratou um novo serviço ou tem uma nova conta fixa mensal.
+NÃO USAR QUANDO: quiser pagar uma conta existente (usar fin_pagar_bill).
+
+CAMPOS:
+- name: string — nome da conta (obrigatório, ex: "Light", "Condomínio").
+- due_day: number — dia de vencimento, 1-31 (obrigatório).
+- amount_type: string — 'fixed' (valor fixo) ou 'variable' (muda todo mês). Default: 'variable'.
+- default_amount_cents: number — valor padrão em centavos (para fixed).
+- account_name: string — conta default de pagamento (match parcial).
+- category_name: string — categoria default.
+- subcategory_name: string — subcategoria default.
+
+REGRAS DE NEGÓCIO:
+- amount_type 'fixed' = valor fixo todo mês (ex: condomínio R$1.383).
+- amount_type 'variable' = valor muda (ex: Light). Definido no momento do pagamento.
+- Valores em centavos.
+
+EXEMPLO:
+{ "name": "Light", "due_day": 1, "amount_type": "variable", "category_name": "Moradia", "account_name": "Itaú" }`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Nome da conta (ex: Light, Condomínio)" },
+        due_day: { type: "number", description: "Dia de vencimento (1-31)" },
+        amount_type: { type: "string", description: "'fixed' ou 'variable' (default: variable)" },
+        default_amount_cents: { type: "number", description: "Valor padrão em centavos (para fixed)" },
+        account_name: { type: "string", description: "Conta default de pagamento" },
+        category_name: { type: "string", description: "Categoria default" },
+        subcategory_name: { type: "string", description: "Subcategoria default" },
+      },
+      required: ["name", "due_day"],
+    },
+  },
+  {
+    name: "fin_editar_bill",
+    description: `Edita uma conta a pagar recorrente: nome, dia de vencimento, valor, categoria, ou desativar.
+
+QUANDO USAR: mudar configurações de uma conta existente ou desativar.
+
+CAMPOS:
+- bill_id: string UUID — ID da bill (obrigatório, obter via fin_listar_bills).
+- name: string — novo nome.
+- due_day: number — novo dia de vencimento (1-31).
+- amount_type: string — 'fixed' ou 'variable'.
+- default_amount_cents: number — novo valor padrão em centavos.
+- account_name: string — nova conta default.
+- category_name: string — nova categoria default.
+- subcategory_name: string — nova subcategoria default.
+- is_active: boolean — false para desativar (soft delete).
+
+REGRAS DE NEGÓCIO:
+- Campos omitidos não são alterados.
+- is_active: false desativa a bill (não gera novas ocorrências, mas mantém histórico).
+- Valores em centavos.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        bill_id: { type: "string", description: "UUID da bill" },
+        name: { type: "string", description: "Novo nome" },
+        due_day: { type: "number", description: "Novo dia de vencimento (1-31)" },
+        amount_type: { type: "string", description: "'fixed' ou 'variable'" },
+        default_amount_cents: { type: "number", description: "Novo valor padrão em centavos" },
+        account_name: { type: "string", description: "Nova conta default" },
+        category_name: { type: "string", description: "Nova categoria default" },
+        subcategory_name: { type: "string", description: "Nova subcategoria default" },
+        is_active: { type: "boolean", description: "false para desativar" },
+      },
+      required: ["bill_id"],
+    },
+  },
+  // ── Admin / Setup ─────────────────────────────────────────────────
+  {
+    name: "fin_criar_conta",
+    description: `Cria uma nova conta bancária.
+
+QUANDO USAR: o usuário quer adicionar uma conta corrente, carteira, poupança ou cartão de crédito.
+
+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).
+- 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').
+
+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.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Nome da conta (ex: Nubank, Inter)" },
+        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)" },
+        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)" },
+      },
+      required: ["name", "type"],
+    },
+  },
+  {
+    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.
+
+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.
+- 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.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        account_id: { type: "string", description: "UUID da conta" },
+        name: { type: "string", description: "Novo nome" },
+        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" },
+        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" },
+      },
+      required: ["account_id"],
+    },
+  },
+  {
+    name: "fin_criar_categoria",
+    description: `Cria uma nova categoria de transação.
+
+QUANDO USAR: o usuário quer uma nova categoria que não existe.
+NÃO USAR QUANDO: a categoria já existir (verificar com fin_listar_categorias).
+
+CAMPOS:
+- name: string — nome da categoria (obrigatório).
+- flow: string — 'expense' (despesa) ou 'income' (receita) (obrigatório).
+
+REGRAS DE NEGÓCIO:
+- flow define se a categoria é usada em despesas ou receitas.
+- Não é possível usar uma categoria de flow 'income' em despesas e vice-versa.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Nome da categoria" },
+        flow: { type: "string", description: "'expense' ou 'income'" },
+      },
+      required: ["name", "flow"],
+    },
+  },
+  {
+    name: "fin_editar_categoria",
+    description: `Edita uma categoria existente: nome, flow, ou status (ativar/arquivar).
+
+QUANDO USAR: renomear, mudar flow, ou arquivar uma categoria.
+
+CAMPOS:
+- category_id: string UUID — ID da categoria (obrigatório).
+- name: string — novo nome.
+- flow: string — 'expense' ou 'income'.
+- is_active: boolean — true para ativar, false para arquivar.
+
+REGRAS DE NEGÓCIO:
+- is_active: false arquiva a categoria (seta archived_at automaticamente).
+- is_active: true reativa (limpa archived_at).
+- Categorias arquivadas não aparecem como opção ao criar transações, mas transações antigas permanecem.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        category_id: { type: "string", description: "UUID da categoria" },
+        name: { type: "string", description: "Novo nome" },
+        flow: { type: "string", description: "'expense' ou 'income'" },
+        is_active: { type: "boolean", description: "true pra ativar, false pra arquivar" },
+      },
+      required: ["category_id"],
+    },
+  },
+  {
+    name: "fin_criar_subcategoria",
+    description: `Cria uma nova subcategoria vinculada a uma categoria existente.
+
+QUANDO USAR: o usuário quer subdividir uma categoria (ex: "Alimentação" → "Restaurantes", "Mercado").
+NÃO USAR QUANDO: a subcategoria já existir (verificar com fin_listar_categorias).
+
+CAMPOS:
+- name: string — nome da subcategoria (obrigatório).
+- category_name: string — nome da categoria pai (obrigatório, resolvido por nome).
+
+REGRAS DE NEGÓCIO:
+- A categoria pai deve existir.
+- A subcategoria herda o flow da categoria pai.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Nome da subcategoria" },
+        category_name: { type: "string", description: "Nome da categoria pai" },
+      },
+      required: ["name", "category_name"],
+    },
+  },
+  {
+    name: "fin_editar_subcategoria",
+    description: `Edita uma subcategoria existente: nome, categoria pai, ou status.
+
+QUANDO USAR: renomear, mover para outra categoria pai, ou arquivar.
+
+CAMPOS:
+- subcategory_id: string UUID — ID da subcategoria (obrigatório).
+- name: string — novo nome.
+- category_name: string — nome da nova categoria pai.
+- is_active: boolean — true para ativar, false para arquivar.
+
+REGRAS DE NEGÓCIO:
+- Mesma lógica de arquivamento que categorias (is_active: false seta archived_at).`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        subcategory_id: { type: "string", description: "UUID da subcategoria" },
+        name: { type: "string", description: "Novo nome" },
+        category_name: { type: "string", description: "Nome da nova categoria pai" },
+        is_active: { type: "boolean", description: "true pra ativar, false pra arquivar" },
+      },
+      required: ["subcategory_id"],
+    },
+  },
+];
+
+// ── Tool handlers ───────────────────────────────────────────────────
+
+async function handleTool(name, args) {
+  switch (name) {
+    case "fin_resumo_mensal": {
+      const qs = args.month ? `?month=${args.month}` : "";
+      return ok(await api("GET", `/api/genius/summary${qs}`));
+    }
+    case "fin_gastos_por_categoria": {
+      const qs = args.month ? `?month=${args.month}` : "";
+      return ok(await api("GET", `/api/genius/spending${qs}`));
+    }
+    case "fin_saldos": {
+      const qs = args.account_name
+        ? `?account_name=${encodeURIComponent(args.account_name)}`
+        : "";
+      return ok(await api("GET", `/api/genius/balance${qs}`));
+    }
+    case "fin_buscar_transacoes": {
+      const params = new URLSearchParams();
+      if (args.q) params.set("q", args.q);
+      if (args.date_from) params.set("date_from", args.date_from);
+      if (args.date_to) params.set("date_to", args.date_to);
+      if (args.category) params.set("category", args.category);
+      if (args.account) params.set("account", args.account);
+      if (args.limit) params.set("limit", String(args.limit));
+      const qs = params.toString() ? `?${params}` : "";
+      return ok(await api("GET", `/api/genius/transactions${qs}`));
+    }
+    case "fin_fatura_cartao": {
+      const params = new URLSearchParams();
+      if (args.card_name) params.set("card_name", args.card_name);
+      if (args.reference_month)
+        params.set("reference_month", args.reference_month);
+      const qs = params.toString() ? `?${params}` : "";
+      return ok(await api("GET", `/api/genius/card-invoice${qs}`));
+    }
+    case "fin_contexto": {
+      return ok(await api("GET", `/api/genius/context`));
+    }
+    case "fin_todas_transacoes": {
+      const params = new URLSearchParams();
+      if (args.account) params.set("account", args.account);
+      if (args.date_from) params.set("date_from", args.date_from);
+      if (args.date_to) params.set("date_to", args.date_to);
+      if (args.tx_type) params.set("tx_type", args.tx_type);
+      if (args.category) params.set("category", args.category);
+      if (args.page) params.set("page", String(args.page));
+      if (args.per_page) params.set("per_page", String(args.per_page));
+      const qs = params.toString() ? `?${params}` : "";
+      return ok(await api("GET", `/api/genius/transactions/all${qs}`));
+    }
+    case "fin_relatorio": {
+      const params = new URLSearchParams();
+      params.set("from_month", args.from_month);
+      params.set("to_month", args.to_month);
+      return ok(await api("GET", `/api/genius/report?${params}`));
+    }
+    case "fin_receitas": {
+      const params = new URLSearchParams();
+      if (args.account) params.set("account", args.account);
+      if (args.date_from) params.set("date_from", args.date_from);
+      if (args.date_to) params.set("date_to", args.date_to);
+      if (args.page) params.set("page", String(args.page));
+      if (args.per_page) params.set("per_page", String(args.per_page));
+      const qs = params.toString() ? `?${params}` : "";
+      return ok(await api("GET", `/api/genius/income${qs}`));
+    }
+    case "fin_fatura_transacoes": {
+      const params = new URLSearchParams();
+      params.set("card_name", args.card_name);
+      if (args.reference_month) params.set("reference_month", args.reference_month);
+      return ok(await api("GET", `/api/genius/card-invoice/transactions?${params}`));
+    }
+    case "fin_criar_despesa": {
+      return ok(await api("POST", `/api/genius/expenses`, args));
+    }
+    case "fin_criar_receita": {
+      return ok(await api("POST", `/api/genius/income`, args));
+    }
+    case "fin_criar_transferencia": {
+      return ok(await api("POST", `/api/genius/transfers`, args));
+    }
+    case "fin_pagar_fatura": {
+      return ok(await api("POST", `/api/genius/card-payments`, args));
+    }
+    case "fin_editar_transacao": {
+      const { transaction_id, ...body } = args;
+      return ok(await api("PATCH", `/api/genius/transactions/${transaction_id}`, body));
+    }
+    case "fin_deletar_transacao": {
+      return ok(
+        await api("DELETE", `/api/genius/transactions/${args.transaction_id}`)
+      );
+    }
+    case "fin_ajuste_fatura": {
+      return ok(await api("POST", `/api/genius/card-invoice-adjustments`, args));
+    }
+    case "fin_listar_bills": {
+      return ok(await api("GET", `/api/genius/bills`));
+    }
+    case "fin_bills_do_mes": {
+      const qs = args.month ? `?month=${args.month}` : "";
+      return ok(await api("GET", `/api/genius/bills/occurrences${qs}`));
+    }
+    case "fin_pagar_bill": {
+      return ok(await api("POST", `/api/genius/bills/pay`, args));
+    }
+    case "fin_criar_bill": {
+      return ok(await api("POST", `/api/genius/bills`, args));
+    }
+    case "fin_editar_bill": {
+      const { bill_id, ...body } = args;
+      return ok(await api("PATCH", `/api/genius/bills/${bill_id}`, body));
+    }
+    // ── Admin / Setup handlers ──────────────────────────────────────
+    case "fin_listar_contas": {
+      return ok(await api("GET", `/api/genius/accounts`));
+    }
+    case "fin_criar_conta": {
+      return ok(await api("POST", `/api/genius/accounts`, args));
+    }
+    case "fin_editar_conta": {
+      const { account_id, ...body } = args;
+      return ok(await api("PATCH", `/api/genius/accounts/${account_id}`, body));
+    }
+    case "fin_listar_categorias": {
+      return ok(await api("GET", `/api/genius/categories`));
+    }
+    case "fin_criar_categoria": {
+      return ok(await api("POST", `/api/genius/categories`, args));
+    }
+    case "fin_editar_categoria": {
+      const { category_id, ...body } = args;
+      return ok(await api("PATCH", `/api/genius/categories/${category_id}`, body));
+    }
+    case "fin_criar_subcategoria": {
+      return ok(await api("POST", `/api/genius/subcategories`, args));
+    }
+    case "fin_editar_subcategoria": {
+      const { subcategory_id, ...body } = args;
+      return ok(await api("PATCH", `/api/genius/subcategories/${subcategory_id}`, body));
+    }
+    default:
+      return err(`Tool desconhecida: ${name}`);
+  }
+}
+
+// ── Server ──────────────────────────────────────────────────────────
+
+const server = new Server(
+  { name: "fin-app", version: "2.0.0" },
+  { capabilities: { tools: {}, resources: {} } }
+);
+
+// Tools
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  try {
+    return await handleTool(req.params.name, req.params.arguments ?? {});
+  } catch (e) {
+    return err(e.message);
+  }
+});
+
+// Resources
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: [
+    {
+      uri: "fin://docs/guia",
+      name: "Guia do FIN",
+      description:
+        "Regras de negócio do FIN: ciclo de fatura, estorno, parcelamento, modelo de dados. Leia antes de operar.",
+      mimeType: "text/markdown",
+    },
+  ],
+}));
+
+server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+  if (req.params.uri === "fin://docs/guia") {
+    return {
+      contents: [
+        { uri: "fin://docs/guia", text: guiaContent, mimeType: "text/markdown" },
+      ],
+    };
+  }
+  throw new Error(`Resource não encontrado: ${req.params.uri}`);
+});
+
+// Start
+const transport = new StdioServerTransport();
+await server.connect(transport);