SqlAugur

SqlAugur

Um servidor MCP que dá aos assistentes de IA acesso seguro e somente leitura a bancos de dados SQL Server. Cada consulta é analisada em uma AST completa usando o parser oficial de T-SQL da Microsoft — não regex — então injeção de comentários, truques com literais de string e bypasses de codificação são bloqueados no nível de sintaxe.

┌──────────────┐          ┌───────────────────────────────────────────┐        ┌──────────────┐
│              │  stdio   │  SqlAugur                                 │        │              │
│  AI Client   │◄────────►│                                           │───────►│  SQL Server  │
│              │          │  ┌────────────┐  ┌──────────────────────┐ │        │              │
└──────────────┘          │  │  Query     │  │  Schema / Diagram /  │ │        └──────────────┘
                          │  │  Validator │  │  DBA Services        │ │
                          │  └────────────┘  └──────────────────────┘ │
                          │  ┌────────────────────────────────────┐   │
                          │  │  Rate Limiter                      │   │
                          │  └────────────────────────────────────┘   │
                          └───────────────────────────────────────────┘

Início Rápido

Use esta ordem para todos os métodos de instalação:

1. Instale o SqlAugur
2. Salve o appsettings.json no local correto
3. Adicione o SqlAugur à configuração do seu cliente MCP
4. Verifique pedindo ao seu assistente para chamar list_servers

Comece com Instalação para comandos exatos e caminhos de arquivos.

Por Que Esta Abordagem

• Validação de consulta em nível de AST — A maioria dos servidores de banco de dados MCP usa bloqueio de palavras-chave ou nenhuma validação. Este projeto analisa cada consulta em uma árvore de sintaxe completa usando o TSql180Parser oficial da Microsoft. Injeção de comentários, truques com literais de string e bypasses de codificação são bloqueados no nível de sintaxe, não com padrões regex frágeis.

• Limitação de taxa — Limitação de throughput com token bucket e controle de concorrência evitam que loops de consulta descontrolados da IA sobrecarreguem servidores SQL Server de produção. Nenhum outro servidor de banco de dados MCP oferece isso.

• Ferramentas de diagnóstico para DBA — Suporte integrado para First Responder Kit, DarlingData e sp_WhoIsActive com bloqueio de parâmetros que impede operações de escrita. Esta é uma categoria totalmente nova de capacidade MCP.

• Otimização do tamanho da resposta — As ferramentas de DBA excluem colunas verbosas (planos de execução XML, gráficos de deadlock, detalhamentos de métricas) e truncam strings longas por padrão, reduzindo o tamanho das respostas em 90–99%. Use os parâmetros verbose e includeQueryPlans para obter saída completa sem truncamento quando necessário.

• Descoberta progressiva — Até 31 ferramentas organizadas em conjuntos que carregam sob demanda. Apenas 6 ferramentas principais são expostas inicialmente, mantendo a janela de contexto da IA pequena e reduzindo o uso de tokens. Conjuntos adicionais de ferramentas são descobertos e habilitados conforme necessário.

Recursos

Segurança

• Somente leitura por design — apenas consultas SELECT e CTE são permitidas
• Validação de consulta baseada em AST usando ScriptDom (não regex)
• Bloqueio de parâmetros em todos os procedimentos armazenados de diagnóstico para evitar escritas
• Limitação de concorrência e throughput

Ferramentas de Banco de Dados

• Suporte a múltiplos servidores — conexões nomeadas para várias instâncias de SQL Server
• Visão geral do esquema — mapas de esquema Markdown concisos com PKs, FKs, constraints e defaults
• Documentação de tabelas — descrições em Markdown de colunas, índices, chaves estrangeiras e constraints
• Geração de diagramas ER — diagramas PlantUML e Mermaid com detecção inteligente de cardinalidade
• Exploração de esquema — listar objetos programáveis, definições de views, propriedades estendidas, grafos de dependência
• Análise de planos de consulta — planos de execução XML estimados ou reais
• Diagnósticos de DBA — integração opcional com First Responder Kit, DarlingData e sp_WhoIsActive com otimização automática do tamanho da resposta
• Descoberta progressiva — modo de conjunto de ferramentas dinâmico reduz o uso inicial da janela de contexto expondo ferramentas sob demanda

