mcp-oracle-server/README.md

MCP (Model Context Protocol) client for Oracle Database with tool discovery - Executable via NPX

# MCP Oracle Server

Servidor MCP (Model Context Protocol) para Oracle Database com suporte a queries SQL, listagem de objetos, código-fonte PL/SQL e métricas de performance.

## 🚀 Características

- ✅ **Protocolo MCP** - Totalmente compatível com Cursor IDE, VS Code e outros
- ✅ **Execução via NPX** - Instalação zero, apenas configure e use
- ✅ **API REST** - Servidor HTTP com endpoints bem definidos
- ✅ **Pool de Conexões** - Gerenciamento eficiente de conexões Oracle
- ✅ **Cache Inteligente** - Resultados em cache por 5 minutos
- ✅ **Rate Limiting** - Proteção contra abuso (60 req/min)
- ✅ **Validação de Segurança** - Apenas SELECT, schemas permitidos
- ✅ **Descoberta de Tools** - Endpoint `/mcp/tools` para IAs

## 📦 Instalação

### Usando NPX (Recomendado)

Não precisa instalar! Configure diretamente no Cursor:

```json
{
  "mcpServers": {
    "oracle-consinco": {
      "command": "npx",
      "args": ["-y", "mcp-oracle-server"],
      "env": {
        "MCP_ORACLE_URL": "http://10.10.11.5:8080"
      }
    }
  }
}
```

### Instalação Local (Desenvolvimento)

```bash
git clone https://github.com/edapinheiro/mcp-oracle.git
cd mcp-oracle
npm install
```

## 🏗️ Arquitetura

O projeto é composto por **2 componentes**:

### 1. Servidor HTTP Python (`mcp_oracle_server.py`)
- Roda no Windows (ou Linux) com acesso ao Oracle
- Gerencia pool de conexões Oracle
- Expõe API REST na porta 8080
- Validações de segurança e cache

### 2. Cliente MCP Node.js (`bin/mcp-oracle.js`)
- Roda localmente via npx
- Conecta ao servidor HTTP
- Implementa protocolo MCP (stdio/pipes)
- Interface com IDEs (Cursor, VS Code, etc)

```
┌─────────────────┐         ┌──────────────────┐         ┌──────────────┐
│   Cursor IDE    │ stdio   │  MCP Client      │  HTTP   │  HTTP Server │
│  (ou VS Code)   │ ◄──────►│  (Node.js/npx)   │ ◄──────►│   (Python)   │
└─────────────────┘         └──────────────────┘         └──────┬───────┘
                                                                  │
                                                          ┌───────▼───────┐
                                                          │ Oracle        │
                                                          │ Database      │
                                                          └───────────────┘
```

## 🔧 Configuração do Servidor

### 1. Criar arquivo `.env` no diretório do servidor:

```bash
# Oracle Database
ORACLE_HOST=172.31.0.11
ORACLE_PORT=1521
ORACLE_SERVICE_NAME=ORCLDB
ORACLE_USERNAME=seu_usuario
ORACLE_PASSWORD=sua_senha
ORACLE_ENCODING=UTF-8

# Connection Pool
ORACLE_MIN_CONNECTIONS=1
ORACLE_MAX_CONNECTIONS=3
ORACLE_CONNECTION_INCREMENT=1
ORACLE_CONNECTION_TIMEOUT=30

# Server
SERVER_HOST=0.0.0.0
SERVER_PORT=8080
SERVER_MAX_REQUEST_SIZE=1MB
SERVER_TIMEOUT=60

# Security
ALLOWED_SCHEMAS=CONSINCO
BLOCKED_OPERATIONS=DROP,DELETE,TRUNCATE,ALTER
RATE_LIMIT_PER_MINUTE=60
RATE_LIMIT_BURST_SIZE=10
MAX_ROWS_RETURNED=1000

# Cache
CACHE_ENABLED=true
CACHE_TTL_SECONDS=300
CACHE_MAX_ENTRIES=100

# Logging
LOG_LEVEL=INFO
LOG_FILE=mcp_oracle.log
LOG_MAX_SIZE_MB=10
LOG_BACKUP_COUNT=3

# Monitoring
HEALTH_CHECK_INTERVAL=30
METRICS_ENABLED=true
```

### 2. Iniciar o servidor:

**Windows:**
```cmd
start-server.bat
```

**Linux/Mac:**
```bash
python3 mcp_oracle_server.py
```

## 📍 Endpoints Disponíveis

### 🔍 Descoberta (Recomendado para IAs)
```bash
GET ${MCP_ORACLE_URL}/mcp/tools
```
Retorna lista completa de endpoints com exemplos e instruções.

### ⭐ Endpoint Principal
```bash
POST ${MCP_ORACLE_URL}/sql
Content-Type: application/json

{
  "sql": "SELECT * FROM CONSINCO.MAP_PRODUTO WHERE ROWNUM <= 10"
}
```

### 📊 Schemas e Objetos
```bash
GET ${MCP_ORACLE_URL}/schemas
GET ${MCP_ORACLE_URL}/objects/CONSINCO
GET ${MCP_ORACLE_URL}/objects/CONSINCO/TABLE
```

