mcp-database-server

Servidor MCP (Model Context Protocol) de nível de produção para acesso unificado a bancos de dados SQL. Conecte múltiplos bancos de dados através de um único servidor MCP, com descoberta de esquemas, mapeamento de relacionamentos, cache e controles de segurança.

GitHub

Documentação

@adevguide/mcp-database-server

Servidor Model Context Protocol (MCP) de nível de produção para acesso unificado a bancos de dados SQL. Conecte vários bancos de dados por meio de um único servidor MCP, com descoberta de schema, mapeamento de relacionamentos, cache e controles de segurança.

Recursos

Suporte a múltiplos bancos de dados: PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, Oracle
Descoberta automática de schema: tabelas, colunas, índices, chaves estrangeiras, relacionamentos
Cache persistente de schema: TTL + versionamento, atualização manual, estatísticas de cache
Inferência de relacionamentos: chaves estrangeiras + heurísticas
Inteligência de consultas: rastreamento, estatísticas, timeouts
Assistência para joins: caminhos de join sugeridos com base em grafos de relacionamento
Controles de segurança: modo somente leitura, permitir/negar operações de escrita, redação de segredos
Otimização de consultas: recomendações de índices, perfil de desempenho, detecção de consultas lentas
Monitoramento de desempenho: análises detalhadas de execução, identificação de gargalos
Reescrita de consultas: sugestões automatizadas de otimização com estimativas de impacto no desempenho

Por que isso existe

Este projeto foi originalmente criado com vibe coding para resolver problemas reais que eu enfrentava ao conectar ferramentas de LLM a vários bancos de dados SQL (conectividade consistente, descoberta de schema e execução segura de consultas). Desde então, foi aprimorado para se tornar um servidor MCP reutilizável, com cache e configurações de segurança padrão.

Arquitetura

┌─────────────────────────────────────────────────────────┐
│                    MCP Client                            │
│            (Claude Desktop, IDEs, etc.)                  │
└────────────────┬────────────────────────────────────────┘
                 │ JSON-RPC over stdio
┌────────────────▼────────────────────────────────────────┐
│                MCP Database Server                       │
│  ┌──────────────────────────────────────────────────┐   │
│  │           Schema Cache (TTL + Versioning)        │   │
│  └──────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Query Tracker (History + Statistics)            │   │
│  └──────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Security Layer (Read-only, Operation Controls)  │   │
│  └──────────────────────────────────────────────────┘   │
└────┬─────────┬─────────┬──────────┬──────────┬─────────┘
     │         │         │          │          │
┌────▼───┐ ┌──▼────┐ ┌──▼─────┐ ┌──▼──────┐ ┌▼────────┐
│Postgres│ │ MySQL │ │ SQLite │ │ MSSQL   │ │ Oracle  │
└────────┘ └───────┘ └────────┘ └─────────┘ └─────────┘

Bancos de Dados Suportados

Banco de Dados	Driver	Status	Observações
PostgreSQL	`pg`	✅ Suporte Completo	Inclui compatibilidade com CockroachDB
MySQL/MariaDB	`mysql2`	✅ Suporte Completo	Inclui compatibilidade com Amazon Aurora MySQL
SQLite	`sql.js`	✅ Suporte Completo	SQLite com suporte WASM e persistência em arquivo
SQL Server	`tedious`	✅ Suporte Completo	Microsoft SQL Server / Azure SQL
Oracle	`oracledb`	⚠️ Stub	Requer Oracle Instant Client

Instalação

Instalação global (recomendado)

npm install -g @adevguide/mcp-database-server

Execute:

mcp-database-server --config /absolute/path/to/.mcp-database-server.config

Executar via npx (sem instalação global)

npx -y @adevguide/mcp-database-server --config /absolute/path/to/.mcp-database-server.config

Instalar a partir do código-fonte

git clone https://github.com/iPraBhu/mcp-database-server.git
cd mcp-database-server
npm install
npm run build
node dist/index.js --config ./.mcp-database-server.config

Configuração

Crie um arquivo .mcp-database-server.config na raiz do seu projeto:

Observação: O arquivo de configuração é descoberto automaticamente dentro da árvore do projeto atual. Se você não especificar --config, a ferramenta busca para cima a partir do diretório atual até alcançar a raiz do projeto detectada (por exemplo, um diretório contendo package.json ou .git). Ela não continua além da raiz do projeto. Se você usar credentialCommand, passe --config explicitamente.

{
  "databases": [
    {
      "id": "postgres-main",
      "type": "postgres",
      "secretRef": "DB_URL_POSTGRES",
      "readOnly": true,
      "pool": {
        "min": 2,
        "max": 10,
        "idleTimeoutMillis": 30000
      },
      "introspection": {
        "includeViews": true,
        "excludeSchemas": ["pg_catalog"]
      }
    },
    {
      "id": "mariadb-reporting",
      "type": "mysql",
      "secretRef": "DB_URL_MARIADB",
      "readOnly": true,
      "pool": {
        "min": 1,
        "max": 5
      }
    },
    {
      "id": "sqlite-local",
      "type": "sqlite",
      "path": "./data/app.db"
    }
  ],
  "cache": {
    "directory": ".sql-mcp-cache",
    "ttlMinutes": 10
  },
  "security": {
    "allowWrite": false,
    "allowedWriteOperations": ["INSERT", "UPDATE"],
    "disableDangerousOperations": true,
    "redactSecrets": true
  },
  "logging": {
    "level": "info",
    "pretty": false
  }
}

