SqlAugur

SqlAugur

Un servidor MCP que brinda a los asistentes de IA acceso seguro y de solo lectura a bases de datos SQL Server. Cada consulta se analiza en un AST completo utilizando el analizador T-SQL oficial de Microsoft, no expresiones regulares, por lo que la inyección de comentarios, los trucos con cadenas literales y los bypass de codificación se bloquean a nivel de sintaxis.

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

Inicio rápido

Use este orden para todos los métodos de instalación:

1. Instale SqlAugur
2. Guarde appsettings.json en la ubicación correcta
3. Agregue SqlAugur a la configuración de su cliente MCP
4. Verifique pidiendo a su asistente que llame a list_servers

Comience con Instalación para comandos y rutas de archivo exactos.

Por qué este enfoque

• Validación de consultas a nivel de AST — La mayoría de los servidores de bases de datos MCP usan bloqueo de palabras clave o ninguna validación. Este proyecto analiza cada consulta en un árbol de sintaxis completo usando el TSql180Parser oficial de Microsoft. La inyección de comentarios, los trucos con cadenas literales y los bypass de codificación se bloquean a nivel de sintaxis, no con patrones de expresiones regulares frágiles.

• Limitación de velocidad — La limitación de rendimiento con token bucket y el control de concurrencia evitan que los bucles de consultas descontrolados de la IA abrumen los SQL Server de producción. Ningún otro servidor de bases de datos MCP ofrece esto.

• Herramientas de diagnóstico para DBA — Soporte integrado para First Responder Kit, DarlingData y sp_WhoIsActive con bloqueo de parámetros que previene operaciones de escritura. Esta es una categoría de capacidad MCP completamente nueva.

• Optimización del tamaño de respuesta — Las herramientas de DBA excluyen columnas verbosas (planes de consulta XML, gráficos de interbloqueo, desgloses de métricas) y truncan cadenas largas por defecto, reduciendo los tamaños de respuesta en un 90–99%. Use los parámetros verbose y includeQueryPlans para obtener salida completa sin truncar cuando sea necesario.

• Descubrimiento progresivo — Hasta 31 herramientas organizadas en conjuntos de herramientas que se cargan bajo demanda. Solo se exponen inicialmente 6 herramientas principales, manteniendo la ventana de contexto de la IA pequeña y reduciendo el uso de tokens. Los conjuntos de herramientas adicionales se descubren y habilitan según sea necesario.

Características

Seguridad

• Solo lectura por diseño — solo se permiten consultas SELECT y CTE
• Validación de consultas basada en AST usando ScriptDom (no expresiones regulares)
• Bloqueo de parámetros en todos los procedimientos almacenados de diagnóstico para prevenir escrituras
• Limitación de concurrencia y rendimiento

Herramientas de base de datos

• Soporte multi-servidor — conexiones nombradas a múltiples instancias de SQL Server
• Resumen de esquema — mapas de esquema Markdown concisos con PKs, FKs, restricciones y valores predeterminados
• Documentación de tablas — descripciones Markdown de columnas, índices, claves foráneas y restricciones
• Generación de diagramas ER — diagramas PlantUML y Mermaid con detección inteligente de cardinalidad
• Exploración de esquema — listar objetos programables, definiciones de vistas, propiedades extendidas, gráficos de dependencias
• Análisis de planes de consulta — planes de ejecución XML estimados o reales
• Diagnósticos de DBA — integración opcional con First Responder Kit, DarlingData y sp_WhoIsActive con optimización automática del tamaño de respuesta
• Descubrimiento progresivo — modo de conjunto de herramientas dinámico reduce el uso inicial de la ventana de contexto al exponer herramientas bajo demanda

Instalación

Todos los métodos producen el mismo servidor MCP. Siga este orden: instalar, guardar configuración, conectar cliente, verificar.

Herramienta global NuGet (recomendada)

1. Instalar (requisito previo: runtime .NET 10.0)

dotnet tool install -g SqlAugur

2. Guardar archivo de configuración

# 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

Ejemplo de appsettings.json para guardar en esa ubicación:

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

3. Agregar al cliente MCP

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

Para actualizar: dotnet tool update -g SqlAugur

Docker / Podman

