bcb-br-mcp 1.3.4 → 1.4.1

package/README.md

@@ -18,7 +18,7 @@ Query economic and financial indicators such as **Selic** (interest rate), **IPC
 
 > If you find this project useful, please consider giving it a [star on GitHub](https://github.com/SidneyBissoli/bcb-br-mcp). It helps others discover the project!
 
-**Capabilities:** 8 tools (skills) · 3 resources · 3 prompts — everything an MCP client needs to query the Brazilian Central Bank (SGS/BCB) time-series API.
+**Capabilities:** 13 tools (skills) · 3 resources · 3 prompts — everything an MCP client needs to query the Brazilian Central Bank: SGS/BCB time series, the **Focus** market-expectations survey and **PTAX** exchange rates.
 
 ## See it in action
 
@@ -27,6 +27,9 @@ Ask your assistant, in plain Portuguese:
 - *"Qual a taxa Selic atual?"* → `bcb_indicadores_atuais`
 - *"Mostre o IPCA mês a mês em 2024."* → `bcb_serie_valores`
 - *"Qual foi a variação do dólar nos últimos 12 meses?"* → `bcb_variacao`
+- *"O que o mercado espera do IPCA em 2027?"* → `bcb_focus_expectativas`
+- *"Qual a Selic esperada na próxima reunião do Copom?"* → `bcb_focus_selic`
+- *"Qual foi a PTAX de fechamento do euro na sexta?"* → `bcb_cambio_cotacao`
 
 The answers come live from the Brazilian Central Bank's SGS API — exact figures with provenance, not numbers guessed from training data.
 
@@ -40,6 +43,8 @@ The answers come live from the Brazilian Central Bank's SGS API — exact figure
 - **Current indicators** - Latest values for key economic indicators
 - **Variation calculation** - Percentage change between periods with statistics
 - **Series comparison** - Compare multiple series over the same period
+- **Focus survey** - Market expectations (mean, median, std. deviation, min, max, respondents) for IPCA, GDP, FX and more, by monthly/quarterly/annual horizon or rolling 12/24-month inflation, plus Selic by Copom meeting
+- **PTAX exchange rates** - Official closing quotes for any currency the BCB publishes, single day or date range
 
 ## Available Tools
 
@@ -53,6 +58,11 @@ The answers come live from the Brazilian Central Bank's SGS API — exact figure
 | `bcb_indicadores_atuais` | Latest values: Selic, IPCA, USD/BRL, IBC-Br |
 | `bcb_variacao` | Calculate percentage variation between dates or last N periods |
 | `bcb_comparar` | Compare 2 to 5 series over the same period with ranking |
+| `bcb_focus_expectativas` | Focus survey expectations for one indicator, horizon as a parameter (monthly, quarterly, annual, rolling 12m/24m inflation); `top5` flag |
+| `bcb_focus_selic` | Focus expectations for the Selic rate, by Copom meeting (R1/2026 form) |
+| `bcb_focus_referencias` | Which indicators and reference dates the Focus survey actually publishes, **broken down per scope** (the five horizons plus `selic`, whose axis is the Copom meeting) — the indicator set differs by scope (9 monthly vs 26 annual) |
+| `bcb_cambio_cotacao` | PTAX quote for a currency (USD by default), single day or date range |
+| `bcb_cambio_moedas` | Currencies with quotes published by the BCB |
 
 ## Resources
 
@@ -85,9 +95,14 @@ Visit [bcb-br-mcp on Smithery](https://smithery.ai/servers/sidneybissoli/bcb-br-
 Use the HTTP endpoint directly, no installation required:
 
 ```
-https://bcb.sidneybissoli.workers.dev
+https://bcb.sidneybissoli.com/mcp
 ```
 
+The legacy hostname `https://bcb.sidneybissoli.workers.dev` keeps working, and so
+does the older `POST /` route — clients configured before the endpoint moved to
+`/mcp` are rewritten transparently, so nothing that used to work stopped working.
+New setups should use the URL above.
+
 ### Via npx (Claude Desktop)
 
 Add to your Claude Desktop configuration file:
@@ -324,11 +339,26 @@ The SGS database contains over 18,000 time series. To find codes for other serie
 
 ### Smart Search
 
-The `bcb_buscar_serie` tool normalizes search terms, allowing you to find series even without Portuguese accents:
+`bcb_buscar_serie` searches two layers: the curated catalog of 150+ series (which ranks first, with reviewed
+names) and the index of the BCB Open Data Portal, with thousands of series identified by code. Terms are
+accent- and case-insensitive, and several terms are combined with AND:
 
 - `"inflacao"` → finds "Inflação"
 - `"cambio"` → finds "Câmbio"
-- `"credito"` → finds "Crédito"
+- `"ipca servicos"` → both terms must match
+
+The portal index is served from a 24-hour cache, renewed by the first search after it expires (one request to
+the portal, only metadata — series codes and names, never observations). Every answer carries
+`catalogo.cobertura`: the index is **not** the whole SGS, so not finding a series here is not proof it does not
+exist.
+
+### Data source and licence
+
+Data obtained from the Banco Central do Brasil (SGS / Olinda-Expectativas / PTAX), published under the
+**Open Data Commons Open Database License (ODbL) v1.0** — https://opendatacommons.org/licenses/odbl/.
+Exchange-rate answers pass through the BCB's own liability disclaimer verbatim; cross-currency parities are
+**not** compiled by the BCB — they come from an information agency (Refinitiv) and are redistributed by the
+BCB, and the tools say so.
 
 ## Development
 
@@ -379,6 +409,32 @@ This server uses the Brazilian Central Bank's public API:
 
 ## Changelog
 
+### v1.4.1
+
+- `bcb_focus_referencias`: the parameter is now `escopo`, not `horizonte`, and the
+  response array is `escopos`. The scopes are the five horizons of
+  `bcb_focus_expectativas` **plus `selic`** — and `selic` is not a horizon: its
+  axis is the Copom meeting. Each block names the `tool` that consumes it. The
+  previous name implied `selic` was a queryable horizon of
+  `bcb_focus_expectativas`, which it is not. Never published to npm under the old
+  name.
+
+### v1.4.0
+
+- **Three APIs under one contract, 8 tools → 13.** Focus market-expectations
+  survey (`bcb_focus_expectativas`, `bcb_focus_selic`, `bcb_focus_referencias`)
+  and PTAX exchange rates (`bcb_cambio_cotacao`, `bcb_cambio_moedas`), consolidated
+  by parameter rather than mirroring the source's ~18 OData resources.
+- **Real search.** `bcb_buscar_serie` now queries the Open Data Portal index
+  (3,500+ series, 24-hour cache, metadata only) on top of the curated catalog, and
+  states the index's coverage instead of claiming a series does not exist.
+- Every Focus and PTAX field name verified against the live API, including the
+  Top 5 Selic resource, which publishes its fields in a different case from the
+  other twelve.
+- ODbL obligations shipped with the exchange-rate tools: the BCB disclaimer is
+  passed through verbatim, and non-USD parities are qualified as third-party
+  (Refinitiv) data redistributed by the BCB.
+
 ### v1.2.0
 
 - HTTP endpoint via Cloudflare Workers (`https://bcb.sidneybissoli.workers.dev`)

package/dist/cambio.d.ts

@@ -0,0 +1,72 @@
+/**
+ * PTAX — cotações de câmbio e lista de moedas.
+ *
+ * Desenho aprovado (fronteira concreta da sessão de D3): os quatro recursos de
+ * cotação da fonte (dólar-dia, dólar-período, moeda-dia, moeda-período) viram
+ * UMA tool, `bcb_cambio_cotacao`, com `moeda` (padrão USD) e data única ou
+ * intervalo. Mais `bcb_cambio_moedas` para a lista de moedas, porque descobrir o
+ * símbolo é pergunta própria.
+ *
+ * Duas obrigações legais do `bcb/docs/01` nascem implementadas aqui, não no D4:
+ *
+ * 1. **O disclaimer do BCB é repassado literalmente** em toda resposta de
+ *    cotação — é o único texto tipo-ToS que a fonte publica.
+ * 2. **Paridades de moedas não-dólar são QUALIFICADAS**: elas não são dado do
+ *    BCB, vêm de agência de informação (Refinitiv) e são redistribuídas pelo BCB.
+ *    Anunciá-las como dado do BCB sem qualificar seria incorreto.
+ *
+ * Pegadinha da API que mora em `olinda.ts`: os parâmetros de data da PTAX são
+ * **MM-DD-YYYY**, não ISO nem dd/MM/yyyy.
+ */
+import { type ToolDefinition, type ToolResult } from "./shared.js";
+/** Repassado literalmente, como o `docs/01` exige. */
+export declare const DISCLAIMER_PTAX: string;
+export declare const QUALIFICACAO_PARIDADE: string;
+export interface CotacaoNormalizada {
+    /** Data e hora da cotação como a fonte publica. */
+    dataHora: string | null;
+    cotacaoCompra: number | null;
+    cotacaoVenda: number | null;
+    /** Só para moedas não-dólar: paridade contra o USD (origem: agência de informação). */
+    paridadeCompra?: number | null;
+    paridadeVenda?: number | null;
+    /** Nulo em USD: verificado contra a origem, os recursos de dólar não publicam este campo. */
+    tipoBoletim: string | null;
+}
+export declare function normalizarCotacao(linha: Record<string, unknown>, dolar: boolean): CotacaoNormalizada;
+interface UrlCotacao {
+    url: string;
+    dolar: boolean;
+    dataInicial: string;
+    dataFinal: string;
+    janelaPadrao: boolean;
+}
+/**
+ * Monta a URL da cotação escolhendo entre os quatro recursos da fonte. É o único
+ * lugar que sabe que existem quatro: para fora há uma tool só.
+ */
+export declare function montarUrlCotacao(args: {
+    moeda?: string;
+    data?: string;
+    dataInicial?: string;
+    dataFinal?: string;
+}): UrlCotacao | {
+    erro: string;
+};
+export interface ArgsCotacao {
+    moeda?: string;
+    data?: string;
+    dataInicial?: string;
+    dataFinal?: string;
+    limite?: number;
+}
+export declare function handleCambioCotacao(args: ArgsCotacao, timeoutMs?: number, maxRetries?: number): Promise<ToolResult>;
+export interface ArgsMoedas {
+    termo?: string;
+}
+export declare function handleCambioMoedas(args: ArgsMoedas, timeoutMs?: number, maxRetries?: number): Promise<ToolResult>;
+export declare const CAMBIO_TOOL_DEFINITIONS: ToolDefinition[];
+/** Retorna null quando a tool não é deste módulo (o dispatcher central segue). */
+export declare function dispatchCambioTool(toolName: string, args: Record<string, unknown>, timeoutMs?: number, maxRetries?: number): Promise<ToolResult> | null;
+export {};
+//# sourceMappingURL=cambio.d.ts.map

package/dist/cambio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cambio.d.ts","sourceRoot":"","sources":["../src/cambio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAaH,OAAO,EAA+D,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAKhI,sDAAsD;AACtD,eAAO,MAAM,eAAe,QAIO,CAAC;AAEpC,eAAO,MAAM,qBAAqB,QAGT,CAAC;AAE1B,MAAM,WAAW,kBAAkB;IACjC,mDAAmD;IACnD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,uFAAuF;IACvF,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,6FAA6F;IAC7F,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAcpG;AAED,UAAU,UAAU;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CA4ChC;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,WAAW,EACjB,SAAS,CAAC,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,UAAU,CAAC,CA0CrB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,UAAU,EAChB,SAAS,CAAC,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,UAAU,CAAC,CA8BrB;AASD,eAAO,MAAM,uBAAuB,EAAE,cAAc,EA6GnD,CAAC;AAEF,kFAAkF;AAClF,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,SAAS,CAAC,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,CAS5B"}

package/dist/cambio.js

@@ -0,0 +1,284 @@
+/**
+ * PTAX — cotações de câmbio e lista de moedas.
+ *
+ * Desenho aprovado (fronteira concreta da sessão de D3): os quatro recursos de
+ * cotação da fonte (dólar-dia, dólar-período, moeda-dia, moeda-período) viram
+ * UMA tool, `bcb_cambio_cotacao`, com `moeda` (padrão USD) e data única ou
+ * intervalo. Mais `bcb_cambio_moedas` para a lista de moedas, porque descobrir o
+ * símbolo é pergunta própria.
+ *
+ * Duas obrigações legais do `bcb/docs/01` nascem implementadas aqui, não no D4:
+ *
+ * 1. **O disclaimer do BCB é repassado literalmente** em toda resposta de
+ *    cotação — é o único texto tipo-ToS que a fonte publica.
+ * 2. **Paridades de moedas não-dólar são QUALIFICADAS**: elas não são dado do
+ *    BCB, vêm de agência de informação (Refinitiv) e são redistribuídas pelo BCB.
+ *    Anunciá-las como dado do BCB sem qualificar seria incorreto.
+ *
+ * Pegadinha da API que mora em `olinda.ts`: os parâmetros de data da PTAX são
+ * **MM-DD-YYYY**, não ISO nem dd/MM/yyyy.
+ */
+import { PTAX_ODATA, consultarOData, hojeIso, montarUrlOData, numeroOuNulo, paraDataPtax, paraIso, somarDiasIso, textoOuNulo } from "./olinda.js";
+import { erroResult, leituraRemota, mensagemDeErro, structuredResult } from "./shared.js";
+/** Janela padrão quando não se informa data nenhuma: cobre feriados e fins de semana. */
+const JANELA_PADRAO_DIAS = 7;
+/** Repassado literalmente, como o `docs/01` exige. */
+export const DISCLAIMER_PTAX = "O Banco Central não assume qualquer responsabilidade pela não simultaneidade ou falta das informações " +
+    "prestadas, assim como por eventuais erros de paridades das moedas. Não assume, também, responsabilidade " +
+    "por qualquer perda ou dano oriundo de tais interrupções, atrasos, falhas ou imperfeições, bem como pelo " +
+    "uso inadequado das informações.";
+export const QUALIFICACAO_PARIDADE = "As paridades das moedas contra o dólar americano NÃO são apuradas pelo Banco Central: são obtidas junto a " +
+    "agências de informação (Refinitiv) e redistribuídas pelo BCB. Trate-as como dado de terceiro qualificado, " +
+    "não como dado do BCB.";
+export function normalizarCotacao(linha, dolar) {
+    const normalizada = {
+        dataHora: textoOuNulo(linha.dataHoraCotacao),
+        cotacaoCompra: numeroOuNulo(linha.cotacaoCompra),
+        cotacaoVenda: numeroOuNulo(linha.cotacaoVenda),
+        tipoBoletim: textoOuNulo(linha.tipoBoletim)
+    };
+    if (!dolar) {
+        normalizada.paridadeCompra = numeroOuNulo(linha.paridadeCompra);
+        normalizada.paridadeVenda = numeroOuNulo(linha.paridadeVenda);
+    }
+    return normalizada;
+}
+/**
+ * Monta a URL da cotação escolhendo entre os quatro recursos da fonte. É o único
+ * lugar que sabe que existem quatro: para fora há uma tool só.
+ */
+export function montarUrlCotacao(args) {
+    const moeda = (args.moeda ?? "USD").toUpperCase();
+    const dolar = moeda === "USD";
+    let inicio;
+    let fim;
+    let janelaPadrao = false;
+    if (args.data !== undefined) {
+        if (args.dataInicial !== undefined || args.dataFinal !== undefined) {
+            return { erro: "Use `data` para um dia específico OU `dataInicial`/`dataFinal` para um intervalo, não os dois." };
+        }
+        inicio = paraIso(args.data);
+        if (!inicio)
+            return { erro: `data inválida: "${args.data}". Use yyyy-MM-dd ou dd/MM/yyyy.` };
+        fim = inicio;
+    }
+    else {
+        fim = args.dataFinal ? paraIso(args.dataFinal) : hojeIso();
+        if (!fim)
+            return { erro: `dataFinal inválida: "${args.dataFinal}". Use yyyy-MM-dd ou dd/MM/yyyy.` };
+        inicio = args.dataInicial ? paraIso(args.dataInicial) : somarDiasIso(fim, -JANELA_PADRAO_DIAS);
+        if (!inicio)
+            return { erro: `dataInicial inválida: "${args.dataInicial}". Use yyyy-MM-dd ou dd/MM/yyyy.` };
+        janelaPadrao = args.dataInicial === undefined && args.dataFinal === undefined;
+    }
+    if (inicio > fim) {
+        return { erro: `A janela está invertida: dataInicial (${inicio}) é posterior a dataFinal (${fim}).` };
+    }
+    const diaUnico = inicio === fim && args.data !== undefined;
+    const pInicio = paraDataPtax(inicio);
+    const pFim = paraDataPtax(fim);
+    // Recursos parametrizados do OData: os argumentos vão como @parâmetros.
+    const recurso = diaUnico
+        ? dolar
+            ? `CotacaoDolarDia(dataCotacao=@dataCotacao)?@dataCotacao='${pInicio}'`
+            : `CotacaoMoedaDia(moeda=@moeda,dataCotacao=@dataCotacao)?@moeda='${moeda}'&@dataCotacao='${pInicio}'`
+        : dolar
+            ? `CotacaoDolarPeriodo(dataInicial=@dataInicial,dataFinalCotacao=@dataFinalCotacao)?@dataInicial='${pInicio}'&@dataFinalCotacao='${pFim}'`
+            : `CotacaoMoedaPeriodo(moeda=@moeda,dataInicial=@dataInicial,dataFinalCotacao=@dataFinalCotacao)?@moeda='${moeda}'&@dataInicial='${pInicio}'&@dataFinalCotacao='${pFim}'`;
+    // O recurso já carrega query string, então o formato entra com `&`.
+    const url = `${PTAX_ODATA}/${recurso}&$format=json`;
+    return { url, dolar, dataInicial: inicio, dataFinal: fim, janelaPadrao };
+}
+export async function handleCambioCotacao(args, timeoutMs, maxRetries) {
+    const montada = montarUrlCotacao(args);
+    if ("erro" in montada)
+        return erroResult(montada.erro);
+    try {
+        const linhas = await consultarOData(montada.url, timeoutMs, maxRetries);
+        const limite = args.limite ?? 100;
+        const todas = linhas
+            .map(l => normalizarCotacao(l, montada.dolar))
+            .sort((a, b) => (b.dataHora ?? "").localeCompare(a.dataHora ?? ""));
+        const cotacoes = todas.slice(0, limite);
+        const payload = {
+            moeda: (args.moeda ?? "USD").toUpperCase(),
+            periodo: {
+                dataInicial: montada.dataInicial,
+                dataFinal: montada.dataFinal,
+                janelaPadrao: montada.janelaPadrao
+            },
+            totalRegistros: todas.length,
+            cotacoes,
+            disclaimer: DISCLAIMER_PTAX,
+            urlConsulta: montada.url,
+            consultadoEm: new Date().toISOString()
+        };
+        if (!montada.dolar)
+            payload.qualificacaoParidade = QUALIFICACAO_PARIDADE;
+        if (cotacoes.length < todas.length) {
+            payload.observacao = `Exibindo ${cotacoes.length} de ${todas.length} boletins; aumente 'limite' ou estreite o período.`;
+        }
+        if (todas.length === 0) {
+            payload.observacao =
+                "Nenhuma cotação no período. A PTAX só existe em dia útil com fechamento de câmbio — fim de semana, " +
+                    "feriado e o próprio dia antes do fechamento voltam vazios. Confirme também o símbolo da moeda com " +
+                    "bcb_cambio_moedas.";
+        }
+        return structuredResult(payload);
+    }
+    catch (error) {
+        return erroResult(`Erro ao consultar cotação de câmbio: ${mensagemDeErro(error)}`);
+    }
+}
+export async function handleCambioMoedas(args, timeoutMs, maxRetries) {
+    const url = montarUrlOData(PTAX_ODATA, { recurso: "Moedas" });
+    try {
+        const linhas = await consultarOData(url, timeoutMs, maxRetries);
+        let moedas = linhas.map(l => ({
+            simbolo: textoOuNulo(l.simbolo),
+            nome: textoOuNulo(l.nomeFormatado),
+            tipo: textoOuNulo(l.tipoMoeda)
+        }));
+        if (args.termo !== undefined) {
+            const termo = args.termo.toUpperCase();
+            moedas = moedas.filter(m => (m.simbolo ?? "").includes(termo) || (m.nome ?? "").toUpperCase().includes(termo));
+        }
+        return structuredResult({
+            termo: args.termo ?? null,
+            totalMoedas: moedas.length,
+            moedas,
+            disclaimer: DISCLAIMER_PTAX,
+            qualificacaoParidade: QUALIFICACAO_PARIDADE,
+            urlConsulta: url,
+            consultadoEm: new Date().toISOString(),
+            observacao: "Use o `simbolo` em bcb_cambio_cotacao. O dólar americano (USD) é o padrão da tool de cotação."
+        });
+    }
+    catch (error) {
+        return erroResult(`Erro ao listar moedas: ${mensagemDeErro(error)}`);
+    }
+}
+// ==================== SCHEMAS ====================
+const NOTA_PTAX = "Fonte: PTAX / Cotações e boletins de câmbio do Banco Central do Brasil, via Olinda OData. A resposta repassa " +
+    "literalmente o disclaimer de responsabilidade do BCB, em `disclaimer`. Cotações existem só em dia útil com " +
+    "fechamento de câmbio.";
+export const CAMBIO_TOOL_DEFINITIONS = [
+    {
+        name: "bcb_cambio_cotacao",
+        description: "Consulta a cotação PTAX de uma moeda contra o real, em um dia específico ou num intervalo de datas. " +
+            "Padrão: dólar americano (USD). Devolve compra, venda, data/hora e tipo de boletim; para moedas " +
+            "não-dólar devolve também a paridade contra o USD, com a origem qualificada. " +
+            "Quando usar: para a cotação oficial de fechamento de um dia ou a série de um período curto. " +
+            "Quando NÃO usar: para a série histórica longa do dólar como série temporal do SGS use bcb_serie_valores " +
+            "(códigos 1 = livre venda, 3698 = PTAX venda, 3697 = PTAX compra, 3695 = PTAX média) — esta tool é a " +
+            "fonte primária do boletim, com compra e venda no mesmo registro; para descobrir o símbolo da moeda use " +
+            "bcb_cambio_moedas. " +
+            "Retorna: `moeda`, `periodo` (dataInicial, dataFinal, janelaPadrao), `totalRegistros`, `cotacoes`, " +
+            "`disclaimer`, `qualificacaoParidade` (só para moedas não-dólar), `urlConsulta`, `consultadoEm` e, quando " +
+            "aplicável, `observacao`. Sem datas, cobre os últimos 7 dias (para atravessar fim de semana e feriado). " +
+            NOTA_PTAX +
+            " As paridades de moedas não-dólar vêm de agência de informação (Refinitiv), redistribuídas pelo BCB — não " +
+            "são apuradas pelo Banco Central.",
+        annotations: leituraRemota("Cotação de câmbio (PTAX)"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                moeda: { type: "string", description: "Símbolo da moeda (ex.: USD, EUR, GBP, JPY). Padrão: USD.", default: "USD" },
+                data: { type: "string", description: "Dia específico (yyyy-MM-dd ou dd/MM/yyyy). Não combine com dataInicial/dataFinal." },
+                dataInicial: { type: "string", description: "Início do intervalo (yyyy-MM-dd ou dd/MM/yyyy). Padrão: 7 dias antes do fim." },
+                dataFinal: { type: "string", description: "Fim do intervalo (yyyy-MM-dd ou dd/MM/yyyy). Padrão: hoje." },
+                limite: { type: "number", description: "Máximo de boletins a devolver (1-1000, padrão 100)", default: 100, minimum: 1, maximum: 1000 }
+            }
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                moeda: { type: "string" },
+                periodo: {
+                    type: "object",
+                    properties: {
+                        dataInicial: { type: "string" },
+                        dataFinal: { type: "string" },
+                        janelaPadrao: { type: "boolean", description: "true quando a janela de 7 dias foi assumida" }
+                    },
+                    required: ["dataInicial", "dataFinal", "janelaPadrao"]
+                },
+                totalRegistros: { type: "number" },
+                cotacoes: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            dataHora: { type: ["string", "null"], description: "Data e hora da cotação" },
+                            cotacaoCompra: { type: ["number", "null"] },
+                            cotacaoVenda: { type: ["number", "null"] },
+                            paridadeCompra: { type: ["number", "null"], description: "Paridade de compra contra o USD (moedas não-dólar; origem: agência de informação)" },
+                            paridadeVenda: { type: ["number", "null"], description: "Paridade de venda contra o USD (moedas não-dólar; origem: agência de informação)" },
+                            tipoBoletim: { type: ["string", "null"], description: "Tipo de boletim (ex.: Fechamento, Abertura, Intermediário). Nulo em USD: a fonte não publica este campo nos recursos de dólar, só nos de moeda." }
+                        },
+                        required: ["dataHora"]
+                    }
+                },
+                disclaimer: { type: "string", description: "Disclaimer de responsabilidade do BCB, repassado literalmente" },
+                qualificacaoParidade: { type: "string", description: "Qualificação da origem das paridades não-dólar" },
+                urlConsulta: { type: "string" },
+                consultadoEm: { type: "string" },
+                observacao: { type: "string" }
+            },
+            required: ["moeda", "periodo", "totalRegistros", "cotacoes", "disclaimer", "urlConsulta", "consultadoEm"]
+        }
+    },
+    {
+        name: "bcb_cambio_moedas",
+        description: "Lista as moedas com cotação publicada pelo Banco Central, com símbolo, nome e tipo, e aceita um termo " +
+            "para filtrar. " +
+            "Quando usar: para descobrir o símbolo correto antes de chamar bcb_cambio_cotacao (é a causa mais comum " +
+            "de cotação vazia). Quando NÃO usar: para valores de cotação. " +
+            "Retorna: `termo`, `totalMoedas`, `moedas` (simbolo, nome, tipo), `disclaimer`, `qualificacaoParidade`, " +
+            "`urlConsulta` e `consultadoEm`. " + NOTA_PTAX,
+        annotations: leituraRemota("Moedas com cotação no BCB"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                termo: { type: "string", description: "Filtro por símbolo ou nome (ex.: 'EUR', 'libra'). Opcional." }
+            }
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                termo: { type: ["string", "null"], description: "Termo aplicado no filtro; nulo quando não foi informado" },
+                totalMoedas: { type: "number" },
+                moedas: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            simbolo: { type: ["string", "null"], description: "Símbolo a usar em bcb_cambio_cotacao" },
+                            nome: { type: ["string", "null"] },
+                            tipo: { type: ["string", "null"], description: "Tipo da moeda conforme a fonte (A ou B)" }
+                        },
+                        required: ["simbolo"]
+                    }
+                },
+                disclaimer: { type: "string" },
+                qualificacaoParidade: { type: "string" },
+                urlConsulta: { type: "string" },
+                consultadoEm: { type: "string" },
+                observacao: { type: "string" }
+            },
+            required: ["totalMoedas", "moedas", "disclaimer", "urlConsulta", "consultadoEm"]
+        }
+    }
+];
+/** Retorna null quando a tool não é deste módulo (o dispatcher central segue). */
+export function dispatchCambioTool(toolName, args, timeoutMs, maxRetries) {
+    switch (toolName) {
+        case "bcb_cambio_cotacao":
+            return handleCambioCotacao(args, timeoutMs, maxRetries);
+        case "bcb_cambio_moedas":
+            return handleCambioMoedas(args, timeoutMs, maxRetries);
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=cambio.js.map

package/dist/cambio.js.map

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

package/dist/catalog.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Í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.
+ */
+import { type SeriePopular } from "./shared.js";
+export declare const CKAN_PACKAGE_LIST = "https://dadosabertos.bcb.gov.br/api/3/action/package_list";
+export declare const CKAN_DATASET_BASE = "https://dadosabertos.bcb.gov.br/dataset";
+/** Validade do catálogo em cache: 24 h (decisão do decisor). */
+export declare const CATALOGO_TTL_MS: number;
+/** Uma entrada do índice: código da série + slug do dataset. Só metadados. */
+export interface EntradaCatalogo {
+    codigo: number;
+    slug: string;
+}
+export interface SnapshotCatalogo {
+    entradas: EntradaCatalogo[];
+    /** ISO 8601 do momento em que o índice foi obtido da origem. */
+    obtidoEm: string;
+    /** Total de datasets devolvidos pelo portal (inclui os sem código). */
+    totalDatasets: number;
+    expiraEm: number;
+}
+export interface ResultadoCatalogo {
+    snapshot: SnapshotCatalogo | null;
+    /** Preenchido quando o índice servido não é o ideal (vencido, ou ausente). */
+    aviso?: string;
+}
+/** Só para os testes: zera o cache do módulo. */
+export declare function _resetCatalogo(): void;
+/** Só para os testes: injeta um snapshot como se tivesse vindo da origem. */
+export declare function _seedCatalogo(snapshot: SnapshotCatalogo): void;
+/**
+ * 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 declare function normalizarMojibake(texto: string): string;
+/**
+ * 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 declare function nomeDoSlug(slug: string): string;
+/** `1-taxa-de-cambio---livre---dolar-americano-venda---diario` -> {1, slug}. */
+export declare function parsePackageList(nomes: unknown): {
+    entradas: EntradaCatalogo[];
+    totalDatasets: number;
+};
+/**
+ * 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 declare function obterCatalogo(timeoutMs?: number, maxRetries?: number): Promise<ResultadoCatalogo>;
+export type OrigemSerie = "curado" | "indice";
+export interface SerieEncontrada {
+    codigo: number;
+    nome: string;
+    categoria?: string;
+    periodicidade?: string;
+    /** `curado` = catálogo local com nome/categoria revisados; `indice` = portal. */
+    origem: OrigemSerie;
+    /** Página do dataset no portal (só para achados do índice). */
+    dataset?: string;
+}
+/**
+ * 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 declare function buscarSeries(termo: string, curadoria: SeriePopular[], entradas: EntradaCatalogo[] | null, limite: number): {
+    total: number;
+    series: SerieEncontrada[];
+};
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAKH,OAAO,EAAgC,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAE9E,eAAO,MAAM,iBAAiB,8DAA8D,CAAC;AAC7F,eAAO,MAAM,iBAAiB,4CAA4C,CAAC;AAE3E,gEAAgE;AAChE,eAAO,MAAM,eAAe,QAAsB,CAAC;AAEnD,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAClC,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD,iDAAiD;AACjD,wBAAgB,cAAc,IAAI,IAAI,CAGrC;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAE9D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQxD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ/C;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,QAAQ,EAAE,eAAe,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAkBvG;AAwBD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+BvG;AAID,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE9C,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,MAAM,EAAE,WAAW,CAAC;IACpB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAqBD;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,YAAY,EAAE,EACzB,QAAQ,EAAE,eAAe,EAAE,GAAG,IAAI,EAClC,MAAM,EAAE,MAAM,GACb;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,eAAe,EAAE,CAAA;CAAE,CA6B9C"}