Referência de Configuração

Configuração do Banco de Dados

Cada banco de dados no array databases representa uma conexão com um banco de dados SQL.

Propriedades Principais

Propriedade	Tipo	Obrigatório	Padrão	Descrição
`id`	string	✅ Sim	-	Identificador exclusivo para esta conexão de banco de dados. Usado em todas as chamadas de ferramentas MCP. Deve ser exclusivo em todos os bancos de dados.
`type`	enum	✅ Sim	-	Tipo de sistema de banco de dados. Valores válidos: `postgres`, `mysql`, `sqlite`, `mssql`, `oracle`
`url`	string	Condicional*	-	String de conexão explícita do banco de dados. Suporta interpolação de variáveis de ambiente com `${DB_URL}`, mas não é o caminho recomendado para lidar com segredos.
`secretRef`	string	Condicional*	-	Nome de uma variável de ambiente que contém a string de conexão completa. Resolvida a partir do ambiente do processo ou de um arquivo `.env` ao lado do arquivo de configuração.
`credentialCommand`	string	Condicional*	-	Comando shell que imprime a string de conexão completa no stdout durante a inicialização. Útil para 1Password, Vault, ferramentas AWS ou outras ferramentas de segredos personalizadas. Requer iniciar o servidor com um caminho explícito de `--config`.
`path`	string	Condicional**	-	Caminho no sistema de arquivos para o arquivo do banco de dados SQLite. Necessário apenas para `type: sqlite`. Pode ser relativo ou absoluto.
`readOnly`	boolean	Não	`true`	Quando `true`, bloqueia todas as operações de escrita (INSERT, UPDATE, DELETE, etc.). Recomendado para segurança em produção.
`eagerConnect`	boolean	Não	`false`	Quando `true`, conecta-se ao banco de dados imediatamente na inicialização (fail-fast). Quando `false`, conecta-se na primeira consulta (carregamento preguiçoso).

_{* Obrigatório para postgres, mysql, mssql, oracle}
_{** Obrigatório apenas para sqlite}

Formatos de String de Conexão:

PostgreSQL:  postgresql://username:password@host:5432/database
MySQL:       mysql://username:password@host:3306/database  
SQL Server:  Server=host,1433;Database=dbname;User Id=user;Password=pass
SQLite:      (use path property instead)
Oracle:      username/password@host:1521/servicename

Configuração do Pool de Conexões

O objeto pool controla o comportamento do pool de conexões. Melhora o desempenho reutilizando conexões de banco de dados.

Propriedade	Tipo	Obrigatório	Padrão	Descrição
`min`	number	Não	`2`	Número mínimo de conexões a manter no pool. Mantidas ativas mesmo quando ociosas.
`max`	number	Não	`10`	Número máximo de conexões simultâneas. Não exceda o limite de conexões do seu banco de dados.
`idleTimeoutMillis`	number	Não	`30000`	Tempo (ms) para manter conexões ociosas antes de fechá-las. Exemplo: `60000` = 1 minuto.
`connectionTimeoutMillis`	number	Não	`10000`	Tempo (ms) de espera ao estabelecer uma conexão antes do timeout. Fail-fast se o banco de dados estiver inacessível.

Recomendações:

Desenvolvimento: min: 1, max: 5
Produção (Baixo Tráfego): min: 2, max: 10
Produção (Alto Tráfego): min: 5, max: 20

Configuração de Introspecção

O objeto introspection controla o comportamento de descoberta de schema. Determina quais objetos do banco de dados são analisados.

Propriedade	Tipo	Obrigatório	Padrão	Descrição
`includeViews`	boolean	Não	`true`	Incluir visualizações (views) do banco de dados na descoberta de schema. Defina como `false` se as visualizações causarem problemas de desempenho.
`includeRoutines`	boolean	Não	`false`	Incluir procedimentos armazenados e funções. (Não totalmente implementado – recurso planejado)
`maxTables`	number	Não	ilimitado	Limitar a introspecção às primeiras N tabelas. Útil para bancos de dados com 1000+ tabelas. Pode resultar em descoberta incompleta de relacionamentos.
`includeSchemas`	string[]	Não	todos	Lista de permissões de schemas para introspectar. Aplicável apenas ao PostgreSQL e SQL Server. Exemplo: `["public", "app"]`
`excludeSchemas`	string[]	Não	nenhum	Lista de bloqueio de schemas a ignorar. Valores comuns: `["pg_catalog", "information_schema", "sys"]`

Schema vs Banco de Dados:

PostgreSQL/SQL Server: Suportam múltiplos schemas por banco de dados. Use includeSchemas/excludeSchemas.
MySQL/MariaDB: Schema = banco de dados. Use o nome do banco de dados na string de conexão.
SQLite: Banco de dados de arquivo único, sem conceito de schema.

Configuração de Cache

Controla o cache de metadados de schema para melhorar o desempenho de inicialização e reduzir a carga no banco de dados.

