cep-search
Find Brazilian address details by entering an 8-digit postal code (CEP). This tool retrieves location information from Brazil's public data services.
Instructions
Query address information from a Brazilian postal code (CEP)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cep | Yes | Postal code to be queried (only numbers, 8 digits) |
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 }; } }