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

Copie .env.example para .env
Preencha usuario, senha e connect string
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:

npm install -g .

Depois disso, o comando abaixo fica disponivel no sistema:

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:

{
	"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:

{
	"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.

4.7 KiB Raw Blame History