Instalação

Todos os métodos produzem o mesmo servidor MCP. Siga esta ordem: instalar, salvar configuração, conectar cliente, verificar.

Ferramenta Global NuGet (recomendado)

1. Instalar (pré-requisito: runtime .NET 10.0)

dotnet tool install -g SqlAugur

2. Salvar arquivo de configuração

# Linux/macOS
mkdir -p ~/.config/sqlaugur
# Edit ~/.config/sqlaugur/appsettings.json with your server connections

# Windows (PowerShell)
mkdir "$env:APPDATA\sqlaugur" -Force
# Edit %APPDATA%\sqlaugur\appsettings.json with your server connections

Exemplo de appsettings.json para salvar nesse local:

{
  "SqlAugur": {
    "Servers": {
      "production": {
        "ConnectionString": "Server=myserver;Database=master;Integrated Security=True;TrustServerCertificate=False;Encrypt=True;"
      }
    }
  }
}

3. Adicionar ao cliente MCP

{
  "mcpServers": {
    "sqlaugur": {
      "command": "sqlaugur"
    }
  }
}

Para atualizar: dotnet tool update -g SqlAugur

Docker / Podman

1. Executar o contêiner SqlAugur

# Volume-mount a config file
docker run -i --rm \
  -v /path/to/appsettings.json:/app/appsettings.json:ro,Z \
  ghcr.io/mbentham/sqlaugur:latest

# Or use environment variables (no config file needed)
docker run -i --rm \
  -e SqlAugur__Servers__production__ConnectionString="Server=host.docker.internal;Database=master;..." \
  ghcr.io/mbentham/sqlaugur:latest

Nota: Para acessar um SQL Server na máquina host, use host.docker.internal (Docker Desktop) ou --network=host (Linux). Substitua docker por podman — todos os comandos são idênticos. A flag :Z em montagens de volume é necessária para sistemas com SELinux habilitado (Fedora, RHEL); usuários de Docker Desktop no macOS/Windows podem omiti-la.

Se você montar um arquivo de configuração, salve-o como /path/to/appsettings.json e monte-o em /app/appsettings.json.

2. Adicionar ao cliente MCP

{
  "mcpServers": {
    "sqlaugur": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-v", "/path/to/appsettings.json:/app/appsettings.json:ro,Z",
        "ghcr.io/mbentham/sqlaugur:latest"]
    }
  }
}

services:
  sqlaugur:
    image: ghcr.io/mbentham/sqlaugur:latest
    stdin_open: true
    volumes:
      - ./appsettings.json:/app/appsettings.json:ro,Z

{
  "mcpServers": {
    "sqlaugur": {
      "command": "docker",
      "args": ["compose", "run", "-i", "--rm", "sqlaugur"]
    }
  }
}

Compilar a partir do Código-Fonte

1. Compilar (pré-requisito: SDK .NET 10.0)

git clone git@github.com:mbentham/SqlAugur.git
cd SqlAugur
dotnet publish SqlAugur -c Release -o SqlAugur/publish

2. Salvar arquivo de configuração

# Linux/macOS
cp SqlAugur/appsettings.example.json SqlAugur/publish/appsettings.json
# Edit SqlAugur/publish/appsettings.json with your server connections

# Windows (PowerShell)
Copy-Item SqlAugur\appsettings.example.json SqlAugur\publish\appsettings.json
# Edit SqlAugur\publish\appsettings.json with your server connections

3. Adicionar ao cliente MCP

{
  "mcpServers": {
    "sqlaugur": {
      "command": "dotnet",
      "args": ["/absolute/path/to/SqlAugur/publish/SqlAugur.dll"]
    }
  }
}

Verificar a conexão MCP (primeiro com LLM)

Após reiniciar seu cliente MCP, pergunte ao assistente:

• Call list_servers
• Call list_databases for server "production"

Resultado esperado:

• list_servers retorna o nome do servidor configurado (por exemplo, production)
• list_databases retorna um array JSON de bancos de dados, não um erro de conexão ou autenticação

