hs-sql-agent

hs-sql-agent

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

hs-sql-agent conecta clientes MCP a 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 admitido en definiciones estructuradas, lo valida y reconstruye la declaración 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 tasa y políticas de ejecución.
• DML seguro — Prueba en seco transaccional seguida de Elicitación MCP para 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 empresas — 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 alcance para el descubrimiento de esquemas.

El soporte SQL está intencionalmente limitado: la sintaxis no admitida se rechaza en lugar de cambiar silenciosamente su significado. Consulte la Referencia de herramientas MCP para conocer el contrato SQL admitido.

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 diálogo de clave muestra el secreto en texto plano una sola vez y genera configuración para Claude Desktop, Cursor y clientes Streamable HTTP genéricos.

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

NuGet para APIs .NET existentes

Incruste el Agente SQL MCP y la UI 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 de paquetes NuGet para obtener detalles de configuración y despliegue.

Cómo funciona la ejecución de SQL

1. Autentique la clave MCP y aplique su alcance de base de datos, tablas y políticas.
2. Analice el SQL admitido en una definición estructurada.
3. Valide la definición y compílela para el proveedor de base de datos configurado.
4. Ejecute las consultas dentro de los límites configurados.
5. Para DML, realice una prueba en seco en una transacción y requiera aprobación humana mediante Elicitación 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. Las reglas de ciclo de vida, parámetros y publicación están documentadas en la Guía del Panel de administración.

Documentación

Tema	Documentación
Primeros pasos	Primeros pasos
Configuración	Configuración
Panel de administración	Panel de administración
Herramientas MCP y soporte SQL	Referencia de herramientas MCP
Seguridad, OIDC y MFA	Gobernanza de seguridad
Despliegue y observabilidad	Despliegue · Despliegue distribuido
API	Referencia de API
Solución de problemas	Solución de problemas
Desarrollo	Desarrollo

Flujo de ejecución de SQL

Indicación de aprobación DML

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

Contribuciones

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

Licencia

Apache License 2.0