sqlite-guard-mcp

Позвольте AI-агенту работать с вашей базой данных SQLite, не доверяя ему. MCP-сервер с четырьмя инструментами — schema, query, execute, audit_log — и тремя гарантиями:

1. Чтение не может писать. query работает через отдельное соединение, открытое как SQLITE_OPEN_READONLY на уровне C. Замаскированная запись (/* just checking */ UPDATE …) не отлавливается регулярным выражением — она отклоняется самим SQLite. Обеспечение через архитектуру, а не через проверку.

2. Запись сначала выполняется в режиме "сухого прогона". execute выполняет оператор внутри транзакции, которая всегда откатывается, и сообщает, что бы произошло (changes, lastInsertRowid). Фиксация требует повторного вызова с confirm: true — агент должен дважды заявить о своем намерении, а его оператор видит предполагаемый эффект между этими вызовами.

3. Зафиксированные записи оставляют след, по которому можно вернуться. Перед любой фиксацией файл базы данных сохраняется в виде снимка (VACUUM INTO — транзакционно целостно даже в режиме WAL с активными читателями). Запись и соответствующая строка неизменяемого аудита фиксируются в одной и той же транзакции: невозможно получить изменение без записи в аудите или запись в аудите для изменения, которого не было.

Зачем это нужно

Я веду панель личных финансов, интерфейс которой намеренно только для чтения — каждое число в ней редактируется AI-агентами через SQL. Такая архитектура прекрасна (никаких форм, никаких конечных точек записи, агенты ведут учет) ровно до того момента, пока агент не выполнит правдоподобный UPDATE с неправильным предложением WHERE.

Вывод из работы этой системы: SQL-агенту нужна не более умная модель, а то же самое, что требовалось людям-операторам десятилетиями — разделение чтения и записи, этап планирования/применения, резервные копии и журнал аудита. Этот сервер упаковывает эти четыре вещи за MCP, чтобы любой агент (Claude Code или любой другой, поддерживающий MCP) получал их бесплатно для любого файла SQLite.

Related MCP server: SQLite Read-Only MCP Server

Быстрый старт

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

Подключите к Claude Code:

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

Или исследуйте интерактивно: npx @modelcontextprotocol/inspector npx tsx src/server.ts (с установленным SQLITE_GUARD_DB).

Инструменты

Замечания по дизайну

• "Сухой прогон" — это реальное выполнение, а не оценка на основе EXPLAIN: оператор действительно выполняется (триггеры, ограничения и все остальное), а затем откатывается. Вы видите именно то, что сделала бы фиксация — включая ошибку ограничения, с которой бы столкнулись.

• Восстановление — это копирование одного файла. Резервные копии — это обычные файлы SQLite с именами <db>-backup-<timestamp>; восстановление после неудачной зафиксированной записи — это cp + перезапуск, а строка аудита точно записывает, какой снимок предшествовал какой записи.

• BEGIN/COMMIT от агента отклоняются — жизненный цикл транзакции принадлежит защите. Иначе случайный BEGIN позволил бы последующему оператору зафиксировать "откаченный" сухой прогон.

• Таблица аудита намеренно доступна для чтения через query. Прозрачность здесь перевешивает секретность: агент может просмотреть свою собственную историю, а оператор может попросить агента подвести итог того, что и когда было изменено.

• Классификация операторов (classify.ts) — это маркировка, а не безопасность. Она помечает строки аудита и сообщения об ошибках; границами безопасности являются флаг соединения и протокол транзакций. Все, что решает регулярное выражение, решительный ввод может отменить.

Ограничения (честные)

• Списки разрешений/запретов для отдельных таблиц не реализованы (API авторизации SQLite не предоставляется better-sqlite3); граница проходит по всей базе данных. Направляйте сервер на базу данных, управление которой вы предполагаете доверить агентам.

• VACUUM INTO требует SQLite ≥ 3.27 (2019); более старые сборки используют копирование файла, которое безопасно только в неактивном состоянии.

• Один MCP-сервер = один файл базы данных. Запустите несколько экземпляров для нескольких файлов.

Стек

TypeScript · @modelcontextprotocol/sdk (транспорт stdio) · better-sqlite3 · zod · vitest.

Лицензия

MIT © Brandon Ta