bcb-br-mcp 1.16.2 → 1.18.0

package/dist/tools.js

@@ -14,7 +14,7 @@ import { criarDeepResearchTools } from "./deep-research.js";
 import { FOCUS_TOOL_DEFINITIONS, dispatchFocusTool } from "./focus.js";
 import { CAMBIO_TOOL_DEFINITIONS, dispatchCambioTool } from "./cambio.js";
 import { DERIVACAO_CORRELACAO, DERIVACAO_DEFLACAO, DERIVACAO_ENCADEAMENTO, DERIVACAO_ESTATISTICA, arredondarDerivado, variacaoAcumulada, correlacaoEntreSeries, emVariacoes, estatisticasDaSerie } from "./stats.js";
-import { ROTULO_PERIODICIDADE, TETO_ULTIMOS, alinharSeries, buscarSerieSgs, buscarUltimosSgs, chaveMes, construirDeflator, deflacionar, harmonizar, hojeSgs, urlSerie } from "./series.js";
+import { BCB_SGS_BASE, ROTULO_PERIODICIDADE, TETO_ULTIMOS, alinharSeries, buscarSerieSgs, buscarUltimosSgs, chaveMes, construirDeflator, deflacionar, formatarDataSgs, harmonizar, hojeSgs, parseDataSgs, urlSerie } from "./series.js";
 import { calculateVariation, erroDeExcecao, erroResult, fetchBcbApi, formatDateForApi, mensagemDeErro, normalizeString, sealDeep, upstreamBcb } from "./shared.js";
 import { withCall } from "@sbissoli/mcp-upstream/als";
 import { classifyThrown } from "./call-shape.js";
@@ -295,6 +295,99 @@ export function mensagemRecusaAcumulado(codigo, nome) {
         `é o próprio valor publicado nessa data — use bcb_serie_valores para lê-lo. Para acumular a inflação ` +
         `num período arbitrário use bcb_variacao sobre a série de variação mensal (IPCA 433).`);
 }
