# 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 = "sua chave de API para o endpoint de serviço do LLM"
```

### Erro: "Model not found"

Ajuste o nome do modelo em `mcp_client.py` se necessário:
```python
MODEL_NAME = "grokcode"  # 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**