Brasil API MCP

Instructions

Implementation Reference

• src/tools/cnpj/index.ts:19-54 (handler)

  The handler function that executes the CNPJ search: logs the CNPJ, fetches data from Brasil API, handles errors, and formats a detailed text response with company information.

      async ({ cnpj }) => {
        console.error(`Consulting CNPJ: ${cnpj}`);
        
        const result = await getBrasilApiData(`/cnpj/v1/${cnpj}`);
        
        if (!result.success) {
          return formatErrorResponse(`Error querying CNPJ: ${result.message}`);
        }
        
        // Format the response data
        const company = result.data;
        return {
          content: [{ 
            type: "text" as const, 
            text: `
  Informações da Empresa:
  CNPJ: ${company.cnpj}
  Razão Social: ${company.razao_social}
  Nome Fantasia: ${company.nome_fantasia || "N/A"}
  Situação Cadastral: ${company.descricao_situacao_cadastral || "N/A"}
  Data de Abertura: ${company.data_inicio_atividade || "N/A"}
  CNAE Principal: ${company.cnae_fiscal} - ${company.cnae_fiscal_descricao || "N/A"}
  Natureza Jurídica: ${company.codigo_natureza_juridica} - ${company.natureza_juridica || "N/A"}
  
  Endereço:
  ${company.logradouro || ""} ${company.numero || ""} ${company.complemento || ""}
  ${company.bairro || ""}, ${company.municipio || ""} - ${company.uf || ""}
  CEP: ${company.cep || "N/A"}
  
  Contato:
  Telefone: ${company.ddd_telefone_1 || "N/A"}
  Email: ${company.email || "N/A"}
  ` 
          }]
        };
      }

• src/tools/cnpj/index.ts:14-18 (schema)

  Input schema using Zod: validates CNPJ as exactly 14 digits string.

  {
    cnpj: z.string()
      .regex(/^\d{14}$/, "CNPJ must contain exactly 14 numbers without any special characters")
      .describe("CNPJ to be queried (only numbers, 14 digits)")
  },

• src/tools/cnpj/index.ts:11-55 (registration)

  Registers the 'cnpj-search' tool on the MCP server, specifying name, description, input schema, and handler function.

    server.tool(
      "cnpj-search",
      "Query information about a Brazilian company by its CNPJ (National Registry of Legal Entities)",
      {
        cnpj: z.string()
          .regex(/^\d{14}$/, "CNPJ must contain exactly 14 numbers without any special characters")
          .describe("CNPJ to be queried (only numbers, 14 digits)")
      },
      async ({ cnpj }) => {
        console.error(`Consulting CNPJ: ${cnpj}`);
        
        const result = await getBrasilApiData(`/cnpj/v1/${cnpj}`);
        
        if (!result.success) {
          return formatErrorResponse(`Error querying CNPJ: ${result.message}`);
        }
        
        // Format the response data
        const company = result.data;
        return {
          content: [{ 
            type: "text" as const, 
            text: `
  Informações da Empresa:
  CNPJ: ${company.cnpj}
  Razão Social: ${company.razao_social}
  Nome Fantasia: ${company.nome_fantasia || "N/A"}
  Situação Cadastral: ${company.descricao_situacao_cadastral || "N/A"}
  Data de Abertura: ${company.data_inicio_atividade || "N/A"}
  CNAE Principal: ${company.cnae_fiscal} - ${company.cnae_fiscal_descricao || "N/A"}
  Natureza Jurídica: ${company.codigo_natureza_juridica} - ${company.natureza_juridica || "N/A"}
  
  Endereço:
  ${company.logradouro || ""} ${company.numero || ""} ${company.complemento || ""}
  ${company.bairro || ""}, ${company.municipio || ""} - ${company.uf || ""}
  CEP: ${company.cep || "N/A"}
  
  Contato:
  Telefone: ${company.ddd_telefone_1 || "N/A"}
  Email: ${company.email || "N/A"}
  ` 
          }]
        };
      }
    );

• src/index.ts:26-26 (registration)

  Top-level call to register CNPJ tools (including 'cnpj-search') on the main MCP server instance.

  registerCnpjTools(server);

• src/utils/api.ts:11-40 (helper)

  Helper function to fetch data from Brasil API, handling requests and errors, used by the CNPJ handler.

  export async function getBrasilApiData(endpoint: string, params: Record<string, any> = {}) {
    try {
      const url = `${BASE_URL}${endpoint}`;
      console.error(`Making request to: ${url}`);
      
      const response = await axios.get(url, { params });
      return { 
        data: response.data,
        success: true
      };
    } catch (error: any) {
      console.error(`Error in API request: ${error.message}`);
      
      // Handle API errors in a structured format
      if (error.response) {
        return {
          success: false,
          statusCode: error.response.status,
          message: error.response.data?.message || error.message,
          error: error.response.data
        };
      }
      
      return {
        success: false,
        message: error.message,
        error
      };
    }
  }