cep-search
Retrieve address details in Brazil by querying a postal code (CEP) using a structured API input. Ideal for integrating location data into applications or systems.
Instructions
Query address information from a Brazilian postal code (CEP)
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cep | Yes | Postal code to be queried (only numbers, 8 digits) |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"cep": {
"description": "Postal code to be queried (only numbers, 8 digits)",
"maxLength": 8,
"minLength": 8,
"pattern": "^\\d+$",
"type": "string"
}
},
"required": [
"cep"
],
"type": "object"
}
Implementation Reference
- src/tools/cep/index.ts:20-47 (handler)The asynchronous handler for the cep-search tool. Fetches CEP data from BrasilAPI, processes the response, and returns formatted address information or error.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)Input schema using Zod to validate the 'cep' parameter as an 8-digit numeric string.{ 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:11-48 (registration)Registration of the 'cep-search' tool on the MCP server, including name, description, schema, and handler.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/utils/api.ts:11-40 (helper)Helper function getBrasilApiData that performs API calls to BrasilAPI endpoints and returns structured success/error responses. 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 }; } }
- src/utils/api.ts:47-55 (helper)Helper function formatErrorResponse that formats error messages into MCP-compatible content structure with isError flag. Used in cep-search handler.export function formatErrorResponse(message: string) { return { content: [{ type: "text" as const, text: message }], isError: true }; }