diff --git a/GenAI/mcp/sample1/vibe/00-SETUP.md b/GenAI/mcp/sample1/vibe/00-SETUP.md new file mode 100644 index 0000000..baf68bf --- /dev/null +++ b/GenAI/mcp/sample1/vibe/00-SETUP.md @@ -0,0 +1,105 @@ +# 00 - Setup Inicial do Projeto + +## 🎯 Objetivo + +Criar a estrutura inicial do projeto MCP com ambiente virtual Python e preparar o diretório de trabalho. + +## 📋 Contexto + +Este é o primeiro passo para construir um sistema MCP (Model Context Protocol) com AI Agent que funciona como uma calculadora inteligente. O projeto utilizará Python 3.11, bibliotecas MCP e OpenAI SDK. + +## 🔧 Especificações Técnicas + +- **Linguagem:** Python 3.11+ +- **Estrutura:** Ambiente virtual isolado +- **Diretório:** `mcp_project/` +- **Dependências principais:** mcp, openai + +--- + +## 💬 PROMPT COMPLETO + +``` +Preciso criar um projeto Python para implementar um sistema MCP (Model Context Protocol) com AI Agent. + +REQUISITOS: +1. Criar diretório chamado "mcp_project" +2. Configurar ambiente virtual Python 3.11 +3. Preparar estrutura básica de arquivos + +ESTRUTURA ESPERADA: +mcp_project/ +├── venv/ # Ambiente virtual (será criado) +├── mcp_server.py # Servidor MCP (será criado depois) +├── mcp_client.py # Cliente MCP (será criado depois) +├── test_system.py # Testes (será criado depois) +├── requirements.txt # Dependências (será criado depois) +├── run.sh # Script de execução (será criado depois) +└── README.md # Documentação (será criado depois) + +Por favor, forneça os comandos bash para: +1. Criar o diretório do projeto +2. Criar ambiente virtual Python +3. Ativar o ambiente virtual +4. Verificar a versão do Python + +Formato de resposta: comandos bash prontos para executar. +``` + +--- + +## ✅ Resultado Esperado + +Você deve receber comandos bash similares a: + +```bash +# Criar diretório do projeto +mkdir mcp_project +cd mcp_project + +# Criar ambiente virtual +python3.11 -m venv venv + +# Ativar ambiente virtual +source venv/bin/activate + +# Verificar versão do Python +python --version +``` + +--- + +## 🧪 Como Validar + +Execute os comandos fornecidos e verifique: + +```bash +# 1. Verificar se diretório foi criado +ls -la mcp_project/ + +# 2. Verificar se ambiente virtual existe +ls -la mcp_project/venv/ + +# 3. Verificar se Python está correto (deve mostrar 3.11.x) +python --version +``` + +**Saída esperada:** +``` +Python 3.11.x +``` + +--- + +## 📝 Notas + +- Se você não tiver Python 3.11, pode usar `python3` ou `python` +- O ambiente virtual isola as dependências do projeto +- Sempre ative o ambiente virtual antes de instalar pacotes +- No Windows, use `venv\Scripts\activate` ao invés de `source venv/bin/activate` + +--- + +## ➡️ Próximo Passo + +Após completar o setup, prossiga para: **`01-MCP-SERVER.md`** diff --git a/GenAI/mcp/sample1/vibe/01-MCP-SERVER.md b/GenAI/mcp/sample1/vibe/01-MCP-SERVER.md new file mode 100644 index 0000000..30755c2 --- /dev/null +++ b/GenAI/mcp/sample1/vibe/01-MCP-SERVER.md @@ -0,0 +1,210 @@ +# 01 - Servidor MCP com 4 Operações Matemáticas + +## 🎯 Objetivo + +Gerar o arquivo `mcp_server.py` que implementa um servidor MCP com 4 ferramentas matemáticas: soma, subtração, multiplicação e divisão, incluindo tratamento robusto de erros. + +## 📋 Contexto + +O servidor MCP expõe ferramentas (tools) que podem ser chamadas pelo cliente. Cada ferramenta realiza uma operação matemática específica e retorna resultados estruturados em JSON. + +## 🔧 Especificações Técnicas + +- **Framework:** MCP (Model Context Protocol) +- **Comunicação:** stdio (entrada/saída padrão) +- **Formato de resposta:** JSON estruturado +- **Validações:** Parâmetros obrigatórios, tipos, divisão por zero +- **Operações:** soma, subtracao, multiplicacao, divisao + +--- + +## 💬 PROMPT COMPLETO + +``` +Você é um desenvolvedor Python especialista em AI Agents e Model Context Protocol (MCP). + +TAREFA: +Crie um arquivo Python chamado "mcp_server.py" que implemente um servidor MCP com 4 ferramentas matemáticas. + +REQUISITOS FUNCIONAIS: + +1. FERRAMENTAS (4 operações): + - soma: Adiciona dois números inteiros + - subtracao: Subtrai numero2 de numero1 + - multiplicacao: Multiplica dois números inteiros + - divisao: Divide numero1 por numero2 (retorna float) + +2. VALIDAÇÕES OBRIGATÓRIAS: + - Verificar se ambos os parâmetros (numero1, numero2) foram fornecidos + - Validar se os números são do tipo inteiro + - Detectar divisão por zero e retornar erro apropriado + - Tratar exceções com try-catch em cada operação + +3. FORMATO DE RESPOSTA (Sucesso): + { + "operacao": "nome_da_operacao", + "numero1": valor1, + "numero2": valor2, + "resultado": resultado_calculado, + "expressao": "representacao_textual" // ex: "15 + 7 = 22" + } + +4. FORMATO DE RESPOSTA (Erro): + { + "error": "descrição_do_erro", + "operacao": "nome_da_operacao", + ... (outros campos relevantes) + } + +5. OPERAÇÕES NÃO IMPLEMENTADAS: + Se uma ferramenta desconhecida for chamada, retornar: + { + "error": "Operação 'nome' não está implementada", + "operacao_solicitada": "nome", + "operacoes_disponiveis": ["soma", "subtracao", "multiplicacao", "divisao"], + "mensagem": "Por favor, utilize uma das operações disponíveis..." + } + +6. DIVISÃO ESPECIAL: + Para divisão, incluir também: + - resultado_inteiro: resultado da divisão inteira (numero1 // numero2) + - resto: resto da divisão (numero1 % numero2) + +REQUISITOS TÉCNICOS: + +- Usar biblioteca: mcp.server, mcp.types, mcp.server.stdio +- Usar asyncio para operações assíncronas +- Nome do servidor: "math-tools-server" +- Comunicação via stdio_server() +- Decoradores: @app.list_tools() e @app.call_tool() +- Shebang: #!/usr/bin/env python3 +- Docstrings em português + +ESTRUTURA DO CÓDIGO: + +1. Imports necessários +2. Criação da instância do servidor +3. Função list_tools() que retorna lista de Tool objects +4. Função call_tool(name, arguments) que executa as operações +5. Função main() que inicia o servidor via stdio +6. Bloco if __name__ == "__main__" + +EXEMPLO DE VALIDAÇÃO DE DIVISÃO POR ZERO: +```python +if name == "divisao": + if numero2 == 0: + return [TextContent( + type="text", + text=json.dumps({ + "error": "Divisão por zero não é permitida", + "operacao": "divisao", + "numero1": numero1, + "numero2": numero2 + }) + )] +``` + +Por favor, gere o código completo do arquivo mcp_server.py seguindo todas estas especificações. +``` + +--- + +## ✅ Resultado Esperado + +Você deve receber um arquivo Python completo (~250 linhas) com: + +**Estrutura:** +```python +#!/usr/bin/env python3 +""" +Servidor MCP com ferramentas matemáticas... +""" + +import asyncio +import json +from mcp.server import Server +from mcp.types import Tool, TextContent +from mcp.server.stdio import stdio_server + +app = Server("math-tools-server") + +@app.list_tools() +async def list_tools() -> list[Tool]: + # Retorna 4 ferramentas... + +@app.call_tool() +async def call_tool(name: str, arguments: dict) -> list[TextContent]: + # Validações e execução... + +async def main(): + # Inicia servidor... + +if __name__ == "__main__": + asyncio.run(main()) +``` + +**Características:** +- ✅ 4 ferramentas definidas (soma, subtracao, multiplicacao, divisao) +- ✅ Validação de parâmetros obrigatórios +- ✅ Validação de tipos +- ✅ Tratamento de divisão por zero +- ✅ Try-catch em cada operação +- ✅ Respostas JSON estruturadas +- ✅ Mensagem para operações não implementadas + +--- + +## 🧪 Como Validar + +Salve o código gerado em `mcp_project/mcp_server.py` e verifique: + +```bash +# 1. Verificar sintaxe Python +python -m py_compile mcp_server.py + +# 2. Verificar imports (sem executar) +python -c "import ast; ast.parse(open('mcp_server.py').read())" + +# 3. Contar linhas +wc -l mcp_server.py +``` + +**Saída esperada:** +``` +253 mcp_server.py +``` + +**Verificação manual:** +- [ ] Arquivo tem shebang `#!/usr/bin/env python3` +- [ ] Imports: mcp.server, mcp.types, mcp.server.stdio, asyncio, json +- [ ] Decorador `@app.list_tools()` presente +- [ ] Decorador `@app.call_tool()` presente +- [ ] 4 ferramentas definidas no list_tools() +- [ ] Validação de divisão por zero implementada +- [ ] Função main() com stdio_server() + +--- + +## 📝 Notas + +- O servidor será executado pelo cliente via subprocess +- A comunicação acontece via stdin/stdout +- Não execute o servidor diretamente ainda (precisa do cliente) +- O servidor fica em loop aguardando comandos MCP + +--- + +## 🔧 Troubleshooting + +**Erro: "Module 'mcp' not found"** +- Solução: Instale as dependências (será feito no prompt 04) + +**Erro de sintaxe:** +- Verifique se copiou o código completo +- Confirme que não há caracteres especiais corrompidos + +--- + +## ➡️ Próximo Passo + +Após validar o servidor, prossiga para: **`02-MCP-CLIENT.md`** diff --git a/GenAI/mcp/sample1/vibe/02-MCP-CLIENT.md b/GenAI/mcp/sample1/vibe/02-MCP-CLIENT.md new file mode 100644 index 0000000..5ef17f9 --- /dev/null +++ b/GenAI/mcp/sample1/vibe/02-MCP-CLIENT.md @@ -0,0 +1,262 @@ +# 02 - Cliente MCP com Interpretação Inteligente + +## 🎯 Objetivo + +Gerar o arquivo `mcp_client.py` que implementa um cliente MCP com integração ao LLM, capaz de interpretar operações matemáticas solicitadas em linguagem natural e executá-las através do servidor MCP. + +## 📋 Contexto + +O cliente MCP conecta-se ao servidor via stdio, integra-se com um LLM (via API compatível com OpenAI) para interpretar as intenções do usuário, e executa tool calls apropriados. O sistema deve entender linguagem natural como "Eu tenho 25 maçãs e ganhei mais 13". + +## 🔧 Especificações Técnicas + +- **Framework:** MCP Client, OpenAI SDK +- **Comunicação:** stdio com servidor MCP +- **LLM:** API compatível com OpenAI +- **Interface:** Chat interativo via terminal +- **Histórico:** Mantém contexto da conversação + +--- + +## 💬 PROMPT COMPLETO + +``` +Você é um desenvolvedor Python especialista em AI Agents e Model Context Protocol (MCP). + +TAREFA: +Crie um arquivo Python chamado "mcp_client.py" que implemente um cliente MCP com integração a um LLM para criar uma calculadora inteligente com interface de chat. + +REQUISITOS FUNCIONAIS: + +1. CONEXÃO COM SERVIDOR MCP: + - Conectar ao servidor via stdio (subprocess) + - Comando: python3, args: ["mcp_server.py"] + - Usar StdioServerParameters e stdio_client + - Inicializar sessão e obter lista de ferramentas disponíveis + +2. INTEGRAÇÃO COM LLM: + - API Base URL: "https://api.xptoai.com.br/genai/grokcode/v1" + - API Key: "biasb986lk657fsdv6d3543vs5b65s7v373sd321vsdv4sdv34bv3f4hb5f4j6mn546tu" + - Modelo: "grok-2-1212" + - Usar OpenAI SDK (compatível) + +3. INTERPRETAÇÃO INTELIGENTE: + O LLM deve ser instruído (via system prompt) a: + - Interpretar qual operação matemática o usuário deseja + - Identificar os dois números envolvidos na conversa + - Chamar a ferramenta apropriada automaticamente + - Apresentar resultados de forma amigável + +4. SYSTEM PROMPT (incluir no código): + """ + Você é um assistente matemático inteligente que ajuda usuários a realizar operações matemáticas. + Você tem acesso a 4 ferramentas: soma, subtração, multiplicação e divisão. + + Seu objetivo é: + 1. Interpretar qual operação matemática o usuário deseja realizar através da conversa natural + 2. Identificar os dois números que o usuário quer usar + 3. Chamar a ferramenta apropriada com os números corretos + 4. Apresentar o resultado de forma clara e amigável + + Exemplos de interpretação: + - 'Quanto é 5 mais 3?' → usar ferramenta 'soma' com 5 e 3 + - 'Subtraia 10 de 25' → usar ferramenta 'subtracao' com 25 e 10 + - 'Multiplique 7 por 8' → usar ferramenta 'multiplicacao' com 7 e 8 + - 'Divida 20 por 4' → usar ferramenta 'divisao' com 20 e 4 + - '15 menos 7' → usar ferramenta 'subtracao' com 15 e 7 + + Se o usuário pedir uma operação que não está disponível (como potência, raiz quadrada, etc.), + informe educadamente que apenas as 4 operações básicas estão implementadas. + + Se houver erro na execução (como divisão por zero), explique o erro de forma educada e sugira uma alternativa. + + Seja conversacional, natural e prestativo na interação. + """ + +5. CLASSE MCPChatClient: + Métodos necessários: + - __init__(): Inicializar OpenAI client, session, tools, histórico + - connect_to_server(): Conectar ao servidor MCP via stdio + - format_tools_for_openai(): Converter ferramentas MCP para formato OpenAI + - call_mcp_tool(tool_name, arguments): Executar ferramenta no servidor + - chat(user_message): Processar mensagem e retornar resposta + - close(): Fechar conexões + +6. FLUXO DO MÉTODO chat(): + a. Adicionar mensagem do usuário ao histórico + b. Preparar mensagens (system prompt + histórico) + c. Chamar LLM com ferramentas disponíveis + d. Se LLM retornar tool_calls: + - Executar cada tool call no servidor MCP + - Adicionar resultados ao histórico + - Fazer nova chamada ao LLM com os resultados + - Retornar resposta final generativa + e. Se não houver tool_calls: + - Retornar resposta textual diretamente + +7. FEEDBACK VISUAL: + Ao executar ferramentas, imprimir: + ``` + 🔧 Executando ferramenta: nome_da_ferramenta + Argumentos: {argumentos} + ✓ Resultado: valor (se sucesso) + ⚠️ Erro: mensagem (se erro) + ``` + +8. INTERFACE DE CHAT: + - Função main() com loop interativo + - Prompt: "👤 Você: " + - Resposta: "🤖 Assistente: " + - Comando "sair" para encerrar + - Tratamento de KeyboardInterrupt (Ctrl+C) + +9. GERENCIAMENTO DE CONTEXTO: + - Usar context managers assíncronos corretamente + - stdio_context = stdio_client(server_params) + - await stdio_context.__aenter__() + - await stdio_context.__aexit__() no close() + +REQUISITOS TÉCNICOS: + +- Imports: asyncio, json, typing.Optional, mcp, mcp.client.stdio, openai +- Usar async/await para todas operações assíncronas +- Manter histórico de conversação (lista de dicts) +- Shebang: #!/usr/bin/env python3 +- Docstrings em português + +ESTRUTURA DO CÓDIGO: + +1. Imports e constantes (API_BASE_URL, API_KEY, MODEL_NAME) +2. Classe MCPChatClient com todos os métodos +3. Função async main() com loop de chat +4. Bloco if __name__ == "__main__" + +EXEMPLO DE CONVERSÃO DE FERRAMENTAS: +```python +def format_tools_for_openai(self) -> list: + openai_tools = [] + for tool in self.available_tools: + openai_tools.append({ + "type": "function", + "function": { + "name": tool.name, + "description": tool.description, + "parameters": tool.inputSchema + } + }) + return openai_tools +``` + +Por favor, gere o código completo do arquivo mcp_client.py seguindo todas estas especificações. +``` + +--- + +## ✅ Resultado Esperado + +Você deve receber um arquivo Python completo (~290 linhas) com: + +**Estrutura:** +```python +#!/usr/bin/env python3 +""" +Cliente MCP que interage com o usuário via chat usando LLM... +""" + +import asyncio +import json +from typing import Optional +from mcp import ClientSession, StdioServerParameters +from mcp.client.stdio import stdio_client +from openai import OpenAI + +# Configuração do LLM +API_BASE_URL = "https://api.xptoai.com.br/genai/grokcode/v1" +API_KEY = "biasb986lk657fsdv6d3543vs5b65s7v373sd321vsdv4sdv34bv3f4hb5f4j6mn546tu" +MODEL_NAME = "grok-2-1212" + +class MCPChatClient: + # Métodos... + +async def main(): + # Loop de chat... + +if __name__ == "__main__": + asyncio.run(main()) +``` + +**Características:** +- ✅ Classe MCPChatClient completa +- ✅ Conexão com servidor MCP via stdio +- ✅ Integração com OpenAI SDK +- ✅ System prompt para interpretação inteligente +- ✅ Conversão de ferramentas MCP para formato OpenAI +- ✅ Execução de tool calls +- ✅ Feedback visual (✓ e ⚠️) +- ✅ Loop de chat interativo +- ✅ Tratamento de erros + +--- + +## 🧪 Como Validar + +Salve o código gerado em `mcp_project/mcp_client.py` e verifique: + +```bash +# 1. Verificar sintaxe Python +python -m py_compile mcp_client.py + +# 2. Verificar imports +python -c "import ast; ast.parse(open('mcp_client.py').read())" + +# 3. Contar linhas +wc -l mcp_client.py + +# 4. Verificar se constantes estão definidas +grep -E "API_BASE_URL|API_KEY|MODEL_NAME" mcp_client.py +``` + +**Saída esperada:** +``` +294 mcp_client.py +``` + +**Verificação manual:** +- [ ] Arquivo tem shebang `#!/usr/bin/env python3` +- [ ] Constantes API_BASE_URL, API_KEY, MODEL_NAME definidas +- [ ] Classe MCPChatClient presente +- [ ] Método connect_to_server() implementado +- [ ] Método chat() com lógica de tool calls +- [ ] System prompt detalhado incluído +- [ ] Função main() com loop interativo +- [ ] Feedback visual com emojis (🔧, ✓, ⚠️) + +--- + +## 📝 Notas + +- O cliente inicia o servidor automaticamente via subprocess +- A API key está hardcoded (em produção, use variáveis de ambiente) +- O histórico de conversação permite contexto entre mensagens +- O LLM decide quando chamar ferramentas baseado no system prompt + +--- + +## 🔧 Troubleshooting + +**Erro: "Module 'openai' not found"** +- Solução: Instale as dependências (será feito no prompt 04) + +**Erro: "Connection refused" ao conectar servidor** +- Verifique se mcp_server.py existe no mesmo diretório +- Confirme que o comando no StdioServerParameters está correto + +**LLM não chama ferramentas:** +- Verifique se o system prompt está correto +- Confirme que format_tools_for_openai() retorna formato válido + +--- + +## ➡️ Próximo Passo + +Após validar o cliente, prossiga para: **`03-TESTS.md`** diff --git a/GenAI/mcp/sample1/vibe/03-TESTS.md b/GenAI/mcp/sample1/vibe/03-TESTS.md new file mode 100644 index 0000000..37f1bad --- /dev/null +++ b/GenAI/mcp/sample1/vibe/03-TESTS.md @@ -0,0 +1,264 @@ +# 03 - Testes Automatizados Abrangentes + +## 🎯 Objetivo + +Gerar o arquivo `test_system.py` que implementa testes automatizados para validar todas as 4 operações matemáticas, tratamento de erros e interpretação de linguagem natural. + +## 📋 Contexto + +Os testes devem cobrir casos de sucesso (happy path), casos de erro (divisão por zero), operações não implementadas e interpretação de linguagem natural contextual. + +## 🔧 Especificações Técnicas + +- **Framework:** Reutiliza MCPChatClient +- **Casos de teste:** 8 cenários diferentes +- **Execução:** Sequencial com pausas entre testes +- **Saída:** Relatório formatado com resumo final + +--- + +## 💬 PROMPT COMPLETO + +``` +Você é um desenvolvedor Python especialista em testes automatizados para sistemas com AI Agents. + +TAREFA: +Crie um arquivo Python chamado "test_system.py" que implemente testes automatizados abrangentes para o sistema MCP de calculadora inteligente. + +REQUISITOS FUNCIONAIS: + +1. IMPORTAR E REUTILIZAR: + - Importar a classe MCPChatClient de mcp_client.py + - Usar asyncio para execução assíncrona + - Não duplicar código, apenas testar + +2. CASOS DE TESTE (8 cenários): + + TESTE 1 - Soma: + - Descrição: "Teste de Soma" + - Mensagem: "Quanto é 15 mais 7?" + - Resultado esperado: 22 + + TESTE 2 - Subtração: + - Descrição: "Teste de Subtração" + - Mensagem: "Subtraia 5 de 20" + - Resultado esperado: 15 + + TESTE 3 - Multiplicação: + - Descrição: "Teste de Multiplicação" + - Mensagem: "Multiplique 8 por 6" + - Resultado esperado: 48 + + TESTE 4 - Divisão: + - Descrição: "Teste de Divisão" + - Mensagem: "Divida 100 por 4" + - Resultado esperado: 25 + + TESTE 5 - Divisão por Zero (Erro Esperado): + - Descrição: "Teste de Divisão por Zero (Erro Esperado)" + - Mensagem: "Divida 10 por 0" + - Resultado esperado: Erro tratado educadamente + + TESTE 6 - Operação Não Implementada: + - Descrição: "Teste de Operação Não Implementada" + - Mensagem: "Calcule 5 elevado ao quadrado" + - Resultado esperado: Informação sobre limitação + + TESTE 7 - Linguagem Natural (Soma): + - Descrição: "Teste de Linguagem Natural - Soma" + - Mensagem: "Eu tenho 25 maçãs e ganhei mais 13, quantas tenho agora?" + - Resultado esperado: 38 + + TESTE 8 - Linguagem Natural (Subtração): + - Descrição: "Teste de Linguagem Natural - Subtração" + - Mensagem: "Se eu tinha 50 reais e gastei 18, quanto sobrou?" + - Resultado esperado: 32 + +3. ESTRUTURA DE DADOS: + Usar lista de dicionários: + ```python + test_cases = [ + { + "descricao": "Teste de Soma", + "mensagem": "Quanto é 15 mais 7?" + }, + # ... outros casos + ] + ``` + +4. FUNÇÃO test_system(): + - Criar instância de MCPChatClient + - Conectar ao servidor + - Iterar sobre test_cases + - Para cada teste: + * Imprimir cabeçalho com número e descrição + * Imprimir mensagem do usuário + * Chamar client.chat(mensagem) + * Imprimir resposta do assistente + * Adicionar pausa de 1 segundo entre testes + - Imprimir resumo final + +5. FORMATAÇÃO DE SAÍDA: + ``` + ============================================================ + 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 + ------------------------------------------------------------ + 👤 Usuário: Quanto é 15 mais 7? + 🤖 Assistente: [resposta do LLM] + ============================================================ + + [Teste 2/8] Teste de 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 + ``` + +6. TRATAMENTO DE ERROS: + - Try-catch na função test_system() + - Imprimir traceback completo em caso de erro + - Sempre fechar conexão no bloco finally + +REQUISITOS TÉCNICOS: + +- Imports: asyncio, json, MCPChatClient +- Função async test_system() +- Usar await asyncio.sleep(1) entre testes +- Shebang: #!/usr/bin/env python3 +- Docstrings em português +- Bloco if __name__ == "__main__" + +ESTRUTURA DO CÓDIGO: + +1. Shebang e docstring +2. Imports +3. Função async test_system() +4. Bloco if __name__ == "__main__" + +EXEMPLO DE LOOP DE TESTES: +```python +for i, test_case in enumerate(test_cases, 1): + print(f"\n[Teste {i}/{len(test_cases)}] {test_case['descricao']}") + print("-" * 60) + print(f"👤 Usuário: {test_case['mensagem']}") + + response = await client.chat(test_case['mensagem']) + + print(f"🤖 Assistente: {response}") + print("=" * 60) + + await asyncio.sleep(1) +``` + +Por favor, gere o código completo do arquivo test_system.py seguindo todas estas especificações. +``` + +--- + +## ✅ Resultado Esperado + +Você deve receber um arquivo Python completo (~100 linhas) com: + +**Estrutura:** +```python +#!/usr/bin/env python3 +""" +Script de teste automatizado para o sistema MCP... +""" + +import asyncio +import json +from mcp_client import MCPChatClient + +async def test_system(): + # Implementação dos testes... + +if __name__ == "__main__": + asyncio.run(test_system()) +``` + +**Características:** +- ✅ 8 casos de teste definidos +- ✅ Formatação visual clara +- ✅ Numeração de testes (1/8, 2/8, etc.) +- ✅ Pausas entre testes +- ✅ Resumo final +- ✅ Tratamento de erros +- ✅ Bloco finally para cleanup + +--- + +## 🧪 Como Validar + +Salve o código gerado em `mcp_project/test_system.py` e verifique: + +```bash +# 1. Verificar sintaxe Python +python -m py_compile test_system.py + +# 2. Contar linhas +wc -l test_system.py + +# 3. Verificar estrutura +grep -E "test_cases|async def test_system" test_system.py +``` + +**Saída esperada:** +``` +97 test_system.py +``` + +**Verificação manual:** +- [ ] Arquivo tem shebang `#!/usr/bin/env python3` +- [ ] Import de MCPChatClient presente +- [ ] Lista test_cases com 8 casos +- [ ] Função async test_system() +- [ ] Loop iterando sobre test_cases +- [ ] Formatação com emojis e separadores +- [ ] Resumo final com checkmarks +- [ ] Bloco try-except-finally + +--- + +## 📝 Notas + +- Os testes não executam ainda (dependências não instaladas) +- Cada teste espera 1 segundo para não sobrecarregar a API +- O resumo final é apenas visual, não valida resultados +- Em produção, considere usar pytest para assertions + +--- + +## 🔧 Troubleshooting + +**Erro: "Cannot import MCPChatClient"** +- Verifique se mcp_client.py está no mesmo diretório +- Confirme que não há erros de sintaxe em mcp_client.py + +**Testes muito lentos:** +- Ajuste o asyncio.sleep(1) para valores menores +- Considere executar testes em paralelo (avançado) + +--- + +## ➡️ Próximo Passo + +Após validar os testes, prossiga para: **`04-REQUIREMENTS.md`** diff --git a/GenAI/mcp/sample1/vibe/04-REQUIREMENTS.md b/GenAI/mcp/sample1/vibe/04-REQUIREMENTS.md new file mode 100644 index 0000000..8bec0dc --- /dev/null +++ b/GenAI/mcp/sample1/vibe/04-REQUIREMENTS.md @@ -0,0 +1,75 @@ +# 04 - Arquivo de Dependências + +## 🎯 Objetivo + +Gerar o arquivo `requirements.txt` com as dependências necessárias para o projeto. + +## 📋 Contexto + +O arquivo requirements.txt lista todas as bibliotecas Python necessárias com suas versões específicas para garantir reprodutibilidade. + +## 🔧 Especificações Técnicas + +- **Formato:** Padrão pip (package==version) +- **Dependências:** mcp, openai +- **Versões:** Fixas para garantir compatibilidade + +--- + +## 💬 PROMPT COMPLETO + +``` +Crie um arquivo chamado "requirements.txt" para um projeto Python que usa: +- Model Context Protocol (MCP) versão 1.23.1 +- OpenAI SDK versão 2.8.1 + +O arquivo deve seguir o formato padrão do pip (package==version). +Liste apenas estas duas dependências, uma por linha. +``` + +--- + +## ✅ Resultado Esperado + +Você deve receber um arquivo de texto simples: + +``` +mcp==1.23.1 +openai==2.8.1 +``` + +--- + +## 🧪 Como Validar + +Salve o conteúdo em `mcp_project/requirements.txt` e verifique: + +```bash +# 1. Verificar conteúdo +cat requirements.txt + +# 2. Contar linhas (deve ser 2) +wc -l requirements.txt + +# 3. Instalar dependências (com ambiente virtual ativado) +pip install -r requirements.txt +``` + +**Saída esperada da instalação:** +``` +Successfully installed mcp-1.23.1 openai-2.8.1 [e outras dependências transitivas] +``` + +--- + +## 📝 Notas + +- As versões especificadas foram testadas e são compatíveis +- Dependências transitivas serão instaladas automaticamente +- Em produção, considere usar `pip freeze > requirements.txt` + +--- + +## ➡️ Próximo Passo + +Após criar requirements.txt, prossiga para: **`05-RUN-SCRIPT.md`** diff --git a/GenAI/mcp/sample1/vibe/05-RUN-SCRIPT.md b/GenAI/mcp/sample1/vibe/05-RUN-SCRIPT.md new file mode 100644 index 0000000..1373c7c --- /dev/null +++ b/GenAI/mcp/sample1/vibe/05-RUN-SCRIPT.md @@ -0,0 +1,163 @@ +# 05 - Script de Inicialização Rápida + +## 🎯 Objetivo + +Gerar o arquivo `run.sh` que automatiza a inicialização do sistema MCP. + +## 📋 Contexto + +O script bash facilita a execução do projeto, verificando dependências e ativando o ambiente virtual automaticamente. + +## 🔧 Especificações Técnicas + +- **Linguagem:** Bash script +- **Funcionalidades:** Verificação de ambiente, instalação de deps, execução +- **Permissões:** Executável (chmod +x) + +--- + +## 💬 PROMPT COMPLETO + +``` +Crie um script bash chamado "run.sh" para iniciar um projeto Python MCP. + +REQUISITOS: + +1. CABEÇALHO: + - Shebang: #!/bin/bash + - Comentário descritivo + +2. BANNER INICIAL: + Imprimir: + ``` + ========================================== + Sistema MCP - Operações Matemáticas + ========================================== + ``` + +3. VERIFICAÇÕES: + - Verificar se diretório "venv" existe + - Se não existir, imprimir erro e instruções + - Exit code 1 se falhar + +4. ATIVAÇÃO DO AMBIENTE VIRTUAL: + - source venv/bin/activate + +5. VERIFICAÇÃO DE DEPENDÊNCIAS: + - Tentar importar módulo "mcp" em Python + - Se falhar, instalar dependências: pip install -r requirements.txt + +6. EXECUÇÃO: + - Imprimir "🚀 Iniciando cliente MCP..." + - Executar: python mcp_client.py + +FORMATO DE MENSAGENS: +- Usar emojis: ❌ para erro, 📦 para instalação, 🚀 para execução +- Linhas em branco para separação visual + +EXEMPLO DE VERIFICAÇÃO: +```bash +if [ ! -d "venv" ]; then + echo "❌ Ambiente virtual não encontrado!" + echo " Execute: python3.11 -m venv venv" + exit 1 +fi +``` + +Por favor, gere o script bash completo seguindo estas especificações. +``` + +--- + +## ✅ Resultado Esperado + +Você deve receber um script bash (~25 linhas): + +```bash +#!/bin/bash +# Script de inicialização rápida do sistema MCP + +echo "==========================================" +echo " Sistema MCP - Operações Matemáticas" +echo "==========================================" +echo "" + +# Verificar se ambiente virtual existe +if [ ! -d "venv" ]; then + echo "❌ Ambiente virtual não encontrado!" + echo " Execute: python3.11 -m venv venv" + exit 1 +fi + +# Ativar ambiente virtual +source venv/bin/activate + +# Verificar se dependências estão instaladas +if ! python -c "import mcp" 2>/dev/null; then + echo "📦 Instalando dependências..." + pip install -r requirements.txt + echo "" +fi + +# Executar cliente MCP +echo "🚀 Iniciando cliente MCP..." +echo "" +python mcp_client.py +``` + +--- + +## 🧪 Como Validar + +Salve o script em `mcp_project/run.sh` e execute: + +```bash +# 1. Tornar executável +chmod +x run.sh + +# 2. Verificar sintaxe +bash -n run.sh + +# 3. Testar execução (com venv criado) +./run.sh +``` + +**Saída esperada:** +``` +========================================== + Sistema MCP - Operações Matemáticas +========================================== + +🚀 Iniciando cliente MCP... + +[Chat interface inicia] +``` + +--- + +## 📝 Notas + +- O script assume que você está no diretório do projeto +- Funciona em Linux/Mac (no Windows, use Git Bash ou WSL) +- Instala dependências automaticamente se necessário +- Requer que o ambiente virtual já exista + +--- + +## 🔧 Troubleshooting + +**Erro: "Permission denied"** +```bash +chmod +x run.sh +``` + +**Erro: "venv not found"** +```bash +python3.11 -m venv venv +``` + +--- + +## ➡️ Próximo Passo + +Após criar o script, prossiga para: **`06-README-DOC.md`** diff --git a/GenAI/mcp/sample1/vibe/06-README-DOC.md b/GenAI/mcp/sample1/vibe/06-README-DOC.md new file mode 100644 index 0000000..24ad5bf --- /dev/null +++ b/GenAI/mcp/sample1/vibe/06-README-DOC.md @@ -0,0 +1,243 @@ +# 06 - Documentação Principal (README.md) + +## 🎯 Objetivo + +Gerar o arquivo `README.md` com documentação completa do projeto incluindo arquitetura, funcionalidades, exemplos e guias de uso. + +## 📋 Contexto + +O README é a documentação principal do projeto, deve ser abrangente mas organizada, com exemplos práticos e informações técnicas detalhadas. + +## 🔧 Especificações Técnicas + +- **Formato:** Markdown (GitHub-flavored) +- **Tamanho:** ~470 linhas +- **Seções:** 20+ seções organizadas +- **Estilo:** Profissional com emojis para navegação + +--- + +## 💬 PROMPT COMPLETO + +``` +Você é um technical writer especialista em documentação de projetos de software. + +TAREFA: +Crie um arquivo README.md completo e profissional para o projeto "Sistema MCP com AI Agent - Calculadora Inteligente v2.0". + +ESTRUTURA DO DOCUMENTO (seguir esta ordem): + +1. TÍTULO E INTRODUÇÃO + # Sistema MCP com AI Agent - Calculadora Inteligente + + Parágrafo introdutório explicando o projeto. + +2. VISÃO GERAL (## 📋 Visão Geral) + - Descrição dos 3 componentes principais + - Lista numerada + +3. FUNCIONALIDADES PRINCIPAIS (## 🎯 Funcionalidades Principais) + + ### ✨ Interpretação Inteligente de Operações + - Explicar como o agente interpreta operações + - Exemplos de perguntas em linguagem natural + + ### 🛡️ Tratamento Robusto de Erros + - Lista de validações implementadas + + ### 🧮 4 Operações Matemáticas + - Lista das 4 operações + +4. ARQUITETURA (## 🏗️ Arquitetura) + - Diagrama ASCII art mostrando fluxo + - Descrição do fluxo de execução (9 passos) + +5. TECNOLOGIAS UTILIZADAS (## 🔧 Tecnologias Utilizadas) + - Lista com bullet points + +6. ESTRUTURA DO PROJETO (## 📦 Estrutura do Projeto) + - Árvore de diretórios em código markdown + +7. INSTALAÇÃO (## 🚀 Instalação) + - Passos numerados com blocos de código bash + +8. USO (## 💻 Uso) + - Modo Interativo + - Exemplos de Interação (4 exemplos detalhados): + * Exemplo 1: Soma em Linguagem Natural + * Exemplo 2: Divisão + * Exemplo 3: Erro - Divisão por Zero + * Exemplo 4: Operação Não Implementada + - Modo Teste Automatizado + +9. COMPONENTES DETALHADOS (## 📝 Componentes Detalhados) + + ### 1. Servidor MCP + - Descrição de cada ferramenta (soma, subtracao, multiplicacao, divisao) + - Formato de retorno JSON para cada uma + - Exemplo de erro (divisão por zero) + - Operações não implementadas + + ### 2. Cliente MCP + - Conexão com Servidor MCP + - Integração com LLM (configurações) + - Prompt do Sistema (incluir o prompt completo) + - Loop de Chat + + ### 3. Script de Teste + - Descrição dos 8 casos de teste + +10. CONFIGURAÇÃO DE SEGURANÇA (## 🔐 Configuração de Segurança) + - Aviso sobre API key hardcoded + - 3 recomendações para produção + +11. TESTES (## 🧪 Testes) + - Teste Manual (passos) + - Teste Automatizado (comando + lista de verificações) + +12. TROUBLESHOOTING (## 🐛 Troubleshooting) + - 4 problemas comuns com soluções + +13. REFERÊNCIAS (## 📚 Referências) + - Links para documentação externa + +14. EXTENSÕES FUTURAS (## 🤝 Extensões Futuras) + - Novas Operações + - Melhorias + - Testes + +15. LICENÇA (## 📄 Licença) + +16. CARACTERÍSTICAS PRINCIPAIS (## ✨ Características Principais) + - Lista com checkmarks (✅) + +17. RODAPÉ + --- + **Desenvolvido como demonstração de AI Agent com MCP e interpretação inteligente de operações** + +REQUISITOS DE FORMATAÇÃO: + +- Usar emojis nos títulos de seção (📋, 🎯, 🏗️, etc.) +- Blocos de código com syntax highlighting (```python, ```bash, ```json) +- Listas com bullet points ou numeradas conforme apropriado +- Tabelas onde fizer sentido +- Negrito para termos importantes +- Links em formato markdown [texto](url) + +CONTEÚDO ESPECÍFICO A INCLUIR: + +API Configuration: +- URL Base: https://api.xptoai.com.br/genai/grokcode/v1 +- API Key: biasb986lk657fsdv6d3543vs5b65s7v373sd321vsdv4sdv34bv3f4hb5f4j6mn546tu +- Modelo: grok-2-1212 + +Dependências: +- mcp==1.23.1 +- openai==2.8.1 + +Arquivos e Linhas: +- mcp_server.py (253 linhas) +- mcp_client.py (294 linhas) +- test_system.py (97 linhas) +- README.md (472 linhas) +- QUICKSTART.md (202 linhas) +- CHANGELOG.md (128 linhas) + +DIAGRAMA ASCII DA ARQUITETURA: +``` +┌─────────────┐ ┌──────────────────┐ ┌──────────────┐ +│ Usuário │ ◄─────► │ Cliente MCP │ ◄─────► │ Servidor MCP │ +│ │ Chat │ + LLM │ stdio │ (4 Tools) │ +│ │ │ (Interpretação) │ │ │ +└─────────────┘ └──────────────────┘ └──────────────┘ + │ + ▼ + ┌──────────────┐ + │ LLM API │ + │ (Grok Code) │ + └──────────────┘ +``` + +EXEMPLOS DE INTERAÇÃO (incluir blocos formatados): + +Exemplo 1 - Soma em Linguagem Natural: +``` +👤 Você: Eu tenho 25 maçãs e ganhei mais 13, quantas tenho agora? + +🔧 Executando ferramenta: soma + Argumentos: {'numero1': 25, 'numero2': 13} + ✓ Resultado: 38 + +🤖 Assistente: Você tinha 25 maçãs e ganhou mais 13, então agora tem 38 maçãs no total! +``` + +[Incluir mais 3 exemplos similares] + +Por favor, gere o documento README.md completo seguindo esta estrutura e especificações. +O documento deve ter aproximadamente 470 linhas e ser profissional, informativo e bem organizado. +``` + +--- + +## ✅ Resultado Esperado + +Você deve receber um documento Markdown completo (~470 linhas) com: + +**Características:** +- ✅ Estrutura bem organizada com 16+ seções +- ✅ Emojis nos títulos para navegação visual +- ✅ Blocos de código com syntax highlighting +- ✅ Exemplos práticos de uso +- ✅ Diagrama ASCII da arquitetura +- ✅ Informações técnicas detalhadas +- ✅ Guias de instalação e troubleshooting +- ✅ Links para referências externas + +--- + +## 🧪 Como Validar + +Salve o documento em `mcp_project/README.md` e verifique: + +```bash +# 1. Contar linhas +wc -l README.md + +# 2. Verificar estrutura markdown +grep "^#" README.md | head -20 + +# 3. Visualizar (se tiver markdown viewer) +mdless README.md +# ou +grip README.md +``` + +**Saída esperada:** +``` +472 README.md +``` + +**Verificação manual:** +- [ ] Título principal presente +- [ ] Seções organizadas com emojis +- [ ] Diagrama ASCII incluído +- [ ] 4 exemplos de interação +- [ ] Blocos de código formatados +- [ ] Informações de API incluídas +- [ ] Seção de troubleshooting +- [ ] Links para referências + +--- + +## 📝 Notas + +- O README é extenso mas bem estruturado +- Use um visualizador Markdown para melhor experiência +- Em plataformas como GitHub, será renderizado automaticamente +- Pode ser dividido em múltiplas chamadas ao LLM se necessário + +--- + +## ➡️ Próximo Passo + +Após criar o README, prossiga para: **`07-QUICKSTART-DOC.md`** diff --git a/GenAI/mcp/sample1/vibe/07-QUICKSTART-DOC.md b/GenAI/mcp/sample1/vibe/07-QUICKSTART-DOC.md new file mode 100644 index 0000000..e0184d1 --- /dev/null +++ b/GenAI/mcp/sample1/vibe/07-QUICKSTART-DOC.md @@ -0,0 +1,181 @@ +# 07 - Guia Rápido (QUICKSTART.md) + +## 🎯 Objetivo + +Gerar o arquivo `QUICKSTART.md` com um guia conciso de início rápido focado em fazer o usuário começar a usar o sistema em minutos. + +## 📋 Contexto + +O QUICKSTART é uma versão simplificada do README, focada em ação rápida com exemplos práticos e comandos prontos para copiar e colar. + +## 🔧 Especificações Técnicas + +- **Formato:** Markdown +- **Tamanho:** ~200 linhas +- **Foco:** Praticidade e velocidade +- **Tom:** Direto e objetivo + +--- + +## 💬 PROMPT COMPLETO + +``` +Você é um technical writer especialista em documentação de início rápido. + +TAREFA: +Crie um arquivo QUICKSTART.md conciso e prático para o projeto "Sistema MCP - Calculadora Inteligente". + +ESTRUTURA DO DOCUMENTO: + +1. TÍTULO + # Guia Rápido - Sistema MCP com Calculadora Inteligente + +2. INÍCIO RÁPIDO (## 🚀 Início Rápido (3 passos)) + Passos numerados com comandos bash: + ### 1. Criar Ambiente Virtual + ### 2. Instalar Dependências + ### 3. Executar o Sistema (Opção A e B) + +3. COMO USAR (## 💬 Como Usar) + Explicar que o sistema interpreta automaticamente. + + ### Exemplos de Perguntas + + #### Soma + - 3 exemplos de perguntas + + #### Subtração + - 3 exemplos + + #### Multiplicação + - 3 exemplos + + #### Divisão + - 3 exemplos + +4. FUNCIONALIDADES (## 🎯 Funcionalidades) + Lista com checkmarks (✅) + +5. TESTAR O SISTEMA (## 🧪 Testar o Sistema) + Comando e lista de validações + +6. EXEMPLO DE INTERAÇÃO COMPLETA (## 📋 Exemplo de Interação Completa) + Bloco de código mostrando uma sessão completa: + - Soma em linguagem natural + - Divisão + - Erro de divisão por zero + - Operação não implementada + +7. COMANDOS ÚTEIS (## 🛠️ Comandos Úteis) + Lista de comandos com descrições: + - Ativar ambiente virtual + - Desativar ambiente virtual + - Reinstalar dependências + - Verificar instalação + - Executar testes + +8. PROBLEMAS COMUNS (## ❓ Problemas Comuns) + 4-5 problemas com soluções rápidas + +9. DICAS DE USO (## 🎓 Dicas de Uso) + 5 dicas numeradas + +10. DOCUMENTAÇÃO COMPLETA (## 📚 Documentação Completa) + Link para README.md + +11. OPERAÇÕES DISPONÍVEIS (## 🔑 Operações Disponíveis) + Tabela com 3 colunas: + | Operação | Exemplos de Perguntas | + + 4 linhas (uma para cada operação) + +12. RODAPÉ + --- + **Sistema pronto para uso! Divirta-se calculando! 🧮✨** + +REQUISITOS DE FORMATAÇÃO: + +- Usar emojis nos títulos +- Blocos de código bash com ```bash +- Comandos prontos para copiar +- Listas com bullet points ou numeradas +- Tabela markdown para operações +- Negrito para comandos importantes + +CONTEÚDO ESPECÍFICO: + +Comandos de instalação: +```bash +cd mcp_project +python3.11 -m venv venv +source venv/bin/activate +pip install -r requirements.txt +``` + +Comandos de execução: +```bash +./run.sh +# ou +python mcp_client.py +``` + +Comando de teste: +```bash +python test_system.py +``` + +Exemplo de interação completa (incluir 4 interações): +1. Soma: "Eu tenho 25 maçãs e ganhei mais 13" → 38 +2. Divisão: "Divida 100 por 4" → 25 +3. Erro: "Divida 10 por 0" → Erro tratado +4. Não implementada: "Calcule 5 ao quadrado" → Limitação informada + +Tabela de operações: +| Operação | Exemplos de Perguntas | +|----------|----------------------| +| **Soma** | "15 mais 7", "Some 10 com 5", "Quanto é 3 + 8?" | +| **Subtração** | "20 menos 5", "Subtraia 7 de 15", "Quanto é 30 - 12?" | +| **Multiplicação** | "8 vezes 6", "Multiplique 5 por 9", "Quanto é 7 × 4?" | +| **Divisão** | "100 dividido por 4", "Divida 50 por 2", "Quanto é 81 ÷ 9?" | + +Por favor, gere o documento QUICKSTART.md completo seguindo esta estrutura. +O documento deve ter aproximadamente 200 linhas e ser direto ao ponto. +``` + +--- + +## ✅ Resultado Esperado + +Você deve receber um documento Markdown (~200 linhas) com: + +**Características:** +- ✅ Guia de 3 passos para começar +- ✅ Exemplos práticos de perguntas +- ✅ Comandos prontos para copiar +- ✅ Exemplo de interação completa +- ✅ Tabela de operações disponíveis +- ✅ Troubleshooting rápido +- ✅ Dicas de uso + +--- + +## 🧪 Como Validar + +```bash +# 1. Contar linhas +wc -l QUICKSTART.md + +# 2. Verificar estrutura +grep "^#" QUICKSTART.md +``` + +**Saída esperada:** +``` +202 QUICKSTART.md +``` + +--- + +## ➡️ Próximo Passo + +Prossiga para: **`08-CHANGELOG-DOC.md`** diff --git a/GenAI/mcp/sample1/vibe/08-CHANGELOG-DOC.md b/GenAI/mcp/sample1/vibe/08-CHANGELOG-DOC.md new file mode 100644 index 0000000..e1312e9 --- /dev/null +++ b/GenAI/mcp/sample1/vibe/08-CHANGELOG-DOC.md @@ -0,0 +1,208 @@ +# 08 - Histórico de Mudanças (CHANGELOG.md) + +## 🎯 Objetivo + +Gerar o arquivo `CHANGELOG.md` documentando a evolução do projeto da versão 1.0 para 2.0. + +## 📋 Contexto + +O CHANGELOG segue o formato "Keep a Changelog" e documenta todas as mudanças significativas entre versões. + +## 🔧 Especificações Técnicas + +- **Formato:** Keep a Changelog +- **Versionamento:** Semantic Versioning +- **Tamanho:** ~130 linhas + +--- + +## 💬 PROMPT COMPLETO + +``` +Você é um technical writer especialista em documentação de mudanças de software. + +TAREFA: +Crie um arquivo CHANGELOG.md seguindo o formato "Keep a Changelog" para documentar a evolução do projeto MCP de v1.0 para v2.0. + +ESTRUTURA DO DOCUMENTO: + +1. TÍTULO + # Changelog + + Parágrafo introdutório. + +2. VERSÃO 2.0.0 (## [2.0.0] - 2024-12-03) + + ### 🎉 Novas Funcionalidades + + #### Interpretação Inteligente de Operações + - Descrição da funcionalidade + - Exemplos de uso + + #### Novas Operações Matemáticas + - Subtração + - Divisão (com detalhes especiais) + + ### 🛡️ Tratamento de Erros + + #### Validações Implementadas + - Lista de validações + + #### Mensagens de Erro Estruturadas + - Descrição do formato JSON + + ### 📊 Melhorias no Servidor MCP + + #### Respostas Enriquecidas + - Campos retornados + + #### Divisão Especial + - Campos adicionais + + ### 🧪 Testes Expandidos + + #### Novos Casos de Teste + - Lista dos 8 casos + + ### 📝 Documentação + + #### Atualizações + - Arquivos atualizados + + #### Novos Exemplos + - Tipos de exemplos + + ### 🔧 Melhorias no Cliente MCP + + #### Prompt do Sistema Aprimorado + - Instruções adicionadas + + #### Feedback Visual + - Melhorias na interface + +3. VERSÃO 1.0.0 (## [1.0.0] - 2024-12-03) + + ### 🎉 Lançamento Inicial + + #### Funcionalidades Básicas + - Lista de funcionalidades + + #### Arquitetura + - Descrição básica + + #### Documentação + - Arquivos iniciais + +4. FORMATO (## Formato) + Explicação sobre Keep a Changelog e Semantic Versioning + + ### Tipos de Mudanças + Lista de categorias com emojis + +CONTEÚDO ESPECÍFICO PARA V2.0: + +Novas Funcionalidades: +- Interpretação inteligente de operações +- Subtração e divisão +- Tratamento de divisão por zero +- Operações não implementadas + +Validações: +- Divisão por zero +- Parâmetros faltantes +- Validação de tipos +- Operações não implementadas + +Testes (8 casos): +1. Soma +2. Subtração (novo) +3. Multiplicação +4. Divisão (novo) +5. Divisão por zero (novo) +6. Operação não implementada (novo) +7. Linguagem natural - soma (novo) +8. Linguagem natural - subtração (novo) + +Documentação atualizada: +- README.md: Completamente reescrito +- QUICKSTART.md: Atualizado com exemplos +- CHANGELOG.md: Criado + +Melhorias no cliente: +- Prompt do sistema aprimorado +- Feedback visual (✓ e ⚠️) +- Mensagens com emojis + +CONTEÚDO ESPECÍFICO PARA V1.0: + +Funcionalidades: +- Servidor MCP com 2 operações (soma, multiplicação) +- Cliente MCP com integração ao LLM +- Chat interativo +- Teste automatizado básico + +Arquitetura: +- Comunicação via stdio +- Integração com LLM via API OpenAI +- Uso de asyncio + +Documentação: +- README.md básico +- QUICKSTART.md +- Script run.sh + +TIPOS DE MUDANÇAS: +- 🎉 Novas Funcionalidades +- 🔧 Alterações +- ❌ Descontinuado +- 🗑️ Removido +- 🐛 Correções +- 🛡️ Segurança + +FORMATO: +Seguir padrão Keep a Changelog: +- Versões em ordem decrescente (mais recente primeiro) +- Data no formato YYYY-MM-DD +- Categorias de mudanças claras +- Descrições concisas mas informativas + +Por favor, gere o documento CHANGELOG.md completo seguindo esta estrutura. +O documento deve ter aproximadamente 130 linhas. +``` + +--- + +## ✅ Resultado Esperado + +Você deve receber um documento Markdown (~130 linhas) com: + +**Características:** +- ✅ Formato Keep a Changelog +- ✅ Versionamento semântico +- ✅ Duas versões documentadas (2.0.0 e 1.0.0) +- ✅ Categorias de mudanças com emojis +- ✅ Descrições detalhadas +- ✅ Seção explicativa sobre o formato + +--- + +## 🧪 Como Validar + +```bash +# 1. Contar linhas +wc -l CHANGELOG.md + +# 2. Verificar estrutura de versões +grep "^## \[" CHANGELOG.md +``` + +**Saída esperada:** +``` +128 CHANGELOG.md +``` + +--- + +## ➡️ Próximo Passo + +Prossiga para: **`09-VALIDATION.md`** diff --git a/GenAI/mcp/sample1/vibe/09-VALIDATION.md b/GenAI/mcp/sample1/vibe/09-VALIDATION.md new file mode 100644 index 0000000..c73b568 --- /dev/null +++ b/GenAI/mcp/sample1/vibe/09-VALIDATION.md @@ -0,0 +1,353 @@ +# 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 + +```bash +# 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 + +```bash +# 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 + +```bash +# 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 +```bash +# 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 +```bash +# 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 +```bash +# Verificar casos de teste +grep -c "descricao" test_system.py +``` + +**Esperado:** 8 (8 casos de teste) + +#### requirements.txt +```bash +# Verificar dependências +cat requirements.txt +``` + +**Esperado:** +``` +mcp==1.23.1 +openai==2.8.1 +``` + +#### run.sh +```bash +# Verificar se é executável +ls -l run.sh | grep -E "^-rwxr" +``` + +**Esperado:** Permissões de execução presentes + +### 🚀 Teste de Instalação + +```bash +# 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 + +```bash +# 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: + +```bash +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:** +```bash +# 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:** +```bash +# 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:** +```bash +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:** + ```bash + ./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** 🎨 diff --git a/GenAI/mcp/sample1/vibe/README.md b/GenAI/mcp/sample1/vibe/README.md index 80c9eb5..30b45a2 100644 --- a/GenAI/mcp/sample1/vibe/README.md +++ b/GenAI/mcp/sample1/vibe/README.md @@ -1 +1,257 @@ -# Vibe Coding +# 🎨 Vibe Coding - Guia de Prompts para Recriar o Projeto MCP v2.0 + +Este diretório contém uma coleção completa de **prompts estruturados** que permitem recriar exatamente o projeto **Sistema MCP com AI Agent - Calculadora Inteligente v2.0** através de interações com um LLM (como Grok Code Fast). + +## 📋 O que é Vibe Coding? + +**Vibe Coding** é uma metodologia de desenvolvimento onde você utiliza prompts bem estruturados e específicos para guiar um LLM na geração de código, documentação e testes. Ao invés de escrever código manualmente, você "programa através de linguagem natural". + +## 🎯 Objetivo + +Permitir que qualquer pessoa recrie este projeto completo submetendo os prompts fornecidos a um LLM, obtendo como resultado exatamente os mesmos arquivos e funcionalidades da versão 2.0. + +## 📂 Estrutura dos Prompts + +Os prompts estão organizados em arquivos separados, cada um focado em gerar um componente específico do projeto: + +``` +vibe-coding-prompts/ +├── README.md # Este arquivo (guia principal) +├── 00-SETUP.md # Prompt para setup inicial do projeto +├── 01-MCP-SERVER.md # Prompt para gerar mcp_server.py +├── 02-MCP-CLIENT.md # Prompt para gerar mcp_client.py +├── 03-TESTS.md # Prompt para gerar test_system.py +├── 04-REQUIREMENTS.md # Prompt para gerar requirements.txt +├── 05-RUN-SCRIPT.md # Prompt para gerar run.sh +├── 06-README-DOC.md # Prompt para gerar README.md +├── 07-QUICKSTART-DOC.md # Prompt para gerar QUICKSTART.md +├── 08-CHANGELOG-DOC.md # Prompt para gerar CHANGELOG.md +└── 09-VALIDATION.md # Prompt para validar o projeto completo +``` + +## 🚀 Como Usar Este Guia + +### Método 1: Sequencial (Recomendado) + +Execute os prompts na ordem numérica (00 → 09) para construir o projeto passo a passo: + +1. **Leia** o arquivo de prompt (ex: `01-MCP-SERVER.md`) +2. **Copie** o prompt completo +3. **Cole** no LLM (Grok Code Fast ou similar) +4. **Salve** o código gerado no arquivo indicado +5. **Repita** para o próximo prompt + +### Método 2: Por Componente + +Se você já tem parte do projeto, pode usar prompts específicos para gerar ou atualizar componentes individuais. + +### Método 3: Validação + +Use o prompt `09-VALIDATION.md` para verificar se o projeto gerado está completo e funcional. + +## 📝 Formato dos Prompts + +Cada arquivo de prompt segue esta estrutura: + +```markdown +# [Título do Componente] + +## 🎯 Objetivo +[Descrição clara do que será gerado] + +## 📋 Contexto +[Informações necessárias sobre o projeto] + +## 🔧 Especificações Técnicas +[Requisitos técnicos detalhados] + +## 💬 PROMPT COMPLETO +[Prompt pronto para copiar e colar no LLM] + +## ✅ Resultado Esperado +[Descrição do arquivo que deve ser gerado] + +## 🧪 Como Validar +[Instruções para testar o componente gerado] +``` + +## 🎓 Pré-requisitos + +Antes de começar, certifique-se de ter: + +- ✅ Acesso a um LLM (Grok Code Fast, GPT-4, Claude, etc.) +- ✅ Python 3.11+ instalado +- ✅ Conhecimento básico de terminal/linha de comando +- ✅ Editor de texto ou IDE + +## 📊 Ordem de Execução Recomendada + +| Ordem | Arquivo | Componente | Tempo Estimado | +|-------|---------|------------|----------------| +| 1 | `00-SETUP.md` | Setup inicial | 2 min | +| 2 | `01-MCP-SERVER.md` | Servidor MCP | 5 min | +| 3 | `02-MCP-CLIENT.md` | Cliente MCP | 5 min | +| 4 | `03-TESTS.md` | Testes automatizados | 3 min | +| 5 | `04-REQUIREMENTS.md` | Dependências | 1 min | +| 6 | `05-RUN-SCRIPT.md` | Script de execução | 2 min | +| 7 | `06-README-DOC.md` | Documentação principal | 3 min | +| 8 | `07-QUICKSTART-DOC.md` | Guia rápido | 2 min | +| 9 | `08-CHANGELOG-DOC.md` | Histórico de mudanças | 2 min | +| 10 | `09-VALIDATION.md` | Validação final | 5 min | + +**Tempo total estimado:** ~30 minutos + +## 🎯 O Que Você Vai Construir + +Ao seguir todos os prompts, você terá um projeto completo com: + +### Funcionalidades +- ✅ Servidor MCP com 4 operações matemáticas (soma, subtração, multiplicação, divisão) +- ✅ Cliente MCP com interpretação inteligente de operações +- ✅ Suporte a linguagem natural ("Eu tenho 25 maçãs e ganhei mais 13") +- ✅ Tratamento robusto de erros (divisão por zero, tipos inválidos) +- ✅ Mensagens educadas para operações não implementadas +- ✅ Interface de chat interativa + +### Arquivos Gerados +- 📄 `mcp_server.py` (253 linhas) - Servidor MCP +- 📄 `mcp_client.py` (294 linhas) - Cliente MCP +- 📄 `test_system.py` (97 linhas) - Testes automatizados +- 📄 `requirements.txt` - Dependências +- 📄 `run.sh` - Script de inicialização +- 📄 `README.md` (472 linhas) - Documentação completa +- 📄 `QUICKSTART.md` (202 linhas) - Guia rápido +- 📄 `CHANGELOG.md` (128 linhas) - Histórico de mudanças + +**Total:** ~1.800 linhas de código e documentação + +## 💡 Dicas para Melhores Resultados + +### 1. Seja Específico com o LLM +- Mencione que você quer código Python 3.11 +- Especifique que está usando MCP e OpenAI SDK +- Indique claramente o nome do arquivo de saída + +### 2. Valide Cada Etapa +- Teste cada componente antes de prosseguir +- Verifique se não há erros de sintaxe +- Confirme que as dependências estão corretas + +### 3. Ajuste Quando Necessário +- Se o LLM gerar código diferente, você pode: + - Pedir para ajustar detalhes específicos + - Usar os prompts como base e iterar + - Combinar partes de diferentes gerações + +### 4. Mantenha o Contexto +- Ao usar prompts sequenciais, mencione o que já foi gerado +- Exemplo: "Já tenho o servidor MCP, agora preciso do cliente..." + +## 🔧 Configurações Importantes + +### API do LLM + +Os prompts incluem configuração para: +- **URL Base:** `https://api.xptoai.com.br/genai/grokcode/v1` +- **API Key:** `biasb986lk657fsdv6d3543vs5b65s7v373sd321vsdv4sdv34bv3f4hb5f4j6mn546tu` +- **Modelo:** `grok-2-1212` + +⚠️ **Nota:** Em produção, use variáveis de ambiente para credenciais. + +### Dependências + +O projeto requer: +- `mcp==1.23.1` +- `openai==2.8.1` + +## 🧪 Testando o Projeto Gerado + +Após gerar todos os componentes: + +```bash +# 1. Criar ambiente virtual +python3.11 -m venv venv +source venv/bin/activate + +# 2. Instalar dependências +pip install -r requirements.txt + +# 3. Executar testes +python test_system.py + +# 4. Executar chat interativo +python mcp_client.py +``` + +## 📚 Recursos Adicionais + +### Documentação de Referência +- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) +- [OpenAI API](https://platform.openai.com/docs/api-reference) +- [Python asyncio](https://docs.python.org/3/library/asyncio.html) + +### Troubleshooting +Se encontrar problemas: +1. Verifique se todas as dependências estão instaladas +2. Confirme que está usando Python 3.11+ +3. Valide que o ambiente virtual está ativado +4. Revise os logs de erro para identificar o problema + +## 🤝 Contribuindo com Novos Prompts + +Se você criar prompts para estender o projeto (novas operações, features, etc.), considere: +1. Seguir o formato estabelecido +2. Testar o prompt múltiplas vezes +3. Documentar o resultado esperado +4. Incluir exemplos de validação + +## ⚡ Quick Start + +Se você quer começar imediatamente: + +```bash +# 1. Criar diretório do projeto +mkdir mcp_project && cd mcp_project + +# 2. Abrir o primeiro prompt +cat vibe-coding-prompts/00-SETUP.md + +# 3. Copiar o prompt e colar no LLM + +# 4. Seguir as instruções geradas + +# 5. Repetir para os próximos prompts +``` + +## ✨ Vantagens do Vibe Coding + +- 🚀 **Velocidade:** Gere código completo em minutos +- 🎯 **Precisão:** Prompts estruturados garantem consistência +- 📚 **Aprendizado:** Entenda o código gerado estudando os prompts +- 🔄 **Reprodutibilidade:** Recrie o projeto quantas vezes quiser +- 🛠️ **Customização:** Ajuste prompts para suas necessidades + +## 📖 Próximos Passos + +1. **Leia** este README completamente +2. **Prepare** seu ambiente (Python, LLM, editor) +3. **Comece** pelo prompt `00-SETUP.md` +4. **Execute** os prompts sequencialmente +5. **Teste** cada componente gerado +6. **Valide** o projeto final com `09-VALIDATION.md` + +--- + +**Pronto para começar?** Abra o arquivo `00-SETUP.md` e inicie sua jornada de Vibe Coding! 🚀 + +--- + +## 📞 Suporte + +Se tiver dúvidas ou problemas: +1. Revise a seção de troubleshooting +2. Verifique se seguiu todos os passos +3. Consulte a documentação de referência +4. Ajuste os prompts conforme necessário + +**Boa codificação vibrante!** ✨🎨