oci_tips/GenAI/mcp/sample1/vibe/09-VALIDATION.md

09 - Validação Final do Projeto

🎯 Objetivo

Fornecer um checklist completo e comandos para validar que o projeto foi gerado corretamente e está funcional.

📋 Contexto

Esta é a última etapa do processo de Vibe Coding. Aqui você verifica se todos os componentes foram gerados corretamente e se o sistema funciona como esperado.

🔧 Especificações Técnicas

• Tipo: Checklist de validação
• Comandos: Bash para verificação
• Resultado: Confirmação de sucesso ou identificação de problemas

---

💬 PROMPT PARA O LLM

Crie um guia de validação completo para verificar se um projeto Python MCP foi gerado corretamente.

O guia deve incluir:

1. CHECKLIST DE ARQUIVOS
   Lista de todos os arquivos que devem existir com tamanho aproximado em linhas

2. COMANDOS DE VERIFICAÇÃO
   Comandos bash para:
   - Listar arquivos do projeto
   - Verificar sintaxe Python de cada arquivo .py
   - Contar linhas de cada arquivo
   - Verificar permissões executáveis

3. VALIDAÇÃO DE CONTEÚDO
   Para cada arquivo principal, lista de verificações:
   - Imports esperados
   - Funções/classes principais
   - Configurações importantes

4. TESTE DE INSTALAÇÃO
   Comandos para:
   - Criar ambiente virtual
   - Instalar dependências
   - Verificar instalação

5. TESTE FUNCIONAL
   Comandos para:
   - Executar testes automatizados
   - Verificar saída esperada

6. TROUBLESHOOTING
   Problemas comuns e soluções

Formato: Markdown com blocos de código bash e checklists.

---

✅ CHECKLIST DE VALIDAÇÃO MANUAL

Use este checklist para validar seu projeto:

📁 Arquivos Obrigatórios

# Verificar estrutura do projeto
cd mcp_project
ls -la

Arquivos esperados:

• mcp_server.py (~253 linhas)
• mcp_client.py (~294 linhas)
• test_system.py (~97 linhas)
• requirements.txt (2 linhas)
• run.sh (~29 linhas, executável)
• README.md (~472 linhas)
• QUICKSTART.md (~202 linhas)
• CHANGELOG.md (~128 linhas)
• venv/ (diretório do ambiente virtual)

🔍 Validação de Sintaxe

# Verificar sintaxe de todos os arquivos Python
python -m py_compile mcp_server.py
python -m py_compile mcp_client.py
python -m py_compile test_system.py

# Se não houver erro, sintaxe está correta
echo "✅ Sintaxe validada"

📊 Contagem de Linhas

# Verificar tamanho dos arquivos
wc -l *.py *.md *.txt *.sh 2>/dev/null

Saída esperada:

  253 mcp_server.py
  294 mcp_client.py
   97 test_system.py
  472 README.md
  202 QUICKSTART.md
  128 CHANGELOG.md
   29 run.sh
    2 requirements.txt
 1477 total

🔧 Validação de Conteúdo

mcp_server.py

# Verificar imports e estrutura
grep -E "from mcp.server import|@app.list_tools|@app.call_tool" mcp_server.py

Esperado:

• ✅ from mcp.server import Server
• ✅ @app.list_tools()
• ✅ @app.call_tool()

mcp_client.py

# Verificar configurações da API
grep -E "API_BASE_URL|API_KEY|MODEL_NAME" mcp_client.py

Esperado:

• ✅ API_BASE_URL = "https://api.xptoai.com.br/genai/grokcode/v1"
• ✅ API_KEY = "biasb986lk657fsdv6d3543vs5b65s7v373sd321vsdv4sdv34bv3f4hb5f4j6mn546tu"
• ✅ MODEL_NAME = "grok-2-1212"

test_system.py

# Verificar casos de teste
grep -c "descricao" test_system.py

Esperado: 8 (8 casos de teste)

requirements.txt

# Verificar dependências
cat requirements.txt

Esperado:

mcp==1.23.1
openai==2.8.1

run.sh

# Verificar se é executável
ls -l run.sh | grep -E "^-rwxr"