+export const NATUREZAS_SERIE = [
+    "nivel",
+    "variacao_no_periodo",
+    "acumulado_no_ano",
+    "acumulado_12_meses"
+];
+/**
+ * Emissão do campo `natureza` no bloco `serie` — DESLIGADA no tempo 1.
+ *
+ * Mesmo rollout em dois tempos do contrato de proveniência: nesta versão o
+ * `outputSchema` passa a DECLARAR o campo (opcional), e nenhuma resposta muda;
+ * um conector que guardou o schema antigo, fechado por `additionalProperties:
+ * false`, recusaria a resposta inteira se o campo saísse já. A sessão de ~7 dias
+ * depois liga a constante (um patch, sem mexer em schema).
+ */
+export const EMITIR_NATUREZA = false;
+/**
+ * Unidades do portal que dizem, por si, que o valor é NÍVEL: montante em moeda,
+ * número-índice, preço (câmbio), razão ou participação ("Percentual", "Pontos
+ * percentuais") e taxa vigente expressa ao ano ("Percentual ao ano" — a meta
+ * Selic, o juro médio cobrado). De fora, de propósito: "Percentual ao dia" e
+ * "Percentual ao mês", que no SGS tanto podem ser a taxa cobrada (nível) quanto o
+ * rendimento do período (variação) — 4390 e a poupança são as segundas, e são
+ * reconhecidas por `metodoVariacaoDaSerie`; o resto fica sem rótulo.
+ */
+const UNIDADES_DE_NIVEL = new Set([
+    "Milhões de reais",
+    "Milhões de dólares americanos",
+    "Unidades monetárias correntes",
+    "Milhares de unidades monetárias correntes",
+    "Índice",
+    "Taxa unidade monetária corrente/dólar americano",
+    "Percentual",
+    "Pontos percentuais",
+    "Percentual ao ano"
+]);
+/**
+ * Nomes que dizem nível nas séries SEM unidade (fonteNome `medido`): o montante
+ * em moeda escrito no nome (PIB em R$ milhões ou US$ milhões) e a taxa de câmbio,
+ * que é preço. Nenhum outro nome do catálogo é afirmativo o bastante.
+ */
+const NOME_DE_NIVEL = /Valores correntes \(R\$ milhões\)|em US\$ \(milhões\)|^Taxa de câmbio - /;
+/**
+ * Natureza de uma série pelo código, ou `null` = "tipo não identificado".
+ *
+ * Deriva SÓ do que o servidor já sabe, nesta ordem:
+ *  1. as listas de acumulados (`ACUMULADOS_NO_ANO`, `ACUMULADOS_EM_12_MESES`),
+ *     as mesmas que a descrição das tools cita;
+ *  2. a decisão de encadeamento (`metodoVariacaoDaSerie` = `encadeamento`: unidade
+ *     "Variação percentual mensal", nome em "Variação mensal" e
+ *     `TAXAS_POR_PERIODO`) — o que a conta já trata como variação do período;
+ *  3. para o resto do CATÁLOGO, o que ele MEDE: `nivel` só quando a unidade do
+ *     portal (`UNIDADES_DE_NIVEL`) ou o nome (`NOME_DE_NIVEL`) o afirma, e nunca
+ *     para nome que diga "acumulada no mês" fora das listas acima (4189: o
+ *     rendimento do mês anualizado não é nível nem cabe no vocabulário).
+ *     Sem afirmação, `null`.
+ *
+ * Fora do catálogo é SEMPRE `null` (decisão do decisor, 08/10/2026): a conta da
+ * `bcb_variacao` supõe nível para poder calcular, mas o rótulo publicado não
+ * repete o palpite — afirmar "nível" sobre uma série que pode ser variação é o
+ * defeito que publicou +23,81% para o IPCA de 2024.
+ *
+ * As RAZÕES 29037/29038 (endividamento sobre renda acumulada em 12 meses) são
+ * `nivel`: só o denominador é acumulado, o valor é a razão naquela data.
+ */
+export function naturezaDaSerie(codigo) {
+    const info = SERIES_POPULARES.find(s => s.codigo === codigo);
+    if (!info)
+        return null;
+    if (ACUMULADOS_NO_ANO.includes(codigo))
+        return "acumulado_no_ano";
+    if (ACUMULADOS_EM_12_MESES.includes(codigo))
+        return "acumulado_12_meses";
+    if (metodoVariacaoDaSerie(codigo) === "encadeamento")
+        return "variacao_no_periodo";
+    if (/acumulad[ao] no mês/i.test(info.nome))
+        return null;
+    if (info.unidade !== undefined && UNIDADES_DE_NIVEL.has(info.unidade))
+        return "nivel";
+    if (NOME_DE_NIVEL.test(info.nome))
+        return "nivel";
+    return null;
+}
+/** Fragmento do `outputSchema` do campo — declarado opcional, aceito desde o tempo 1. */
+const NATUREZA_SCHEMA = {
+    type: ["string", "null"],
+    enum: [...NATUREZAS_SERIE, null],
+    description: "O que o valor da série é em cada data: 'nivel' (o valor da grandeza no período — saldo, fluxo, preço, " +
+        "taxa vigente, razão ou índice), 'variacao_no_periodo' (a variação ou rendimento do próprio período, como " +
+        "o IPCA mensal), 'acumulado_no_ano' ou 'acumulado_12_meses' (o acumulado até aquela data: não some nem " +
+        "subtraia esses valores). null = tipo não identificado: a série está fora do catálogo curado ou o catálogo " +
+        "não diz o que ela mede."
+};
 // ==================== TOOL HANDLERS ====================
 /**
  * Bloco `serie` das respostas do SGS.
@@ -314,7 +407,8 @@ function refSerie(codigo, periodicidade) {
         nome: info?.nome || `Série ${codigo}`,
         categoria: info?.categoria || "Desconhecida",
         periodicidade: info?.periodicidade || (periodicidade ? ROTULO_PERIODICIDADE[periodicidade] : "Desconhecida"),
-        ...(inferida ? { periodicidadeInferida: true } : {})
+        ...(inferida ? { periodicidadeInferida: true } : {}),
+        ...(EMITIR_NATUREZA ? { natureza: naturezaDaSerie(codigo) } : {})
     };
 }
 /**
@@ -324,13 +418,28 @@ function refSerie(codigo, periodicidade) {
  * O SGS não publica versão do dado e **não tem endpoint de metadados**
  * (`bcb/docs/04`), então a competência sai do que já veio na resposta — zero
  * requisição a mais. As datas saem no formato da própria fonte.
+ *
+ * Primeira e última são o MÍNIMO e o MÁXIMO pela data lida, não as pontas da
+ * lista: até 08/10/2026 a função pegava `[0]` e `[length − 1]` e só acertava
+ * porque toda leitura passava antes por `ordenarPorData`. Ordenar por texto
+ * dd/MM/yyyy ordena pelo dia — o defeito que o ibge tinha com rótulos por
+ * extenso. Data que não se lê não entra no intervalo.
  */
