Brazilian CEP MCP

Instructions

Implementation Reference

• src/index.ts:27-87 (handler)

  Handler function that executes the CEP lookup using ViaCEP API, handles errors, and formats the address response.

  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)

  Zod schema for input validation of the 'cep' parameter, ensuring 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/index.ts:18-88 (registration)

  Registration of the 'consultar-cep' tool on the MCP server with description, schema, and handler.

  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
        };
      }
    }
  );