BCB MCP

Instructions

Implementation Reference

• src/tools.ts:668-716 (handler)

  The 'handleComparar' function executes the logic for the 'bcb_comparar' tool, fetching time series data from the BCB API for multiple codes and calculating statistics like variation, min, max, and average.

  export async function handleComparar(
    args: { codigos: number[]; dataInicial: string; dataFinal: string },
    timeoutMs?: number,
    maxRetries?: number
  ): Promise<ToolResult> {
    try {
      const resultados = await Promise.all(
        args.codigos.map(async (codigo) => {
          try {
            let url = `${BCB_API_BASE}.${codigo}/dados?formato=json`;
            url += `&dataInicial=${formatDateForApi(args.dataInicial)}`;
            url += `&dataFinal=${formatDateForApi(args.dataFinal)}`;
  
            const data = await fetchBcbApi(url, timeoutMs, maxRetries) as SerieValor[];
            const serieInfo = SERIES_POPULARES.find(s => s.codigo === codigo);
  
            if (!Array.isArray(data) || data.length === 0) {
              return { codigo, nome: serieInfo?.nome || `Série ${codigo}`, erro: "Sem dados no período" };
            }
  
            const valores = data.map(d => parseFloat(d.valor));
            const valorInicial = valores[0];
            const valorFinal = valores[valores.length - 1];
            const variacao = calculateVariation(valorInicial, valorFinal);
  
            return {
              codigo,
              nome: serieInfo?.nome || `Série ${codigo}`,
              categoria: serieInfo?.categoria || "Desconhecida",
              periodicidade: serieInfo?.periodicidade || "Desconhecida",
              totalRegistros: data.length,
              valorInicial, valorFinal,
              variacaoPercentual: Number(variacao.toFixed(4)),
              variacaoFormatada: `${variacao >= 0 ? "+" : ""}${variacao.toFixed(2)}%`,
              maximo: Math.max(...valores),
              minimo: Math.min(...valores),
              media: Number((valores.reduce((a, b) => a + b, 0) / valores.length).toFixed(4))
            };
          } catch (err) {
            const serieInfo = SERIES_POPULARES.find(s => s.codigo === codigo);
            return { codigo, nome: serieInfo?.nome || `Série ${codigo}`, erro: err instanceof Error ? err.message : "Erro desconhecido" };
          }
        })
      );
  
      const seriesComDados = resultados.filter(r => !("erro" in r));
      const seriesComErro = resultados.filter(r => "erro" in r);
  
      const seriesOrdenadas = [...seriesComDados].sort((a, b) => {

• src/tools.ts:822-834 (schema)

  Input schema definition for the 'bcb_comparar' tool, specifying 'codigos', 'dataInicial', and 'dataFinal'.

  {
    name: "bcb_comparar",
    description: "Compara 2 a 5 séries temporais no mesmo período. Útil para análise de correlação entre indicadores.",
    inputSchema: {
      type: "object" as const,
      properties: {
        codigos: { type: "array" as const, items: { type: "number" as const }, description: "Array com 2 a 5 códigos de séries para comparar" },
        dataInicial: { type: "string" as const, description: "Data inicial (yyyy-MM-dd ou dd/MM/yyyy)" },
        dataFinal: { type: "string" as const, description: "Data final (yyyy-MM-dd ou dd/MM/yyyy)" }
      },
      required: ["codigos", "dataInicial", "dataFinal"]
    }
  }

• src/tools.ts:863-864 (registration)

  Dispatcher registration for 'bcb_comparar' connecting the tool name to the 'handleComparar' function.

  case "bcb_comparar":
    return handleComparar(args as { codigos: number[]; dataInicial: string; dataFinal: string }, timeoutMs, maxRetries);