Propriedade	Tipo	Obrigatório	Padrão	Descrição
`directory`	string	Não	`.sql-mcp-cache`	Caminho do diretório onde os arquivos de schema em cache são armazenados. Um arquivo JSON por banco de dados.
`ttlMinutes`	number	Não	`10`	Tempo de vida (Time-To-Live) em minutos. Por quanto tempo o schema em cache é considerado válido antes da atualização automática.

Comportamento do Cache:

Na inicialização: Carrega o schema do cache se disponível e não expirado
Após expiração do TTL: A próxima consulta aciona a re-introspecção automática
Atualização manual: Use a ferramenta clear_cache ou introspect_schema com forceRefresh: true
Arquivos de cache: Armazenados como {database-id}.json (por exemplo, postgres-main.json)

Valores de TTL Recomendados:

Desenvolvimento: 5 minutos (schema muda com frequência)
Staging: 30-60 minutos
Produção (Estático): 1440 minutos (24 horas)
Produção (Ativo): 60-240 minutos (1-4 horas)

Configuração de Segurança

Controles de segurança abrangentes para proteger seus bancos de dados contra operações não autorizadas ou perigosas.

Propriedade	Tipo	Obrigatório	Padrão	Descrição
`allowWrite`	boolean	Não	`false`	Interruptor principal para operações de escrita. Quando `false`, todas as escritas são bloqueadas em todos os bancos de dados.
`allowedWriteOperations`	string[]	Não	todos	Lista de permissões de operações SQL permitidas quando `allowWrite: true`. Valores válidos: `INSERT`, `UPDATE`, `DELETE`, `CREATE`, `ALTER`, `DROP`, `TRUNCATE`, `REPLACE`, `MERGE`
`disableDangerousOperations`	boolean	Não	`true`	Camada extra de segurança. Quando `true`, bloqueia operações `DELETE`, `TRUNCATE` e `DROP` mesmo que escritas sejam permitidas. Previne perda acidental de dados.
`redactSecrets`	boolean	Não	`true`	Redigir strings de conexão, senhas e credenciais semelhantes em logs e em mensagens de erro retornadas.

Camadas de Segurança (Avaliadas em Ordem):

readOnly no nível do banco de dados → Bloqueia todas as escritas para um banco específico
allowWrite global → Interruptor principal para todos os bancos de dados
disableDangerousOperations → Bloqueia especificamente DELETE/TRUNCATE/DROP
allowedWriteOperations → Lista de permissões de operações permitidas

Exemplos de Configuração:

// Read-only access (default - safest)
{
  "allowWrite": false
}

// Allow INSERT and UPDATE only (no deletes)
{
  "allowWrite": true,
  "allowedWriteOperations": ["INSERT", "UPDATE"],
  "disableDangerousOperations": true
}

// Full write access (development only - dangerous!)
{
  "allowWrite": true,
  "disableDangerousOperations": false
}

Configuração de Logging

Controla o nível de detalhe e a formatação da saída de logs.

Propriedade	Tipo	Obrigatório	Padrão	Descrição
`level`	enum	Não	`info`	Nível de log. Valores válidos: `trace`, `debug`, `info`, `warn`, `error`. Níveis mais baixos incluem os níveis mais altos.
`pretty`	boolean	Não	`false`	Quando `true`, formata logs como texto legível para humanos. Quando `false`, gera JSON estruturado (melhor para agregação de logs em produção).

Níveis de Log:

trace: Tudo (extremamente detalhado – use apenas para depuração)
debug: Informações detalhadas de diagnóstico
info: Mensagens informativas gerais (recomendado para produção)
warn: Mensagens de aviso que não impedem a operação
error: Apenas mensagens de erro

Recomendações:

Desenvolvimento: level: "debug", pretty: true
Produção: level: "info", pretty: false
Solução de problemas: level: "trace", pretty: true

Exemplo Completo de Configuração

{
  "databases": [
    {
      "id": "postgres-production",
      "type": "postgres",
      "url": "${DATABASE_URL}",
      "readOnly": true,
      "pool": {
        "min": 5,
        "max": 20,
        "idleTimeoutMillis": 60000,
        "connectionTimeoutMillis": 5000
      },
      "introspection": {
        "includeViews": true,
        "includeRoutines": false,
        "excludeSchemas": ["pg_catalog", "information_schema"]
      },
      "eagerConnect": true
    },
    {
      "id": "mysql-analytics",
      "type": "mysql",
      "url": "${MYSQL_URL}",
      "readOnly": true,
      "pool": {
        "min": 2,
        "max": 10
      },
      "introspection": {
        "includeViews": true,
        "maxTables": 100
      }
    },
    {
      "id": "sqlite-local",
      "type": "sqlite",
      "path": "./data/app.db",
      "readOnly": true
    }
  ],
  "cache": {
    "directory": ".sql-mcp-cache",
    "ttlMinutes": 60
  },
  "security": {
    "allowWrite": false,
    "allowedWriteOperations": ["INSERT", "UPDATE"],
    "disableDangerousOperations": true,
    "redactSecrets": true
  },
  "logging": {
    "level": "info",
    "pretty": false
  }
}