Se a verificação falhar:

1. Confirme que a configuração MCP executa o comando esperado (sqlaugur, docker run ... ou dotnet /path/to/SqlAugur.dll)
2. Confirme que o appsettings.json está salvo onde seu método de instalação espera:
   • Ferramenta local: ~/.config/sqlaugur/appsettings.json (Linux/macOS) ou %APPDATA%\sqlaugur\appsettings.json (Windows)
   • Contêiner: montado em /app/appsettings.json
   • Compilação a partir do código-fonte: ao lado da DLL publicada (SqlAugur/publish/appsettings.json)
3. Confirme que a chamada de ferramenta usa uma chave de servidor configurada (por exemplo, production)
4. Confirme a conectividade SQL e a autenticação na string de conexão

Configuração

O servidor carrega a configuração de múltiplas fontes. Fontes de prioridade mais alta substituem as de prioridade mais baixa:

1. Argumentos de linha de comando
2. Variáveis de ambiente — usando __ como delimitador de seção (ex.: SqlAugur__Servers__production__ConnectionString=...)
3. Diretório de trabalho atual — appsettings.json no diretório de onde você executa o comando
4. Diretório de configuração do usuário — ~/.config/sqlaugur/appsettings.json no Linux, %APPDATA%\sqlaugur\appsettings.json no Windows
5. Azure Key Vault — quando AzureKeyVaultUri está definido (veja abaixo)
6. Diretório do aplicativo — appsettings.json ao lado da DLL

Exemplo de configuração (Autenticação do Windows — recomendado):

{
  "SqlAugur": {
    "Servers": {
      "production": {
        "ConnectionString": "Server=myserver;Database=master;Integrated Security=True;TrustServerCertificate=False;Encrypt=True;"
      }
    },
    "MaxRows": 1000,
    "CommandTimeoutSeconds": 30,
    "MaxConcurrentQueries": 5,
    "MaxQueriesPerMinute": 60,
    "EnableFirstResponderKit": false,
    "EnableDarlingData": false,
    "EnableWhoIsActive": false,
    "EnableDynamicToolsets": false
  }
}

Nota de Segurança: appsettings.json está no gitignore para evitar commits acidentais de credenciais. Veja SECURITY.md para métodos de autenticação recomendados, incluindo Autenticação do Windows, Azure Managed Identity e opções seguras de armazenamento de credenciais.

Ferramentas

O servidor fornece 31 ferramentas organizadas em conjuntos. Seis ferramentas principais estão sempre disponíveis. Conjuntos adicionais são carregados na inicialização (modo estático) ou sob demanda (modo dinâmico).

Ferramentas Principais

Ferramentas de Diagnóstico para DBA

Cada kit de ferramentas é habilitado independentemente via flags de configuração e requer os procedimentos armazenados correspondentes instalados no SQL Server de destino.

Todas as ferramentas de DBA aplicam otimização do tamanho da resposta por padrão — colunas de planos de execução XML são excluídas e valores de strings longas são truncados para manter as respostas dentro dos limites da janela de contexto da IA. Cada ferramenta suporta estes parâmetros opcionais:

Algumas ferramentas têm parâmetros adicionais: includeXmlReports (BlitzLock, HealthParser, HumanEventsBlockViewer), compact (sp_WhoIsActive), verboseMetrics (QuickieStore).

Descoberta Progressiva

Quando EnableDynamicToolsets é verdadeiro, apenas as ferramentas principais são carregadas na inicialização. Três meta-ferramentas permitem que a IA descubra e habilite conjuntos de ferramentas adicionais sob demanda, reduzindo o uso inicial da janela de contexto:

Fluxo de exemplo:

1. A IA chama list_toolsets — vê que first_responder_kit está "disponível" (configurado, mas ainda não habilitado)
2. A IA chama get_toolset_tools("first_responder_kit") — revisa as 7 ferramentas e seus parâmetros
3. A IA chama enable_toolset("first_responder_kit") — as 7 ferramentas agora estão registradas e utilizáveis
4. A IA chama sp_blitz — executa a verificação de saúde normalmente

