victor
125 lines
4.7 KiB
Markdown
125 lines
4.7 KiB
Markdown
# 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.
|