Resolução de Segredos

Abordagem recomendada: secretRef

Mantenha segredos fora da configuração do cliente MCP e fora dos próprios valores de configuração do servidor.

Exemplo de Configuração:

{
  "databases": [
    {
      "id": "production-db",
      "type": "postgres",
      "secretRef": "DATABASE_URL"
    }
  ]
}

O servidor resolve secretRef primeiro a partir do ambiente do processo e, em seguida, a partir de um arquivo .env próximo a .mcp-database-server.config.

Arquivo de Ambiente (.env):

DATABASE_URL=postgresql://user:password@localhost:5432/dbname
DB_URL_MYSQL=mysql://user:password@localhost:3306/dbname
DB_URL_MARIADB=mysql://report_user:password@mariadb.local:3306/reporting
DB_URL_MSSQL=Server=host,1433;Database=db;User Id=sa;Password=pass

Alternativa: credentialCommand

{
  "databases": [
    {
      "id": "analytics-db",
      "type": "mysql",
      "credentialCommand": "op read op://analytics/mysql/url"
    }
  ]
}

O comando deve imprimir apenas a string de conexão no stdout. Por segurança, credentialCommand só é permitido quando o servidor é iniciado com um caminho explícito de --config. Configurações descobertas automaticamente não podem executar comandos de credenciais.

Ainda suportado: interpolação direta de env

Você ainda pode escrever "url": "${DATABASE_URL}", mas secretRef é a opção mais limpa porque torna a fonte do segredo explícita. Melhores Práticas:

✅ Armazene o arquivo .env fora do controle de versão (adicione ao .gitignore)
✅ Use arquivos .env diferentes para cada ambiente (dev, staging, prod)
✅ Nunca envie credenciais para repositórios git
✅ Use serviços de gerenciamento de segredos (AWS Secrets Manager, HashiCorp Vault) em produção

Referência de String de Conexão

Banco de Dados	Formato	Exemplo
PostgreSQL	`postgresql://user:pass@host:port/db`	`postgresql://admin:secret@localhost:5432/myapp`
MySQL	`mysql://user:pass@host:port/db`	`mysql://root:password@localhost:3306/myapp`
MariaDB	`mysql://user:pass@host:port/db`	`mysql://report_user:password@mariadb.local:3306/reporting`
SQL Server	`Server=host,port;Database=db;User Id=user;Password=pass`	`Server=localhost,1433;Database=myapp;User Id=sa;Password=secret`
SQLite	Use a propriedade `path`	`"path": "./data/app.db"` ou `"path": "/var/db/app.sqlite"`

Parâmetros Adicionais:

PostgreSQL:

postgresql://user:pass@host:5432/db?sslmode=require&connect_timeout=10

MySQL:

mysql://user:pass@host:3306/db?charset=utf8mb4&timezone=Z

MariaDB:

mysql://user:pass@host:3306/db?charset=utf8mb4

SQL Server:

Server=host;Database=db;User Id=user;Password=pass;Encrypt=true;TrustServerCertificate=false

Integração com Cliente MCP

Localizações dos Arquivos de Configuração

Cliente MCP	Caminho do Arquivo de Configuração
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Cline (VS Code)	Configurações do VS Code → MCP Servers
Outros Clientes	Consulte a documentação específica do cliente

Métodos de Configuração

Método 1: Instalação Global via npm

Configuração:

{
  "mcpServers": {
    "database": {
      "command": "mcp-database-server",
      "args": ["--config", "/absolute/path/to/.mcp-database-server.config"]
    }
  }
}

Método 2: Instalação a partir do Código Fonte

Configuração:

{
  "mcpServers": {
    "database": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-database-server/dist/index.js",
        "--config",
        "/absolute/path/to/.mcp-database-server.config"
      ]
    }
  }
}

Propriedades de Configuração

Propriedade	Descrição	Exemplo
`command`	Executável a ser executado. Use `mcp-database-server` para instalação via npm, `node` para instalação a partir do código fonte.	`"mcp-database-server"`
`args`	Matriz de argumentos de linha de comando. O primeiro argumento geralmente é `--config`, seguido pelo caminho do arquivo de configuração.	`["--config", "/path/to/config"]`
`env`	Variáveis de ambiente opcionais passadas ao servidor. Prefira `secretRef` com um arquivo local `.env` ou ferramentas externas de segredos para credenciais de banco de dados.	`{"APP_ENV": "production"}`

Encontrando Caminhos Absolutos:

# macOS/Linux
cd /path/to/mcp-database-server
pwd  # prints: /Users/username/projects/mcp-database-server

# Windows (PowerShell)
cd C:\path\to\mcp-database-server
$PWD.Path  # prints: C:\Users\username\projects\mcp-database-server

Ferramentas MCP Disponíveis

Este servidor fornece 15 ferramentas para interação e otimização abrangentes de banco de dados.

Referência de Ferramentas

