MCP SQL Database Server

Um servidor Model Context Protocol (MCP) robusto para SQL Server que permite executar consultas seguras, explorar metadados complexos e pesquisar stored procedures, functions e triggers.

📋 Funcionalidades

• ✅ Execução segura de consultas SELECT com validação rigorosa
• ✅ Consulta abrangente de metadados (9 tipos diferentes)
• ✅ Busca avançada de Stored Procedures com múltiplas estratégias
• ✅ Exploração de Functions (scalar, table-valued, inline)
• ✅ Pesquisa de Triggers e Indexes
• ✅ Análise de Constraints e Schemas
• ✅ Proteção contra comandos DDL/DML perigosos
• ✅ Suporte completo a parâmetros SQL (prevenção de SQL injection)
• ✅ Pool de conexões com reconexão automática
• ✅ Conexão criptografada com autenticação

🛠️ Ferramentas Disponíveis

1. executeQuery

Executa uma query SELECT segura nas tabelas/views do banco de dados.

Parâmetros:

• query (string, obrigatório): Comando SQL SELECT a ser executado
• params (object, opcional): Parâmetros SQL para a query

Validações:

• Apenas comandos SELECT são permitidos
• Comandos DDL/DML (UPDATE, DELETE, INSERT, ALTER, DROP, etc.) são bloqueados
• Comentários SQL são removidos antes da validação

Exemplo:

{
  "query": "SELECT TOP 10 * FROM usuarios WHERE status = @status",
  "params": {
    "status": "ativo"
  }
}

2. getDatabaseMetadata

Consulta metadados do banco de dados com filtros opcionais.

Parâmetros:

• type (string, obrigatório): Tipo de metadado - TABLES, VIEWS, COLUMNS, STORED_PROCEDURES, FUNCTIONS, TRIGGERS, INDEXES, CONSTRAINTS ou SCHEMAS
• filters (object, opcional): Filtros para a consulta

Tipos de Metadados Disponíveis:

TABLES

Consulta tabelas do banco de dados.

• Filtros: TABLE_CATALOG, TABLE_SCHEMA, TABLE_NAME, TABLE_TYPE

VIEWS

Consulta views do banco de dados.

• Filtros: TABLE_CATALOG, TABLE_SCHEMA, TABLE_NAME, VIEW_DEFINITION

COLUMNS

Consulta colunas das tabelas. Obrigatório usar filtro: TABLE_NAME OU COLUMN_NAME

• Filtros: TABLE_CATALOG, TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE, IS_NULLABLE

STORED_PROCEDURES

Consulta stored procedures definidas no banco.

• Filtros: SCHEMA_NAME (opcional), PROCEDURE_NAME (opcional, usa LIKE)

FUNCTIONS

Consulta functions (scalar, table-valued, inline).

• Filtros: SCHEMA_NAME (opcional), FUNCTION_NAME (opcional, usa LIKE), FUNCTION_TYPE (opcional)

TRIGGERS

Consulta triggers vinculados a tabelas.

• Filtros: SCHEMA_NAME (opcional), TRIGGER_NAME (opcional), TABLE_NAME (opcional)

INDEXES

Consulta índices das tabelas.

• Filtros: SCHEMA_NAME (opcional), TABLE_NAME (opcional), INDEX_NAME (opcional)

CONSTRAINTS

Consulta constraints (PK, FK, UNIQUE, CHECK, DEFAULT).

• Filtros: SCHEMA_NAME (opcional), TABLE_NAME (opcional), CONSTRAINT_TYPE (opcional)

SCHEMAS

Consulta schemas criados no banco.

• Sem filtros disponíveis

Exemplos:

// Listar todas as tabelas
{
  "type": "TABLES"
}

// Obter colunas de uma tabela específica
{
  "type": "COLUMNS",
  "filters": {
    "TABLE_NAME": "usuarios"
  }
}

// Buscar colunas que contenham "id" no nome
{
  "type": "COLUMNS", 
  "filters": {
    "COLUMN_NAME": "id"
  }
}

// Listar todas as stored procedures
{
  "type": "STORED_PROCEDURES"
}

// Buscar procedures que referenciam uma tabela específica
{
  "type": "STORED_PROCEDURES",
  "filters": {
    "PROCEDURE_NAME": "%Get%"
  }
}

// Listar triggers de uma tabela
{
  "type": "TRIGGERS",
  "filters": {
    "TABLE_NAME": "usuarios"
  }
}