-function vintageDeObservacoes(observacoes) {
-    if (observacoes.length === 0)
+export function vintageDeObservacoes(observacoes) {
+    let min = null;
+    let max = null;
+    for (const { data } of observacoes) {
+        const t = parseDataSgs(data);
+        if (t === null)
+            continue;
+        if (min === null || t < min)
+            min = t;
+        if (max === null || t > max)
+            max = t;
+    }
+    if (min === null || max === null)
         return null;
-    const primeira = observacoes[0].data;
-    const ultima = observacoes[observacoes.length - 1].data;
-    return primeira === ultima ? primeira : `${primeira}–${ultima}`;
+    return min === max ? formatarDataSgs(min) : `${formatarDataSgs(min)}–${formatarDataSgs(max)}`;
 }
 /**
  * Bloco de proveniência do catálogo curado do servidor.
@@ -366,7 +475,15 @@ function provSerieSgs(codigo, observacoes, janela = {}, derivado) {
  *
  * O `source_url` não pode ser o de uma série só — escolher uma entre cinco
  * mentiria por omissão sobre as outras quatro. Vai o endpoint-base, e cada série
- * entra em `field_sources` com a própria URL.
+ * entra em `field_sources` com a própria URL e a própria competência.
+ *
+ * A competência sai das observações de cada série (as ORIGINAIS da fonte, antes
+ * de qualquer harmonização); a do topo cobre todas — da data mais antiga à mais
+ * nova entre as séries. Até 08/10/2026 nenhum chamador passava a competência, e
+ * as quatro tools que calculam sobre um período (`bcb_indicadores_atuais`,
+ * `bcb_comparar`, `bcb_correlacao`, `bcb_deflacionar`) saíam com
+ * `data_vintage: null` no topo e em toda sub-fonte. Série que falhou não tem
+ * observação e sai com `null` — "não há dado", que é o que aconteceu.
  */
 function provMultiSerieSgs(series, detalhe, derivado) {
     return provenienciaBcb({
@@ -377,13 +494,17 @@ function provMultiSerieSgs(series, detalhe, derivado) {
             name: detalhe,
             version: null
         },
-        dataVintage: series.map(s => s.vintage).find(v => v != null) ?? null,
+        dataVintage: vintageDeObservacoes(series.flatMap(s => s.observacoes ?? [])),
         detalheCitacao: `${detalhe} (séries ${series.map(s => s.codigo).join(", ")})`,
         fontesPorCampo: series.map(s => ({
             fields: [s.campo],
             source_url: urlSerie(s.codigo, s.inicio, s.fim),
             dataset_id: `bcdata.sgs.${s.codigo}`,
-            data_vintage: s.vintage ?? null
+            data_vintage: vintageDeObservacoes(s.observacoes ?? []),
+            // Todo acesso DESTA série — janela fatiada, sonda `ultimos/20` e
+            // repetições —, não só a URL canônica: o instante de cada sub-fonte é o
+            // da série dela, e o topo é o mais antigo entre elas.
+            filtro: (url) => url.startsWith(`${BCB_SGS_BASE}.${s.codigo}/`)
         })),
         ...(derivado ? { derivado } : {})
     });
@@ -656,7 +777,10 @@ export async function handleIndicadoresAtuais(_args, timeoutMs, maxRetries) {
                 return { indicador: ind.nome, codigo: ind.codigo, erro: err instanceof Error ? err.message : "Erro desconhecido" };
             }
         }));
