Estrutura inicial, ambiente IA
This commit is contained in:
victor
Vendored
+124
@@ -0,0 +1,124 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user