BCB MCP

Instructions

Implementation Reference

• src/tools.ts:608-680 (handler)

  The handleVariacao function calculates the percentage variation of a series based on the provided inputs (data range or number of periods).

  export async function handleVariacao(
    args: { codigo: number; dataInicial?: string; dataFinal?: string; periodos?: number },
    timeoutMs?: number,
    maxRetries?: number
  ): Promise<ToolResult> {
    try {
      let data: SerieValor[];
  
      if (args.periodos && args.periodos > 1) {
        const url = `${BCB_API_BASE}.${args.codigo}/dados/ultimos/${args.periodos}?formato=json`;
        data = await fetchBcbApi(url, timeoutMs, maxRetries) as SerieValor[];
      } else {
        let url = `${BCB_API_BASE}.${args.codigo}/dados?formato=json`;
        if (args.dataInicial) url += `&dataInicial=${formatDateForApi(args.dataInicial)}`;
        if (args.dataFinal) url += `&dataFinal=${formatDateForApi(args.dataFinal)}`;
        data = await fetchBcbApi(url, timeoutMs, maxRetries) as SerieValor[];
      }
  
      if (!Array.isArray(data) || data.length < 2) {
        return {
          content: [{ type: "text" as const, text: `Dados insuficientes para calcular variação. São necessários pelo menos 2 valores.` }]
        };
      }
  
      const serieInfo = SERIES_POPULARES.find(s => s.codigo === args.codigo);
      const valorInicial = parseFloat(data[0].valor);
      const valorFinal = parseFloat(data[data.length - 1].valor);
      const variacao = calculateVariation(valorInicial, valorFinal);
      const diferencaAbsoluta = valorFinal - valorInicial;
      const valores = data.map(d => parseFloat(d.valor));
      const maximo = Math.max(...valores);
      const minimo = Math.min(...valores);
      const media = valores.reduce((a, b) => a + b, 0) / valores.length;
  
      const result = {
        serie: { codigo: args.codigo, nome: serieInfo?.nome || `Série ${args.codigo}`, categoria: serieInfo?.categoria || "Desconhecida" },
        periodo: { dataInicial: data[0].data, dataFinal: data[data.length - 1].data, totalPeriodos: data.length },
        analise: {
          valorInicial, valorFinal,
          diferencaAbsoluta: Number(diferencaAbsoluta.toFixed(4)),
          variacaoPercentual: Number(variacao.toFixed(4)),
          variacaoFormatada: `${variacao >= 0 ? "+" : ""}${variacao.toFixed(2)}%`
        },
        estatisticas: {
          maximo: Number(maximo.toFixed(4)),
          minimo: Number(minimo.toFixed(4)),
          media: Number(media.toFixed(4)),
          amplitude: Number((maximo - minimo).toFixed(4))
        }
      };
  
      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
    } catch (error) {
      return {
        content: [{ type: "text" as const, text: `Erro ao calcular variação: ${error instanceof Error ? error.message : String(error)}` }],
        isError: true
      };
    }
  }
  
  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)}`;

• src/tools.ts:808-821 (schema)

  The registration definition for the 'bcb_variacao' tool, including its description and input schema.

  {
    name: "bcb_variacao",
    description: "Calcula a variação percentual de uma série entre duas datas ou nos últimos N períodos. Útil para análise de tendências.",
    inputSchema: {
      type: "object" as const,
      properties: {
        codigo: { type: "number" as const, description: "Código da série no SGS/BCB" },
        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)" },
        periodos: { type: "number" as const, description: "Alternativa: calcular variação dos últimos N períodos (ignora datas se informado)" }
      },
      required: ["codigo"]
    }
  },

• src/tools.ts:861-862 (registration)

  The tool dispatcher in src/tools.ts handles the 'bcb_variacao' command by calling the handleVariacao function.

  case "bcb_variacao":
    return handleVariacao(args as { codigo: number; dataInicial?: string; dataFinal?: string; periodos?: number }, timeoutMs, maxRetries);