litescope

Litescope

The MCP-first operations tool for Cloudflare D1 and SQLite.

Website · Roadmap · Sponsor

Ask Claude about your D1 database. Rewind it. Migrate it. Diff it against local. All from chat.

Free and open source (AGPL-3.0) — every command, every fleet operation, no license key.

MCP — Give Claude direct access to your D1

Add Litescope to your Claude Desktop or Claude Code config:

{
  "mcpServers": {
    "litescope": {
      "command": "litescope",
      "args": ["mcp", "--allow-writes"],
      "env": {
        "CLOUDFLARE_API_TOKEN": "your-token",
        "CLOUDFLARE_ACCOUNT_ID": "your-account-id"
      }
    }
  }
}

Then ask Claude things like:

"List my D1 databases"
"Show me the schema of the users table in d1://abc-123"
"How many orders were placed in the last 7 days?"
"The deploy at 2pm broke something — rewind prod to 1:45pm"
"Diff my local dev.db against d1://prod-db-id and show me the migration SQL"
"Apply this migration to d1://prod-db-id"

Read-only tools (always available)

litescope_query enforces token budgeting — max_rows cap + columns projection + truncation reporting — so a large table never blows the agent's context window.

Write tools (--allow-writes)

Prompts & Resources

Beyond tools, the MCP server exposes prompts — canned workflows like diagnose_locked_database, review_migration, safe_optimize, and health_checkup that chain the tools above into a safe plan — and resources: a database's schema and a data dictionary, readable by the agent without spending a tool call. Bind one with litescope mcp ./app.db, or address any source via litescope://schema/{source} and litescope://dictionary/{source}.

The server implements MCP 2025-06-18: tool annotations (read-only / destructive hints), structured output (structuredContent + outputSchema), argument completion, resource-change subscriptions, and server logging.

Remote / hosted (Streamable HTTP)

By default litescope mcp speaks stdio. For a hosted, remote, or multi-client setup, serve over the Streamable HTTP transport instead:

litescope mcp --http :7577 --http-token "$LITESCOPE_MCP_TOKEN"

POST a JSON-RPC message to the endpoint (/mcp by default), or open a GET SSE stream for server notifications; each client gets its own session via the Mcp-Session-Id header.

Before exposing it publicly, lock it down: --http-token (or the LITESCOPE_MCP_TOKEN env var) requires Authorization: Bearer <token> on every request, and --http-origin allowlists browser Origins (localhost is always allowed) for DNS-rebinding protection. Without a token the endpoint is open and the server prints a warning.

D1 — CLI operations

Rewind — D1 Time Travel

# Restore to a previous point in time
litescope rewind d1://DB_ID --to "2h ago"
litescope rewind d1://DB_ID --to "yesterday"
litescope rewind d1://DB_ID --to "2024-01-15T10:30:00Z"

# List available restore points (30-day window + migration timestamps)
litescope rewind list d1://DB_ID

Pull / Push — sync between D1 and local SQLite

# Download D1 → local (for inspection, backup, or diffing)
litescope d1 pull d1://DB_ID ./snapshot.db

# Upload local → D1 (seed a fresh database or restore from snapshot)
litescope d1 push ./seed.db d1://DB_ID
litescope d1 push ./seed.db d1://DB_ID --drop-existing

Migrate — schema changes on D1

# Diff local dev schema against live D1 — generate migration SQL
litescope migrate local.db d1://DB_ID

# Apply a migration directly to D1
litescope migrate apply d1://DB_ID migration.sql

Bisect — find which commit broke a D1 database

Binary-search D1 Time Travel to pinpoint the exact snapshot where a query started returning wrong results:

litescope bisect d1://DB_ID \
  --good "3d ago" \
  --bad now \
  --check "SELECT COUNT(*) FROM orders WHERE status = 'paid'" \
  --expect "gt:0"

Checks gt:0 (greater-than), lt:N, eq:N, or a literal value. Narrows to the snapshot window where the condition first failed, then lets you inspect or rewind.

Local SQLite

doctor — one-shot checkup

litescope doctor app.db
litescope doctor app.db --deep            # exhaustive integrity_check
litescope doctor app.db --format html -o report.html

Combines integrity check, WAL/fragmentation health, index advisor, and schema lint in one command. Exits 1 when attention is needed — use it as a CI quality gate.

snapshot / restore — point-in-time backups

litescope snapshot app.db                     # consistent VACUUM INTO copy
litescope snapshot app.db --label before-migration
litescope snapshot app.db --keep 7            # retain only the 7 newest
litescope snapshot list app.db
litescope restore app.db                      # restore the newest snapshot
litescope restore app.db --from <snapshot.db>