-        return resultadoComProveniencia({ consultadoEm: new Date().toISOString(), indicadores: resultados }, provMultiSerieSgs(indicadores.map(i => ({ codigo: i.codigo, campo: i.nome })), "painel de indicadores atuais"));
+        return resultadoComProveniencia({ consultadoEm: new Date().toISOString(), indicadores: resultados }, provMultiSerieSgs(indicadores.map((i, k) => {
+            const r = resultados[k];
+            return { codigo: i.codigo, campo: i.nome, observacoes: "data" in r && r.data ? [{ data: r.data }] : [] };
+        }), "painel de indicadores atuais"));
     }
     catch (error) {
         return erroDeExcecao(`Erro ao consultar indicadores`, error);
@@ -726,6 +850,8 @@ export async function handleVariacao(args, timeoutMs, maxRetries) {
 export async function handleComparar(args, timeoutMs, maxRetries) {
     try {
         const periodicidades = new Map();
+        // Observações ORIGINAIS de cada série, para a competência da proveniência.
+        const originais = new Map();
         let harmonizacao;
         const resultados = await Promise.all(args.codigos.map(async (codigo) => {
             const serieInfo = SERIES_POPULARES.find(s => s.codigo === codigo);
@@ -748,6 +874,7 @@ export async function handleComparar(args, timeoutMs, maxRetries) {
                 if (data.length === 0) {
                     return { codigo, nome: serieInfo?.nome || `Série ${codigo}`, erro: "Sem dados no período" };
                 }
+                originais.set(codigo, data);
                 const ref = refSerie(codigo, resultado.periodicidade);
                 // O aviso de periodicidade decide pela periodicidade MEDIDA, não pelo
                 // rótulo do catálogo — mesma regra do `bcb_correlacao`. A série 11 está
@@ -842,7 +969,8 @@ export async function handleComparar(args, timeoutMs, maxRetries) {
             codigo,
             campo: `ranking[codigo=${codigo}]`,
             inicio: formatDateForApi(args.dataInicial),
-            fim: formatDateForApi(args.dataFinal)
+            fim: formatDateForApi(args.dataFinal),
+            observacoes: originais.get(codigo)
         })), "comparação entre séries", { nota: haEncadeada ? NOTA_DERIVACAO_ENCADEAMENTO : NOTA_DERIVACAO_ESTATISTICA }));
     }
     catch (error) {
@@ -989,7 +1117,8 @@ export async function handleCorrelacao(args, timeoutMs, maxRetries) {
             codigo: s.codigo,
             campo: `series[codigo=${s.codigo}]`,
             inicio: formatDateForApi(args.dataInicial),
-            fim: formatDateForApi(args.dataFinal)
+            fim: formatDateForApi(args.dataFinal),
+            observacoes: s.observacoes
         })), "correlação entre séries", { nota: NOTA_DERIVACAO_ESTATISTICA }));
     }
     catch (error) {
@@ -1086,8 +1215,8 @@ export async function handleDeflacionar(args, timeoutMs, maxRetries) {
             ...(avisos.length > 0 ? { avisos } : {}),
             ...blocoRede(serie)
         }, provMultiSerieSgs([
-            { codigo: args.codigo, campo: "dados[].valorNominal", inicio, fim },
-            { codigo: deflatorInfo.codigo, campo: "dados[].fator", inicio }
+            { codigo: args.codigo, campo: "dados[].valorNominal", inicio, fim, observacoes: serie.observacoes },
+            { codigo: deflatorInfo.codigo, campo: "dados[].fator", inicio, observacoes: indice.observacoes }
         ], `deflação por ${chaveIndice.toUpperCase()}`, { nota: NOTA_DERIVACAO_DEFLACAO }));
     }
     catch (error) {
@@ -1145,14 +1274,19 @@ const SERIE_REF_CONSULTADA_SCHEMA = {
             type: "boolean",
             description: "Presente e true quando a periodicidade foi inferida do espaçamento das observações, e não lida " +
                 "do catálogo — a API do SGS não publica metadados de série."
-        }
+        },
+        natureza: NATUREZA_SCHEMA
     }
 };
 // Shared fragment: a single observation (date + numeric value).
 const OBSERVACAO_SCHEMA = {
     type: "object",
     properties: {
-        data: { type: "string", description: "Data da observação (dd/MM/yyyy)" },
+        data: {
+            type: "string",
+            description: "Data de referência da observação (dd/MM/yyyy), na convenção do SGS: em série mensal, trimestral ou " +
+                "anual é o PRIMEIRO dia do período (01/03/2026 = março de 2026); em série diária, o próprio dia"
+        },
         valor: { type: "number", description: "Valor numérico da observação" }
     },
     required: ["data", "valor"]
@@ -1271,6 +1405,25 @@ const BEHAVIOR_NOTE = "Comportamento: consome a API pública SGS do Banco Centra
  */
 const TOTAL_CURADAS = SERIES_POPULARES.length;
 const CURADAS_DO_PORTAL = SERIES_POPULARES.filter(s => s.fonteNome === "portal").length;
+/**
+ * O que cada número do SGS é — período, acumulação e revisão. Nada disso está no
+ * dado: o SGS devolve só `{data, valor}`, a acumulação só aparece no NOME da série
+ * e a fonte não guarda a versão originalmente divulgada (achado de leitor no
+ * dev.to, 08/10/2026: o mesmo par de armadilhas dos dados XBRL da SEC). Os códigos
+ * citados são os acumulados do catálogo curado; o teste confere que cada um está
+ * lá com "acumulad" no nome, para a frase não envelhecer calada.
+ */
+export const ACUMULADOS_NO_ANO = [4381, 4386];
+export const ACUMULADOS_EM_12_MESES = [13522, 4382, 5793];
+const NOTA_O_QUE_E_CADA_NUMERO = "O que cada número é: `data` é a data de referência na convenção do SGS — em série mensal, trimestral ou " +
+    "anual, o PRIMEIRO dia do período (01/03/2026 = março de 2026). Algumas séries já chegam ACUMULADAS da " +
+    "origem e só o nome diz isso: acumulado no ano (PIB " + ACUMULADOS_NO_ANO.join(", ") + ") e acumulado em " +
+    "12 meses (" + ACUMULADOS_EM_12_MESES.join(", ") + ") — o valor numa data é o acumulado até aquele " +
+    "período, então não some esses valores nem subtraia um do outro; para o valor de um mês, use a série mensal. " +
+    "Revisões: o valor é o que o SGS publica no instante da extração (`retrieved_at` na proveniência). O BCB " +
+    "revisa séries como PIB, IBC-Br, balanço de pagamentos e crédito, e o SGS não guarda a versão originalmente " +
+    "divulgada — um ponto passado pode mudar entre duas consultas, e este servidor não tem como devolver o " +
+    "número da primeira divulgação. ";
 export const TOOL_DESCRIPTIONS = {
     bcb_serie_valores: "Consulta o histórico de valores de UMA série temporal do BCB pelo código SGS, opcionalmente " +
         "limitado por um intervalo de datas (dataInicial/dataFinal). " +
@@ -1287,6 +1440,7 @@ export const TOOL_DESCRIPTIONS = {
         "se o período pedido estava aberto numa série diária, `janelaAplicada` diz qual janela foi usada e por quê. " +
         "Harmonização: `frequencia` (mensal|trimestral|anual) reamostra a série antes de responder, com a " +
         "convenção escolhida em `agregacao`; a resposta traz `harmonizacao` com `derived: true` e a nota do cálculo. " +
+        NOTA_O_QUE_E_CADA_NUMERO +
         BEHAVIOR_NOTE,
     bcb_serie_ultimos: "Obtém as últimas N observações de UMA série temporal do BCB (mais recentes primeiro a partir " +
         "do fim da série). " +
@@ -1297,6 +1451,7 @@ export const TOOL_DESCRIPTIONS = {
         "`totalRegistros` = 0 com `observacao`. " +
         "Acima de 20: o endpoint nativo do BCB rejeita N > 20 em qualquer periodicidade, então o servidor " +
         "descobre a periodicidade da série e busca por janela de datas, devolvendo os N últimos pontos. " +
+        NOTA_O_QUE_E_CADA_NUMERO +
         BEHAVIOR_NOTE,
     bcb_serie_metadados: "Obtém a descrição de UMA série do BCB (nome, periodicidade, categoria, fonte e último valor), sem " +
         "trazer a série histórica. " +
@@ -1953,6 +2108,7 @@ const RAW_TOOL_DEFINITIONS = [
                             categoria: { type: "string" },
                             periodicidade: { type: "string" },
                             periodicidadeInferida: { type: "boolean" },
+                            natureza: NATUREZA_SCHEMA,
                             totalRegistros: { type: "number" }
                         },
                         required: ["codigo", "nome"]
@@ -2060,6 +2216,7 @@ const RAW_TOOL_DEFINITIONS = [
                         categoria: { type: "string" },
                         periodicidade: { type: "string" },
                         periodicidadeInferida: { type: "boolean" },
+                        natureza: NATUREZA_SCHEMA,
                         totalRegistros: { type: "number" }
                     },
                     required: ["codigo", "nome"]