Ferramenta	Propósito	Acesso de Escrita	Dados em Cache
`list_databases`	Listar todos os bancos de dados configurados com status	Não	Usa cache
`introspect_schema`	Descobrir e armazenar em cache o esquema do banco de dados	Não	Grava cache
`get_schema`	Recuperar metadados de esquema em cache	Não	Lê cache
`run_query`	Executar consultas SQL com controles de segurança	Condicional*	Atualiza estatísticas
`export_query`	Exportar grandes resultados de consultas somente leitura para um arquivo local	Não	Sem cache
`explain_query`	Analisar planos de execução de consultas	Não	Sem cache
`suggest_joins`	Obter recomendações inteligentes de caminhos de junção	Não	Usa cache
`clear_cache`	Limpar cache de esquema e estatísticas	Não	Limpa cache
`cache_status`	Visualizar saúde e estatísticas do cache	Não	Lê cache
`health_check`	Testar conectividade do banco de dados	Não	Sem cache
`analyze_performance`	Obter análises detalhadas de desempenho	Não	Usa estatísticas
`suggest_indexes`	Analisar consultas e recomendar índices	Não	Usa estatísticas
`detect_slow_queries`	Identificar e alertar sobre consultas lentas	Não	Usa estatísticas
`rewrite_query`	Sugerir versões otimizadas de consultas	Não	Usa cache
`profile_query`	Perfilar desempenho de consultas com gargalos	Não	Sem cache

_{* Requer allowWrite: true e respeita as configurações de segurança}

1. list_databases

Lista todos os bancos de dados configurados com seu status de conexão e informações de cache.

Parâmetros de Entrada:

Nenhum necessário.

Resposta:

[
  {
    "id": "postgres-main",
    "type": "postgres",
    "connected": true,
    "cached": true,
    "cacheAge": 45000,
    "version": "abc123"
  }
]

Campos da Resposta:

Campo	Tipo	Descrição
`id`	string	Identificador do banco de dados a partir da configuração
`type`	string	Tipo de banco de dados (postgres, mysql, sqlite, mssql, oracle)
`connected`	boolean	Se a conexão do banco de dados está ativa
`cached`	boolean	Se o esquema está atualmente em cache
`cacheAge`	number	Idade do esquema em cache em milissegundos (se em cache)
`version`	string	Hash da versão do cache (se em cache)

2. introspect_schema

Descobre e armazena em cache o esquema completo do banco de dados, incluindo tabelas, colunas, índices, chaves estrangeiras e relacionamentos.

Parâmetros de Entrada:

Parâmetro	Tipo	Obrigatório	Descrição
`dbId`	string	Sim	Identificador do banco de dados a ser inspecionado
`forceRefresh`	boolean	Não	Forçar reintrospecção mesmo se o cache for válido (padrão: `false`)
`schemaFilter`	object	Não	Filtrar quais objetos inspecionar
`schemaFilter.includeSchemas`	string[]	Não	Inspecionar apenas estes esquemas (PostgreSQL/SQL Server)
`schemaFilter.excludeSchemas`	string[]	Não	Pular estes esquemas durante a introspecção
`schemaFilter.includeViews`	boolean	Não	Incluir visões (views) do banco de dados (padrão: `true`)
`schemaFilter.maxTables`	number	Não	Limitar às primeiras N tabelas

Exemplo de Solicitação:

{
  "dbId": "postgres-main",
  "forceRefresh": false,
  "schemaFilter": {
    "includeSchemas": ["public"],
    "excludeSchemas": ["temp"],
    "includeViews": true,
    "maxTables": 100
  }
}

Resposta:

{
  "dbId": "postgres-main",
  "version": "a1b2c3d4",
  "introspectedAt": "2026-01-26T10:00:00.000Z",
  "schemas": [
    {
      "name": "public",
      "tableCount": 15,
      "viewCount": 3
    }
  ],
  "totalTables": 15,
  "totalRelationships": 12
}

3. get_schema

Recupera metadados detalhados do esquema a partir do cache, sem consultar o banco de dados.

Parâmetros de Entrada:

Parâmetro	Tipo	Obrigatório	Descrição
`dbId`	string	Sim	Identificador do banco de dados
`schema`	string	Não	Filtrar por nome específico de esquema
`table`	string	Não	Filtrar por nome específico de tabela

Exemplo de Solicitação:

{
  "dbId": "postgres-main",
  "schema": "public",
  "table": "users"
}

Resposta: Metadados completos do esquema, incluindo tabelas, colunas, tipos de dados, índices, chaves estrangeiras e relacionamentos inferidos.

4. run_query

Executa consultas SQL com armazenamento automático em cache do esquema, anotação de relacionamentos e controles de segurança abrangentes.

Parâmetros de Entrada:

Parâmetro	Tipo	Obrigatório	Descrição
`dbId`	string	Sim	Identificador do banco de dados a ser consultado
`sql`	string	Sim	Consulta SQL a ser executada
`params`	array	Não	Valores de consulta parametrizados (previne injeção de SQL)
`limit`	number	Não	Número máximo de linhas a retornar
`offset`	number	Não	Deslocamento de linhas para leituras paginadas. Requer `limit`.
`maxBytes`	number	Não	Aproximadamente o máximo de bytes serializados para as linhas retornadas.
`includeMetadata`	boolean	Não	Incluir metadados de relacionamentos e estatísticas de consulta na resposta. Padrão: `true`.
`trackQuery`	boolean	Não	Rastrear esta consulta no histórico e nas análises de desempenho. Padrão: `true`.
`timeoutMs`	number	Não	Tempo limite da consulta em milissegundos

