bcb-br-mcp 1.3.4 → 1.4.1

package/dist/catalog.js

@@ -0,0 +1,206 @@
+/**
+ * Índice de séries do Portal de Dados Abertos do BCB (CKAN) — busca real.
+ *
+ * Desenho fechado pelo decisor na fase bcb (arbitragem 5), e as restrições
+ * importam mais que o código:
+ *
+ * - Fonte é `package_list` do CKAN: UMA requisição (~310 KB) devolve o nome de
+ *   todos os datasets do portal, e 3.555 deles são nomeados pelo próprio código
+ *   da série (`{codigo}-{slug}`) — ~24× a cobertura do catálogo curado local.
+ *   Nada de raspar o localizador JSP do SGS.
+ * - O catálogo é servido de cache com validade de 24 h e a renovação é
+ *   BLOQUEANTE: quem faz a primeira busca depois do vencimento paga o ~0,8 s.
+ *   Sem tarefa agendada e sem seed manual — se ninguém buscar, a origem não
+ *   recebe requisição nenhuma. Descartado de propósito o
+ *   stale-while-revalidate: com tráfego baixo ele entregaria retrato de semanas
+ *   ao primeiro usuário para poupar 0,8 s de um único usuário por dia.
+ * - O cache guarda **só metadados** (código e slug), NUNCA observações. É por
+ *   isso que ele não é a "base derivada" que a arbitragem 2 evitou: o servidor
+ *   segue sendo *Produced Work* sob a ODbL, e valores de série continuam
+ *   buscados ao vivo a cada pergunta.
+ * - `Disallow: /api/` + `Crawl-Delay: 10` no robots do portal do catálogo é o
+ *   motivo de existir cache: ≤1 requisição por dia por instância, não uma por
+ *   chamada.
+ *
+ * O cache é módulo-level, ou seja, por processo (stdio) e por isolate
+ * (Cloudflare). Isolate reciclado = catálogo buscado de novo; com o tráfego
+ * atual isso mantém a ordem de grandeza prometida (unidades de requisição por
+ * dia), e é a única forma de cache que não introduz armazenamento persistente.
+ */
+// Só primitivos: a curadoria de séries entra por parâmetro (e não por import de
+// `tools.ts`) para a busca ser testável sem estado global e para não haver ciclo
+// entre os módulos de tool.
+import { fetchBcbApi, normalizeString } from "./shared.js";
+export const CKAN_PACKAGE_LIST = "https://dadosabertos.bcb.gov.br/api/3/action/package_list";
+export const CKAN_DATASET_BASE = "https://dadosabertos.bcb.gov.br/dataset";
+/** Validade do catálogo em cache: 24 h (decisão do decisor). */
+export const CATALOGO_TTL_MS = 24 * 60 * 60 * 1000;
+let cache = null;
+/** Renovação em voo: duas buscas simultâneas após o vencimento fazem 1 fetch. */
+let renovacaoEmVoo = null;
+/** Só para os testes: zera o cache do módulo. */
+export function _resetCatalogo() {
+    cache = null;
+    renovacaoEmVoo = null;
+}
+/** Só para os testes: injeta um snapshot como se tivesse vindo da origem. */
+export function _seedCatalogo(snapshot) {
+    cache = snapshot;
+}
+/**
+ * Conserta mojibake de ISO-8859-1 servido como UTF-8 ("Câmbio" -> "Câmbio").
+ * Os slugs do `package_list` são ASCII, então isto é defesa para os campos de
+ * texto do CKAN que já apareceram corrompidos na verificação de abertura.
+ */
+export function normalizarMojibake(texto) {
+    if (!/[ÃÂ][€-¿]/.test(texto))
+        return texto;
+    try {
+        const bytes = Uint8Array.from(Array.from(texto, c => c.charCodeAt(0) & 0xff));
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        return texto;
+    }
+}
+/**
+ * Nome legível a partir do slug do dataset. O `package_list` devolve slug, não
+ * título: `---` é separador de campos e `-` separa palavras, e os acentos foram
+ * perdidos na origem — daí o nome reconstruído ser aproximado de propósito. Para
+ * as séries do catálogo curado o nome bom (com acento) prevalece; para as
+ * demais, quem quiser o nome oficial usa `bcb_serie_metadados`.
+ */
+export function nomeDoSlug(slug) {
+    const texto = normalizarMojibake(slug)
+        .replace(/^\d+-/, "") // o código já é campo próprio
+        .split(/-{2,}/) // `---` separa campos; um `-` só separa palavras
+        .map(parte => parte.replace(/-/g, " ").replace(/\s+/g, " ").trim())
+        .filter(Boolean)
+        .join(" - ");
+    return texto.charAt(0).toUpperCase() + texto.slice(1);
+}
+/** `1-taxa-de-cambio---livre---dolar-americano-venda---diario` -> {1, slug}. */
+export function parsePackageList(nomes) {
+    if (!Array.isArray(nomes))
+        return { entradas: [], totalDatasets: 0 };
+    const entradas = [];
+    const vistos = new Set();
+    for (const bruto of nomes) {
+        if (typeof bruto !== "string")
+            continue;
+        const match = /^(\d+)-(.+)$/.exec(bruto);
+        if (!match)
+            continue;
+        const codigo = Number(match[1]);
+        if (!Number.isSafeInteger(codigo) || vistos.has(codigo))
+            continue;
+        vistos.add(codigo);
+        entradas.push({ codigo, slug: bruto });
+    }
+    entradas.sort((a, b) => a.codigo - b.codigo);
+    return { entradas, totalDatasets: nomes.length };
+}
+async function renovar(timeoutMs, maxRetries) {
+    const resposta = (await fetchBcbApi(CKAN_PACKAGE_LIST, timeoutMs, maxRetries));
+    if (!resposta || resposta.success === false || !Array.isArray(resposta.result)) {
+        throw new Error("Resposta inesperada do portal de dados abertos (package_list)");
+    }
+    const { entradas, totalDatasets } = parsePackageList(resposta.result);
+    if (entradas.length === 0)
+        throw new Error("Índice do portal veio sem nenhuma série identificável por código");
+    const agora = Date.now();
+    return {
+        entradas,
+        obtidoEm: new Date(agora).toISOString(),
+        totalDatasets,
+        expiraEm: agora + CATALOGO_TTL_MS
+    };
+}
+/**
+ * Devolve o índice do portal, renovando de forma bloqueante quando vencido.
+ *
+ * Degradação: se a renovação falhar e houver retrato anterior, ele é servido
+ * COM aviso e com a data de obtenção visível — a API do BCB cai de verdade
+ * (ocorreu durante esta fase), e nesse caso é melhor um índice velho declarado
+ * do que busca nenhuma. Sem retrato anterior, devolve `snapshot: null` e quem
+ * chamou cai no catálogo curado.
+ */
+export async function obterCatalogo(timeoutMs, maxRetries) {
+    if (cache && Date.now() < cache.expiraEm)
+        return { snapshot: cache };
+    if (!renovacaoEmVoo) {
+        renovacaoEmVoo = renovar(timeoutMs, maxRetries)
+            .then(snapshot => {
+            cache = snapshot;
+            return snapshot;
+        })
+            .finally(() => {
+            renovacaoEmVoo = null;
+        });
+    }
+    try {
+        return { snapshot: await renovacaoEmVoo };
+    }
+    catch (error) {
+        const motivo = error instanceof Error ? error.message : String(error);
+        if (cache) {
+            return {
+                snapshot: cache,
+                aviso: `Índice do portal servido de cache VENCIDO (obtido em ${cache.obtidoEm}) — ` +
+                    `a renovação falhou: ${motivo}`
+            };
+        }
+        return {
+            snapshot: null,
+            aviso: `Índice do portal indisponível (${motivo}); a busca usou apenas o catálogo curado local.`
+        };
+    }
+}
+function comoEncontrada(serie) {
+    return {
+        codigo: serie.codigo,
+        nome: serie.nome,
+        categoria: serie.categoria,
+        periodicidade: serie.periodicidade,
+        origem: "curado"
+    };
+}
+function comoEncontradaDoIndice(entrada) {
+    return {
+        codigo: entrada.codigo,
+        nome: nomeDoSlug(entrada.slug),
+        origem: "indice",
+        dataset: `${CKAN_DATASET_BASE}/${entrada.slug}`
+    };
+}
+/**
+ * Ranqueia os achados. O catálogo curado é a CAMADA DE DESTAQUE: quando uma
+ * série está nele, ela vem primeiro e com o nome bom, porque foi revisada à
+ * mão; o índice do portal entra depois, ordenado do slug mais curto (mais
+ * específico) para o mais longo, com desempate estável pelo código.
+ */
+export function buscarSeries(termo, curadoria, entradas, limite) {
+    const termoNorm = normalizeString(termo).trim();
+    const tokens = termoNorm.split(/\s+/).filter(Boolean);
+    // Busca por código: "433" deve achar a série 433, não as que contêm "433".
+    if (/^\d+$/.test(termoNorm)) {
+        const codigo = Number(termoNorm);
+        const curada = curadoria.find(s => s.codigo === codigo);
+        if (curada)
+            return { total: 1, series: [comoEncontrada(curada)] };
+        const doIndice = entradas?.find(e => e.codigo === codigo);
+        if (doIndice)
+            return { total: 1, series: [comoEncontradaDoIndice(doIndice)] };
+        return { total: 0, series: [] };
+    }
+    const casaTodosTokens = (texto) => tokens.every(t => texto.includes(t));
+    const curadas = curadoria.filter(s => casaTodosTokens(normalizeString(s.nome)) || casaTodosTokens(normalizeString(s.categoria)));
+    const codigosCurados = new Set(curadas.map(s => s.codigo));
+    const doIndice = (entradas ?? [])
+        .filter(e => !codigosCurados.has(e.codigo) && casaTodosTokens(normalizeString(e.slug)))
+        .sort((a, b) => a.slug.length - b.slug.length || a.codigo - b.codigo);
+    const total = curadas.length + doIndice.length;
+    const series = [...curadas.map(comoEncontrada), ...doIndice.map(comoEncontradaDoIndice)].slice(0, limite);
+    return { total, series };
+}
+//# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"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"}