1. Ejecutar el contenedor 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 alcanzar un SQL Server en la máquina host, use host.docker.internal (Docker Desktop) o --network=host (Linux). Reemplace docker con podman — todos los comandos son idénticos. El indicador :Z en los montajes de volumen es necesario para sistemas con SELinux habilitado (Fedora, RHEL); los usuarios de Docker Desktop en macOS/Windows pueden omitirlo.

Si monta un archivo de configuración, guárdelo como /path/to/appsettings.json y móntelo en /app/appsettings.json.

2. Agregar al 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 desde el código fuente

1. Compilar (requisito previo: SDK .NET 10.0)

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

2. Guardar archivo de configuración

# 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. Agregar al cliente MCP

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

Verificar la conexión MCP (priorizando LLM)

Después de reiniciar su cliente MCP, pregunte al asistente:

• Call list_servers
• Call list_databases for server "production"

Resultado esperado:

• list_servers devuelve el nombre de su servidor configurado (por ejemplo production)
• list_databases devuelve una matriz JSON de bases de datos, no un error de conexión o autenticación

Si la verificación falla:

1. Confirme que la configuración MCP ejecuta el comando esperado (sqlaugur, docker run ... o dotnet /path/to/SqlAugur.dll)
2. Confirme que appsettings.json está guardado donde su método de instalación lo espera:
   • Herramienta local: ~/.config/sqlaugur/appsettings.json (Linux/macOS) o %APPDATA%\sqlaugur\appsettings.json (Windows)
   • Contenedor: montado en /app/appsettings.json
   • Compilación desde fuente: junto al DLL publicado (SqlAugur/publish/appsettings.json)
3. Confirme que la llamada a la herramienta usa una clave de servidor configurada (por ejemplo production)
4. Confirme la conectividad SQL y la autenticación en la cadena de conexión

Configuración

El servidor carga la configuración de múltiples fuentes. Las fuentes de mayor prioridad anulan a las de menor:

1. Argumentos de línea de comandos
2. Variables de entorno — usando __ como delimitador de sección (p. ej., SqlAugur__Servers__production__ConnectionString=...)
3. Directorio de trabajo actual — appsettings.json en el directorio desde el que ejecuta el comando
4. Directorio de configuración del usuario — ~/.config/sqlaugur/appsettings.json en Linux, %APPDATA%\sqlaugur\appsettings.json en Windows
5. Azure Key Vault — cuando AzureKeyVaultUri está configurado (ver más abajo)
6. Directorio de la aplicación — appsettings.json junto al DLL

Ejemplo de configuración (Autenticación de Windows — recomendada):

