Upgrade-Leitfaden | hs-sql-agent

Was ändert sich in 2.0.5?

2.0.5 konzentriert sich auf Agent DX, Erklärbarkeit und Deployment Readiness. Die fünf eingebauten MCP-Tools liefern maschinenlesbare strukturierte Ergebnisse. Zusätzlich kommen der compile-only SQL Explain / Policy Simulator, Configuration Doctor und ein einheitlicher Weg bis zur ersten governed agent request hinzu.

Die fail-closed Grenzen werden dabei nicht gelockert: SQL Compiler, Provider-Capability-Prüfungen, Table/Tool Authorization, DML Approval, row-set revalidation, Rollback und server-owned transactions bleiben unverändert sicherheitskritische Servergrenzen.

Die fünf Built-ins bleiben get_schemas, get_tables, get_columns, execute_query_sql und execute_dml_sql.

Migration auf strukturierte MCP-Ergebnisse

Alle Built-ins stellen typisierte Daten über MCP structuredContent und ein abgeleitetes output schema bereit. Menschenlesbare Textfelder bleiben erhalten, Automatisierung sollte jedoch keine Message-Texte mehr parsen.

Für execute_query_sql sollten Success, Provider, RowCount, DurationMs, Rows und Error direkt verwendet werden. Die Metadata-Tools liefern Schemas, Tables und Columns; autorisierte Semantic-Layer-Informationen erscheinen als verschachtelte strukturierte Felder.

Fehlerlogik sollte auf McpToolError.Code, Stage und Retryable basieren, nicht auf Message-Präfixen.

DML-Status

execute_dml_sql unterscheidet vier Werte in Status:

`Status`	Bedeutung	`Committed`	`Error`
`committed`	genehmigt und committed	`true`	null
`pending`	wartet auf externe Freigabe	`false`	null
`rejected`	Freigabe abgelehnt	`false`	null
`failed`	policy-, validation-, concurrency-, configuration- oder execution-Fehler	`false`	gesetzt

pending und rejected sind gültige Approval-Ergebnisse und keine Execution-Fehler. Bei pending wurde noch keine Datenbankänderung committed. Für asynchrone Freigaben sollte ApprovalRequestId gespeichert werden; wenn vorhanden, kann auch ApprovalExternalReference korreliert werden. Ergebnisse von Klauseln wie RETURNING stehen nach erfolgreichem Commit in ReturnedRows.

SQL Explain / Policy Simulator

Die Security-Seite der Admin Console enthält jetzt SQL Explain / Policy Simulator. Der Simulator nutzt die echte F# compiler pipeline, den gewählten Target Provider und das verifizierte runtime capability profile, ist aber vollständig compile-only:

SQL wird nicht ausgeführt;
es wird keine database transaction geöffnet;
es wird kein DML approval request erzeugt;
der Simulator kann keine Target-Daten verändern.

Query, DML und DML batches werden unterstützt. Optional kann ein vorhandener MCP Key ausgewählt werden, sodass tool access und table allowlist mit dessen effektivem Scope simuliert werden.

Angezeigt werden rendered target SQL, Parameterwerte, referenced tables, QueryFacts, plan fingerprint, compiler decision boundary/code, Diagnostics mit source spans, source/target capability evidence und effective policy evidence.

Das DML affected-row Limit benötigt row-count evidence aus dem runtime preview und wird deshalb nicht fälschlich als compile-time proof dargestellt.

Configuration Doctor

Unter Runtime → Operability steht Configuration Doctor zur Verfügung. Die API lautet GET /api/runtime/operability/doctor.

Doctor liefert einen Gesamtstatus Healthy, Warning oder Error sowie einzelne Checks mit id, category, status, title, detail und optional action. Secret-Werte werden nie zurückgegeben.

Geprüft werden unter anderem MCP-HMAC/JWT-Secrets, Mcp:PublicEndpoint, Admin Store, Data Protection, Memory/Redis coordination, fehlende Redis connection strings, fail-closed limiter/concurrency, DML Webhook approval, OIDC, OTLP, Alert/SIEM webhooks sowie Readiness von Database, active MCP Key und beobachtetem Agent Traffic.

Die Coordination wird als SingleNode, Distributed oder Mixed klassifiziert. Error bedeutet, dass eine sicherheitsrelevante oder notwendige Voraussetzung fehlt. Warning bedeutet, dass die Konfiguration funktionieren kann, aber Operator-Review verdient.

Einheitliche System Readiness

Das bestehende System Readiness auf der Home-Seite wird erweitert statt durch einen zweiten Wizard dupliziert:

Configuration-Doctor-Blocker beseitigen;
governed database connection hinzufügen;
public MCP endpoint prüfen;
MCP access key ausstellen;
die erste governed agent request abschließen.

Doctor-Warnings blockieren Readiness nicht, Errors schon. Der öffentliche MCP Endpoint darf für das Onboarding angezeigt werden, der MCP-Key-Secret jedoch nicht.

Neue MCP Keys wählen weiterhin standardmäßig die vier read/query Tools aus; execute_dml_sql bleibt opt-in.

Checkliste nach dem Upgrade

MCP-Clients, die Tool-Text parsen, auf strukturierte Felder umstellen.
Runtime → Operability öffnen und Configuration Doctor ausführen.
Alle Errors beheben und Warnings passend zur tatsächlichen Topologie prüfen.
In Security Policy mit SQL Explain repräsentative Query/DML-Beispiele gegen Provider und Policy testen.
Sicherstellen, dass Mcp:PublicEndpoint die extern erreichbare /mcp URL ist.
Database, tool set und table scope eines aktiven Keys prüfen.
Client verbinden und eine governed request erfolgreich abschließen.

Unveränderte Sicherheitsgrenzen

Nicht unterstütztes SQL bleibt fail closed.
Table allowlists und tool authorization werden serverseitig erzwungen.
execute_dml_sql bleibt bei neuen Keys opt-in.
Multi-statement DML wird einmal genehmigt und in server-owned transaction order atomar committed.
Durable pending approval validiert vor dem Commit erneut authorization, configuration, policy, plan, row-set und affected-row evidence.
Client-seitige transaction-control SQL bleibt verboten.
Für diese 2.0.5-Funktionen ist keine Admin-Store-Schema-Migration erforderlich.

Rollback

Ein Rollback auf 2.0.4 stellt das vorherige Built-in-MCP-Ergebnisformat wieder her und entfernt Explain, Doctor und die erweiterte Readiness UI. Clients, die ausschließlich strukturierte Felder verwenden, sollten bei einem gestaffelten Rollout versionsbewusst arbeiten.

Die exakten Felder stehen in der MCP-Tool-Referenz.