consultar_cep

Instructions

Implementation Reference

• src/tools/cep.ts:49-85 (handler)

  Main handler function for consultar_cep. Cleans the CEP (removes non-digits), validates it (8 digits, not all same), calls brasilApi.get('/cep/v2/{cep}'). Returns JSON stringified address data on success, or translated error messages on failure.

  export async function consultarCepHandler(
    input: ConsultarCepInput,
  ): Promise<CallToolResult> {
    const cepLimpo = limparCep(input.cep);
  
    if (!validarCep(cepLimpo)) {
      return {
        content: [
          {
            type: "text",
            text: `CEP inválido: '${input.cep}'. Deve conter 8 dígitos (com ou sem hífen) e não pode ser uma sequência repetida.`,
          },
        ],
        isError: true,
      };
    }
  
    try {
      const dados = await brasilApi.get<unknown>(`/cep/v2/${cepLimpo}`);
      return {
        content: [{ type: "text", text: JSON.stringify(dados, null, 2) }],
      };
    } catch (err) {
      return {
        content: [
          {
            type: "text",
            text: traduzirErroBrasilApi(err, {
              notFound: `CEP ${cepLimpo} não encontrado. Verifique se está correto — alguns CEPs muito específicos só existem em provedores pagos.`,
              contextoErro: "Erro ao consultar CEP",
            }),
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/cep.ts:14-20 (schema)

  Zod schema for consultar_cep input. Accepts a single 'cep' field: string with 8 digits, with or without hyphen.

  export const consultarCepSchema = z.object({
    cep: z
      .string()
      .describe(
        "CEP brasileiro com ou sem hífen. Aceita '01310-100' ou '01310100'. Deve ter 8 dígitos.",
      ),
  });

• src/index.ts:90-97 (registration)

  Registration of the consultar_cep tool on the MCP server via server.registerTool(), using the tool's name, description, schema shape, and the wrapped handler.

  server.registerTool(
    consultarCepTool.name,
    {
      description: consultarCepTool.description,
      inputSchema: consultarCepSchema.shape,
    },
    wrapHandler(consultarCepTool.name, consultarCepHandler),
  );

• src/tools/cep.ts:24-36 (registration)

  Tool metadata definition: name ('consultar_cep'), description (natural language prompt instructions), and inputSchema reference.

  export const consultarCepTool = {
    name: "consultar_cep",
    description: [
      "Consulta endereço completo a partir de um CEP brasileiro via BrasilAPI v2 (agrega ViaCEP, Postmon e outros provedores com fallback automático).",
      "",
      "Retorna em JSON: estado (UF), cidade, bairro, logradouro e, quando disponível, coordenadas geográficas.",
      "",
      "Use quando o usuário pedir o endereço de um CEP, validar um CEP, ou descobrir cidade/UF a partir de um CEP.",
      "",
      "NÃO use para: códigos postais de outros países, descobrir CEP a partir de endereço (a operação é só CEP → endereço, não inversa). Aceita CEP com ou sem hífen.",
    ].join(" "),
    inputSchema: consultarCepSchema,
  };

• src/tools/cep.ts:38-40 (helper)

  Helper function that strips all non-digit characters from the CEP string.

  function limparCep(s: string): string {
    return s.replace(/\D/g, "");
  }