No modo estático (EnableDynamicToolsets: false), todos os conjuntos de ferramentas habilitados são carregados na inicialização e as ferramentas de descoberta não são registradas. Os conjuntos de ferramentas Schema Exploration e Diagrams são sempre carregados independentemente do modo.

Limitação conhecida: A descoberta progressiva depende da notificação notifications/tools/list_changed do MCP para informar aos clientes que novas ferramentas foram registradas. O Claude Code atualmente não trata essa notificação (anthropics/claude-code#4118), portanto, conjuntos de ferramentas habilitados dinamicamente não aparecerão. Use o modo estático (EnableDynamicToolsets: false) ao usar o Claude Code.

Segurança

Validação de Consulta

Cada consulta é analisada em uma Árvore Sintática Abstrata (AST) usando o TSql180Parser oficial da Microsoft e deve passar pelas seguintes regras:

• Apenas uma instrução — múltiplas instruções são rejeitadas
• Somente SELECT — INSERT, UPDATE, DELETE, DROP, EXEC, CREATE, ALTER e todos os outros tipos de instrução são bloqueados
• Sem SELECT INTO — impede a criação de tabelas via SELECT
• Sem acesso a dados externos — OPENROWSET (todas as variantes, incluindo BULK, Cosmos DB e internas), OPENQUERY, OPENDATASOURCE, OPENXML bloqueados
• Sem servidores vinculados — referências de nomes de quatro partes são rejeitadas
• Sem dica MAXRECURSION — impede a substituição do limite de recursão padrão
• Consultas entre bancos de dados são permitidas — nomes de três partes funcionam por design; o limite de segurança é o servidor, não o banco de dados. Para restringir a um único banco de dados, limite as permissões do login.

Como a validação opera na AST analisada, ela lida corretamente com casos extremos que derrotam abordagens baseadas em strings: palavras-chave dentro de comentários, literais de string, comentários de bloco aninhados e truques de codificação.

Bloqueio de Parâmetros

Procedimentos armazenados de diagnóstico são executados por meio de nomes de procedimentos na lista de permissões com parâmetros bloqueados que impedem gravações:

• First Responder Kit — todos os parâmetros @Output* bloqueados (impede a gravação de resultados em tabelas do servidor)
• DarlingData — parâmetros de log e saída bloqueados (impede a criação de tabelas e a retenção de dados)
• sp_WhoIsActive — @destination_table, @return_schema, @schema, @help bloqueados

Limitação de Taxa

Todas as execuções de ferramentas estão sujeitas a limitação de concorrência (MaxConcurrentQueries, padrão 5) e limitação de taxa de transferência (MaxQueriesPerMinute, padrão 60). Solicitações em excesso são rejeitadas com uma mensagem de nova tentativa.

Segurança de Conexão

Use Autenticação do Windows ou Identidade Gerenciada do Azure quando possível para evitar armazenar credenciais em arquivos de configuração. Quando a Autenticação SQL for necessária, use substituições de variáveis de ambiente para injetar credenciais em tempo de execução. Consulte SECURITY.md para obter orientações detalhadas, incluindo armazenamentos de credenciais e criptografia de strings de conexão.

Riscos Conhecidos

• Este projeto depende do SDK C# do MCP oficial da Microsoft (pacote NuGet ModelContextProtocol, versão 1.3.0). Como o framework MCP lida com toda a E/S de protocolo, qualquer vulnerabilidade nele afeta diretamente o limite de segurança deste aplicativo. Monitore o pacote em busca de atualizações e faça upgrade quando novas versões forem lançadas.
• Os dados retornados de uma consulta do SQL Server podem incluir injeção maliciosa de prompt direcionada a IAs. Este é um risco de todo uso de IA e não pode ser mitigado por este projeto. Certifique-se de seguir as melhores práticas de segurança de IA e conectar-se apenas a fontes de dados confiáveis.

Contribuindo

Contribuições são bem-vindas. Consulte CONTRIBUTING.md para detalhes de arquitetura, configuração de desenvolvimento, instruções de teste e diretrizes para adicionar novas ferramentas.

Licença

MIT