NALU/Prompt2.md

Prompt 2 — NALU AI: Validadores adicionais + MCP Server

Pré-requisito: o projeto do Prompt 1 já está funcionando com POST /v1/extract/name e o validador validate_full_name.md.

---

Parte A — Novos validadores + endpoints

Para cada validador abaixo:

1. Criar o arquivo .md em Validators/ seguindo o mesmo formato de validate_full_name.md
2. Registrar o endpoint em ExtractEndpoints.cs (2 linhas, mesmo padrão)
3. Criar pós-processadores e enrichers necessários

1. validate_cpf.md → POST /v1/extract/cpf

Extrai e valida CPF (11 dígitos, algoritmo mod 11).

Config MCP:

• mcp_tool: nalu_extract_cpf
• mcp_description: Extrai e valida o CPF do usuário. Valida dígitos verificadores automaticamente. Se certain=true, o CPF é válido e pode ser usado. Se certain=false, use suggestion_to_agent para pedir correção.

Regras determinísticas:

• Aceitar: 123.456.789-09, 12345678909, 123 456 789 09
• Rejeitar sequências repetidas: 111.111.111-11, 000.000.000-00, etc.
• Validar dígitos verificadores (mod 11)
• Rejeitar se não tiver exatamente 11 dígitos numéricos

Prompt LLM: extrair CPF mesmo quando informal ("meu cpf é um dois três quatro...") ou no meio de frase longa.

Few-shot (mínimo 5):

• CPF válido direto
• CPF no meio de frase
• CPF com dígito errado
• Resposta evasiva ("não lembro")
• CPF escrito por extenso

Pós-processador: ValidateCpfDigit — validar mod 11, formatar XXX.XXX.XXX-XX

Sugestões:

• when_null_evasive: "Preciso do seu CPF para continuar. São 11 dígitos, pode digitar?"
• when_invalid: "Esse CPF parece estar incorreto. Pode verificar e digitar novamente?"
• when_uncertain: "Só confirmando: seu CPF é {{extracted_value}}?"

---

2. validate_cep.md → POST /v1/extract/cep

Extrai CEP (8 dígitos) e enriquece com endereço via ViaCEP.

Config MCP:

• mcp_tool: nalu_extract_cep
• mcp_description: Extrai o CEP do usuário e retorna o endereço completo (logradouro, bairro, cidade, estado). Se certain=true, o endereço está confirmado. Se obtained=false, o CEP é inválido — use suggestion_to_agent.

Regras determinísticas:

• Aceitar: 01001-000, 01001000
• Rejeitar se não tiver 8 dígitos
• Rejeitar 00000-000

Enricher: ViaCepEnricher

• Chamar https://viacep.com.br/ws/{cep}/json/
• Se retornar erro: true, marcar obtained: false
• Fallback: https://brasilapi.com.br/api/cep/v2/{cep}

extracted_value quando enriquecido:

{
  "cep": "01001-000",
  "logradouro": "Praça da Sé",
  "bairro": "Sé",
  "cidade": "São Paulo",
  "estado": "SP"
}

Sugestões:

• when_invalid: "Esse CEP não parece válido. Pode verificar? Formato: XXXXX-XXX"
• when_enriched_certain: "Encontrei: {{logradouro}}, {{bairro}} — {{cidade}}/{{estado}}. Correto?"
• when_not_found: "Não encontrei esse CEP. Pode verificar e digitar novamente?"

---

3. validate_phone_br.md → POST /v1/extract/phone

Extrai telefone brasileiro com DDD.

Config MCP:

• mcp_tool: nalu_extract_phone
• mcp_description: Extrai o número de telefone brasileiro do usuário, incluindo DDD. Formata automaticamente. Se certain=true, o número é válido.

Regras determinísticas:

• Aceitar: (11) 99999-9999, 11999999999, +55 11 99999-9999, 11 99999 9999
• DDD válido: 11-99
• Celular: 9 dígitos começando com 9
• Fixo: 8 dígitos começando com 2-5

Pós-processador: FormatPhone — normalizar para (XX) XXXXX-XXXX ou (XX) XXXX-XXXX

Sugestões:

• when_invalid: "Não consegui identificar o telefone. Pode digitar com DDD? Ex: (11) 99999-9999"
• when_uncertain: "Seu telefone é {{extracted_value}}? Pode confirmar?"

---

4. validate_email.md → POST /v1/extract/email

Extrai email com correção de typos.

Config MCP:

• mcp_tool: nalu_extract_email
• mcp_description: Extrai o email do usuário com correção automática de typos em domínios comuns (gmail, hotmail, outlook). Se houve correção, certain=false para o agente confirmar.

Regras determinísticas:

• Regex de email
• Rejeitar sem @ ou sem ponto após @

