hs-sql-agent

Un servidor MCP de alto rendimiento para acceso SQL seguro y gobernanza empresarial.

hs-sql-agent conecta clientes MCP con SQLite, PostgreSQL, MySQL, SQL Server, Oracle y Firebird a través de un endpoint MCP HTTP y un Panel de administración integrado.

¿Por qué hs-sql-agent?

En lugar de ejecutar SQL generado por LLM sin restricciones, el servidor analiza el SQL compatible en definiciones estructuradas, lo valida y reconstruye la sentencia final mediante un compilador SQL específico del proveedor.

• Seis proveedores de bases de datos — SQLite, PostgreSQL, MySQL, SQL Server, Oracle y Firebird.

• Acceso gobernado — Vinculación de base de datos por clave, listas blancas de tablas, CORS, límites de velocidad y políticas de ejecución.

• DML seguro — Prueba en seco transaccional seguida de obtención de MCP para la aprobación humana explícita.

• Panel de administración — Gestione bases de datos, claves, roles, herramientas personalizadas, registros de auditoría y políticas de ejecución.

• Listo para la empresa — SSO OIDC, MFA TOTP, retención de auditoría, métricas de Prometheus, OTLP y entrega a webhook/SIEM.

• Metadatos semánticos — Sinónimos de tablas y columnas, relaciones y metadatos de métricas con ámbito para el descubrimiento de esquemas.

La compatibilidad con SQL está limitada intencionadamente: la sintaxis no compatible se rechaza en lugar de cambiar silenciosamente su significado. Consulte la Referencia de herramientas MCP para conocer el contrato SQL compatible.

Related MCP server: safedb-mcp

Inicio rápido

cp .env.example .env
# Set HMAC_KEY and JWT_KEY to unique secrets of at least 32 bytes.
docker compose up -d

Abra el Panel de administración en http://localhost:8080. Las opciones de configuración y las guías de despliegue en producción están documentadas en la Wiki.

Uso con un cliente MCP

Cree una clave MCP en el Panel de administración. El cuadro de diálogo de claves muestra el secreto en texto plano una sola vez y genera configuración para clientes Claude Desktop, Cursor y clientes HTTP Streamable genéricos.

Establezca MCP_PUBLIC_ENDPOINT en la URL MCP accesible externamente, incluida /mcp. Para conocer los requisitos de compatibilidad de clientes, incorporación y obtención de DML, consulte Incorporación de clientes MCP.

NuGet para API .NET existentes

Incruste el Agente SQL MCP y la interfaz de administración opcional en una aplicación ASP.NET Core:

dotnet add package HsSqlAgent.Server

builder.Services.AddHsSqlAgent(options => { ... });
app.UseHsSqlAgent();                    // API only
// app.UseHsSqlAgent().ServeAdminUi();  // API and Admin UI

Consulte la guía del paquete NuGet para obtener detalles de configuración e implementación.

Cómo funciona la ejecución de SQL

1. Autentique la clave MCP y aplique su alcance de base de datos, tabla y políticas.

2. Analice el SQL compatible en una definición estructurada.

3. Valide la definición y compílela para el proveedor de base de datos configurado.

4. Ejecute consultas dentro de los límites configurados.

5. Para DML, realice una prueba en seco en una transacción y solicite la aprobación humana mediante la obtención de MCP antes de confirmar.

Las herramientas SQL personalizadas pasan por el mismo analizador, validación, política de acceso y límites de ejecución que las herramientas integradas. El ciclo de vida, los parámetros y las reglas de publicación están documentados en la guía del Panel de administración.

Documentación

Flujo de ejecución de SQL

Solicitud de aprobación de DML

Así es como se ve el paso de aprobación humana en el bucle durante execute_dml_sql:

Contribuciones

Consulte CONTRIBUTING.md y la guía de desarrollo.

Licencia

Licencia Apache 2.0