{
  "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 seguridad: appsettings.json está en gitignore para prevenir confirmaciones accidentales de credenciales. Consulte SECURITY.md para métodos de autenticación recomendados, incluidos Autenticación de Windows, Azure Managed Identity y opciones seguras de almacenamiento de credenciales.

Herramientas

El servidor proporciona 31 herramientas organizadas en conjuntos de herramientas. Seis herramientas principales están siempre disponibles. Los conjuntos de herramientas adicionales se cargan al inicio (modo estático) o bajo demanda (modo dinámico).

Herramientas principales

Herramientas de diagnóstico para DBA

Cada kit de herramientas se habilita independientemente mediante indicadores de configuración y requiere que los procedimientos almacenados correspondientes estén instalados en el SQL Server de destino.

Todas las herramientas de DBA aplican optimización del tamaño de respuesta por defecto — las columnas de planes de consulta XML se excluyen y los valores de cadenas largas se truncan para mantener las respuestas dentro de los límites de la ventana de contexto de la IA. Cada herramienta soporta estos parámetros opcionales:

Algunas herramientas tienen parámetros adicionales: includeXmlReports (BlitzLock, HealthParser, HumanEventsBlockViewer), compact (sp_WhoIsActive), verboseMetrics (QuickieStore).

Descubrimiento Progresivo

Cuando EnableDynamicToolsets es verdadero, solo las herramientas principales se cargan al inicio. Tres meta-herramientas permiten que la IA descubra y habilite conjuntos de herramientas adicionales bajo demanda, reduciendo el uso inicial de la ventana de contexto:

Flujo de ejemplo:

1. La IA llama a list_toolsets — ve que first_responder_kit está "disponible" (configurado pero aún no habilitado)
2. La IA llama a get_toolset_tools("first_responder_kit") — revisa las 7 herramientas y sus parámetros
3. La IA llama a enable_toolset("first_responder_kit") — las 7 herramientas ahora están registradas y utilizables
4. La IA llama a sp_blitz — ejecuta la verificación de salud como de costumbre

En modo estático (EnableDynamicToolsets: false), todos los conjuntos de herramientas habilitados se cargan al inicio y las herramientas de descubrimiento no se registran. Los conjuntos de herramientas de Exploración de Esquemas y Diagramas siempre se cargan independientemente del modo.

Limitación conocida: El descubrimiento progresivo depende de la notificación MCP notifications/tools/list_changed para informar a los clientes que se han registrado nuevas herramientas. Claude Code actualmente no maneja esta notificación (anthropics/claude-code#4118), por lo que los conjuntos de herramientas habilitados dinámicamente no aparecerán. Use el modo estático (EnableDynamicToolsets: false) cuando use Claude Code.

Seguridad

Validación de Consultas

Cada consulta se analiza en un Árbol de Sintaxis Abstracta (AST) usando el TSql180Parser oficial de Microsoft y debe pasar estas reglas:

• Solo una declaración — se rechazan múltiples declaraciones
• Solo SELECT — INSERT, UPDATE, DELETE, DROP, EXEC, CREATE, ALTER y todos los demás tipos de declaraciones están bloqueados
• Sin SELECT INTO — evita la creación de tablas mediante SELECT
• Sin acceso a datos externos — OPENROWSET (todas las variantes incluyendo BULK, Cosmos DB e internas), OPENQUERY, OPENDATASOURCE, OPENXML bloqueados
• Sin servidores vinculados — se rechazan referencias de nombres de cuatro partes
• Sin sugerencia MAXRECURSION — evita anular el límite de recursión predeterminado
• Se permiten consultas entre bases de datos — los nombres de tres partes funcionan por diseño; el límite de seguridad es el servidor, no la base de datos. Para restringir a una sola base de datos, limite los permisos del inicio de sesión.

Debido a que la validación opera en el AST analizado, maneja correctamente casos límite que derrotan los enfoques basados en cadenas: palabras clave dentro de comentarios, literales de cadena, comentarios de bloque anidados y trucos de codificación.

Bloqueo de Parámetros

Los procedimientos almacenados de diagnóstico se ejecutan mediante nombres de procedimientos en lista blanca con parámetros bloqueados que evitan escrituras:

• First Responder Kit — todos los parámetros @Output* bloqueados (evita escribir resultados en tablas del servidor)
• DarlingData — parámetros de registro y salida bloqueados (evita la creación de tablas y la retención de datos)
• sp_WhoIsActive — @destination_table, @return_schema, @schema, @help bloqueados

Limitación de Velocidad

Todas las ejecuciones de herramientas están sujetas a limitación de concurrencia (MaxConcurrentQueries, predeterminado 5) y limitación de rendimiento (MaxQueriesPerMinute, predeterminado 60). Las solicitudes excesivas se rechazan con un mensaje de reintento.

Seguridad de Conexión

Use Autenticación de Windows o Identidad Administrada de Azure cuando sea posible para evitar almacenar credenciales en archivos de configuración. Cuando se requiera Autenticación SQL, use anulaciones de variables de entorno para inyectar credenciales en tiempo de ejecución. Consulte SECURITY.md para obtener orientación detallada, incluidos almacenes de credenciales y cifrado de cadenas de conexión.

Riesgos Conocidos

• Este proyecto depende del MCP C# SDK oficial de Microsoft (paquete NuGet ModelContextProtocol, versión 1.3.0). Como el marco MCP maneja toda la E/S del protocolo, cualquier vulnerabilidad en él afecta directamente el límite de seguridad de esta aplicación. Monitoree el paquete para actualizaciones y actualice cuando se publiquen nuevas versiones.
• Los datos devueltos de una consulta de SQL Server podrían incluir inyección de indicaciones maliciosa dirigida a IAs. Este es un riesgo de todo uso de IA y no puede mitigarse con este proyecto. Asegúrese de seguir las mejores prácticas de seguridad de IA y conéctese solo a fuentes de datos confiables.

Contribuciones

Las contribuciones son bienvenidas. Consulte CONTRIBUTING.md para detalles de arquitectura, configuración de desarrollo, instrucciones de prueba y pautas para agregar nuevas herramientas.

Licencia

MIT