### 💚 Health e Métricas
```bash
GET ${MCP_ORACLE_URL}/health
GET ${MCP_ORACLE_URL}/metrics
```

### 📄 Código-Fonte PL/SQL
```bash
GET ${MCP_ORACLE_URL}/source/CONSINCO/PACKAGE_NAME
GET ${MCP_ORACLE_URL}/trigger/CONSINCO/TRIGGER_NAME
```

## 🤖 Para IAs e Agentes de Código

Se você é uma IA (Cursor, Claude Code, Gemini, etc), siga este fluxo:

### 1️⃣ SEMPRE comece consultando os endpoints disponíveis:
```bash
curl ${MCP_ORACLE_URL}/mcp/tools
```

### 2️⃣ Para executar queries SQL, use POST /sql:
```bash
curl -X POST ${MCP_ORACLE_URL}/sql \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM CONSINCO.MAP_PRODUTO WHERE ROWNUM <= 10"}'
```

### ⚠️ IMPORTANTE:
- ❌ **NÃO use /execute** - Este endpoint NÃO existe
- ✅ **Use /sql** - Endpoint correto para queries
- ✅ **Sempre inclua o schema** - Ex: `CONSINCO.TABELA`
- ✅ **Sempre limite resultados** - Use `WHERE ROWNUM <= N`

### 📋 Arquivo .cursorrules
O projeto inclui um arquivo `.cursorrules` com instruções detalhadas para o Cursor IDE. O Cursor lerá automaticamente essas regras.

## 🧪 Testes

### Testar conectividade:
```bash
curl http://10.10.11.5:8080/health
```

### Testar query:
```bash
curl -X POST http://10.10.11.5:8080/sql \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT SYSDATE FROM DUAL"}'
```

### Ver métricas:
```bash
curl http://10.10.11.5:8080/metrics
```

## 📚 Exemplos de Uso

### Listar produtos:
```bash
curl -X POST ${MCP_ORACLE_URL}/sql \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT SEQPRODUTO, DESCCOMPLETA, DESCREDUZIDA FROM CONSINCO.MAP_PRODUTO WHERE ROWNUM <= 20"
  }'
```

### Contar registros:
```bash
curl -X POST ${MCP_ORACLE_URL}/sql \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT COUNT(*) as TOTAL FROM CONSINCO.MAP_PRODUTO"
  }'
```

### Buscar com filtro:
```bash
curl -X POST ${MCP_ORACLE_URL}/sql \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT * FROM CONSINCO.MAP_PRODUTO WHERE UPPER(DESCCOMPLETA) LIKE '%AGUA%' AND ROWNUM <= 10"
  }'
```

## 🔒 Segurança

- ✅ Apenas queries SELECT são permitidas
- ✅ Schemas são validados contra lista permitida
- ✅ Rate limiting: 60 requisições por minuto
- ✅ Limite máximo de 1000 linhas por query
- ✅ Timeout de conexão: 30 segundos
- ✅ Pool de conexões limitado (1-3 conexões)

## 🚀 Deploy

### No Servidor Windows:

1. **Sincronizar código:**
   ```cmd
   git pull origin main
   ```

2. **Parar servidor (se rodando):**
   ```cmd
   Ctrl+C
   ```

3. **Iniciar servidor:**
   ```cmd
   start-server.bat
   ```

4. **Testar:**
   ```cmd
   curl http://localhost:8080/health
   ```

### Autostart no Oracle Linux:

Ver arquivo `INSTRUCOES_DIAGNOSTICO.md` para configurar o banco Oracle para iniciar automaticamente.

## 📖 Documentação Adicional

- **`.cursorrules`** - Instruções para Cursor IDE e outras IAs
- **`INSTRUCOES_DIAGNOSTICO.md`** - Troubleshooting e diagnóstico
- **`oracle_config.json`** - Configuração do servidor (template)
- **`package.json`** - Configuração do pacote NPM

## 🤝 Contribuindo

1. Fork o projeto
2. Crie uma branch: `git checkout -b feature/nova-funcionalidade`
3. Commit suas mudanças: `git commit -m 'Adiciona nova funcionalidade'`
4. Push para a branch: `git push origin feature/nova-funcionalidade`
5. Abra um Pull Request

## 📝 Changelog

### v1.2.0 (2025-11-03)
- ✨ Adicionado endpoint `/mcp/tools` para descoberta de ferramentas
- 📚 Adicionado arquivo `.cursorrules` para IAs
- 📖 Documentação completa para agentes de código
- 🔧 Exemplos usando variável `${MCP_ORACLE_URL}`

### v1.1.1 (2025-11-02)
- 🐛 Corrigido script de teste no package.json
- 📦 Publicação NPM corrigida

### v1.1.0 (2025-10-XX)
- 🎉 Primeira versão publicada no NPM
- ✨ Suporte a execução via npx
- 🔧 Cliente MCP Node.js implementado

## 📄 Licença

MIT

## 👤 Autor

**Ed Pinheiro**
- Email: ed1404@gmail.com
- GitHub: [@edapinheiro](https://github.com/edapinheiro)

## 🙏 Agradecimentos

- Anthropic pelo protocolo MCP
- Comunidade Oracle
- Cursor IDE team

---

**Versão:** 1.2.0
**Última atualização:** 2025-11-03