Exemplo de Solicitação:

{
  "dbId": "postgres-main",
  "sql": "SELECT * FROM users WHERE active = $1 ORDER BY id",
  "params": [true],
  "limit": 10,
  "offset": 0,
  "maxBytes": 32768,
  "includeMetadata": false,
  "trackQuery": false,
  "timeoutMs": 5000
}

Resposta:

{
  "rows": [
    {"id": 1, "name": "Alice", "email": "alice@example.com", "active": true},
    {"id": 2, "name": "Bob", "email": "bob@example.com", "active": true}
  ],
  "columns": ["id", "name", "email", "active"],
  "rowCount": 2,
  "executionTimeMs": 15,
  "metadata": {
    "relationships": [...],
    "queryStats": {
      "totalQueries": 10,
      "avgExecutionTime": 20,
      "errorCount": 0
    },
    "pagination": {
      "limit": 10,
      "offset": 0,
      "hasMore": true,
      "nextOffset": 10
    },
    "responseSize": {
      "maxBytes": 32768,
      "rowsBytes": 1842,
      "rowsTrimmed": false,
      "omittedRowCount": 0
    }
  }
}

Para o caminho de leitura mais rápido em MariaDB/MySQL, defina "includeMetadata": false e "trackQuery": false quando você precisar apenas das linhas de resultado e não precisar de anotações de relacionamento, histórico de consultas ou análises de desempenho para essa solicitação.

Controles de Segurança:

✅ Operações de escrita bloqueadas por padrão (allowWrite: false)
✅ Operações perigosas (DELETE, TRUNCATE, DROP) desabilitadas por padrão
✅ Operações específicas podem ser adicionadas à lista de permissões via allowedWriteOperations
✅ Modo readOnly por banco de dados

5. explain_query

Recupera o plano de execução da consulta do banco de dados sem executar a consulta.

Parâmetros de Entrada:

Parâmetro	Tipo	Obrigatório	Descrição
`dbId`	string	Sim	Identificador do banco de dados
`sql`	string	Sim	Consulta SQL a ser analisada
`params`	array	Não	Parâmetros da consulta (para consultas parametrizadas)

Exemplo de Solicitação:

{
  "dbId": "postgres-main",
  "sql": "SELECT * FROM users JOIN orders ON users.id = orders.user_id WHERE users.active = $1",
  "params": [true]
}

Resposta: Plano de execução nativo do banco de dados (o formato varia conforme o tipo de banco de dados).

5a. export_query

Exporta grandes resultados de consultas somente leitura para um arquivo local em .sql-mcp-cache/exports.

Estratégia de Execução:

MySQL/MariaDB usa streaming de linhas em nível de adaptador para evitar carregar o conjunto de resultados completo na memória.
PostgreSQL e SQLite usam exportação paginada, reescrevendo janelas LIMIT/OFFSET de nível superior.
A exportação do SQL Server requer um caminho futuro de streaming específico do adaptador e atualmente falhará, a menos que a reescrita de paginação seja suportada.

Parâmetros de Entrada:

Parâmetro	Tipo	Obrigatório	Descrição
`dbId`	string	Sim	Identificador do banco de dados
`sql`	string	Sim	Consulta SQL somente leitura a ser exportada
`params`	array	Não	Parâmetros da consulta
`format`	string	Não	Formato de saída: `jsonl` ou `csv` (padrão: `jsonl`)
`pageSize`	number	Não	Tamanho da página para adaptadores sem streaming (padrão: `1000`)
`fileName`	string	Não	Nome opcional do arquivo de saída gravado dentro do diretório de exportação
`timeoutMs`	number	Não	Tempo limite da consulta em milissegundos

Exemplo de Solicitação:

{
  "dbId": "mariadb-reporting",
  "sql": "SELECT id, email, created_at FROM users ORDER BY id",
  "format": "jsonl",
  "fileName": "users-export.jsonl",
  "timeoutMs": 10000
}

Resposta:

{
  "dbId": "mariadb-reporting",
  "outputPath": "/absolute/path/to/.sql-mcp-cache/exports/users-export.jsonl",
  "format": "jsonl",
  "strategy": "stream",
  "rowsExported": 250000,
  "columns": ["id", "email", "created_at"],
  "fileSizeBytes": 18342011,
  "executionTimeMs": 8421
}

6. suggest_joins

Analisa o grafo de relacionamentos para recomendar caminhos de junção ideais entre várias tabelas.

Parâmetros de Entrada:

Parâmetro	Tipo	Obrigatório	Descrição
`dbId`	string	Sim	Identificador do banco de dados
`tables`	string[]	Sim	Matriz de nomes de tabelas para unir (2-10 tabelas)

Exemplo de Solicitação:

{
  "dbId": "postgres-main",
  "tables": ["users", "orders", "products"]
}

Resposta:

