mcloh/oci_tips
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add files via upload

Browse Source
This commit is contained in:
Marcos Lohmann
2025-12-03 11:49:34 -03:00
committed by GitHub
parent 3080d62b7d
commit fb28005f13
11 changed files with 2321 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

105
GenAI/mcp/sample1/vibe/00-SETUP.md Normal file
View File

@@ -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`**

210
GenAI/mcp/sample1/vibe/01-MCP-SERVER.md Normal file
View File

@@ -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`**

262
GenAI/mcp/sample1/vibe/02-MCP-CLIENT.md Normal file
View File

@@ -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`**

264
GenAI/mcp/sample1/vibe/03-TESTS.md Normal file
View File

@@ -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`**

75
GenAI/mcp/sample1/vibe/04-REQUIREMENTS.md Normal file
View File

@@ -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`**

163
GenAI/mcp/sample1/vibe/05-RUN-SCRIPT.md Normal file
View File

@@ -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`**

243
GenAI/mcp/sample1/vibe/06-README-DOC.md Normal file
View File

@@ -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`**

181
GenAI/mcp/sample1/vibe/07-QUICKSTART-DOC.md Normal file
View File

@@ -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`**

208
GenAI/mcp/sample1/vibe/08-CHANGELOG-DOC.md Normal file
View File

@@ -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`**

353
GenAI/mcp/sample1/vibe/09-VALIDATION.md Normal file
View File

@@ -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** 🎨

258
GenAI/mcp/sample1/vibe/README.md
View File

@@ -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!** ✨🎨