Brasil API MCP

Instructions

Implementation Reference

• src/tools/cep/index.ts:20-47 (handler)

  Handler function that queries BrasilAPI CEP endpoint, formats the address information, and returns it as MCP content or error response.

      async ({ cep }) => {
        console.error(`Consulting postal code: ${cep}`);
        
        const result = await getBrasilApiData(`/cep/v2/${cep}`);
        
        if (!result.success) {
          return formatErrorResponse(`Error querying postal code: ${result.message}`);
        }
        
        // Format the response data
        const address = result.data;
        return {
          content: [{ 
            type: "text" as const, 
            text: `
  Endereço encontrado:
  CEP: ${address.cep}
  Logradouro: ${address.street || "N/A"}
  Bairro: ${address.neighborhood || "N/A"}
  Cidade: ${address.city}
  Estado: ${address.state}
  Latitude: ${address.location?.coordinates?.latitude || "N/A"}
  Longitude: ${address.location?.coordinates?.longitude || "N/A"}
  Código IBGE: ${address.city_ibge_code || "N/A"}
  ` 
          }]
        };
      }

• src/tools/cep/index.ts:14-19 (schema)

  Zod input schema validating the 'cep' parameter as exactly 8 digits.

  {
    cep: z.string()
      .length(8, "Postal code must have exactly 8 digits")
      .regex(/^\d+$/, "Postal code must contain only numbers")
      .describe("Postal code to be queried (only numbers, 8 digits)")
  },

• src/tools/cep/index.ts:9-49 (registration)

  Registers the cep-search tool on the MCP server, defining name, description, input schema, and handler.

  export function registerCepTools(server: McpServer) {
    // Tool to query address information from a Brazilian postal code
    server.tool(
      "cep-search",
      "Query address information from a Brazilian postal code (CEP)",
      {
        cep: z.string()
          .length(8, "Postal code must have exactly 8 digits")
          .regex(/^\d+$/, "Postal code must contain only numbers")
          .describe("Postal code to be queried (only numbers, 8 digits)")
      },
      async ({ cep }) => {
        console.error(`Consulting postal code: ${cep}`);
        
        const result = await getBrasilApiData(`/cep/v2/${cep}`);
        
        if (!result.success) {
          return formatErrorResponse(`Error querying postal code: ${result.message}`);
        }
        
        // Format the response data
        const address = result.data;
        return {
          content: [{ 
            type: "text" as const, 
            text: `
  Endereço encontrado:
  CEP: ${address.cep}
  Logradouro: ${address.street || "N/A"}
  Bairro: ${address.neighborhood || "N/A"}
  Cidade: ${address.city}
  Estado: ${address.state}
  Latitude: ${address.location?.coordinates?.latitude || "N/A"}
  Longitude: ${address.location?.coordinates?.longitude || "N/A"}
  Código IBGE: ${address.city_ibge_code || "N/A"}
  ` 
          }]
        };
      }
    );
  }

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

  Top-level call to register the CEP tools during server initialization.

  registerCepTools(server);

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

  Helper utility to fetch data from BrasilAPI endpoints, handling requests and errors, used in cep-search 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
      };
    }
  }