[
  {
    "tables": ["users", "orders", "products"],
    "joins": [
      {
        "fromTable": "users",
        "toTable": "orders",
        "relationship": {
          "type": "one-to-many",
          "confidence": 1.0
        },
        "joinCondition": "users.id = orders.user_id"
      },
      {
        "fromTable": "orders",
        "toTable": "products",
        "relationship": {
          "type": "many-to-one",
          "confidence": 1.0
        },
        "joinCondition": "orders.product_id = products.id"
      }
    ],
    "sql": "FROM users JOIN orders ON users.id = orders.user_id JOIN products ON orders.product_id = products.id"
  }
]

7. clear_cache

Limpa o cache de esquema e as estatísticas de consultas para um ou todos os bancos de dados.

Parâmetros de Entrada:

Parâmetro	Tipo	Obrigatório	Descrição
`dbId`	string	Não	Banco de dados a limpar (omitir para limpar todos)

Exemplo de Solicitação:

{
  "dbId": "postgres-main"
}

Resposta: Mensagem de confirmação.

8. cache_status

Recupera estatísticas detalhadas do cache e informações de saúde.

Parâmetros de Entrada:

Nenhum necessário.

Resposta:

{
  "directory": ".sql-mcp-cache",
  "ttlMinutes": 10,
  "databases": [
    {
      "dbId": "postgres-main",
      "cached": true,
      "version": "abc123",
      "age": 120000,
      "expired": false,
      "tableCount": 15,
      "sizeBytes": 45678
    }
  ]
}

9. health_check

Testa a conectividade do banco de dados e retorna informações de status.

Parâmetros de Entrada:

Parâmetro	Tipo	Obrigatório	Descrição
`dbId`	string	Não	Banco de dados a verificar (omitir para verificar todos)

Resposta:

{
  "databases": [
    {
      "dbId": "postgres-main",
      "healthy": true,
      "connected": true,
      "version": "PostgreSQL 15.3",
      "responseTimeMs": 12
    }
  ]
}

10. analyze_performance

Obtenha análises abrangentes de desempenho em todas as consultas de um banco de dados.

Parâmetros de Entrada:

Parâmetro	Tipo	Obrigatório	Descrição
`dbId`	string	Sim	Banco de dados a analisar

Resposta:

{
  "totalQueries": 1250,
  "slowQueries": 23,
  "avgExecutionTime": 45.67,
  "p95ExecutionTime": 234.5,
  "errorRate": 1.2,
  "mostFrequentTables": [
    { "table": "users", "count": 456 },
    { "table": "orders", "count": 234 }
  ],
  "performanceTrend": "improving"
}

11. suggest_indexes

Analisa padrões de consulta e recomenda índices ideais de banco de dados.

Parâmetros de Entrada:

Parâmetro	Tipo	Obrigatório	Descrição
`dbId`	string	Sim	Banco de dados a analisar

Resposta:

[
  {
    "table": "orders",
    "columns": ["customer_id", "order_date"],
    "type": "composite",
    "reason": "Frequently used in WHERE and JOIN conditions",
    "impact": "high"
  },
  {
    "table": "products",
    "columns": ["category_id"],
    "type": "single",
    "reason": "Column category_id is frequently queried",
    "impact": "medium"
  }
]

12. detect_slow_queries

Identifica consultas que excedem os limites de desempenho e fornece alertas.

Parâmetros de Entrada:

Parâmetro	Tipo	Obrigatório	Descrição
`dbId`	string	Sim	Banco de dados a analisar

Resposta:

[
  {
    "dbId": "postgres-main",
    "queryId": "a1b2c3",
    "sql": "SELECT * FROM large_table WHERE slow_column = ?",
    "executionTimeMs": 2500,
    "thresholdMs": 1000,
    "timestamp": "2024-01-27T10:30:00Z",
    "frequency": 5,
    "recommendations": [
      {
        "type": "add_index",
        "description": "Add index on slow_column for better performance",
        "impact": "high",
        "effort": "medium"
      }
    ]
  }
]

13. rewrite_query

Sugere versões otimizadas de consultas SQL com melhorias de desempenho.

Parâmetros de Entrada:

Parâmetro	Tipo	Obrigatório	Descrição
`dbId`	string	Sim	ID do banco de dados
`sql`	string	Sim	Consulta SQL a otimizar

Resposta:

{
  "originalQuery": "SELECT * FROM users WHERE active = 1",
  "optimizedQuery": "SELECT id, name, email FROM users WHERE active = 1 LIMIT 1000",
  "improvements": [
    "Removed unnecessary SELECT *",
    "Added LIMIT clause to prevent large result sets"
  ],
  "performanceGain": 35,
  "confidence": "high"
}

14. profile_query

Perfila o desempenho de uma consulta específica com análise detalhada de gargalos.

Parâmetros de Entrada:

Parâmetro	Tipo	Obrigatório	Descrição
`dbId`	string	Sim	ID do banco de dados
`sql`	string	Sim	Consulta SQL para perfil
`params`	array	Não	Parâmetros da consulta

Resposta:

{
  "queryId": "def456",
  "sql": "SELECT u.name, COUNT(o.id) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.id",
  "executionTimeMs": 1250,
  "rowCount": 5000,
  "bottlenecks": [
    {
      "type": "join",
      "severity": "high",
      "description": "Nested loop join on large tables",
      "estimatedCost": 150
    }
  ],
  "recommendations": [
    {
      "type": "add_index",
      "description": "Add index on orders.user_id",
      "impact": "high",
      "effort": "low"
    }
  ],
  "overallScore": 65
}