// Listar constraints de uma tabela
{
  "type": "CONSTRAINTS",
  "filters": {
    "TABLE_NAME": "usuarios"
  }
}

3. searchStoredProcedures

Pesquisa avançada de stored procedures com múltiplas estratégias.

Parâmetros:

• operation (string, obrigatório): Tipo de operação
• Parâmetros específicos conforme a operação

Operações Disponíveis:

SEARCH_PROCEDURES_BY_NAME

Busca procedures por nome (suporta LIKE).

• Parâmetros: name_pattern (obrigatório), schema_name (opcional)

SEARCH_PROCEDURES_BY_TABLE

Busca procedures que referenciam uma tabela específica.

• Parâmetros: table_name (obrigatório), schema_name (opcional)

SEARCH_PROCEDURES_BY_COLUMN

Busca procedures que referenciam uma coluna específica.

• Parâmetros: column_name (obrigatório), schema_name (opcional)

LIST_PROCEDURE_PARAMETERS

Lista parâmetros definidos em uma procedure.

• Parâmetros: procedure_name (obrigatório), schema_name (opcional)

GET_PROCEDURE_DEFINITION

Obtém o código-fonte completo de uma procedure.

• Parâmetros: procedure_name (obrigatório), schema_name (opcional)

4. searchFunctions

Pesquisa avançada de functions com múltiplas estratégias.

Operações Disponíveis:

SEARCH_FUNCTIONS_BY_NAME

Busca functions por nome (suporta LIKE).

• Parâmetros: name_pattern (obrigatório), schema_name (opcional), function_type (opcional)

SEARCH_FUNCTIONS_BY_TABLE

Busca functions que referenciam uma tabela.

• Parâmetros: table_name (obrigatório), schema_name (opcional)

SEARCH_FUNCTIONS_BY_COLUMN

Busca functions que referenciam uma coluna.

• Parâmetros: column_name (obrigatório), schema_name (opcional)

LIST_FUNCTION_PARAMETERS

Lista parâmetros definidos em uma function.

• Parâmetros: function_name (obrigatório), schema_name (opcional)

GET_FUNCTION_DEFINITION

Obtém o código-fonte completo de uma function.

• Parâmetros: function_name (obrigatório), schema_name (opcional), function_type (opcional)

5. searchTriggers

Pesquisa avançada de triggers.

Operações Disponíveis:

SEARCH_TRIGGERS_BY_NAME

Busca triggers por nome (suporta LIKE).

• Parâmetros: name_pattern (obrigatório), schema_name (opcional)

SEARCH_TRIGGERS_BY_TABLE

Busca triggers associados a uma tabela específica.

• Parâmetros: table_name (obrigatório), schema_name (opcional)

GET_TRIGGER_DEFINITION

Obtém o código-fonte completo de um trigger.

• Parâmetros: trigger_name (obrigatório), schema_name (opcional)

🚀 Instalação e Configuração

Requisitos

• Node.js 16+
• SQL Server 2019+ ou Azure SQL Database
• npm ou yarn

Opção 1: Executar Localmente (Desenvolvimento)

1. Clone o repositório:

git clone <url-do-repositorio>
cd mcp-server-sql-database

2. Instale as dependências:

npm install

3. Configure a conexão (.env): Crie um arquivo .env na raiz do projeto com sua connection string:

SQL_DATABASE_CONNECTION_STRING="Server=SEU_SERVIDOR;Database=SEU_BANCO;User Id=SEU_USUARIO;Password=SUA_SENHA;Encrypt=true;TrustServerCertificate=true;"

4. Compile o TypeScript:

npm run build

5. Inicie o servidor MCP:

npm run mcp

Opção 2: Usar via NPM (Recomendado para Produção)

1. Instale o pacote globalmente:

npm install -g haroldorg-mcp-server-sql-database

2. Configure a variável de ambiente:

export SQL_DATABASE_CONNECTION_STRING="Server=SEU_SERVIDOR;Database=SEU_BANCO;..."

3. Execute o servidor:

haroldorg-mcp-server-sql-database

Configuração no VS Code

Adicione ao seu settings.json de usuario:

