BCB Payment Methods MCP Server

Instructions

Implementation Reference

• src/index.ts:325-348 (handler)

  MCP tool handler for 'consultar_transacoes_cartoes'. Extracts input parameters, fetches data from BCB's 'Quantidadeetransacoesdecartoes' OData endpoint using the shared fetchBCBData helper, and returns the JSON response as text content.

  case "consultar_transacoes_cartoes": {
    const { trimestre, top = 100, ordenar_por, filtro } = args as {
      trimestre: string;
      top?: number;
      ordenar_por?: string;
      filtro?: string;
    };
  
    const data = await fetchBCBData(`Quantidadeetransacoesdecartoes(trimestre=@trimestre)?@trimestre='${trimestre}'`, {
      formato: "json",
      top,
      orderby: ordenar_por,
      filter: filtro,
    });
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(data, null, 2),
        },
      ],
    };
  }

• src/index.ts:120-145 (schema)

  Input schema definition for the 'consultar_transacoes_cartoes' tool, defining parameters including the required 'trimestre' in YYYYQ format, optional top, ordenar_por, and filtro.

  {
    name: "consultar_transacoes_cartoes",
    description: "Consulta estoque e transações de cartões de pagamento por trimestre. Retorna dados sobre quantidade e valor das transações realizadas com cartões.",
    inputSchema: {
      type: "object",
      properties: {
        trimestre: {
          type: "string",
          description: "Ano e trimestre no formato YYYYQ (exemplo: '20234')",
        },
        top: {
          type: "number",
          description: "Número máximo de registros a retornar (padrão: 100)",
        },
        ordenar_por: {
          type: "string",
          description: "Campo para ordenação (exemplo: 'Trimestre desc')",
        },
        filtro: {
          type: "string",
          description: "Filtro OData para refinar a consulta",
        },
      },
      required: ["trimestre"],
    },
  },

• src/http-server.ts:329-352 (handler)

  MCP tool handler for 'consultar_transacoes_cartoes' in the HTTP/SSE server's createMCPServer function. Identical logic to index.ts handler.

  case "consultar_transacoes_cartoes": {
    const { trimestre, top = 100, ordenar_por, filtro } = args as {
      trimestre: string;
      top?: number;
      ordenar_por?: string;
      filtro?: string;
    };
  
    const data = await fetchBCBData(`Quantidadeetransacoesdecartoes(trimestre=@trimestre)?@trimestre='${trimestre}'`, {
      formato: "json",
      top,
      orderby: ordenar_por,
      filter: filtro,
    });
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(data, null, 2),
        },
      ],
    };
  }

• src/http-server.ts:110-135 (schema)

  Input schema definition for the 'consultar_transacoes_cartoes' tool in http-server.ts, identical to index.ts.

  {
    name: "consultar_transacoes_cartoes",
    description: "Consulta estoque e transações de cartões de pagamento por trimestre. Retorna dados sobre quantidade e valor das transações realizadas com cartões.",
    inputSchema: {
      type: "object",
      properties: {
        trimestre: {
          type: "string",
          description: "Ano e trimestre no formato YYYYQ (exemplo: '20234')",
        },
        top: {
          type: "number",
          description: "Número máximo de registros a retornar (padrão: 100)",
        },
        ordenar_por: {
          type: "string",
          description: "Campo para ordenação (exemplo: 'Trimestre desc')",
        },
        filtro: {
          type: "string",
          description: "Filtro OData para refinar a consulta",
        },
      },
      required: ["trimestre"],
    },
  },

• src/index.ts:37-52 (helper)

  Shared helper function used by all tool handlers, including 'consultar_transacoes_cartoes', to make HTTP requests to the BCB Olinda API and handle errors.

  async function fetchBCBData(endpoint: string, params: QueryParams = {}) {
    try {
      const url = buildUrl(endpoint, params);
      const response = await axios.get(url, {
        headers: {
          "Accept": "application/json"
        }
      });
      return response.data;
    } catch (error) {
      if (axios.isAxiosError(error)) {
        throw new Error(`Erro ao consultar API do BCB: ${error.message}`);
      }
      throw error;
    }
  }