Recursos

O servidor expõe esquemas em cache como recursos MCP:

URI: schema://{dbId}
Tipo MIME: application/json
Conteúdo: Metadados completos do esquema em cache

Introspecção de Esquema

Descoberta Automática

O servidor descobre automaticamente:

Tabelas e Visões: Todas as tabelas de usuário e opcionalmente visões
Colunas: Nome, tipo de dados, nulabilidade, padrões, auto-incremento
Índices: Incluindo chaves primárias e restrições únicas
Chaves Estrangeiras: Metadados explícitos de relacionamento
Relacionamentos: Tanto explícitos quanto inferidos

Inferência de Relacionamentos

Quando chaves estrangeiras não são definidas, o servidor infere relacionamentos usando heurísticas:

Nomes de colunas correspondentes a {table}_id ou {table}Id
Compatibilidade de tipo de dados com a chave primária de destino
Pontuação de confiança para relacionamentos inferidos

Estratégia de Cache

Memória + Disco: Cache em duas camadas para desempenho
Baseado em TTL: Tempo de vida configurável
Rastreamento de Versão: Versionamento baseado em conteúdo (hash)
Seguro para Concorrência: Evita introspecção duplicada
Atualização Sob Demanda: Atualização manual ou automática

Rastreamento de Consultas

O servidor mantém histórico de consultas por banco de dados:

Carimbo de data/hora e texto SQL
Tempo de execução e contagem de linhas
Tabelas referenciadas (extração de melhor esforço)
Rastreamento de erros
Estatísticas agregadas

Use esses dados para:

Monitorar o desempenho de consultas
Identificar tabelas frequentemente acessadas
Detectar padrões de consulta
Depurar problemas

Desenvolvimento

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint
npm run lint

# Format code
npm run format

# Type check
npm run typecheck

Estrutura do Projeto

src/
├── adapters/          # Database adapters
│   ├── base.ts        # Base adapter class
│   ├── postgres.ts    # PostgreSQL adapter
│   ├── mysql.ts       # MySQL adapter
│   ├── sqlite.ts      # SQLite adapter
│   ├── mssql.ts       # SQL Server adapter
│   ├── oracle.ts      # Oracle adapter (stub)
│   └── index.ts       # Adapter factory
├── cache.ts           # Schema caching
├── config.ts          # Configuration loader
├── database-manager.ts # Database orchestration
├── logger.ts          # Logging setup
├── mcp-server.ts      # MCP server implementation
├── query-tracker.ts   # Query history tracking
├── types.ts           # TypeScript types
├── utils.ts           # Utility functions
└── index.ts           # Entry point

Adicionando Novos Adaptadores de Banco de Dados

Implemente a interface DatabaseAdapter em src/adapters/
Siga o padrão dos adaptadores existentes
Adicione à fábrica de adaptadores em src/adapters/index.ts
Atualize as definições de tipo se necessário
Adicione testes

Exemplo:

import { BaseAdapter } from './base.js';

export class CustomAdapter extends BaseAdapter {
  async connect(): Promise<void> { /* ... */ }
  async disconnect(): Promise<void> { /* ... */ }
  async introspect(): Promise<DatabaseSchema> { /* ... */ }
  async query(): Promise<QueryResult> { /* ... */ }
  async explain(): Promise<ExplainResult> { /* ... */ }
  async testConnection(): Promise<boolean> { /* ... */ }
  async getVersion(): Promise<string> { /* ... */ }
}

Solução de Problemas

Problemas de Conexão

Verifique strings de conexão e credenciais
Verifique a conectividade de rede e regras de firewall
Ative o registro de depuração: "logging": { "level": "debug" }
Use a ferramenta health_check para testar a conectividade

Problemas de Cache

Limpe o cache: Use a ferramenta clear_cache
Verifique as permissões do diretório de cache
Verifique as configurações de TTL
Revise o status do cache com a ferramenta cache_status

Desempenho

Ajuste as configurações do pool de conexões
Use maxTables para limitar o escopo da introspecção
Defina um TTL de cache apropriado
Ative o modo somente leitura quando possível

Configuração do Oracle

O adaptador Oracle requer configuração adicional:

Instale o Oracle Instant Client
Defina variáveis de ambiente (LD_LIBRARY_PATH ou PATH)
Instale o pacote oracledb
Implemente métodos stub em src/adapters/oracle.ts

Considerações de Segurança

Sempre use o modo somente leitura em produção, a menos que o acesso de escrita seja necessário
Use variáveis de ambiente para credenciais, nunca codifique
Ative a redação de segredos nos logs
Restrinja operações de escrita com allowedWriteOperations
Use criptografia de string de conexão onde houver suporte
Auditorias regulares de segurança das configurações

Licença

MIT

Contribuição

Contribuições são bem-vindas! Por favor:

Faça um fork do repositório
Crie um branch de recurso
Adicione testes para novas funcionalidades
Garanta que todos os testes passem
Envie um pull request

Suporte

Para problemas, dúvidas ou solicitações de recursos, abra uma issue no GitHub.