sqlite-guard-mcp

Permite que un agente de IA trabaje en tu base de datos SQLite sin confiar en él. Un servidor MCP con cuatro herramientas — schema, query, execute, audit_log — y tres garantías:

1. Las lecturas no pueden escribir. query se ejecuta en una conexión separada abierta con SQLITE_OPEN_READONLY a nivel de C. Una escritura disfrazada (/* solo comprobando */ UPDATE …) no es detectada por una expresión regular — es rechazada por el propio SQLite. Cumplimiento por construcción, no por inspección.

2. Las escrituras se ejecutan primero en seco. execute ejecuta la sentencia dentro de una transacción que siempre se revierte e informa lo que habría sucedido (changes, lastInsertRowid). Confirmar requiere volver a llamar con confirm: true — el agente debe declarar su intención dos veces, y su operador ve el efecto previsto entre medias.

3. Las escrituras confirmadas dejan un rastro que puedes recorrer hacia atrás. Antes de cualquier confirmación, se crea una instantánea del archivo de la base de datos (VACUUM INTO — transaccionalmente consistente incluso bajo WAL con lectores activos). La escritura y su fila de auditoría de solo anexión se confirman en la misma transacción: no puedes terminar con un cambio sin una entrada de auditoría, o una entrada de auditoría para un cambio que no ocurrió.

Por qué existe esto

Ejecuto un panel de control de finanzas personales cuya interfaz de usuario es deliberadamente de solo lectura — cada número en él es editado por agentes de IA a través de SQL. Esa arquitectura es maravillosa (sin formularios, sin puntos finales de escritura, los agentes mantienen los libros) hasta que un agente ejecuta un UPDATE de aspecto plausible con una cláusula WHERE incorrecta.

La conclusión de operar ese sistema: lo que el SQL de los agentes necesita no es un modelo más inteligente, es lo mismo que las operaciones humanas necesitaron durante décadas — separación de lectura/escritura, un paso de planificar/aplicar, copias de seguridad y un registro de auditoría. Este servidor empaqueta esas cuatro cosas detrás de MCP para que cualquier agente (Claude Code, o cualquier otra cosa que hable MCP) las obtenga gratis en cualquier archivo SQLite.

Related MCP server: SQLite Read-Only MCP Server

Inicio rápido

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

Conéctalo a Claude Code:

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

O inspecciónalo interactivamente: npx @modelcontextprotocol/inspector npx tsx src/server.ts (con SQLITE_GUARD_DB configurada).

Las herramientas

Notas de diseño

• La ejecución en seco es ejecución real, no una estimación basada en EXPLAIN: la sentencia se ejecuta genuinamente (desencadenadores, restricciones y todo) y se revierte. Lo que ves es lo que haría una confirmación — incluyendo el error de restricción que encontrarías.

• Restaurar es copiar un archivo. Las copias de seguridad son archivos SQLite planos nombrados <db>-backup-<timestamp>; la recuperación de una escritura confirmada incorrecta es cp + reinicio, y la fila de auditoría registra exactamente qué instantánea es anterior a qué escritura.

• BEGIN/COMMIT del agente son rechazados — el ciclo de vida de la transacción pertenece al guardia. De lo contrario, un BEGIN fuera de lugar permitiría que una sentencia posterior confirme la ejecución en seco "revertida".

• La tabla de auditoría es legible a través de query intencionadamente. La transparencia supera al secretismo aquí: el agente puede revisar su propio historial, y el operador puede pedir al agente que resuma qué cambió y cuándo.

• La clasificación de sentencias (classify.ts) es etiquetado, no seguridad. Etiqueta filas de auditoría y mensajes de error; los límites de seguridad son el indicador de conexión y el protocolo de transacción. Cualquier cosa que decida una expresión regular, una entrada determinada puede deshacerla.

Limitaciones (honestas)

• No se implementan listas de permitir/denegar por tabla (la API de autorización de SQLite no está expuesta por better-sqlite3); el límite es por base de datos. Apunta el servidor a una base de datos que pretendas que los agentes administren.

• VACUUM INTO necesita SQLite ≥ 3.27 (2019); las compilaciones más antiguas recurren a una copia de archivo, que solo es segura cuando está inactiva.

• Un servidor MCP = un archivo de base de datos. Ejecuta varias instancias para varios archivos.

Stack

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

Licencia

MIT © Brandon Ta