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:05:21 -03:00
committed by GitHub
parent 8e3042962c
commit cbf0796e2e
7 changed files with 1349 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

473
GenAI/mcp/sample1/README.md
View File

@@ -1 +1,472 @@
# exemplo de servidor e cliente MCP
# Sistema MCP com AI Agent - Calculadora Inteligente
Este projeto implementa um **servidor MCP (Model Context Protocol)** e um **cliente MCP** em Python que utiliza um LLM para interpretar operações matemáticas solicitadas pelo usuário em linguagem natural e executá-las através de tool calls.
## 📋 Visão Geral
O sistema é composto por três componentes principais:
1. **Servidor MCP** (`mcp_server.py`): Expõe 4 ferramentas matemáticas (soma, subtração, multiplicação e divisão) através do protocolo MCP
2. **Cliente MCP** (`mcp_client.py`): Interface de chat que conecta o usuário ao LLM e ao servidor MCP
3. **Script de Teste** (`test_system.py`): Testa automaticamente todas as operações e casos de erro
## 🎯 Funcionalidades Principais
### ✨ Interpretação Inteligente de Operações
O agente **interpreta automaticamente** qual operação matemática o usuário deseja realizar através de linguagem natural:
- **"Quanto é 15 mais 7?"** → Executa soma
- **"Subtraia 5 de 20"** → Executa subtração
- **"Multiplique 8 por 6"** → Executa multiplicação
- **"Divida 100 por 4"** → Executa divisão
- **"Eu tenho 25 maçãs e ganhei mais 13"** → Interpreta como soma e calcula
### 🛡️ Tratamento Robusto de Erros
- **Divisão por zero**: Detectada e tratada com mensagem educada
- **Operações não implementadas**: Informa que apenas as 4 operações básicas estão disponíveis
- **Validação de tipos**: Garante que os números sejam inteiros
- **Parâmetros faltantes**: Verifica se ambos os números foram fornecidos
### 🧮 4 Operações Matemáticas
1. **Soma** (`soma`): Adição de dois números inteiros
2. **Subtração** (`subtracao`): Subtração de dois números inteiros
3. **Multiplicação** (`multiplicacao`): Multiplicação de dois números inteiros
4. **Divisão** (`divisao`): Divisão de dois números (retorna float)
## 🏗️ Arquitetura
```
┌─────────────┐ ┌──────────────────┐ ┌──────────────┐
│ Usuário │ ◄─────► │ Cliente MCP │ ◄─────► │ Servidor MCP │
│ │ Chat │ + LLM │ stdio │ (4 Tools) │
│ │ │ (Interpretação) │ │ │
└─────────────┘ └──────────────────┘ └──────────────┘
│
▼
┌──────────────┐
│ LLM API │
│ (Grok Code) │
└──────────────┘
```
### Fluxo de Execução
1. **Usuário** envia mensagem em linguagem natural (ex: "Quanto é 15 mais 7?")
2. **Cliente MCP** envia mensagem para o LLM
3. **LLM** interpreta a operação desejada e identifica os números
4. **LLM** faz tool call para a ferramenta apropriada (ex: `soma`)
5. **Cliente MCP** executa a ferramenta no **Servidor MCP**
6. **Servidor MCP** valida parâmetros e retorna resultado ou erro
7. **Cliente MCP** envia resultado de volta ao LLM
8. **LLM** gera resposta generativa e amigável
9. **Usuário** recebe resposta final
## 🔧 Tecnologias Utilizadas
- **Python 3.11**: Linguagem de programação
- **MCP (Model Context Protocol)**: Protocolo para comunicação entre cliente e servidor
- **OpenAI SDK**: Cliente para comunicação com LLM compatível com API OpenAI
- **LLM**: Grok Code via API compatível com OpenAI
- **asyncio**: Programação assíncrona
## 📦 Estrutura do Projeto
```
mcp_project/
├── venv/ # Ambiente virtual Python
├── mcp_server.py # Servidor MCP com 4 ferramentas matemáticas
├── mcp_client.py # Cliente MCP com interpretação inteligente
├── test_system.py # Script de teste automatizado completo
├── requirements.txt # Dependências do projeto
├── run.sh # Script de inicialização rápida
├── README.md # Esta documentação
└── QUICKSTART.md # Guia rápido de início
```
## 🚀 Instalação
### 1. Criar Ambiente Virtual
```bash
cd mcp_project
python3.11 -m venv venv
source venv/bin/activate
```
### 2. Instalar Dependências
```bash
pip install -r requirements.txt
```
## 💻 Uso
### Modo Interativo (Chat com Usuário)
Execute o cliente MCP para iniciar uma sessão de chat interativa:
```bash
source venv/bin/activate
python mcp_client.py
```
Ou use o script de inicialização rápida:
```bash
./run.sh
```
### Exemplos de Interação
#### 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!
```
#### Exemplo 2: Divisão
```
👤 Você: Divida 100 por 4
🔧 Executando ferramenta: divisao
Argumentos: {'numero1': 100, 'numero2': 4}
✓ Resultado: 25.0
🤖 Assistente: 100 dividido por 4 é igual a 25!
```
#### Exemplo 3: Erro - Divisão por Zero
```
👤 Você: Divida 10 por 0
🔧 Executando ferramenta: divisao
Argumentos: {'numero1': 10, 'numero2': 0}
⚠️ Erro: Divisão por zero não é permitida
🤖 Assistente: Dividir 10 por 0 é uma operação matematicamente indefinida.
Não posso fazer isso. Mas posso ajudar com outras contas válidas!
```
#### Exemplo 4: Operação Não Implementada
```
👤 Você: Calcule 5 elevado ao quadrado
🤖 Assistente: Desculpe, mas eu só consigo fazer as operações básicas:
soma, subtração, multiplicação e divisão. Potências não estão disponíveis.
Se quiser fazer 5 vezes 5, posso ajudar!
```
### Modo Teste Automatizado
Execute o script de teste para validar todas as operações:
```bash
source venv/bin/activate
python test_system.py
```
O teste valida:
- ✅ Soma
- ✅ Subtração
- ✅ Multiplicação
- ✅ Divisão
- ✅ Tratamento de erro (divisão por zero)
- ✅ Operação não implementada
- ✅ Interpretação de linguagem natural
## 📝 Componentes Detalhados
### 1. Servidor MCP (`mcp_server.py`)
O servidor MCP expõe quatro ferramentas matemáticas com validação completa:
#### Ferramenta: `soma`
Realiza a soma de dois números inteiros.
**Parâmetros:**
- `numero1` (integer): Primeiro número
- `numero2` (integer): Segundo número
**Retorno de Sucesso:**
```json
{
"operacao": "soma",
"numero1": 15,
"numero2": 7,
"resultado": 22,
"expressao": "15 + 7 = 22"
}
```
#### Ferramenta: `subtracao`
Realiza a subtração de dois números inteiros (numero1 - numero2).
**Parâmetros:**
- `numero1` (integer): Minuendo
- `numero2` (integer): Subtraendo
**Retorno de Sucesso:**
```json
{
"operacao": "subtracao",
"numero1": 20,
"numero2": 5,
"resultado": 15,
"expressao": "20 - 5 = 15"
}
```
#### Ferramenta: `multiplicacao`
Realiza a multiplicação de dois números inteiros.
**Parâmetros:**
- `numero1` (integer): Primeiro número
- `numero2` (integer): Segundo número
**Retorno de Sucesso:**
```json
{
"operacao": "multiplicacao",
"numero1": 8,
"numero2": 6,
"resultado": 48,
"expressao": "8 × 6 = 48"
}
```
#### Ferramenta: `divisao`
Realiza a divisão de dois números (numero1 / numero2). Retorna resultado como float.
**Parâmetros:**
- `numero1` (integer): Dividendo
- `numero2` (integer): Divisor
**Retorno de Sucesso:**
```json
{
"operacao": "divisao",
"numero1": 100,
"numero2": 4,
"resultado": 25.0,
"resultado_inteiro": 25,
"resto": 0,
"expressao": "100 ÷ 4 = 25.0"
}
```
**Retorno de Erro (Divisão por Zero):**
```json
{
"error": "Divisão por zero não é permitida",
"operacao": "divisao",
"numero1": 10,
"numero2": 0
}
```
#### Tratamento de Operações Não Implementadas
Se uma ferramenta não reconhecida for chamada:
```json
{
"error": "Operação 'potencia' não está implementada",
"operacao_solicitada": "potencia",
"operacoes_disponiveis": ["soma", "subtracao", "multiplicacao", "divisao"],
"mensagem": "Por favor, utilize uma das operações disponíveis..."
}
```
### 2. Cliente MCP (`mcp_client.py`)
O cliente MCP integra três componentes principais:
#### Conexão com Servidor MCP
Estabelece comunicação via stdio com o servidor MCP e obtém lista de ferramentas disponíveis.
#### Integração com LLM
Utiliza a API do LLM (compatível com OpenAI) para:
- **Interpretar** a operação matemática desejada pelo usuário
- **Identificar** os números na conversa natural
- **Executar** tool calls apropriados
- **Gerar** respostas generativas e amigáveis
**Configuração do LLM:**
- **URL Base**: `https://api.xptoai.com.br/genai/grokcode/v1`
- **Autenticação**: Bearer Token
- **Modelo**: `grok-2-1212`
**Prompt do Sistema:**
O cliente instrui o LLM a:
1. Interpretar qual operação matemática o usuário deseja
2. Identificar os dois números envolvidos
3. Chamar a ferramenta apropriada
4. Apresentar resultados de forma clara
5. Tratar erros educadamente
6. Informar sobre operações não disponíveis
#### Loop de Chat
Mantém histórico de conversação e gerencia o fluxo de mensagens entre usuário, LLM e servidor MCP.
### 3. Script de Teste (`test_system.py`)
Automatiza o teste do sistema com 8 casos de teste:
1. **Soma**: "Quanto é 15 mais 7?"
2. **Subtração**: "Subtraia 5 de 20"
3. **Multiplicação**: "Multiplique 8 por 6"
4. **Divisão**: "Divida 100 por 4"
5. **Divisão por Zero**: "Divida 10 por 0" (erro esperado)
6. **Operação Não Implementada**: "Calcule 5 elevado ao quadrado"
7. **Linguagem Natural - Soma**: "Eu tenho 25 maçãs e ganhei mais 13..."
8. **Linguagem Natural - Subtração**: "Se eu tinha 50 reais e gastei 18..."
## 🔐 Configuração de Segurança
A chave de API está hardcoded no código para fins de demonstração. Em produção, recomenda-se:
1. Usar variáveis de ambiente:
```python
import os
API_KEY = os.getenv("XPTOAI_API_KEY")
```
2. Usar arquivo `.env`:
```bash
echo "XPTOAI_API_KEY=sua_chave_aqui" > .env
```
3. Carregar com `python-dotenv`:
```python
from dotenv import load_dotenv
load_dotenv()
```
## 🧪 Testes
### Teste Manual
1. Execute o cliente: `python mcp_client.py`
2. Digite mensagens em linguagem natural
3. Teste diferentes operações
4. Teste casos de erro (divisão por zero)
5. Teste operações não implementadas
### Teste Automatizado
```bash
python test_system.py
```
Verifica automaticamente:
- ✅ Conexão com servidor MCP
- ✅ Listagem de 4 ferramentas
- ✅ Interpretação de operações
- ✅ Execução de todas as 4 operações
- ✅ Tratamento de divisão por zero
- ✅ Resposta para operações não implementadas
- ✅ Interpretação de linguagem natural
## 🐛 Troubleshooting
### Erro: "Permission denied"
Se encontrar erros de permissão ao instalar pacotes:
```bash
# Use ambiente virtual
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
### Erro: "Connection refused"
Verifique se o servidor MCP está sendo iniciado corretamente pelo cliente.
### Erro: "API Key invalid"
Verifique se a chave de API está correta em `mcp_client.py`:
```python
API_KEY = "biasb986lk657fsdv6d3543vs5b65s7v373sd321vsdv4sdv34bv3f4hb5f4j6mn546tu"
```
### Erro: "Model not found"
Ajuste o nome do modelo em `mcp_client.py` se necessário:
```python
MODEL_NAME = "grok-2-1212" # Ajuste conforme disponível na API
```
### Erro: "Divisão por zero"
Este é um erro esperado e tratado pelo sistema. O agente informará que a operação não é permitida.
## 📚 Referências
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
- [OpenAI API Documentation](https://platform.openai.com/docs/api-reference)
- [Python asyncio](https://docs.python.org/3/library/asyncio.html)
## 🤝 Extensões Futuras
Sugestões para expandir o sistema:
### Novas Operações
- Potenciação
- Raiz quadrada
- Módulo/resto
- Valor absoluto
- Arredondamento
### Melhorias
- Suporte a números decimais (float)
- Histórico de cálculos
- Exportar resultados para arquivo
- Interface gráfica (GUI)
- API REST para integração
### Testes
- Testes unitários com pytest
- Testes de integração
- Testes de carga
- Cobertura de código
## 📄 Licença
Este projeto é fornecido como exemplo educacional.
## ✨ Características Principais
- ✅ **Interpretação Inteligente**: LLM identifica automaticamente a operação desejada
- ✅ **Linguagem Natural**: Entende perguntas contextuais e conversacionais
- ✅ **4 Operações Básicas**: Soma, subtração, multiplicação e divisão
- ✅ **Tratamento de Erros**: Validação completa e mensagens educadas
- ✅ **Operações Não Implementadas**: Informa claramente as limitações
- ✅ **Protocolo MCP**: Comunicação padronizada entre componentes
- ✅ **Assíncrono**: Uso de asyncio para melhor performance
- ✅ **Extensível**: Fácil adicionar novas ferramentas matemáticas
- ✅ **Testável**: Scripts de teste automatizado incluídos
---
**Desenvolvido como demonstração de AI Agent com MCP e interpretação inteligente de operações**