Esperado: Permissões de execução presentes

🚀 Teste de Instalação

# 1. Criar ambiente virtual (se ainda não existe)
python3.11 -m venv venv

# 2. Ativar ambiente virtual
source venv/bin/activate

# 3. Instalar dependências
pip install -r requirements.txt

# 4. Verificar instalação
pip list | grep -E "mcp|openai"

Saída esperada:

mcp                1.23.1
openai             2.8.1

🧪 Teste Funcional

# Executar testes automatizados
source venv/bin/activate
python test_system.py

Saída esperada:

============================================================
  TESTE AUTOMATIZADO - Sistema MCP
============================================================

✓ Conectado ao servidor MCP
✓ Ferramentas disponíveis: ['soma', 'subtracao', 'multiplicacao', 'divisao']

📝 Executando sequência de testes...

[Teste 1/8] Teste de Soma
...
[Teste 8/8] Teste de Linguagem Natural - Subtração
...

✅ Todos os testes concluídos!

Resumo dos testes:
  ✓ Soma
  ✓ Subtração
  ✓ Multiplicação
  ✓ Divisão
  ✓ Tratamento de erro (divisão por zero)
  ✓ Operação não implementada
  ✓ Interpretação de linguagem natural

✅ Validação Final

Se todos os itens acima passaram:

echo "🎉 PROJETO VALIDADO COM SUCESSO!"
echo "✅ Todos os arquivos presentes"
echo "✅ Sintaxe Python correta"
echo "✅ Dependências instaladas"
echo "✅ Testes funcionais passando"
echo ""
echo "Você pode agora usar o sistema:"
echo "  ./run.sh"

---

🐛 Troubleshooting

Problema: Arquivo faltando

Solução: Volte ao prompt correspondente e gere novamente

Problema: Erro de sintaxe Python

Solução:

# Ver detalhes do erro
python -m py_compile arquivo.py
# Corrija o erro ou regenere o arquivo

Problema: Dependências não instalam

Solução:

# Atualizar pip
pip install --upgrade pip

# Tentar novamente
pip install -r requirements.txt

Problema: Testes falham

Solução:

1. Verifique se API key está correta em mcp_client.py
2. Verifique conexão com internet
3. Confirme que mcp_server.py está no mesmo diretório

Problema: "Permission denied" ao executar run.sh

Solução:

chmod +x run.sh

---

📊 Resumo de Validação

Componente	Validação	Status
Arquivos	8 arquivos presentes	⬜
Sintaxe	Python válido	⬜
Linhas	~1.477 linhas total	⬜
Dependências	mcp + openai instalados	⬜
Testes	8 testes passando	⬜

Marque cada item quando validado!

---

🎓 Próximos Passos

Após validação bem-sucedida:

1. Explorar o sistema:

   ./run.sh
   

2. Testar diferentes operações:

   • Soma: "Quanto é 10 mais 5?"
   • Subtração: "Subtraia 3 de 20"
   • Multiplicação: "Multiplique 7 por 8"
   • Divisão: "Divida 50 por 2"

3. Experimentar linguagem natural:

   • "Eu tenho 30 laranjas e dei 12"
   • "Se eu ganho 1500 e gasto 800"

4. Testar casos de erro:

   • "Divida 10 por 0"
   • "Calcule raiz quadrada de 16"

5. Customizar o projeto:

   • Adicionar novas operações
   • Modificar o system prompt
   • Criar novos testes

---

🎉 Conclusão

Se você chegou até aqui e todos os testes passaram:

PARABÉNS! 🎊

Você recriou com sucesso o projeto Sistema MCP com AI Agent - Calculadora Inteligente v2.0 usando Vibe Coding!

O projeto está:

• ✅ Completo
• ✅ Funcional
• ✅ Testado
• ✅ Documentado
• ✅ Pronto para uso

Divirta-se explorando e expandindo o sistema! 🚀✨

---

📞 Suporte

Se encontrar problemas:

1. Revise o checklist acima
2. Consulte a seção de troubleshooting
3. Verifique os prompts originais
4. Regenere arquivos problemáticos

---

Fim do Guia de Vibe Coding 🎨