Add files via upload
This commit is contained in:
Marcos Lohmann
105
GenAI/mcp/sample1/vibe/00-SETUP.md
Normal file
105
GenAI/mcp/sample1/vibe/00-SETUP.md
Normal 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
210
GenAI/mcp/sample1/vibe/01-MCP-SERVER.md
Normal 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
262
GenAI/mcp/sample1/vibe/02-MCP-CLIENT.md
Normal 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
264
GenAI/mcp/sample1/vibe/03-TESTS.md
Normal 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
75
GenAI/mcp/sample1/vibe/04-REQUIREMENTS.md
Normal 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
163
GenAI/mcp/sample1/vibe/05-RUN-SCRIPT.md
Normal 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
243
GenAI/mcp/sample1/vibe/06-README-DOC.md
Normal 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
181
GenAI/mcp/sample1/vibe/07-QUICKSTART-DOC.md
Normal 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
208
GenAI/mcp/sample1/vibe/08-CHANGELOG-DOC.md
Normal 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
353
GenAI/mcp/sample1/vibe/09-VALIDATION.md
Normal 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** 🎨
|
||||
@@ -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!** ✨🎨
|
||||
|
||||
Reference in New Issue
Block a user