io.github.SidneyBissoli/bcb-br-mcp

Busca séries no catálogo interno curado por nome ou categoria, ignorando acentos e maiúsculas (ex.: 'inflacao' encontra 'Inflação'; 'dolar' encontra 'Dólar'). Quando usar: para encontrar o código de uma série a partir de uma palavra-chave (selic, ipca, cambio, pib, emprego, credito...). Quando NÃO usar: para listar tudo por categoria use bcb_series_populares. Limitação: pesquisa apenas o catálogo curado (150+ séries), não o SGS completo (dezenas de milhares); quando nada é encontrado, retorna sugestões e o link do portal SGS. Retorna: `termo`, `totalEncontradas`, `series` (array de {codigo, nome, categoria, periodicidade}) e, quando vazio, `mensagem` e `sugestao`. Catálogo local: não faz chamada de rede.

Compara de 2 a 5 séries temporais no MESMO período (dataInicial e dataFinal obrigatórias), calculando a variação percentual de cada uma e ordenando-as num ranking (maior para menor variação). Quando usar: para comparar/correlacionar a evolução de vários indicadores lado a lado. Quando NÃO usar: para uma única série use bcb_variacao. Retorna: `periodo`, `totalSeries`, `seriesComDados`, `seriesComErro`, `ranking` (cada item com posicao, codigo, nome, valorInicial, valorFinal, variacaoPercentual, maximo, minimo, media) e `erros`. Resiliente: séries sem dados no período são isoladas em `erros` sem invalidar a comparação. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).

Atalho que retorna, em uma única chamada, o valor mais recente dos principais indicadores da economia brasileira: Selic anualizada, IPCA mensal, IPCA acumulado 12 meses, Dólar PTAX (venda) e IBC-Br. Não recebe parâmetros. Quando usar: para um panorama econômico rápido. Quando NÃO usar: para qualquer outra série, para dados históricos ou para escolher o período use bcb_serie_ultimos ou bcb_serie_valores. Retorna: `consultadoEm` (timestamp ISO 8601) e `indicadores` (array com indicador, codigo, data, valor — ou `erro` no item). Resiliente: cada indicador é buscado de forma independente, então a falha de um não derruba os demais. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).

Obtém os metadados descritivos de UMA série do BCB (nome, unidade de medida, periodicidade, fonte, categoria), sem trazer a série de valores. Quando usar: para confirmar o que uma série representa e em que unidade antes de consultar os dados. Quando NÃO usar: para os valores em si use bcb_serie_valores ou bcb_serie_ultimos. Retorna: codigo, nome, unidade, periodicidade, fonte, categoria, especial e URLs diretas da API (urlConsulta, urlUltimos10). Se o endpoint de metadados do BCB não responder, faz fallback para o catálogo interno ou para o último valor disponível, sinalizando a origem em `observacao`. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).

Obtém as últimas N observações de UMA série temporal do BCB (mais recentes primeiro a partir do fim da série). Quando usar: para ver os dados mais recentes sem precisar calcular datas (ex.: últimos 12 meses do IPCA). Quantidade entre 1 e 1000 (padrão 10). Quando NÃO usar: para um intervalo de datas ou o histórico completo use bcb_serie_valores. Retorna: objeto `serie`, `totalRegistros` e `dados` (array de {data, valor}); sem dados, `totalRegistros` = 0 com `observacao`. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).

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). Quando usar: para obter a série histórica completa ou uma janela de datas específica. Quando NÃO usar: para apenas os pontos mais recentes use bcb_serie_ultimos; para a variação percentual use bcb_variacao; para comparar várias séries use bcb_comparar; se não souber o código, descubra-o antes com bcb_buscar_serie ou bcb_series_populares. Retorna: objeto `serie` (codigo, nome, categoria, periodicidade), `totalRegistros`, `periodoInicial`, `periodoFinal` e `dados` (array de {data, valor}); quando não há dados, `totalRegistros` = 0 e uma `observacao` explicativa. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).

Lista o catálogo interno curado de 150+ séries econômicas do BCB com seus códigos, agrupadas por categoria (Juros, Inflação, Câmbio, Atividade Econômica, Emprego, Fiscal, Setor Externo, Crédito, Agregados Monetários, Poupança, Índices de Mercado, Expectativas); aceita filtro por categoria. Quando usar: para navegar/descobrir as séries disponíveis por tema. Quando NÃO usar: para busca por palavra-chave use bcb_buscar_serie; esta ferramenta não busca valores. Retorna: `totalSeries`, `categorias` (nº de categorias) e `series` — objeto agrupado por categoria quando sem filtro, ou array plano quando filtrado por categoria; cada item tem codigo, nome, categoria e periodicidade. Catálogo local: não faz chamada de rede.

Calcula a variação percentual de UMA série entre o primeiro e o último ponto do período, mais estatísticas descritivas. O período pode ser definido por datas (dataInicial/dataFinal) OU pelos últimos N períodos (parâmetro `periodos`, que tem precedência e ignora as datas). Quando usar: para medir tendência/variação de uma única série. Quando NÃO usar: para comparar várias séries use bcb_comparar; para os valores brutos use bcb_serie_valores. Requer ao menos 2 observações no período (senão retorna `isError`). Retorna: `serie`, `periodo` (dataInicial, dataFinal, totalPeriodos), `analise` (valorInicial, valorFinal, diferencaAbsoluta, variacaoPercentual, variacaoFormatada) e `estatisticas` (maximo, minimo, media, amplitude). Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).