{
  "mcp": {
    "servers": {
      "haroldorg-mcp-server-sql-database": {
        "type": "stdio",
        "command": "npx",
        "args": ["haroldorg-mcp-server-sql-database"],
        "env": {
          "SQL_DATABASE_CONNECTION_STRING": "Server=SEU_SERVIDOR;Database=SEU_BANCO;User Id=SEU_USUARIO;Password=SUA_SENHA;Encrypt=true;TrustServerCertificate=true;"
        }
      }
    }
  }
}

Ou para desenvolvimento local:

{
  "mcp": {
    "servers": {
      "haroldorg-mcp-server-sql-database": {
        "type": "stdio",
        "command": "node",
        "args": ["C:\\caminho\\completo\\para\\dist\\mcp-server.js"],
        "env": {
          "SQL_DATABASE_CONNECTION_STRING": "Server=SEU_SERVIDOR;Database=SEU_BANCO;User Id=SEU_USUARIO;Password=SUA_SENHA;Encrypt=true;TrustServerCertificate=true;"
        }
      }
    }
  }
}

⚙️ Configuração da Connection String

A connection string deve seguir o formato do SQL Server:

Server=SERVIDOR\\INSTANCIA;Database=NOME_DO_BANCO;User Id=USUARIO;Password=SENHA;Encrypt=true;TrustServerCertificate=true;

Exemplos Práticos:

# Servidor local com instância padrão
Server=localhost;Database=MinhaBase;User Id=usuario;Password=senha123;Encrypt=true;TrustServerCertificate=true;

# Servidor remoto com instância nomeada
Server=servidor.empresa.com\\SQLEXPRESS;Database=Producao;User Id=app_user;Password=minhaSenha;Encrypt=true;TrustServerCertificate=true;

# Autenticação Windows (Integrated Security)
Server=localhost;Database=MinhaBase;Integrated Security=true;Encrypt=true;TrustServerCertificate=true;

# Azure SQL Database
Server=servidor.database.windows.net;Database=MinhaBase;User Id=usuario@servidor;Password=Senha123!;Encrypt=true;TrustServerCertificate=false;

Variáveis de Resiliência (Opcionais)

Configure a reconexão automática com variáveis de ambiente:

# Número máximo de tentativas de reconexão (padrão: 5)
SQL_MAX_RECONNECT_ATTEMPTS=10

# Intervalo entre tentativas em milissegundos (padrão: 5000)
SQL_RECONNECT_DELAY_MS=3000

🔒 Segurança

Proteções Implementadas

• Whitelist de Comandos: Apenas SELECT é permitido
• Bloqueio de Comandos Perigosos: DDL/DML são rejeitados automaticamente
  • Bloqueados: UPDATE, DELETE, INSERT, ALTER, DROP, CREATE, TRUNCATE, MERGE, EXEC, EXECUTE
• Parâmetros SQL: Suporte completo com proteção contra SQL injection
• Remoção de Comentários: Comentários SQL são removidos antes da validação
• Validação Rigorosa: Múltiplas camadas de verificação de segurança
• Conexão Criptografada: Usa Encrypt=true por padrão
• Autenticação: Suporte a autenticação SQL e Windows

Boas Práticas

1. Sempre use parâmetros em vez de concatenar strings
2. Valide filters de metadados obrigatoriamente para COLUMNS
3. Use HTTPS em ambientes de produção com VS Code
4. Restrinja permissões do banco ao mínimo necessário
5. Monitore logs de erro para possíveis tentativas de ataque

📁 Estrutura do Projeto

├── src/
│   ├── app.ts                          # Aplicação Express (opcional)
│   ├── mcp-server.ts                   # Servidor MCP principal
│   ├── sqlPool.ts                      # Pool de conexões com resiliência
│   ├── controllers/
│   │   └── sqlDatabaseController.ts    # Lógica de negócio
│   └── routes/
│       └── sqlDatabaseRoutes.ts        # Rotas Express (opcional)
├── dist/                               # Código compilado
├── package.json
├── tsconfig.json
└── README.md

🧪 Scripts Disponíveis

# Executar em modo desenvolvimento (via Express)
npm start

# Executar servidor MCP (recomendado)
npm run mcp

# Compilar TypeScript para JavaScript
npm run build

# Executar testes (não configurado)
npm test

📝 Exemplos de Uso Avançados

Exemplo 1: Explorar Estrutura de Banco

// 1. Listar todas as tabelas
{
  "name": "getDatabaseMetadata",
  "arguments": {
    "type": "TABLES"
  }
}

