sqlite-guard-mcp

AI 에이전트가 SQLite 데이터베이스를 신뢰 없이 다루게 하세요. 네 가지 도구 — schema, query, execute, audit_log — 와 세 가지 보장 사항을 제공하는 MCP 서버입니다:

1. 읽기는 쓸 수 없습니다. query는 C 레벨에서 SQLITE_OPEN_READONLY로 열린 별도의 연결에서 실행됩니다. 위장된 쓰기(/* just checking */ UPDATE …)는 정규식으로 탐지되지 않습니다 — SQLite 자체가 거부합니다. 검사가 아닌 구조에 의한 강제입니다.

2. 쓰기는 먼저 드라이런(dry-run)됩니다. execute는 항상 롤백되는 트랜잭션 내에서 명령문을 실행하고, 어떤 일이 일어났을지(changes, lastInsertRowid) 보고합니다. 커밋하려면 confirm: true로 다시 호출해야 합니다 — 에이전트는 의도를 두 번 명시해야 하며, 운영자는 그 사이에 의도된 효과를 볼 수 있습니다.

3. 커밋된 쓰기는 되돌릴 수 있는 흔적을 남깁니다. 커밋 전에 DB 파일은 스냅샷됩니다(VACUUM INTO — 활성 리더가 있는 WAL에서도 트랜잭션 일관성 유지). 쓰기와 추가 전용 감사 로그 행은 동일한 트랜잭션에서 커밋됩니다: 감사 항목이 없는 변경사항이 생기거나, 발생하지 않은 변경에 대한 감사 항목이 생길 수 없습니다.

왜 이것이 존재하는가

저는 개인 재무 대시보드를 운영하고 있으며, 그 UI는 의도적으로 읽기 전용입니다 — 모든 숫자는 AI 에이전트가 SQL을 통해 편집합니다. 그 아키텍처는 훌륭합니다(폼 없음, 쓰기 엔드포인트 없음, 에이전트가 장부를 관리함) — 잘못된 WHERE 절이 포함된 그럴듯한 UPDATE를 에이전트가 실행할 때까지는요.

그 시스템을 운영하면서 얻은 통찰: 에이전트 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 기반 추정이 아닙니다: 명령문이 실제로 실행(트리거, 제약 조건 등 포함)되고 롤백됩니다. 보이는 그대로가 커밋 시의 결과입니다 — 발생할 제약 조건 오류까지 포함합니다.

• 복원은 파일 복사 하나입니다. 백업은 <db>-backup-<timestamp> 이름의 일반 SQLite 파일입니다. 잘못된 커밋 쓰기로부터의 복구는 cp + 재시작이며, 감사 로그 항목은 어떤 스냅샷이 어떤 쓰기보다 앞서는지 정확히 기록합니다.

• 에이전트의 BEGIN/COMMIT은 거부됩니다 — 트랜잭션 생명주기는 가드(guard)에 속합니다. 그렇지 않으면 잘못된 BEGIN이 이후의 명령문으로 "롤백된" 드라이런을 커밋할 수 있습니다.

• 감사 테이블은 의도적으로 query를 통해 읽을 수 있습니다. 여기서는 투명성이 비밀보다 낫습니다: 에이전트는 자신의 이력을 검토할 수 있고, 운영자는 에이전트에게 무엇을 언제 변경했는지 요약하도록 요청할 수 있습니다.

• 명령문 분류(classify.ts)는 라벨링이지 보안이 아닙니다. 감사 로그 행과 오류 메시지에 태그를 붙입니다. 보안 경계는 연결 플래그와 트랜잭션 프로토콜입니다. 정규식이 결정하는 것은 결심된 입력이 무효화할 수 있습니다.

한계(솔직한 것들)

• 테이블별 허용/거부 목록은 구현되지 않았습니다(better-sqlite3가 SQLite의 authorizer API를 노출하지 않음); 경계는 데이터베이스 단위입니다. 서버가 에이전트가 관리하도록 의도한 데이터베이스를 가리키도록 하세요.

• VACUUM INTO는 SQLite ≥ 3.27(2019)이 필요합니다. 이전 빌드는 파일 복사로 대체되며, 이는 정지 상태에서만 안전합니다.

• 하나의 MCP 서버 = 하나의 데이터베이스 파일. 여러 파일을 위해 여러 인스턴스를 실행하세요.

스택

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

라이선스

MIT © Brandon Ta