bcb-br-mcp 1.4.1 → 1.5.0

package/README.md

@@ -41,8 +41,15 @@ The answers come live from the Brazilian Central Bank's SGS API — exact figure
 - **Popular series catalog** - 150+ economic indicators organized in 12 categories
 - **Smart search** - Find series by keyword (accent-insensitive)
 - **Current indicators** - Latest values for key economic indicators
+- **Long periods, handled** - The BCB API caps daily series at a 10-year window
+  (HTTP 406) and refuses open windows; requests are sliced, fetched and merged
+  automatically, so a 15-year daily query just works
+- **Frequency harmonisation** - Resample a series to monthly, quarterly or annual
+  with an explicit convention, including geometric compounding for series that
+  already are percentage changes (monthly IPCA into annual IPCA)
 - **Variation calculation** - Percentage change between periods with statistics
-- **Series comparison** - Compare multiple series over the same period
+- **Series comparison** - Compare multiple series over the same period, with a
+  warning when their periodicities differ
 - **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
 
@@ -50,9 +57,9 @@ The answers come live from the Brazilian Central Bank's SGS API — exact figure
 
 | Tool | Description |
 |------|-------------|
-| `bcb_serie_valores` | Query series values by code and date range |
-| `bcb_serie_ultimos` | Get the last N values of a series |
-| `bcb_serie_metadados` | Get series metadata (name, frequency, source) |
+| `bcb_serie_valores` | Query series values by code and date range; slices long windows automatically and can harmonise the series to a coarser frequency |
+| `bcb_serie_ultimos` | Get the last N values of a series (any N — the upstream cap of 20 is worked around) |
+| `bcb_serie_metadados` | Get series metadata (name, frequency, category, last value) |
 | `bcb_series_populares` | List popular series grouped by category |
 | `bcb_buscar_serie` | Search series by name or description (accent-insensitive) |
 | `bcb_indicadores_atuais` | Latest values: Selic, IPCA, USD/BRL, IBC-Br |
@@ -334,9 +341,35 @@ The SGS database contains over 18,000 time series. To find codes for other serie
 ### Robustness
 
 - **Timeout**: 30 seconds per request (prevents hanging)
-- **Auto-retry**: 3 attempts with exponential backoff (1s, 2s, 4s)
+- **Auto-retry**: 3 attempts with exponential backoff (1s, 2s, 4s) for transient
+  failures; client errors (4xx) are not retried, since they are deterministic
 - **Error handling**: Clear error messages
 