// 2. Obter colunas de uma tabela
{
  "name": "getDatabaseMetadata",
  "arguments": {
    "type": "COLUMNS",
    "filters": { "TABLE_NAME": "usuarios" }
  }
}

// 3. Listar constraints da tabela
{
  "name": "getDatabaseMetadata",
  "arguments": {
    "type": "CONSTRAINTS",
    "filters": { "TABLE_NAME": "usuarios" }
  }
}

Exemplo 2: Pesquisar e Obter Code de Procedure

// 1. Buscar procedures que usam uma tabela
{
  "name": "searchStoredProcedures",
  "arguments": {
    "operation": "SEARCH_PROCEDURES_BY_TABLE",
    "table_name": "usuarios"
  }
}

// 2. Obter código-fonte completo
{
  "name": "searchStoredProcedures",
  "arguments": {
    "operation": "GET_PROCEDURE_DEFINITION",
    "procedure_name": "sp_GetUsersByStatus",
    "schema_name": "dbo"
  }
}

// 3. Listar parâmetros da procedure
{
  "name": "searchStoredProcedures",
  "arguments": {
    "operation": "LIST_PROCEDURE_PARAMETERS",
    "procedure_name": "sp_GetUsersByStatus",
    "schema_name": "dbo"
  }
}

Exemplo 3: Pesquisar Functions

// Buscar functions que referenciam uma coluna
{
  "name": "searchFunctions",
  "arguments": {
    "operation": "SEARCH_FUNCTIONS_BY_COLUMN",
    "column_name": "email"
  }
}

// Obter definição de uma function
{
  "name": "searchFunctions",
  "arguments": {
    "operation": "GET_FUNCTION_DEFINITION",
    "function_name": "fn_CalculateAge",
    "schema_name": "dbo"
  }
}

Exemplo 4: Executar Consulta Segura

{
  "name": "executeQuery",
  "arguments": {
    "query": "SELECT id, nome, email, data_criacao FROM usuarios WHERE status = @status AND criado_apos = @data ORDER BY data_criacao DESC",
    "params": {
      "status": "ativo",
      "data": "2024-01-01"
    }
  }
}

🐛 Troubleshooting

Erro: "Conexão recusada"

• ✅ Verifique se o SQL Server está em execução
• ✅ Confirme se o SERVIDOR e DATABASE estão corretos na connection string
• ✅ Teste a conectividade: telnet SERVIDOR 1433

Erro: "Autenticação falhou"

• ✅ Verifique nome de usuário e senha
• ✅ Confirme permissões do usuário no banco
• ✅ Para Integrated Security, execute como administrador

Erro: "Comando não permitido"

• ✅ O servidor só aceita comandos SELECT
• ✅ Não use UPDATE, DELETE, INSERT, ALTER, DROP, CREATE, etc.
• ✅ Verifique se não há comentários SQL na query

Erro: "COLUMNS requer filtro"

• ✅ Ao pesquisar colunas, sempre informe TABLE_NAME OU COLUMN_NAME
• ✅ Use COLUMN_NAME com padrão LIKE para buscas parciais: "%id"

Pool desconecta constantemente

• ✅ Use SQL_MAX_RECONNECT_ATTEMPTS e SQL_RECONNECT_DELAY_MS para tunar
• ✅ Verifique connectivity entre o servidor e o SQL Server
• ✅ Aumente timeouts se estiver em rede lenta

📊 Saída de Exemplo

Consultar Usuários

{
  "result": [
    {
      "id": 1,
      "nome": "João Silva",
      "email": "[email protected]",
      "status": "ativo"
    },
    {
      "id": 2,
      "nome": "Maria Costa",
      "email": "[email protected]",
      "status": "ativo"
    }
  ]
}

Obter Metadados de Colunas

{
  "result": [
    {
      "TABLE_NAME": "usuarios",
      "COLUMN_NAME": "id",
      "DATA_TYPE": "int",
      "IS_NULLABLE": "NO",
      "ORDINAL_POSITION": 1
    },
    {
      "TABLE_NAME": "usuarios",
      "COLUMN_NAME": "email",
      "DATA_TYPE": "varchar",
      "IS_NULLABLE": "NO",
      "ORDINAL_POSITION": 3,
      "CHARACTER_MAXIMUM_LENGTH": 255
    }
  ]
}

🚦 Status de Compilação

• TypeScript: ✅ v4.5+
• Node.js: ✅ v16+
• SQL Server: ✅ 2019+
• MCP SDK: ✅ v1.15+