Snapshots live in a sibling .litescope-snapshots/ directory. Restore is integrity-checked and takes a pre-restore safety snapshot first — the same "did you back up?" safety net that D1 gets from Time Travel, for local and Turso.

autopilot — self-driving optimization

litescope autopilot app.db                    # dry-run: show the plan
litescope autopilot app.db --apply            # apply the safe actions
litescope autopilot app.db --apply --aggressive
litescope autopilot --fleet litescope.fleet.yaml --apply

Runs ANALYZE + PRAGMA optimize, adds missing foreign-key indexes, and (with --aggressive) VACUUMs and drops redundant indexes — each explained in plain language. Dry-run by default; every real change is preceded by an automatic snapshot.

locks — diagnose "database is locked"

litescope locks app.db                        # static config diagnosis
litescope locks app.db --live                 # is a writer holding the lock now?
litescope locks app.db --watch                # stream lock-state changes

Inspects journal mode, busy_timeout, locking mode, and WAL bloat, and prescribes the exact PRAGMA/DSN fix. --live identifies the process holding the lock right now.

diff — schema and data diff

litescope diff old.db new.db
litescope diff old.db new.db --format json
litescope diff local.db d1://DB_ID        # local vs live D1
litescope diff local.db turso://TOKEN@ORG/prod

migrate — generate and apply migrations

litescope migrate before.db after.db --output migration.sql
litescope migrate apply prod.db migration.sql --dry-run
litescope migrate apply prod.db migration.sql --verify after.db

migrate apply safety sequence: pre-flight integrity check → VACUUM INTO backup → single transaction → FK verification → auto-rollback on failure.

lint — schema anti-patterns

litescope lint app.db
litescope lint app.db --strict   # exit 1 on info findings too

Rules: no-primary-key, untyped-column, not-strict, autoincrement-overhead, non-integer-pk.

schema — inspect schema + ERD

litescope schema app.db
litescope schema app.db --erd    # Mermaid ER diagram

dump — portable SQL export

litescope dump app.db -o backup.sql
litescope dump app.db --schema-only
litescope dump app.db --table users

import / export — spreadsheets and SQLite

litescope import sales.csv              # → sales.db, table "sales"
litescope import budget.xlsx            # first sheet → budget.db
litescope export shop.db --table orders -o orders.xlsx
litescope export shop.db --query "SELECT city, COUNT(*) FROM users GROUP BY city"

Formats: CSV, TSV, JSON, Excel (.xlsx). No external dependencies.

monitor — schema drift detection

litescope monitor snapshot prod.db --output baseline.json
litescope monitor check prod.db --baseline baseline.json     # exits 1 on drift
litescope monitor watch prod.db --baseline baseline.json --interval 1h --webhook https://hooks.slack.com/...

serve — local web dashboard

litescope serve                   # opens http://127.0.0.1:7575
litescope serve --config litescope.fleet.yaml

Fleet topology map, health triage, schema fingerprinting, interactive ERD, a paginated data browser with a visual query builder, drag-drop import, and a visual diff panel — pick any two databases to review schema and row-count changes before applying. Entirely local, no account required.

Fleet

Manage hundreds of databases at once. Built for multi-tenant apps on Turso and D1.

# Discover all databases
litescope fleet discover turso --org my-org --token $TURSO_API_TOKEN
litescope fleet discover d1 --account $CF_ACCOUNT_ID --token $CF_API_TOKEN

# Triage the whole fleet
litescope fleet health
litescope fleet fingerprint   # cluster by schema — find drift before it bites

# Stage a migration across the fleet
litescope fleet migrate migration.sql --dry-run
litescope fleet migrate migration.sql --canary 5
litescope fleet migrate migration.sql

CI — GitHub Action

Run Litescope on every pull request — lint the schema, diff against the base branch, and comment the blast radius so a risky migration can't merge unreviewed.

- uses: croc100/Litescope@v1
  with:
    args: "lint app.db --strict"
    comment: "true"          # post the result as a sticky PR comment

args is any Litescope command; the job exits non-zero when Litescope flags something, failing the check. See examples/github-actions/migration-ci.yml for a full lint + diff workflow.

Install

Homebrew

brew install croc100/tap/litescope

npm / npx — for JS and wrangler users, no separate install:

npx litescope doctor app.db
npm install -g litescope

Go install

go install github.com/croc100/litescope/cmd/litescope@latest

Binary download

macOS, Linux, Windows — Releases.

Remote sources

License

Litescope is AGPL-3.0. Free to use, modify, and self-host. If you offer it as a network service the AGPL requires you to share your modifications. A commercial license (AGPL exception + support SLA) is available for organizations — see COMMERCIAL.md or email dl_litescope@crode.net.