package/dist/focus.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Expectativas de Mercado (Focus) sob contrato consolidado.
+ *
+ * Desenho aprovado pelo decisor (arbitragem 3 + fronteira concreta da sessão de
+ * D3): NÃO espelhar os recursos OData. Três tools em vez de treze:
+ *
+ * - `bcb_focus_expectativas` — as cinco expectativas de calendário (mensal,
+ *   trimestral, anual, inflação em 12 e em 24 meses) numa tool só, com
+ *   `horizonte` como parâmetro. Os dois horizontes rolantes não têm data de
+ *   referência (o alvo é "os próximos N meses", não um mês do calendário) e têm
+ *   o campo `suavizada`, que os de calendário não têm: `referencia` é obrigatória
+ *   nos três de calendário e recusada nos rolantes, com erro que diz o que usar.
+ * - `bcb_focus_selic` — separada porque o eixo temporal é a REUNIÃO do Copom, não
+ *   o calendário. Consolidar aqui esconderia a diferença que importa.
+ * - `bcb_focus_referencias` — auxiliar de descoberta. Sem ela o agente adivinha
+ *   strings de referência ("2026"? "12/2026"? "4/2026"?), que é o modo mais
+ *   comum de a consulta voltar vazia.
+ *
+ * Top 5 é SINALIZADOR (`top5: true`), não tool espelhada — e não existe para
+ * toda combinação: a tabela de combinações válidas mora em `RECURSOS` e o erro
+ * diz qual usar.
+ *
+ * `ExpectativasMercadoInstituicoes` jamais entra (desativado pelo BCB por
+ * confidencialidade).
+ */
+import { type ToolDefinition, type ToolResult } from "./shared.js";
+export type Horizonte = "mensal" | "trimestral" | "anual" | "inflacao_12m" | "inflacao_24m";
+interface RecursoFocus {
+    /** Recurso OData das expectativas do consenso. */
+    consenso: string;
+    /** Recurso das expectativas do Top 5, quando existe para este horizonte. */
+    top5: string | null;
+    /** Nome do campo que carrega o alvo da expectativa. */
+    campoReferencia: string | null;
+    /** Formato da referência, para descrição e mensagem de erro. */
+    formatoReferencia: string | null;
+}
+/**
+ * Mapa horizonte -> recurso OData. É o ÚNICO lugar que conhece os nomes dos
+ * recursos: se a fonte renomear ou deixar de oferecer Top 5 em algum horizonte, a
+ * correção é uma linha aqui.
+ *
+ * Os nomes foram lidos do documento de serviço do OData contra a origem, não
+ * supostos. Repare na irregularidade da fonte, que é real e não erro de digitação:
+ * o mensal é `ExpectativaMercadoMensais` (singular) e o Top 5 trimestral é
+ * `ExpectativaMercadoTop5Trimestral` (singular nas duas pontas), enquanto todo o
+ * resto é plural.
+ */
+export declare const RECURSOS: Record<Horizonte, RecursoFocus>;
+/** Recurso de Selic, fora do mapa de horizontes porque o eixo é a reunião do Copom. */
+export declare const RECURSO_SELIC: {
+    readonly consenso: "ExpectativasMercadoSelic";
+    readonly top5: "ExpectativasMercadoTop5Selic";
+};
+/** Linha normalizada: um contrato para os cinco horizontes e para o Top 5. */
+export interface ExpectativaNormalizada {
+    indicador: string | null;
+    indicadorDetalhe: string | null;
+    /** Data da coleta (campo `Data` da fonte) — o Focus é vintage por construção. */
+    coletadoEm: string | null;
+    /** Alvo da expectativa: data de referência, reunião do Copom, ou null nos rolantes. */
+    referencia: string | null;
+    media: number | null;
+    mediana: number | null;
+    desvioPadrao: number | null;
+    minimo: number | null;
+    maximo: number | null;
+    respondentes: number | null;
+    baseCalculo: number | null;
+    /** Só nos horizontes rolantes: se a série é a suavizada. */
+    suavizada?: boolean | null;
+    /** Só no Top 5: tipo de cálculo publicado pela fonte. */
+    tipoCalculo?: string | null;
+    /** Só no Top 5 da Selic: único recurso da fonte que publica este campo. */
+    coeficienteVariacao?: number | null;
+}
+/**
+ * Normaliza uma linha do OData. Defensivo de propósito: os recursos não têm o
+ * mesmo conjunto de campos, o alvo aparece como `DataReferencia` (calendário) ou
+ * `Reuniao` (Selic), e a caixa dos nomes varia entre recursos.
+ */
+export declare function normalizarExpectativa(linha: Record<string, unknown>): ExpectativaNormalizada;
+export interface ArgsExpectativas {
+    indicador: string;
+    horizonte: Horizonte;
+    referencia?: string;
+    dataInicial?: string;
+    dataFinal?: string;
+    top5?: boolean;
+    suavizada?: boolean;
+    limite?: number;
+}
+export declare function handleFocusExpectativas(args: ArgsExpectativas, timeoutMs?: number, maxRetries?: number): Promise<ToolResult>;
+export interface ArgsSelic {
+    reuniao?: string;
+    dataInicial?: string;
+    dataFinal?: string;
+    top5?: boolean;
+    limite?: number;
+}
+export declare function handleFocusSelic(args: ArgsSelic, timeoutMs?: number, maxRetries?: number): Promise<ToolResult>;
+/** Escopos de descoberta: os cinco horizontes mais a Selic, que é tool própria. */
+export type EscopoReferencias = Horizonte | "selic";
+export interface ArgsReferencias {
+    indicador?: string;
+    escopo?: EscopoReferencias;
+}
+/**
+ * Descobre os textos EXATOS de indicador e de referência, por escopo.
+ *
+ * O parâmetro chama-se `escopo`, e não `horizonte`, de propósito: os cinco
+ * horizontes de `bcb_focus_expectativas` mais a Selic — cujo eixo é a reunião do
+ * Copom, não o calendário — não formam um conjunto de horizontes. Esta tool cobre
+ * tudo o que o Focus publica, e cada bloco diz em `tool` quem o consome.
+ *
+ * O desenho consulta os próprios recursos de expectativa — e não o recurso
+ * `DatasReferencia`, que o nome sugere e que foi descartado com o spike contra a
+ * origem: ele publica `Indicador`, `periodo`, `DataReferencia1` e
+ * `DataReferencia2` (não existe `DataReferencia`), cobre 11 indicadores contra os
+ * 26 do recurso anual, não separa por escopo e, para o IPCA, para em 12/2026
+ * enquanto as expectativas mensais já carregam referência 07/2028. É um calendário
+ * de datas de referência, não um índice das referências consultáveis.
+ *
+ * A quebra POR ESCOPO é o ponto: o conjunto de indicadores varia muito entre eles
+ * (9 no mensal contra 26 no anual), e pedir um indicador no horizonte errado —
+ * "PIB Total" no mensal, por exemplo — é justamente o modo mais comum de a
+ * consulta voltar vazia sem explicação.
+ */
+export declare function handleFocusReferencias(args: ArgsReferencias, timeoutMs?: number, maxRetries?: number): Promise<ToolResult>;
+export declare const FOCUS_TOOL_DEFINITIONS: ToolDefinition[];
+/** Retorna null quando a tool não é deste módulo (o dispatcher central segue). */
+export declare function dispatchFocusTool(toolName: string, args: Record<string, unknown>, timeoutMs?: number, maxRetries?: number): Promise<ToolResult> | null;
+export {};
+//# sourceMappingURL=focus.d.ts.map

package/dist/focus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus.d.ts","sourceRoot":"","sources":["../src/focus.ts"],"names":[],"mappings":"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"}