hs-sql-agent

Servidor MCP de agente SQL en C# con entrada SQL sin procesar, validación estricta de AST y una interfaz de administración integrada. Elimina las alucinaciones de LLM y los riesgos de seguridad en 6 bases de datos principales.

GitHub

Prueba este MCPPatrocinado

Documentación

hs-sql-agent

Convierte SQL confiable en herramientas MCP gobernadas para agentes de IA.

hs-sql-agent es una fábrica de herramientas SQL-a-MCP de código abierto y un límite de ejecución SQL gobernado. Define SQL parametrizado en la interfaz de administración, publícalo como una herramienta MCP tipada, y permite que los agentes de IA proporcionen solo los argumentos — sin escribir un nuevo método en C# ni redesplegar tu servidor MCP para cada operación de base de datos.

Cada herramienta publicada sigue pasando por el mismo compilador SQL de cierre ante fallos, la política por clave de base de datos/tabla, los límites de ejecución, el registro de auditoría y los controles de aprobación de DML seguro. Las herramientas SQL sin procesar siguen disponibles para casos donde un agente realmente necesite consultas ad-hoc flexibles.

Soporta PostgreSQL, MySQL, SQL Server, Oracle, SQLite y Firebird y puede ejecutarse como el servidor completo de primera parte con su interfaz de administración o integrarse en una aplicación ASP.NET Core existente.

Publica SQL como una herramienta MCP

En lugar de enseñar al modelo a regenerar la misma consulta cada vez, define la forma del SQL una sola vez:

SELECT id, total, status
FROM orders
WHERE customer_id = {{ customerId }}
  AND status = {{ status }}

Declara customerId y status en Runtime → Herramientas personalizadas, prueba el borrador y luego publícalo. hs-sql-agent expone la definición publicada a los clientes MCP como una herramienta nombrada con un esquema de entrada JSON generado.

El agente ve un contrato conceptualmente como:

get_customer_orders(
  customerId: number,
  status: string
)

La plantilla SQL permanece definida por el ingeniero. Los marcadores de posición son solo parámetros de valor; los identificadores y fragmentos SQL arbitrarios no pueden inyectarse a través de ellos.

Las herramientas personalizadas publicadas pueden ser herramientas de Consulta o DML. Las herramientas de consulta usan el mismo compilador tipado y la ruta de política de acceso que la ejecución SQL integrada. Las herramientas DML usan el mismo protocolo de vista previa → aprobación → revalidación → confirmación, incluyendo transacciones atómicas de múltiples sentencias.

¿Por qué hs-sql-agent?

Herramientas personalizadas SQL-a-MCP — Convierte plantillas SQL revisadas por ingenieros en herramientas MCP descubribles con parámetros tipados, descripciones, ciclo de vida de borrador/prueba/publicación, revisiones, reversión y vinculación a bases de datos.
Compilador SQL de cierre ante fallos — La sintaxis no soportada o no comprobada se rechaza en lugar de reescribirse silenciosamente con semántica diferente.
Núcleo compilador F# cerrado — El SQL entra en un AST cerrado de unión discriminada y avanza a través de etapas de compilador parsed → bound → canonical → validated → executable infalsificables.
Seis proveedores de bases de datos — PostgreSQL, MySQL, SQL Server, Oracle, SQLite y Firebird con validación y reducción conscientes del proveedor.
DML seguro — Vista previa de impacto de solo lectura, desafío de aprobación de una sola vez, revalidación del conjunto de filas al confirmar y aprobación humana explícita mediante Elicitación MCP o un proveedor de aprobación.
Acceso gobernado — Vinculación de base de datos por clave, listas blancas de tablas, límites de tasa, límites de ejecución, roles, políticas y registros de auditoría.
Alojamiento flexible — Ejecuta el servidor empaquetado y la interfaz de administración, usa el host estándar ASP.NET Core o compón integraciones avanzadas a partir de capacidades modulares.
Observabilidad de producción — Métricas Prometheus, OpenTelemetry/OTLP, retención de auditoría y entrega webhook/SIEM.

El soporte SQL está intencionalmente limitado a semántica comprobada. Consulta la Referencia de soporte SQL para el contrato actual.

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

Abre la interfaz de administración en http://localhost:8080.

Para configuraciones de producción y opciones de despliegue, usa la Referencia de configuración y la Guía de despliegue.

Uso con un cliente MCP

Establece MCP_PUBLIC_ENDPOINT a la URL MCP accesible externamente, incluyendo /mcp, antes de emitir claves de producción.

Luego abre Runtime → Claves MCP en la interfaz de administración y emite una clave. El diálogo único de Guardar y conectar genera configuración lista para pegar para Claude Desktop, Cursor, Visual Studio Code y clientes genéricos de Streamable HTTP.

El secreto en texto plano se muestra solo una vez. Consulta Incorporación de clientes MCP para la configuración del cliente, compatibilidad y requisitos de Elicitación DML.

Uso desde .NET

Para la misma composición completa que el host oficial de Docker, instala HsSqlAgent.Hosting:

dotnet add package HsSqlAgent.Hosting

using HsSqlAgent.Hosting;

var builder = WebApplication.CreateBuilder(args);
builder.AddHsSqlAgentStandardHost();

var app = builder.Build();
app.UseHsSqlAgentStandardHost();

await app.RunAsync();

Usa HsSqlAgent.Server directamente solo cuando necesites autenticación personalizada, orden de middleware, proveedores de aprobación, interfaz de usuario o composición de capacidades.

Consulta la Guía de integración ASP.NET Core y el README del paquete HsSqlAgent.Hosting para el contrato de integración completo.

Cómo funciona la ejecución SQL

Autentica la clave MCP y establece su alcance de base de datos, tabla, herramienta y política de ejecución.
Para herramientas personalizadas, resuelve la definición publicada y renderiza los parámetros de valor declarados en la plantilla SQL definida por el ingeniero.
Analiza el SQL en el modelo de compilador cerrado y vincula la semántica de origen.
Normaliza y valida sintaxis, semántica, capacidades y política.
Renderiza solo un tipado de estado ejecutable en SQL y parámetros específicos del proveedor.
Ejecuta dentro de los límites de ejecución configurados.

El núcleo del compilador es independiente de los controladores de proveedor: el análisis, la validación, la normalización, la prueba de capacidad, la reducción y el renderizado se mantienen separados de los controladores de base de datos y la ejecución en tiempo de ejecución.

Para DML, hs-sql-agent primero construye una vista previa de impacto de solo lectura, vincula la aprobación al plan validado y al conjunto de filas coincidentes, requiere aprobación humana explícita y revalida dentro de la transacción de confirmación antes de aplicar la mutación.

Las herramientas SQL personalizadas pasan por el mismo compilador, política de acceso y límites de ejecución que las herramientas integradas.

Flujo de ejecución SQL

Mensaje de aprobación DML

Documentación

El sitio de documentación es la fuente de verdad para la configuración detallada, integración, capacidad SQL, seguridad y guía de operaciones:

Contribuciones

Consulta CONTRIBUTING.md y el Flujo de arquitectura y contribuciones.

Licencia

Licencia Apache 2.0