consultar-cep
Retrieve detailed address information in Brazil using an 8-digit postal code (CEP). This tool provides data like street names, neighborhoods, cities, states, regions, and IBGE codes via the ViaCEP API.
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/index.ts:27-87 (handler)Handler function that queries the ViaCEP API for address details based on the provided CEP, handles errors like invalid CEP or API failures, and returns formatted text response or error messages.async ({ cep }) => { try { console.error(`Consulting postal code: ${cep}`); const url = `https://viacep.com.br/ws/${cep}/json/`; const response = await axios.get(url); // Verificando se houve erro na resposta da API if (response.data.erro) { return { content: [{ type: "text", text: "Postal code not found in the database." }], isError: true }; } // Formatando a resposta para exibição const endereco = response.data; return { content: [{ type: "text", text: ` Endereço encontrado: CEP: ${endereco.cep} Logradouro: ${endereco.logradouro} Complemento: ${endereco.complemento || "N/A"} Bairro: ${endereco.bairro} Cidade: ${endereco.localidade} Estado: ${endereco.uf} (${endereco.estado}) Região: ${endereco.regiao} DDD: ${endereco.ddd} IBGE: ${endereco.ibge} ` }] }; } catch (erro: any) { console.error(`Error querying postal code: ${erro.message}`); // Verificando se o erro é devido a formato inválido (status 400) if (erro.response && erro.response.status === 400) { return { content: [{ type: "text", text: "Invalid postal code format. Use only numbers (8 digits)." }], isError: true }; } return { content: [{ type: "text", text: `Error querying postal code: ${erro.message}` }], isError: true }; } }
- src/index.ts:21-26 (schema)Input schema defining the 'cep' parameter with Zod validation: exactly 8 digits, only numbers.{ 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/index.ts:18-88 (registration)Registration of the 'consultar-cep' tool on the MCP server, including name, description, input schema, and handler function.server.tool( "consultar-cep", "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 }) => { try { console.error(`Consulting postal code: ${cep}`); const url = `https://viacep.com.br/ws/${cep}/json/`; const response = await axios.get(url); // Verificando se houve erro na resposta da API if (response.data.erro) { return { content: [{ type: "text", text: "Postal code not found in the database." }], isError: true }; } // Formatando a resposta para exibição const endereco = response.data; return { content: [{ type: "text", text: ` Endereço encontrado: CEP: ${endereco.cep} Logradouro: ${endereco.logradouro} Complemento: ${endereco.complemento || "N/A"} Bairro: ${endereco.bairro} Cidade: ${endereco.localidade} Estado: ${endereco.uf} (${endereco.estado}) Região: ${endereco.regiao} DDD: ${endereco.ddd} IBGE: ${endereco.ibge} ` }] }; } catch (erro: any) { console.error(`Error querying postal code: ${erro.message}`); // Verificando se o erro é devido a formato inválido (status 400) if (erro.response && erro.response.status === 400) { return { content: [{ type: "text", text: "Invalid postal code format. Use only numbers (8 digits)." }], isError: true }; } return { content: [{ type: "text", text: `Error querying postal code: ${erro.message}` }], isError: true }; } } );