+### Working around the SGS limits
+
+Measured against the live API, not inferred from documentation:
+
+- A **date window over 10 years on a daily series** is refused with HTTP **406**,
+  and so is an open window (no `dataInicial`, or no dates at all). The limit
+  applies to the *implicit* window: with no `dataFinal` the API assumes today.
+  Requests are sliced into windows of up to **3 years**, fetched with bounded
+  concurrency and merged in date order without duplicating the seams; the response
+  reports it in `chunking`. The slice is 3 years rather than the allowed 10 because
+  a 10-year daily window costs 10–20 s upstream and may be cut off around 30 s.
+- **`dados/ultimos/N` is capped at 20** by the API, in every periodicity. Above 20,
+  the server infers the series' periodicity and fetches by date window instead.
+- **There is no per-series metadata endpoint** (`/metadados` answers 404). Frequency
+  is inferred from the spacing of the observations and flagged with
+  `periodicidadeInferida`; unit of measure is not available from any source.
+
+### Derived values
+
+Anything this server computes — variation, descriptive statistics, harmonised
+series — is marked `derived: true` and carries a note with the conventions used.
+Statistics come from [`@sbissoli/mcp-stats`](https://www.npmjs.com/package/@sbissoli/mcp-stats).
+A value published by the BCB is always returned verbatim; only computed values are
+rounded (to 4 decimals).
+
 ### Smart Search
 
 `bcb_buscar_serie` searches two layers: the curated catalog of 150+ series (which ranks first, with reviewed

package/README.pt-BR.md

@@ -38,16 +38,23 @@ As respostas vêm ao vivo da API SGS do Banco Central — valores exatos com pro
 - **Catálogo de séries populares** - Lista de 150+ indicadores econômicos organizados em 12 categorias
 - **Busca inteligente** - Encontra séries por termo de busca (com ou sem acentos)
 - **Indicadores atuais** - Valores mais recentes dos principais indicadores econômicos
+- **Períodos longos resolvidos** - A API do BCB limita séries diárias a uma janela
+  de 10 anos (HTTP 406) e recusa janela aberta; a consulta é fatiada, buscada e
+  fundida automaticamente, então pedir 15 anos de série diária simplesmente funciona
+- **Harmonização de frequências** - Reamostra a série para mensal, trimestral ou
+  anual com convenção explícita, inclusive composição geométrica para séries que já
+  são variação percentual (IPCA mensal virando IPCA anual)
 - **Cálculo de variação** - Variação percentual entre períodos com estatísticas
-- **Comparação de séries** - Compara múltiplas séries no mesmo período
+- **Comparação de séries** - Compara múltiplas séries no mesmo período, com aviso
+  quando as periodicidades diferem
 
 ## Ferramentas Disponíveis
 
 | Ferramenta | Descrição |
 |------------|-----------|
-| `bcb_serie_valores` | Consulta valores de uma série por código e período |
-| `bcb_serie_ultimos` | Obtém os últimos N valores de uma série |
-| `bcb_serie_metadados` | Retorna informações/metadados de uma série |
+| `bcb_serie_valores` | Consulta valores de uma série por código e período; fatia janelas longas automaticamente e pode harmonizar a série para uma frequência mais grossa |
+| `bcb_serie_ultimos` | Obtém os últimos N valores de uma série (qualquer N — o teto de 20 da origem é contornado) |
+| `bcb_serie_metadados` | Retorna nome, periodicidade, categoria e último valor de uma série |
 | `bcb_series_populares` | Lista séries populares agrupadas por categoria |
 | `bcb_buscar_serie` | Busca séries por nome ou descrição (aceita termos sem acento) |
 | `bcb_indicadores_atuais` | Valores mais recentes: Selic, IPCA, Dólar, IBC-Br |
@@ -319,9 +326,35 @@ O SGS possui mais de 18.000 séries temporais. Para encontrar o código de outra
 ### Robustez
 
 - **Timeout**: 30 segundos por requisição (evita travamentos)
-- **Retry automático**: 3 tentativas com backoff exponencial (1s, 2s, 4s)
+- **Retry automático**: 3 tentativas com backoff exponencial (1s, 2s, 4s) em falha
+  transitória; erro de cliente (4xx) não é repetido, porque é determinístico
 - **Tratamento de erros**: Mensagens claras em português
 
+### Contornando os limites do SGS
+
+Tudo abaixo foi **medido** contra a API ao vivo, não inferido da documentação:
+
+- Uma **janela maior que 10 anos em série diária** é recusada com HTTP **406**, e
+  janela aberta (sem `dataInicial`, ou sem data nenhuma) também. O limite vale sobre
+  a janela *implícita*: sem `dataFinal`, a API assume hoje. A consulta é fatiada em
+  janelas de até **3 anos**, buscada com concorrência limitada e fundida em ordem de
+  data sem duplicar as emendas; a resposta informa isso em `chunking`. A fatia é de
+  3 anos, e não dos 10 permitidos, porque uma janela diária decenal custa 10–20 s na
+  origem e pode ser cortada por volta de 30 s.
+- **`dados/ultimos/N` tem teto de 20** na API, em qualquer periodicidade. Acima de
+  20, o servidor infere a periodicidade da série e busca por janela de datas.
+- **Não existe endpoint de metadados por série** (`/metadados` responde 404). A
+  periodicidade é inferida do espaçamento das observações e marcada com
+  `periodicidadeInferida`; unidade de medida não está disponível em fonte nenhuma.
+
+### Valores derivados
+
+Todo número que este servidor calcula — variação, estatísticas descritivas, série
+harmonizada — vem marcado com `derived: true` e uma nota com as convenções usadas.
+A estatística é do [`@sbissoli/mcp-stats`](https://www.npmjs.com/package/@sbissoli/mcp-stats).
+Valor publicado pelo BCB sai sempre verbatim; só o que é calculado é arredondado
+(em 4 casas).
+
 ### Busca Inteligente
 
 A ferramenta `bcb_buscar_serie` normaliza os termos de busca, permitindo encontrar séries mesmo sem acentos:

package/dist/series.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Engenharia de série do SGS: periodicidade, janelas, chunking e harmonização.
+ *
+ * Este é o módulo do **D1**. Tudo aqui existe por um limite MEDIDO da origem em
+ * 11/08/2026 (`bcb/docs/04-limites-sgs-medidos.md`) — não por precaução:
+ *
+ * - **Janela de 10 anos, só em série diária, erro 406.** A fronteira é exata ao
+ *   dia e o limite é inclusivo: 10 anos justos passam, 10 anos e 1 dia não. E
+ *   vale sobre a janela IMPLÍCITA — sem `dataFinal` a origem assume hoje; sem
+ *   `dataInicial`, o início da série (que quase sempre estoura os 10 anos).
+ * - **O 406 identifica a periodicidade** ("séries de periodicidade diária") e se
+ *   mostrou estável nas oito medições em que apareceu. Por isso o chunking é
+ *   REATIVO: quem diz que a série é diária é a origem, não um palpite nosso.
+ * - **Janela legal também precisa ser fatiada.** Dez anos de série diária
+ *   custam 10–20 s (~4–8 ms por observação) e há corte por volta de 30 s que
+ *   devolve HTML com 200. O worker tem timeout de 10 s: uma janela decenal que a
+ *   origem ACEITA não completa no canal hospedado. A fatia é de 3 anos (~2,6 s),
+ *   não de 10.
+ * - **Não há endpoint de metadados** (404 `endpoint not found!`), então a
+ *   periodicidade de um código arbitrário se descobre pelo espaçamento das
+ *   datas. `ultimos/20` custa 75–340 ms e serve de sonda.
+ *
+ * A harmonização de frequências vive aqui pelo mesmo motivo: reamostrar exige
+ * saber a periodicidade de origem, e é este módulo que a conhece.
+ */
+import { type SerieValor } from "./shared.js";
+export declare const BCB_SGS_BASE = "https://api.bcb.gov.br/dados/serie/bcdata.sgs";
+/** Teto da origem para `dados/ultimos/N`, em TODA periodicidade (medido). */
+export declare const TETO_ULTIMOS = 20;
+/** Janela máxima que a origem aceita em série diária. */
+export declare const JANELA_MAX_ANOS = 10;
+/**
+ * Fatia do chunking. Não é o limite da origem (10) de propósito: a 3 anos a
+ * requisição custa ~2,6 s e cabe nos 10 s de timeout do worker; a 10 anos custa
+ * 10–20 s e não cabe.
+ */
+export declare const FATIA_ANOS = 3;
+/** Requisições simultâneas por série. O portal pede parcimônia (~≤5 req/s). */
+export declare const CONCORRENCIA = 3;
+export type Periodicidade = "diaria" | "semanal" | "mensal" | "trimestral" | "anual" | "irregular";
+/** Rótulo em pt-BR para a resposta das tools (a superfície é pt-BR). */
+export declare const ROTULO_PERIODICIDADE: Record<Periodicidade, string>;
+/** `dd/MM/yyyy` (formato do SGS) para epoch UTC; `null` se não casar. */
+export declare function parseDataSgs(data: string): number | null;
+export declare function formatarDataSgs(epoch: number): string;
+/**
+ * Periodicidade pelo espaçamento MEDIANO entre observações consecutivas.
+ *
+ * A mediana, e não a média: série diária tem buracos de feriado e fim de semana
+ * (espaçamentos de 1 a 4 dias, e às vezes mais), e um buraco grande arrastaria a
+ * média para a faixa da semanal. Com menos de 3 observações não há espaçamento
+ * suficiente para afirmar nada — devolve `null`, que quem chama traduz como
+ * "desconhecida" em vez de inventar.
+ */
+export declare function inferirPeriodicidade(observacoes: Array<{
+    data: string;
+}>): Periodicidade | null;
+/**
+ * Sonda de periodicidade: `ultimos/20` e inferência pelo espaçamento.
+ *
+ * É o substituto do endpoint de metadados que não existe. Devolve `null` (em vez
+ * de propagar) quando a sonda falha: ela é uma otimização, e falhar nela não
+ * pode derrubar a consulta que o usuário pediu de verdade.
+ */
+export declare function sondarPeriodicidade(codigo: number, timeoutMs?: number, maxRetries?: number): Promise<Periodicidade | null>;
+export interface Janela {
+    /** `dd/MM/yyyy` */
+    inicio: string;
+    /** `dd/MM/yyyy` */
+    fim: string;
+}
+/**
+ * Fatia [inicio, fim] em janelas de no máximo `anos`, sem sobreposição.
+ *
+ * A origem trata a janela como fechada nas duas pontas, então a fatia seguinte
+ * começa no dia SEGUINTE ao fim da anterior — sem isso, cada emenda duplicaria
+ * uma observação. (A fusão remove duplicata de qualquer forma; isto evita pagar
+ * por ela.)
+ */
+export declare function fatiarJanela(inicio: string, fim: string, anos?: number): Janela[];
+export interface PedidoSerie {
+    codigo: number;
+    /** `dd/MM/yyyy` — já normalizado por quem chama. */
+    dataInicial?: string;
+    /** `dd/MM/yyyy` — já normalizado por quem chama. */
+    dataFinal?: string;
+}
+export interface JanelaAplicada {
+    dataInicial: string;
+    dataFinal: string;
+    motivo: string;
+}
+export interface ResultadoSerie {
+    observacoes: SerieValor[];
+    /** `null` quando não deu para inferir (menos de 3 observações). */
+    periodicidade: Periodicidade | null;
+    /** Presente só quando a consulta foi fatiada. */
+    chunking?: {
+        janelas: number;
+        fatiaAnos: number;
+    };
+    /** Presente só quando a janela pedida estava aberta e foi fechada por nós. */
+    janelaAplicada?: JanelaAplicada;
+    /** Requisições gastas à origem, contando a sonda. */
+    requisicoes: number;
+}
+/** `dd/MM/yyyy` de hoje — a origem usa este formato e o fuso do BCB é -03:00. */
+export declare function hojeSgs(): string;
+/**
+ * Busca uma série do SGS respeitando os limites da origem.
+ *
+ * Caminho normal (janela estreita ou série não-diária): UMA requisição, igual ao
+ * que o servidor sempre fez. O trabalho extra só acontece quando é preciso:
+ *
+ * 1. Janela mais larga que a fatia ⇒ sonda a periodicidade (80–340 ms). Se for
+ *    diária, já sai fatiando: evita a requisição de 10–20 s que morreria no
+ *    timeout do worker.
+ * 2. Consulta direta que volta **406** ⇒ a origem acabou de dizer que a série é
+ *    diária e a janela é grande demais. Fatia e repete.
+ * 3. Janela aberta em série diária (sem `dataInicial`, ou sem data nenhuma) ⇒
+ *    não há como fatiar o que não tem começo, e a origem recusa a janela
+ *    implícita. Aplicamos a janela máxima que ela própria aceita — 10 anos até
+ *    `dataFinal` (ou até hoje) — e devolvemos isso explícito em
+ *    `janelaAplicada`, para a resposta poder dizer o que fez e por quê. Truncar
+ *    em silêncio seria o pior dos mundos.
+ */
+export declare function buscarSerieSgs(pedido: PedidoSerie, timeoutMs?: number, maxRetries?: number, concorrencia?: number): Promise<ResultadoSerie>;
+/**
+ * Busca os N últimos valores, contornando o teto de 20 da origem.
+ *
+ * O `inputSchema` anuncia até 1000 desde sempre e a origem devolve **400** para
+ * qualquer N acima de 20, em qualquer periodicidade — ou seja, a promessa nunca
+ * foi cumprida. Em vez de reduzir o que o schema promete, cumprimos: a sonda dá
+ * a periodicidade, a periodicidade dimensiona a janela de datas, e a janela vem
+ * pelo caminho de `dados?dataInicial=...` (que não tem teto de linhas), fatiada
+ * se for preciso. Devolve as N últimas observações.
+ *
+ * A margem de 1,6× na janela existe porque feriado, recesso e mês sem publicação
+ * rarefazem a série: pedir exatamente o período nominal costuma voltar com menos
+ * pontos do que o usuário pediu.
+ */
+export declare function buscarUltimosSgs(codigo: number, quantidade: number, timeoutMs?: number, maxRetries?: number): Promise<ResultadoSerie>;
+export type FrequenciaAlvo = "mensal" | "trimestral" | "anual";
+export type Agregacao = "ultimo" | "primeiro" | "media" | "soma" | "acumulada";
+export declare const ROTULO_AGREGACAO: Record<Agregacao, string>;
+export interface ObservacaoHarmonizada {
+    data: string;
+    valor: number;
+    /** Observações de origem que entraram neste ponto. */
+    observacoes: number;
+}
+export interface ResultadoHarmonizacao {
+    dados: ObservacaoHarmonizada[];
+    frequencia: FrequenciaAlvo;
+    agregacao: Agregacao;
+    nota: string;
+}
+/**
+ * Reamostra a série para uma frequência mais grossa.
+ *
+ * Só agrega para baixo: pedir diária a partir de mensal exigiria inventar
+ * observação, e este servidor não faz isso — devolve erro explícito.
+ *
+ * A escolha da agregação é do usuário porque **não existe padrão universal
+ * correto**: nível de preço e taxa pedem `ultimo`, fluxo pede `soma`, e série
+ * que JÁ É variação percentual (IPCA mensal, por exemplo) pede `acumulada` —
+ * somar 12 variações mensais não dá a inflação do ano, e a média dá menos ainda.
+ * Toda resposta harmonizada carrega a convenção usada e a marca de derivação.
+ */
+export declare function harmonizar(observacoes: Array<{
+    data: string;
+    valor: number;
+}>, alvo: FrequenciaAlvo, agregacao: Agregacao, origem: Periodicidade | null): ResultadoHarmonizacao;
+//# sourceMappingURL=series.d.ts.map

package/dist/series.d.ts.map

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