next-finance-mcp 0.9.39 → 0.9.41

package/dist/client.d.ts

@@ -123,6 +123,7 @@ export interface CriteriosLancamento {
     data: string;
     valor?: number;
     descricao?: string;
+    moeda?: string;
 }
 /** Edita um lançamento existente. Localiza por critérios e aplica as alterações. */
 export interface EditarLancamentoOpts extends CriteriosLancamento {
@@ -364,6 +365,7 @@ export declare function buscarLancamentos(opts: FiltroLancamentos): Promise<Resu
 export interface TituloSlim {
     vencimento: string;
     valor: number;
+    moeda: string;
     contraparte: string;
     conta: string;
     em_cobranca: boolean;
@@ -378,12 +380,21 @@ export interface FiltroTitulos {
     dataInicio?: string;
     dataFim?: string;
     busca?: string;
+    moeda?: string;
     apenasVencidos?: boolean;
     incluirCobranca?: boolean;
     apenasCobranca?: boolean;
     pagina?: number;
     limite?: number;
 }
+export interface TotaisTitulosMoeda {
+    moeda: string;
+    quantidade: number;
+    valor_total: number;
+    valor_vencido: number;
+    valor_a_vencer: number;
+    em_cobranca: number;
+}
 export interface ResultadoTitulos {
     titulos: TituloSlim[];
     paginacao: PaginaMeta;
@@ -391,15 +402,10 @@ export interface ResultadoTitulos {
         inicio: string;
         fim: string;
     };
-    totais: {
-        quantidade: number;
-        valor_total: number;
-        valor_vencido: number;
-        valor_a_vencer: number;
-        em_cobranca: number;
-    };
+    totais_por_moeda: TotaisTitulosMoeda[];
     por_contraparte?: {
         contraparte: string;
+        moeda: string;
         valor: number;
         quantidade: number;
         vencido: number;
@@ -407,15 +413,43 @@ export interface ResultadoTitulos {
 }
 export declare const buscarContasAPagar: (o?: FiltroTitulos) => Promise<ResultadoTitulos>;
 export declare const buscarContasAReceber: (o?: FiltroTitulos) => Promise<ResultadoTitulos>;
+export interface PeriodicoSlim {
+    descricao: string;
+    valor_estimado: number;
+    moeda: string;
+    dia: number;
+    periodicidade: string;
+    plano_de_contas?: string;
+    centro_de_custo?: string;
+    variacao_tolerada_pct?: number;
+    previsoes_associadas: number;
+    observacoes?: string;
+}
+export interface FiltroPeriodicos {
+    busca?: string;
+    moeda?: string;
+}
+export interface ResultadoPeriodicos {
+    periodicos: PeriodicoSlim[];
+    estimativa_mensal_por_moeda: {
+        moeda: string;
+        quantidade: number;
+        valor: number;
+    }[];
+}
+export declare const buscarDespesasPeriodicas: (o?: FiltroPeriodicos) => Promise<ResultadoPeriodicos>;
+export declare const buscarReceitasPeriodicas: (o?: FiltroPeriodicos) => Promise<ResultadoPeriodicos>;
 export interface ClienteSlim {
     nome: string;
     tipo: "PF" | "PJ";
+    moeda: string;
     titulos_a_receber: number;
     valor_a_receber: number;
     valor_vencido: number;
 }
 export interface FiltroClientes {
     busca?: string;
+    moeda?: string;
     pagina?: number;
     limite?: number;
 }
@@ -423,7 +457,10 @@ export interface FiltroClientes {
 export declare function listarClientes(opts?: FiltroClientes): Promise<{
     clientes: ClienteSlim[];
     paginacao: PaginaMeta;
-    total_a_receber: number;
+    total_a_receber_por_moeda: {
+        moeda: string;
+        valor: number;
+    }[];
 }>;
 export interface UltimoPrecoProdutoOpts {
     busca: string;

package/dist/client.js

@@ -1004,38 +1004,58 @@ export async function criarTransferencia(o) {
     };
 }
 /** Localiza UM lançamento por critérios. Retorna ID interno (não exposto).
- *  Usado por editar/excluir → exige permissão Editar na conta. */
+ *  Usado por editar/excluir → exige permissão Editar na conta.
+ *  IMPORTANTE: há contas HOMÔNIMAS (ex.: 5 contas "Conta a Pagar", uma por moeda).
+ *  Por isso varremos TODAS as contas cujo nome casa e desambiguamos por
+ *  valor/descrição/moeda — assim a edição funciona mesmo com nomes repetidos. */
 async function localizarLancamento(crit) {
-    const { id: idConta } = await resolverIdConta(crit.nomeConta, "Editar");
-    const body = {
-        IntervaloDeDatas: { DataInicio: crit.data, DataFim: crit.data },
-        Pagina: 0, RegistrosPorPagina: 200,
-        ListarOrdenadoPelaDataDeModificacao: false,
-        IdConta: idConta,
+    const { contas } = await fetchContas();
+    const me = await obterUsuarioLogado();
+    const termo = crit.nomeConta.trim().toLowerCase();
+    const candContas = contas
+        .filter(isContaAtiva)
+        .filter(c => permissaoDaConta(c, me) === "Editar")
+        .filter(c => String(c["Nome"] ?? c["NomeConta"] ?? "").toLowerCase().includes(termo));
+    if (candContas.length === 0) {
+        throw new Error(`Conta "${crit.nomeConta}" não encontrada (ou sem permissão de edição).`);
+    }
+    // Resolve moeda de cada conta candidata (para desambiguar e filtrar)
+    const mapaMoedas = await obterMapaMoedas();
+    const moedaDaConta = (c) => {
+        const m = mapaMoedas.get(String(c["IdMoeda"] ?? ""));
+        return (m?.sigla || m?.nome || String(c["NomeMoeda"] ?? "")).trim();
     };
-    let lancs;
-    try {
-        const r = await apiPost("/api/Lancamento/Filtrar", body);
-        lancs = r["Lancamentos"] ?? [];
+    // Filtra por moeda, se informada (ex.: "BRL", "Real")
+    let contasBusca = candContas;
+    if (crit.moeda?.trim()) {
+        const tm = normalizar(crit.moeda);
+        contasBusca = candContas.filter(c => normalizar(moedaDaConta(c)).includes(tm));
+        if (contasBusca.length === 0) {
+            const disp = [...new Set(candContas.map(moedaDaConta))].join(", ");
+            throw new Error(`Nenhuma conta "${crit.nomeConta}" na moeda "${crit.moeda}". Moedas disponíveis: ${disp}`);
+        }
     }
-    catch {
-        // Fallback web
-        const params = new URLSearchParams();
-        params.set("filtro[IdConta]", idConta);
-        params.set("filtro[IntervaloDeDatas][DataInicio]", crit.data);
-        params.set("filtro[IntervaloDeDatas][DataFim]", crit.data);
-        params.set("filtro[ListarOrdenadoPelaDataDeModificacao]", "false");
-        const r = await webPost("/LancamentoAjax/Filtrar", params.toString(), "application/x-www-form-urlencoded");
-        if (r.status !== 200)
-            throw new Error(`Erro ${r.status} ao buscar lançamentos.`);
-        const raw = JSON.parse(r.text);
-        lancs = (Array.isArray(raw) ? raw : raw.Lancamentos) ?? [];
+    // Busca lançamentos na data em cada conta candidata
+    const all = [];
+    for (const c of contasBusca) {
+        const idConta = String(c["Id"] ?? "");
+        if (!idConta)
+            continue;
+        try {
+            const lancs = await fetchLancamentosWebDeUmaConta(idConta, crit.data, crit.data);
+            for (const l of lancs) {
+                if (!l["NomeConta"])
+                    l["NomeConta"] = c["Nome"];
+                l["__moeda"] = moedaDaConta(c);
+            }
+            all.push(...lancs);
+        }
+        catch { /* ignora conta que falhou; segue nas demais */ }
     }
     // Filtra por valor e descrição
-    let cand = lancs;
-    if (crit.valor !== undefined) {
+    let cand = all;
+    if (crit.valor !== undefined)
         cand = cand.filter(l => Math.abs(Number(l["Valor"]) - crit.valor) < 0.001);
-    }
     if (crit.descricao?.trim()) {
         const t = crit.descricao.trim().toLowerCase();
         cand = cand.filter(l => String(l["Descricao"] ?? "").toLowerCase().includes(t));
@@ -1044,11 +1064,11 @@ async function localizarLancamento(crit) {
         throw new Error(`Nenhum lançamento encontrado em ${crit.data} para "${crit.nomeConta}" com os critérios informados.`);
     }
     if (cand.length > 1) {
-        const lista = cand.slice(0, 5).map(l => `R$ ${Number(l["Valor"]).toFixed(2)} — ${String(l["Descricao"] ?? "")}`).join("; ");
-        throw new Error(`${cand.length} lançamentos batem com os critérios. Refine valor/descrição. Encontrados: ${lista}`);
+        const lista = cand.slice(0, 6).map(l => `${Number(l["Valor"]).toFixed(2)} ${String(l["__moeda"] ?? "")} — ${String(l["Descricao"] ?? "")} [${String(l["NomeConta"] ?? "")}]`).join("; ");
+        throw new Error(`${cand.length} lançamentos batem com os critérios. Refine valor/descrição/moeda. Encontrados: ${lista}`);
     }
     const m = cand[0];
-    return { id: String(m["Id"]), descricao: String(m["Descricao"] ?? ""), valor: Number(m["Valor"]) };
+    return { id: String(m["Id"]), descricao: String(m["Descricao"] ?? ""), valor: Number(m["Valor"]), conta: String(m["NomeConta"] ?? ""), moeda: m["__moeda"] ? String(m["__moeda"]) : undefined };
 }
 export async function editarLancamento(opts) {
     const alvo = await localizarLancamento(opts);
@@ -1896,6 +1916,11 @@ async function buscarTitulos(grupo, opts) {
     const cobrancaTipos = new Set(TIPOS_TITULO.cobranca);
     const { contas } = await fetchContas();
     const me = await obterUsuarioLogado();
+    const mapaMoedas = await obterMapaMoedas();
+    const moedaDaConta = (c) => {
+        const m = mapaMoedas.get(String(c["IdMoeda"] ?? ""));
+        return (m?.sigla || m?.nome || String(c["NomeMoeda"] ?? "") || "?").trim();
+    };
     const alvo = contas
         .filter(isContaAtiva)
         .filter(c => permissaoDaConta(c, me) !== "Negar")
@@ -1903,12 +1928,13 @@ async function buscarTitulos(grupo, opts) {
     const todas = await mapWithConcurrency(alvo, 8, async (c) => {
         const id = String(c["Id"] ?? c["IdConta"] ?? "");
         const nome = String(c["Nome"] ?? c["NomeConta"] ?? "");
+        const moeda = moedaDaConta(c);
         const emCob = cobrancaTipos.has(String(c["NomeTipoConta"] ?? "").toLowerCase().trim());
         if (!id)
             return [];
         try {
             const lancs = await fetchLancamentosWebDeUmaConta(id, dataInicio, dataFim);
-            return lancs.map(l => ({ l, nome, emCob }));
+            return lancs.map(l => ({ l, nome, moeda, emCob }));
         }
         catch {
             return [];
@@ -1917,7 +1943,7 @@ async function buscarTitulos(grupo, opts) {
     const hojeStr = isoDate(new Date());
     let titulos = todas.flat()
         .filter(({ l }) => !(l["IdLancamentoTransferencia"] ?? l["Transferencia"]))
-        .map(({ l, nome, emCob }) => {
+        .map(({ l, nome, moeda, emCob }) => {
         const s = slimLancamento(l);
         if (!s.conta)
             s.conta = nome;
@@ -1927,6 +1953,7 @@ async function buscarTitulos(grupo, opts) {
         return {
             vencimento: venc,
             valor: s.valor,
+            moeda,
             contraparte: s.descricao,
             conta: s.conta,
             em_cobranca: emCob,
@@ -1938,6 +1965,10 @@ async function buscarTitulos(grupo, opts) {
             observacoes: s.observacoes,
         };
     });
+    if (opts.moeda?.trim()) {
+        const tm = normalizar(opts.moeda);
+        titulos = titulos.filter(t => normalizar(t.moeda).includes(tm));
+    }
     if (opts.apenasCobranca)
         titulos = titulos.filter(t => t.em_cobranca);
     if (opts.busca) {
@@ -1947,19 +1978,23 @@ async function buscarTitulos(grupo, opts) {
     if (opts.apenasVencidos)
         titulos = titulos.filter(x => x.vencido);
     titulos.sort((a, b) => (a.vencimento < b.vencimento ? -1 : a.vencimento > b.vencimento ? 1 : 0));
-    let valorTotal = 0, valorVencido = 0, valorAVencer = 0, valorCobranca = 0;
+    // Totais SEMPRE separados por moeda (nunca somar moedas diferentes)
+    const mapMoeda = new Map();
     const mapCp = new Map();
     for (const t of titulos) {
         const v = Math.abs(t.valor);
-        valorTotal += v;
+        const tm = mapMoeda.get(t.moeda) ?? { moeda: t.moeda, quantidade: 0, valor_total: 0, valor_vencido: 0, valor_a_vencer: 0, em_cobranca: 0 };
+        tm.quantidade += 1;
+        tm.valor_total += v;
         if (t.vencido)
-            valorVencido += v;
+            tm.valor_vencido += v;
         else
-            valorAVencer += v;
+            tm.valor_a_vencer += v;
         if (t.em_cobranca)
-            valorCobranca += v;
-        const key = t.contraparte || "(sem descrição)";
-        const g = mapCp.get(key) ?? { contraparte: key, valor: 0, quantidade: 0, vencido: 0 };
+            tm.em_cobranca += v;
+        mapMoeda.set(t.moeda, tm);
+        const key = `${t.contraparte || "(sem descrição)"}|${t.moeda}`;
+        const g = mapCp.get(key) ?? { contraparte: t.contraparte || "(sem descrição)", moeda: t.moeda, valor: 0, quantidade: 0, vencido: 0 };
         g.valor += v;
         g.quantidade += 1;
         if (t.vencido)
@@ -1968,38 +2003,103 @@ async function buscarTitulos(grupo, opts) {
     }
     const inicio = (pagina - 1) * limite;
     const pageItems = titulos.slice(inicio, inicio + limite);
+    const totais_por_moeda = [...mapMoeda.values()]
+        .sort((a, b) => b.valor_total - a.valor_total)
+        .map(t => ({ moeda: t.moeda, quantidade: t.quantidade, valor_total: round2(t.valor_total), valor_vencido: round2(t.valor_vencido), valor_a_vencer: round2(t.valor_a_vencer), em_cobranca: round2(t.em_cobranca) }));
     const por_contraparte = [...mapCp.values()]
         .sort((a, b) => b.valor - a.valor).slice(0, 50)
-        .map(g => ({ contraparte: g.contraparte, valor: round2(g.valor), quantidade: g.quantidade, vencido: round2(g.vencido) }));
+        .map(g => ({ contraparte: g.contraparte, moeda: g.moeda, valor: round2(g.valor), quantidade: g.quantidade, vencido: round2(g.vencido) }));
     return {
         titulos: pageItems,
         paginacao: { pagina, limite, total: titulos.length, paginas: Math.ceil(titulos.length / limite) || 1, tem_mais: inicio + limite < titulos.length },
         periodo: { inicio: dataInicio, fim: dataFim },
-        totais: {
-            quantidade: titulos.length,
-            valor_total: round2(valorTotal),
-            valor_vencido: round2(valorVencido),
-            valor_a_vencer: round2(valorAVencer),
-            em_cobranca: round2(valorCobranca),
-        },
+        totais_por_moeda,
         por_contraparte,
     };
 }
 export const buscarContasAPagar = (o = {}) => buscarTitulos("pagar", o);
 export const buscarContasAReceber = (o = {}) => buscarTitulos("receber", o);
+// ── Despesas / Receitas Periódicas (camada de ESTIMATIVA) ────────────────────
+// Modelo recorrente que o usuário cadastra nas telas "Despesas Periódicas" /
+// "Receitas Periódicas". É a ESTIMATIVA mensal (valor previsto, dia do mês),
+// que depois é programada em Contas a Pagar/Receber e, ao pagar/receber, vira
+// lançamento real na conta corrente. Endpoint: POST /api/LancamentoPeriodico/Filtrar
+// {IdConta} — um conjunto por conta-título (a pagar/receber), por moeda.
+const PERIODICIDADE_LABEL = { 0: "Mensal", 1: "Bimestral", 2: "Trimestral", 3: "Semestral", 4: "Anual" };
+async function buscarPeriodicos(grupo, opts = {}) {
+    log("buscar_periodicos", grupo, opts.busca ?? "", opts.moeda ?? "");
+    const { contas } = await fetchContas();
+    const me = await obterUsuarioLogado();
+    const mapaMoedas = await obterMapaMoedas();
+    const moedaDaConta = (c) => {
+        const m = mapaMoedas.get(String(c["IdMoeda"] ?? ""));
+        return (m?.sigla || m?.nome || String(c["NomeMoeda"] ?? "") || "?").trim();
+    };
+    const tipoAlvo = grupo === "pagar" ? "conta a pagar" : "conta a receber";
+    const alvo = contas
+        .filter(isContaAtiva)
+        .filter(c => permissaoDaConta(c, me) !== "Negar")
+        .filter(c => String(c["NomeTipoConta"] ?? "").toLowerCase().trim() === tipoAlvo);
+    const todas = await mapWithConcurrency(alvo, 6, async (c) => {
+        const id = String(c["Id"] ?? "");
+        const moeda = moedaDaConta(c);
+        if (!id)
+            return [];
+        try {
+            const r = await apiPost("/api/LancamentoPeriodico/Filtrar", { IdConta: id });
+            const arr = (Array.isArray(r) ? r : Object.values(r).find(v => Array.isArray(v)) ?? []);
+            return arr.map(p => ({ p, moeda }));
+        }
+        catch {
+            return [];
+        }
+    });
+    let periodicos = todas.flat().map(({ p, moeda }) => ({
+        descricao: String(p["Descricao"] ?? "").trim(),
+        valor_estimado: Number(p["Valor"] ?? 0),
+        moeda,
+        dia: Number(p["Dia"] ?? 0),
+        periodicidade: PERIODICIDADE_LABEL[Number(p["Periodicidade"] ?? 0)] ?? `Código ${p["Periodicidade"]}`,
+        plano_de_contas: p["NomePlanoDeContas"] ? String(p["NomePlanoDeContas"]).trim() : undefined,
+        centro_de_custo: p["NomeCentroDeCustos"] ? String(p["NomeCentroDeCustos"]).trim() : undefined,
+        variacao_tolerada_pct: p["PercentualDiferencaDeVariacao"] != null ? Number(p["PercentualDiferencaDeVariacao"]) : undefined,
+        previsoes_associadas: Number(p["QuantidadeDeLancamentosDePrevisaoAssociados"] ?? 0),
+        observacoes: p["Observacoes"] ? String(p["Observacoes"]).trim() : undefined,
+    }));
+    if (opts.moeda?.trim()) {
+        const tm = normalizar(opts.moeda);
+        periodicos = periodicos.filter(x => normalizar(x.moeda).includes(tm));
+    }
+    if (opts.busca?.trim()) {
+        const t = normalizar(opts.busca);
+        periodicos = periodicos.filter(x => normalizar(x.descricao).includes(t));
+    }
+    periodicos.sort((a, b) => a.dia - b.dia || a.descricao.localeCompare(b.descricao, "pt-BR"));
+    const mapMoeda = new Map();
+    for (const p of periodicos) {
+        const g = mapMoeda.get(p.moeda) ?? { moeda: p.moeda, quantidade: 0, valor: 0 };
+        g.quantidade += 1;
+        g.valor += Math.abs(p.valor_estimado);
+        mapMoeda.set(p.moeda, g);
+    }
+    return {
+        periodicos,
+        estimativa_mensal_por_moeda: [...mapMoeda.values()].sort((a, b) => b.valor - a.valor).map(g => ({ moeda: g.moeda, quantidade: g.quantidade, valor: round2(g.valor) })),
+    };
+}
+export const buscarDespesasPeriodicas = (o = {}) => buscarPeriodicos("pagar", o);
+export const buscarReceitasPeriodicas = (o = {}) => buscarPeriodicos("receber", o);
 /** Lista os clientes da carteira: pessoas com títulos a receber (a partir das contas a receber/cobrança). */
 export async function listarClientes(opts = {}) {
     log("listar_clientes", opts.busca ?? "");
     const pagina = Math.max(1, opts.pagina ?? 1);
     const limite = Math.min(200, Math.max(1, opts.limite ?? 50));
     // Base: títulos a receber (inclui em cobrança) — a contraparte é o cliente.
-    const recebiveis = await buscarTitulos("receber", { incluirCobranca: true, limite: 200, pagina: 1 });
-    // Reagrupa por contraparte usando TODOS os títulos (não só a página).
+    const recebiveis = await buscarTitulos("receber", { incluirCobranca: true, moeda: opts.moeda, limite: 200, pagina: 1 });
+    // Reagrupa por contraparte+moeda (nunca somar moedas diferentes).
     const mapa = new Map();
     for (const g of recebiveis.por_contraparte ?? []) {
-        const nome = g.contraparte;
-        // tipo: tenta achar a pessoa no cadastro para classificar PF/PJ
-        mapa.set(nome, { nome, tipo: "PJ", titulos_a_receber: g.quantidade, valor_a_receber: g.valor, valor_vencido: g.vencido });
+        mapa.set(`${g.contraparte}|${g.moeda}`, { nome: g.contraparte, tipo: "PJ", moeda: g.moeda, titulos_a_receber: g.quantidade, valor_a_receber: g.valor, valor_vencido: g.vencido });
     }
     // Classifica PF/PJ consultando o cadastro de pessoas (lista completa cacheada).
     try {
@@ -2018,11 +2118,14 @@ export async function listarClientes(opts = {}) {
         clientes = clientes.filter(c => normalizar(c.nome).includes(t));
     }
     clientes.sort((a, b) => b.valor_a_receber - a.valor_a_receber);
+    const totMoeda = new Map();
+    for (const c of clientes)
+        totMoeda.set(c.moeda, (totMoeda.get(c.moeda) ?? 0) + c.valor_a_receber);
     const inicio = (pagina - 1) * limite;
     return {
         clientes: clientes.slice(inicio, inicio + limite),
         paginacao: { pagina, limite, total: clientes.length, paginas: Math.ceil(clientes.length / limite) || 1, tem_mais: inicio + limite < clientes.length },
-        total_a_receber: round2(clientes.reduce((s, c) => s + c.valor_a_receber, 0)),
+        total_a_receber_por_moeda: [...totMoeda.entries()].map(([moeda, valor]) => ({ moeda, valor: round2(valor) })),
     };
 }
 /**

package/dist/index.js

@@ -11,7 +11,7 @@ import { enterDefaultCtx } from "./context.js";
 import { openLoginUI } from "./login-server.js";
 // Modo stdio: ativa um contexto único global no startup. Multi-tenancy só no modo HTTP.
 enterDefaultCtx();
-const server = new Server({ name: "next-finance-mcp", version: "0.9.39" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "next-finance-mcp", version: "0.9.41" }, { capabilities: { tools: {} } });
 // ── Ferramentas ─────────────────────────────────────────────────────────────
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
@@ -136,15 +136,16 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         {
             name: "buscar_contas_a_pagar",
             description: "Lista os TÍTULOS A PAGAR (contas a pagar) da carteira — agrega TODAS as contas do tipo 'Conta a Pagar'. " +
-                "Cada título traz: vencimento, valor, fornecedor (campo 'contraparte'), conta, se está vencido e os dias " +
-                "de atraso/para vencer. Retorna totais (valor_total, valor_vencido, valor_a_vencer) e agregação por fornecedor. " +
-                "Use apenas_vencidos=true para ver só o que está em atraso. Janela padrão: 1 ano atrás a 1 ano à frente.",
+                "Cada título traz: vencimento, valor, moeda, fornecedor (campo 'contraparte'), conta, se está vencido e os dias " +
+                "de atraso/para vencer. Retorna totais_por_moeda (nunca soma moedas diferentes) e agregação por fornecedor. " +
+                "Use moeda='BRL' para focar no real; apenas_vencidos=true para só o que está em atraso. Janela padrão: 1 ano atrás a 1 ano à frente.",
             inputSchema: {
                 type: "object",
                 properties: {
                     data_inicio: { type: "string", description: "Data início do vencimento YYYY-MM-DD (padrão: 1 ano atrás)" },
                     data_fim: { type: "string", description: "Data fim do vencimento YYYY-MM-DD (padrão: 1 ano à frente)" },
                     busca: { type: "string", description: "Filtra pelo nome do fornecedor (contraparte)" },
+                    moeda: { type: "string", description: "Filtra por moeda (ex: 'BRL'). Sem isso, retorna todas — e os totais vêm separados por moeda (nunca somados)." },
                     apenas_vencidos: { type: "boolean", description: "Se true, retorna só títulos vencidos (em atraso)" },
                     pagina: { type: "number", description: "Página (começa em 1, padrão: 1)" },
                     limite: { type: "number", description: "Títulos por página (padrão: 50, máximo: 200)" },
@@ -155,15 +156,16 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             name: "buscar_contas_a_receber",
             description: "Lista os TÍTULOS A RECEBER da carteira — agrega TODAS as contas do tipo 'Conta a Receber' e, por padrão, " +
                 "também as do tipo 'Contas em Cobrança' (cada título tem o flag em_cobranca). Cada título traz: vencimento, " +
-                "valor, cliente (campo 'contraparte'), conta, se está vencido e os dias de atraso/para vencer. Retorna totais " +
-                "(valor_total, valor_vencido, valor_a_vencer, em_cobranca) e agregação por cliente. Use apenas_cobranca=true " +
-                "para ver SÓ os recebíveis em cobrança, ou apenas_vencidos=true para só os vencidos. Janela padrão: 1 ano atrás a 1 ano à frente.",
+                "valor, moeda, cliente (campo 'contraparte'), conta, se está vencido e os dias de atraso/para vencer. Retorna " +
+                "totais_por_moeda (nunca soma moedas diferentes) e agregação por cliente. Use moeda='BRL' para focar no real; " +
+                "apenas_cobranca=true para SÓ os recebíveis em cobrança; apenas_vencidos=true para só os vencidos. Janela padrão: 1 ano atrás a 1 ano à frente.",
             inputSchema: {
                 type: "object",
                 properties: {
                     data_inicio: { type: "string", description: "Data início do vencimento YYYY-MM-DD (padrão: 1 ano atrás)" },
                     data_fim: { type: "string", description: "Data fim do vencimento YYYY-MM-DD (padrão: 1 ano à frente)" },
                     busca: { type: "string", description: "Filtra pelo nome do cliente (contraparte)" },
+                    moeda: { type: "string", description: "Filtra por moeda (ex: 'BRL'). Sem isso, retorna todas — e os totais vêm separados por moeda (nunca somados)." },
                     apenas_vencidos: { type: "boolean", description: "Se true, retorna só títulos vencidos (em atraso)" },
                     apenas_cobranca: { type: "boolean", description: "Se true, retorna SÓ os títulos em cobrança" },
                     incluir_cobranca: { type: "boolean", description: "Inclui as contas 'em Cobrança' na agregação (padrão: true)" },
@@ -172,6 +174,36 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
             },
         },
+        {
+            name: "buscar_despesas_periodicas",
+            description: "Lista as DESPESAS PERIÓDICAS (estimativas recorrentes) da carteira — a camada de PREVISÃO que o usuário " +
+                "cadastra na tela 'Despesas Periódicas' e que depois é programada em Contas a Pagar. Cada item traz: descrição, " +
+                "valor_estimado, moeda, dia do mês, periodicidade (Mensal/Anual…), plano de contas, centro de custo, " +
+                "variacao_tolerada_pct e previsoes_associadas. Retorna a estimativa_mensal_por_moeda (orçamento mensal). " +
+                "Use moeda='BRL' para focar no real. Distinta de buscar_contas_a_pagar (que traz os títulos já programados/reais).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    busca: { type: "string", description: "Filtra pela descrição (ex: 'Energisa')" },
+                    moeda: { type: "string", description: "Filtra por moeda (ex: 'BRL')" },
+                },
+            },
+        },
+        {
+            name: "buscar_receitas_periodicas",
+            description: "Lista as RECEITAS PERIÓDICAS (estimativas recorrentes) da carteira — a camada de PREVISÃO da tela " +
+                "'Receitas Periódicas', depois programada em Contas a Receber. Cada item traz: descrição, valor_estimado, " +
+                "moeda, dia do mês, periodicidade, plano de contas, centro de custo, variacao_tolerada_pct e previsoes_associadas. " +
+                "Retorna a estimativa_mensal_por_moeda. Use moeda='BRL' para focar no real. " +
+                "Distinta de buscar_contas_a_receber (títulos já programados/reais).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    busca: { type: "string", description: "Filtra pela descrição (ex: 'Aluguel')" },
+                    moeda: { type: "string", description: "Filtra por moeda (ex: 'BRL')" },
+                },
+            },
+        },
         {
             name: "listar_clientes",
             description: "Lista os CLIENTES da carteira (quem tem títulos a receber), ordenados pelo valor a receber. " +
@@ -183,6 +215,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 type: "object",
                 properties: {
                     busca: { type: "string", description: "Filtra pelo nome do cliente" },
+                    moeda: { type: "string", description: "Filtra por moeda dos recebíveis (ex: 'BRL'). O total a receber vem separado por moeda." },
                     pagina: { type: "number", description: "Página (começa em 1, padrão: 1)" },
                     limite: { type: "number", description: "Clientes por página (padrão: 50, máximo: 200)" },
                 },
@@ -234,8 +267,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "editar_lancamento",
-            description: "Edita um lançamento existente. Localiza pelo trio (nome_conta + data + valor/descrição) e aplica " +
-                "as alterações informadas. Se mais de um lançamento bater, a tool lista as opções para você refinar.",
+            description: "Edita um lançamento existente. Localiza pelo nome_conta + data + valor/descrição (varre TODAS as contas " +
+                "homônimas, inclusive em moedas diferentes — ex: as várias 'Conta a Pagar') e aplica as alterações. " +
+                "Se mais de um lançamento bater, a tool lista as opções para você refinar (use 'moeda' para desambiguar).",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -244,6 +278,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                     data: { type: "string", description: "Data do lançamento YYYY-MM-DD (para localizar)" },
                     valor: { type: "number", description: "Valor original (para localizar, opcional)" },
                     descricao: { type: "string", description: "Descrição original (substring, para localizar, opcional)" },
+                    moeda: { type: "string", description: "Moeda da conta (ex: 'BRL') — desambigua contas homônimas em moedas diferentes" },
                     // Campos a alterar (qualquer um, todos opcionais)
                     nova_descricao: { type: "string", description: "Nova descrição" },
                     novo_valor: { type: "number", description: "Novo valor (negativo = despesa, positivo = receita)" },
@@ -271,6 +306,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                     data: { type: "string", description: "Data do lançamento YYYY-MM-DD" },
                     valor: { type: "number", description: "Valor (opcional, ajuda a desambiguar)" },
                     descricao: { type: "string", description: "Descrição (substring, opcional)" },
+                    moeda: { type: "string", description: "Moeda da conta (ex: 'BRL') — desambigua contas homônimas em moedas diferentes" },
                 },
                 required: ["nome_conta", "data"],
             },
@@ -787,6 +823,7 @@ async function handleTool(name, args) {
                 dataInicio: args["data_inicio"],
                 dataFim: args["data_fim"],
                 busca: args["busca"],
+                moeda: args["moeda"],
                 apenasVencidos: args["apenas_vencidos"],
                 pagina: args["pagina"],
                 limite: args["limite"],
@@ -803,6 +840,7 @@ async function handleTool(name, args) {
                 dataInicio: args["data_inicio"],
                 dataFim: args["data_fim"],
                 busca: args["busca"],
+                moeda: args["moeda"],
                 apenasVencidos: args["apenas_vencidos"],
                 apenasCobranca: args["apenas_cobranca"],
                 incluirCobranca: args["incluir_cobranca"],
@@ -810,6 +848,30 @@ async function handleTool(name, args) {
                 limite: args["limite"],
             }));
         }
+        case "buscar_despesas_periodicas": {
+            const authErr = requireAuth();
+            if (authErr)
+                return authErr;
+            const walErr = requireWallet();
+            if (walErr)
+                return walErr;
+            return ok(await client.buscarDespesasPeriodicas({
+                busca: args["busca"],
+                moeda: args["moeda"],
+            }));
+        }
+        case "buscar_receitas_periodicas": {
+            const authErr = requireAuth();
+            if (authErr)
+                return authErr;
+            const walErr = requireWallet();
+            if (walErr)
+                return walErr;
+            return ok(await client.buscarReceitasPeriodicas({
+                busca: args["busca"],
+                moeda: args["moeda"],
+            }));
+        }
         case "listar_clientes": {
             const authErr = requireAuth();
             if (authErr)
@@ -819,6 +881,7 @@ async function handleTool(name, args) {
                 return walErr;
             return ok(await client.listarClientes({
                 busca: args["busca"],
+                moeda: args["moeda"],
                 pagina: args["pagina"],
                 limite: args["limite"],
             }));
@@ -879,6 +942,7 @@ async function handleTool(name, args) {
                 data: args["data"],
                 valor: args["valor"],
                 descricao: args["descricao"],
+                moeda: args["moeda"],
                 nova_descricao: args["nova_descricao"],
                 novo_valor: args["novo_valor"],
                 nova_data: args["nova_data"],
@@ -904,6 +968,7 @@ async function handleTool(name, args) {
                 data: args["data"],
                 valor: args["valor"],
                 descricao: args["descricao"],
+                moeda: args["moeda"],
             }));
         }
         case "permissao_conta": {
@@ -1182,6 +1247,6 @@ async function handleTool(name, args) {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    client.log(`NEXT Finance MCP server v0.9.39 iniciado. Timeout upstream: ${process.env.NEXT_FINANCE_TIMEOUT_MS ?? "15000"}ms`);
+    client.log(`NEXT Finance MCP server v0.9.41 iniciado. Timeout upstream: ${process.env.NEXT_FINANCE_TIMEOUT_MS ?? "15000"}ms`);
 }
 main().catch((err) => { console.error("Erro fatal:", err); process.exit(1); });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-finance-mcp",
-  "version": "0.9.39",
+  "version": "0.9.41",
   "mcpName": "io.github.paivapiovesan/next-finance",
   "description": "MCP Server para o NEXT Finance (finance.net.br) — login via browser, listagem de carteiras, contas e lançamentos",
   "type": "module",
@@ -39,6 +39,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "docx": "^9.7.1",
     "express": "^5.2.1",
     "undici": "^7.25.0"
   },