Pós-processador: CorrectEmailTypos

• gmail.com.br → gmail.com
• gamil.com, gmaill.com, gnail.com → gmail.com
• hotmal.com, hotmial.com → hotmail.com
• outlok.com → outlook.com
• yaho.com → yahoo.com

Se corrigiu: certain=false, guardar original para a sugestão.

Sugestões:

• when_corrected: "Seu email é {{extracted_value}}? (notamos um possível erro em '{{original}}')"
• when_invalid: "Não parece um email válido. Pode digitar novamente?"

---

5. validate_yes_no.md → POST /v1/extract/yes-no

Detecta sim/não.

Config MCP:

• mcp_tool: nalu_extract_yes_no
• mcp_description: Detecta se o usuário respondeu sim ou não. Retorna true (sim), false (não), ou null (ambíguo). Ideal para confirmações. Se ambíguo, use suggestion_to_agent para re-perguntar.

Regras determinísticas:

• Sim: sim, s, ss, yes, si, pode, claro, com certeza, bora, vamos, isso, exato, beleza, blz, ok, tá, aham, uhum, positivo, aceito, quero, concordo, fechado, feito, show, top, massa, dale
• Não: não, nao, n, no, nope, nada, nunca, jamais, nem, negativo, recuso, discordo, não quero, de jeito nenhum

Quando ambíguo → LLM interpreta com contexto.

extracted_value: true, false, ou null

Sugestões:

• when_ambiguous: "Desculpa, não entendi. Pode responder sim ou não?"

---

Parte B — MCP Server

Adicionar MCP ao mesmo projeto ASP.NET Core, expondo cada validador como uma tool.

Transporte

Streamable HTTP no endpoint /mcp.

Tools registradas

Cada validador gera uma tool MCP automaticamente, usando os campos mcp_tool e mcp_description do seu arquivo .md:

nalu_extract_name     — parâmetros: agent_input, user_input, agent_context?, language?
nalu_extract_cpf      — parâmetros: agent_input, user_input, agent_context?, language?
nalu_extract_cep      — parâmetros: agent_input, user_input, agent_context?, language?
nalu_extract_phone    — parâmetros: agent_input, user_input, agent_context?, language?
nalu_extract_email    — parâmetros: agent_input, user_input, agent_context?, language?
nalu_extract_yes_no   — parâmetros: agent_input, user_input, agent_context?, language?

Todos compartilham os mesmos parâmetros de entrada e o mesmo formato de resposta. Internamente, cada tool chama ExtractionPipeline.ExecuteAsync(validator_id, request).

Registro dinâmico de tools

O MCP server deve gerar a lista de tools automaticamente a partir dos arquivos .md na pasta Validators/. Quando um novo .md é adicionado com as configs mcp_tool e mcp_description, ele aparece automaticamente em tools/list.

Instrução para o agente consumidor

Incluir no mcp_description de cada tool:

Se certain: true, aceite o extracted_value e prossiga para o próximo passo. Se certain: false e suggestion_to_agent não é null, use a sugestão como próxima mensagem ao usuário. Se obtained: false, use a sugestão para re-pedir o dado ao usuário.

Auth

• API key via Authorization: Bearer {key} no header HTTP
• Mesma validação de auth e rate limit do REST

Implementação

Verificar se existe pacote NuGet ModelContextProtocol maduro para C#. Se sim, usá-lo. Se não, implementar manualmente:

• Endpoint POST /mcp (Streamable HTTP)
• Responder a initialize, tools/list, tools/call
• JSON-RPC 2.0
• Content-Type: application/json

Arquivo de setup para devs

Criar mcp-config.json na raiz para facilitar conexão:

{
  "mcpServers": {
    "nalu": {
      "url": "http://localhost:5000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Testes MCP

• Teste que simula tools/list e verifica que todas as tools estão listadas
• Teste que chama tools/call no nalu_extract_name e verifica a resposta
• Teste que verifica que um novo .md adicionado aparece em tools/list

---

Resumo de arquivos a criar/modificar

Criar:

• Validators/validate_cpf.md
• Validators/validate_cep.md
• Validators/validate_phone_br.md
• Validators/validate_email.md
• Validators/validate_yes_no.md
• PostProcessors/ValidateCpfDigit.cs
• PostProcessors/FormatPhone.cs
• PostProcessors/CorrectEmailTypos.cs
• Enrichers/ViaCepEnricher.cs
• Mcp/NaluMcpServer.cs (ou equivalente)
• mcp-config.json
• Testes para os novos validadores e MCP

Modificar:

• ExtractEndpoints.cs — adicionar 5 novos endpoints
• PostProcessorRegistry.cs — registrar novos processadores
• EnrichmentService.cs — registrar ViaCepEnricher
• Program.cs — registrar MCP server e novos serviços