sqlite-guard-mcp

Lassen Sie einen KI-Agenten auf Ihrer SQLite-Datenbank arbeiten, ohne ihm zu vertrauen. Ein MCP-Server mit vier Werkzeugen — schema, query, execute, audit_log — und drei Garantien:

1. Lesevorgänge können nicht schreiben. query läuft auf einer separaten Verbindung, die auf C-Ebene mit SQLITE_OPEN_READONLY geöffnet wird. Ein getarnter Schreibvorgang (/* just checking */ UPDATE …) wird nicht von einem Regex abgefangen – er wird von SQLite selbst abgelehnt. Durchsetzung durch Konstruktion, nicht durch Inspektion.

2. Schreibvorgänge werden zuerst trocken ausgeführt. execute führt die Anweisung in einer Transaktion aus, die immer rückgängig gemacht wird, und meldet, was passiert wäre (changes, lastInsertRowid). Zum Bestätigen muss mit confirm: true erneut aufgerufen werden – der Agent muss seine Absicht zweimal angeben, und der Betreiber sieht dazwischen die beabsichtigte Wirkung.

3. Bestätigte Schreibvorgänge hinterlassen eine Spur, die Sie zurückverfolgen können. Vor jedem Commit wird ein Snapshot der DB-Datei erstellt (VACUUM INTO – transaktionskonsistent selbst unter WAL mit aktiven Lesern). Der Schreibvorgang und die zugehörige Append-Only-Audit-Zeile werden in der gleichen Transaktion committet: Sie können nicht mit einer Änderung ohne Audit-Eintrag oder einem Audit-Eintrag für eine nicht durchgeführte Änderung enden.

Warum es das gibt

Ich betreibe ein persönliches Finanz-Dashboard, dessen UI bewusst schreibgeschützt ist – jede Zahl darin wird von KI-Agenten über SQL bearbeitet. Diese Architektur ist wunderbar (keine Formulare, keine Schreib-Endpunkte, Agenten führen die Bücher) – bis ein Agent ein plausibel aussehendes UPDATE mit einer falschen WHERE-Klausel ausführt.

Die Erkenntnis aus dem Betrieb dieses Systems: Was Agenten-SQL braucht, ist kein intelligenteres Modell, sondern das Gleiche, was menschliche Ops seit Jahrzehnten brauchen – Lese-/Schreibtrennung, einen Plan-/Ausführen-Schritt, Backups und ein Audit-Log. Dieser Server verpackt diese vier Dinge hinter MCP, sodass jeder Agent (Claude Code oder alles andere, das MCP spricht) sie für jede SQLite-Datei kostenlos erhält.

Related MCP server: SQLite Read-Only MCP Server

Schnellstart

npm install
npm run demo        # full guardrail walkthrough on a temp DB — 10 seconds, no setup
npm test            # 10 tests: rollback semantics, backup consistency, audit atomicity

Binden Sie es in Claude Code ein:

claude mcp add sqlite-guard \
  -e SQLITE_GUARD_DB=/path/to/app.db \
  -- npx tsx src/server.ts

Oder überprüfen Sie es interaktiv: npx @modelcontextprotocol/inspector npx tsx src/server.ts (mit gesetztem SQLITE_GUARD_DB).

Die Werkzeuge

Design-Notizen

• Der Trockenlauf ist eine echte Ausführung, keine auf EXPLAIN basierende Schätzung: Die Anweisung läuft tatsächlich (Trigger, Constraints und alles) und wird zurückgesetzt. Was Sie sehen, ist das, was ein Commit tun würde – einschließlich des Constraints-Fehlers, den Sie erhalten würden.

• Wiederherstellung ist eine Dateikopie. Backups sind einfache SQLite-Dateien mit Namen <db>-backup-<timestamp>; die Wiederherstellung nach einem fehlerhaften bestätigten Schreibvorgang erfolgt über cp + Neustart, und die Audit-Zeile zeichnet genau auf, welcher Snapshot vor welchem Schreibvorgang existiert.

• BEGIN/COMMIT vom Agenten werden abgelehnt – der Transaktionslebenszyklus gehört zum Schutzmechanismus. Andernfalls würde ein versehentliches BEGIN einer späteren Anweisung erlauben, den „zurückgesetzten“ Trockenlauf zu committen.

• Die Audit-Tabelle ist absichtlich über query lesbar. Transparenz schlägt Geheimhaltung: Der Agent kann seine eigene Historie überprüfen, und der Betreiber kann den Agenten bitten, zusammenzufassen, was und wann er geändert hat.

• Die Anweisungsklassifizierung (classify.ts) ist Kennzeichnung, keine Sicherheit. Sie markiert Audit-Zeilen und Fehlermeldungen; die Sicherheitsgrenzen sind das Verbindungsflag und das Transaktionsprotokoll. Alles, was ein Regex entscheidet, kann eine entschlossene Eingabe wieder rückgängig machen.

Einschränkungen (ehrliche)

• Erlaubnis-/Verbotslisten pro Tabelle sind nicht implementiert (SQLites Authorizer-API wird von better-sqlite3 nicht freigegeben); die Grenze ist pro Datenbank. Richten Sie den Server auf eine Datenbank, die Sie von Agenten verwalten lassen möchten.

• VACUUM INTO benötigt SQLite ≥ 3.27 (2019); ältere Builds fallen auf eine Dateikopie zurück, die nur im Ruhezustand sicher ist.

• Ein MCP-Server = eine Datenbankdatei. Führen Sie mehrere Instanzen für mehrere Dateien aus.

Technologie-Stack

TypeScript · @modelcontextprotocol/sdk (stdio transport) · better-sqlite3 · zod · vitest.

Lizenz

MIT © Brandon Ta