# MCP Oracle Custom

Servidor MCP local para Oracle com foco em estabilidade:

- pool de conexoes reutilizavel
- timeout por chamada
- limite padrao e limite rigido de linhas
- execucao apenas de consultas de leitura
- fallback automatico para SQLcl quando o driver Thin do node-oracledb nao suporta o verificador de senha da conta

## Arquivos

- `server.mjs`: servidor MCP via stdio
- `cli.mjs`: entrypoint Node executavel e cross-platform
- `run-mcp.sh`: bootstrap local que encontra `node`, instala dependencias quando necessario e sobe o servidor
- `.env.example`: exemplo de configuracao das conexoes

## Configuracao

1. Copie `.env.example` para `.env`
2. Preencha usuario, senha e connect string
3. Ajuste limites e timeout se necessario

Alternativas para configuracao:

- voce pode passar um arquivo externo com `--env-file /caminho/para/.env`
- voce pode definir as variaveis diretamente no ambiente do processo MCP
- na ausencia de `--env-file`, o servidor procura `.env` no diretorio atual, em diretorios pais, em `mcp-oracle-custom/.env` a partir do diretorio atual e, por fim, na pasta do pacote

Variaveis opcionais de backend:

- `ORACLE_BACKEND=auto`: tenta `node-oracledb` primeiro e cai para SQLcl quando necessario
- `ORACLE_BACKEND=oracledb`: forca uso apenas do driver Node
- `ORACLE_BACKEND=sqlcl`: forca uso apenas do SQLcl
- `ORACLE_SQLCL_PATH`: caminho explicito para o executavel `sql`
- `ORACLE_SQLCL_TIMEOUT_MS`: timeout do fallback SQLcl

Se `ORACLE_SQLCL_PATH` nao for informado, o servidor tenta localizar o SQLcl automaticamente em instalacoes comuns do VS Code sob o diretorio do usuario e em caminhos padrao do sistema.

## Ferramentas expostas

- `list_connections`: lista as conexoes configuradas
- `test_connection`: testa a conexao com o banco
- `run_query`: executa `SELECT` ou `WITH` com binds opcionais em JSON
- `reset_pools`: fecha todos os pools mantidos pelo servidor

## Observacoes

- Este MCP bloqueia DDL e DML por seguranca
- O servidor pode carregar o `.env` da pasta atual, da propria pasta do pacote ou de um arquivo informado em `--env-file`
- O retorno da consulta vem em JSON com colunas, linhas, truncamento e conexao usada
- Quando o fallback SQLcl estiver ativo, `bindsJson` nao e suportado
- O parser do fallback SQLcl normaliza numeros retornados com virgula decimal para manter o JSON valido
- Se quiser ampliar para metadata, DDL gerado ou chamadas especificas, da para adicionar novas ferramentas depois

## Uso no workspace

O arquivo `.vscode/mcp.json` deste workspace pode apontar diretamente para `./mcp-oracle-custom/run-mcp.sh` via `bash`.
Depois de preencher o `.env`, recarregue o VS Code ou o catalogo de MCPs para o servidor aparecer.

Esse bootstrap local faz o seguinte:

- procura um `node` no PATH e, se nao encontrar, tenta usar o Node embutido do VS Code neste ambiente Linux
- evita depender de caminhos fixos de um usuario especifico para localizar o Node embutido do VS Code
- verifica se as dependencias do pacote estao presentes
- executa `npm install` automaticamente quando as dependencias estiverem ausentes ou desatualizadas
- exibe mensagens claras quando `node` ou `npm` nao existirem no ambiente

## Instalacao cross-platform

Para usar no Windows e no Linux sem depender do `run-mcp.sh`, instale o pacote com npm para gerar o comando executavel `mcp-oracle-custom`:

```bash
npm install -g .
```

Depois disso, o comando abaixo fica disponivel no sistema:

```bash
mcp-oracle-custom --help
```

No Windows, o npm cria automaticamente o shim executavel correspondente.
No Linux, o comando e exposto como executavel com shebang Node.
Quando o comando for executado a partir do workspace do repositorio, o servidor encontra automaticamente `mcp-oracle-custom/.env`.

No bootstrap local via `run-mcp.sh`, nao e necessario instalar o pacote globalmente. O requisito e ter `node` disponivel para executar o servidor e `npm` disponivel quando for necessario instalar dependencias.

## Exemplo de configuracao em clientes MCP

Exemplo generico para VS Code, Copilot ou Claude Desktop usando o executavel do pacote:

```json
{
	"mcpServers": {
		"oracle-davinti": {
			"command": "mcp-oracle-custom"
		}
	}
}
```

Se preferir, ainda e possivel informar `--env-file` explicitamente. O `cli.mjs` foi adicionado para permitir distribuicao e instalacao sem depender de shell Bash.

## Exemplo de bootstrap local no workspace

Exemplo para VS Code no Linux usando o launcher do repositorio:

```json
{
	"servers": {
		"oracle-davinti": {
			"type": "stdio",
			"command": "bash",
			"args": [
				"./mcp-oracle-custom/run-mcp.sh"
			]
		}
	}
}
```

Se `node` nao existir, o bootstrap encerra informando isso explicitamente.
Se as dependencias ainda nao estiverem instaladas e `npm` nao existir, o bootstrap tambem encerra com mensagem clara explicando o que falta.