MCP-CEP

Instructions

Args:
    uf: Sigla do estado (ex: SP, RJ)
    cidade: Nome da cidade (ex: São Paulo)
    logradouro: Nome da rua, avenida, praça etc (ex: Praça da Sé)

Returns:
    Lista de dicionários com endereços que correspondem à busca.

Implementation Reference

• cep.py:33-55 (handler)

  The main handler function for the 'buscar_ceps_por_logradouro' tool. It queries the ViaCEP API with the provided state (uf), city (cidade), and street (logradouro) to retrieve a list of matching CEPs and addresses. Includes error handling for API failures and invalid addresses. The @mcp.tool() decorator registers it as an MCP tool.

  @mcp.tool()
  async def buscar_ceps_por_logradouro(uf: str, cidade: str, logradouro: str) -> list:
      """Busca todos os CEPs associados a um logradouro em uma cidade e estado.
  
      Args:
          uf: Sigla do estado (ex: SP, RJ)
          cidade: Nome da cidade (ex: São Paulo)
          logradouro: Nome da rua, avenida, praça etc (ex: Praça da Sé)
  
      Returns:
          Lista de dicionários com endereços que correspondem à busca.
      """
      url = f"https://viacep.com.br/ws/{uf}/{cidade}/{logradouro}/json/"
      try:
          async with httpx.AsyncClient(timeout=10.0) as client:
              response = await client.get(url)
              response.raise_for_status()
              data = response.json()
              if isinstance(data, dict) and "erro" in data:
                  return [{"erro": "Endereço não encontrado."}]
              return data
      except Exception as e:
          return [{"erro": f"Erro ao buscar logradouro: {str(e)}"}]