hs-sql-agent

Ein Hochleistungs-MCP-Server für sicheren SQL-Zugriff und Enterprise-Governance.

hs-sql-agent verbindet MCP-Clients mit SQLite, PostgreSQL, MySQL, SQL Server, Oracle und Firebird über einen HTTP-MCP-Endpunkt und ein integriertes Admin-Panel.

Warum hs-sql-agent?

Statt uneingeschränktes LLM-generiertes SQL auszuführen, parst der Server unterstütztes SQL in strukturierte Definitionen, validiert es und erstellt die endgültige Anweisung über einen anbieterspezifischen SQL-Compiler neu.

• Sechs Datenbankanbieter — SQLite, PostgreSQL, MySQL, SQL Server, Oracle und Firebird.

• Gesteuerter Zugriff — Datenbankbindung pro Schlüssel, Tabellen-Whitelisting, CORS, Ratenbegrenzungen und Ausführungsrichtlinien.

• Sicheres DML — Transaktionaler Probelauf, gefolgt von MCP-Elicitation zur expliziten menschlichen Genehmigung.

• Admin-Panel — Verwalten Sie Datenbanken, Schlüssel, Rollen, benutzerdefinierte Tools, Audit-Aufzeichnungen und Laufzeitrichtlinien.

• Enterprise-tauglich — OIDC-SSO, TOTP-MFA, Audit-Aufbewahrung, Prometheus-Metriken, OTLP und Webhook-/SIEM-Zustellung.

• Semantische Metadaten — Synonyme für Tabellen und Spalten, Beziehungen und bereichsbezogene Metrik-Metadaten für die Schema-Erkennung.

Die SQL-Unterstützung ist bewusst begrenzt: Nicht unterstützte Syntax wird abgelehnt, anstatt ihre Bedeutung stillschweigend zu verändern. Siehe die MCP-Tools-Referenz für den unterstützten SQL-Vertrag.

Related MCP server: safedb-mcp

Schnellstart

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

Öffnen Sie das Admin-Panel unter http://localhost:8080. Konfigurationsoptionen und Hinweise zur Produktionsbereitstellung sind im Wiki dokumentiert.

Verwendung mit einem MCP-Client

Erstellen Sie einen MCP-Schlüssel im Admin-Panel. Der Schlüsseldialog zeigt das Klartext-Geheimnis einmal an und generiert Konfigurationen für Claude Desktop, Cursor und generische Streamable-HTTP-Clients.

Setzen Sie MCP_PUBLIC_ENDPOINT auf die extern erreichbare MCP-URL, einschließlich /mcp. Informationen zu Client-Kompatibilität, Onboarding und DML-Elicitation-Anforderungen finden Sie unter MCP-Client-Onboarding.

NuGet für bestehende .NET-APIs

Betten Sie den MCP-SQL-Agenten und die optionale Admin-UI in eine ASP.NET-Core-Anwendung ein:

dotnet add package HsSqlAgent.Server

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

Weitere Details zu Konfiguration und Bereitstellung finden Sie im NuGet-Paket-Leitfaden.

So funktioniert die SQL-Ausführung

1. Authentifizieren Sie den MCP-Schlüssel und wenden Sie dessen Datenbank-, Tabellen- und Richtlinienbereich an.

2. Parsen Sie unterstütztes SQL in eine strukturierte Definition.

3. Validieren Sie die Definition und kompilieren Sie sie für den konfigurierten Datenbankanbieter.

4. Führen Sie Abfragen innerhalb der konfigurierten Grenzen aus.

5. Führen Sie bei DML einen Probelauf in einer Transaktion durch und verlangen Sie vor dem Commit eine menschliche Genehmigung über MCP-Elicitation.

Benutzerdefinierte SQL-Tools durchlaufen denselben Parser, dieselbe Validierung, dieselbe Zugriffsrichtlinie und dieselben Ausführungsgrenzen wie integrierte Tools. Lebenszyklus-, Parameter- und Veröffentlichungsregeln sind im Admin-Panel-Leitfaden dokumentiert.

Dokumentation

SQL-Ausführungsablauf

DML-Genehmigungsaufforderung

So sieht der Genehmigungsschritt mit menschlicher Beteiligung während execute_dml_sql aus:

Mitwirken

Siehe CONTRIBUTING.md und den Entwicklungsleitfaden.

Lizenz

Apache-Lizenz 2.0