BCB MCP

Instructions

Implementation Reference

• src/tools.ts:428-462 (handler)

  The handler function 'handleSerieMetadados' fetches and formats metadata for a given BCB series code.

  export async function handleSerieMetadados(
    args: { codigo: number },
    timeoutMs?: number,
    maxRetries?: number
  ): Promise<ToolResult> {
    try {
      const metadataUrl = `https://api.bcb.gov.br/dados/serie/bcdata.sgs.${args.codigo}/metadados?formato=json`;
  
      try {
        const metadata = await fetchBcbApi(metadataUrl, timeoutMs, maxRetries) as SerieMetadados;
        const serieInfo = SERIES_POPULARES.find(s => s.codigo === args.codigo);
  
        const result = {
          codigo: metadata.codigo || args.codigo,
          nome: metadata.nome || serieInfo?.nome || `Série ${args.codigo}`,
          unidade: metadata.unidade || "Não informada",
          periodicidade: metadata.periodicidade || serieInfo?.periodicidade || "Não informada",
          fonte: metadata.fonte || "Banco Central do Brasil",
          categoria: serieInfo?.categoria || "Não categorizada",
          especial: metadata.especial || false,
          urlConsulta: `${BCB_API_BASE}.${args.codigo}/dados?formato=json`,
          urlUltimos10: `${BCB_API_BASE}.${args.codigo}/dados/ultimos/10?formato=json`
        };
  
        return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
      } catch {
        const serieInfo = SERIES_POPULARES.find(s => s.codigo === args.codigo);
  
        if (serieInfo) {
          const result = {
            codigo: args.codigo,
            nome: serieInfo.nome,
            periodicidade: serieInfo.periodicidade,
            categoria: serieInfo.categoria,
            fonte: "Banco Central do Brasil",

• src/tools.ts:768-778 (schema)

  The schema definition for the 'bcb_serie_metadados' tool in the tool registration array.

  {
    name: "bcb_serie_metadados",
    description: "Obtém informações/metadados de uma série temporal do BCB. Retorna nome, periodicidade, categoria e outros detalhes.",
    inputSchema: {
      type: "object" as const,
      properties: {
        codigo: { type: "number" as const, description: "Código da série no SGS/BCB" }
      },
      required: ["codigo"]
    }
  },

• src/tools.ts:853-854 (registration)

  The registration of 'bcb_serie_metadados' within the 'dispatchTool' dispatcher.

  case "bcb_serie_metadados":
    return handleSerieMetadados(args as { codigo: number }, timeoutMs, maxRetries);