LiteScope

Litescope

AI エージェントが本番 SQLite を安全に操作できるようにします。 書き込みの前に診断し、実行後に巻き戻します。Cloudflare D1、Turso、ローカルファイルに対応しています。

ウェブサイト · ロードマップ · スポンサーになる

Claude に D1 データベースの変更を頼み、間違っていたら元に戻せます。すべての書き込みはデフォルトでドライランされ、正確な影響範囲が示されます。また、1 回の呼び出しで元に戻せます。

無料のオープンソース（AGPL-3.0） — すべてのコマンド、すべてのフリート操作をライセンスキーなしでセルフホストできます。有料なのは、当社が運用するホステッドダッシュボードだけです。

---

SQLite 向けのツールが必要な理由

「ただのファイルなのに、何を運用する必要があるの？」

SQLite がローカル開発用のおもちゃだった頃は、そのとおりでした。しかし、今は違います。D1、Turso、 LiteFS、Litestream により、SQLite はフリート規模の本番環境で使われています。テナントごとに 1 つ、数千もの データベースが稼働しています。しかし、ツールは追いついていません。

• sqlite3 はデータベースが 1 つであることを前提としています。 本番環境では数千のデータベースが前提です。 pg_stat も APM もなく、データベースがロックされる理由、WAL が肥大化する理由、どのテナントが応答しなくなったのかを 外部から確認する標準的な方法もありません。
• 組み込み型であるため、可観測性がありません。 SQLite の強みそのもの、つまりサーバーが不要なことが、 本番環境で状況を把握できなくしています。
• エージェントがデータを書き込むようになりました。 AI がマイグレーションを実行することを前提に作られた SQLite ツールはありません。 Litescope はそのために作られました。

Postgres には、あらゆる問題に対応する成熟したツールがあります。SQLite には何もないため、Litescope は あらゆる作業を 1 つのバイナリで実行できます。フリートの可観測性、ファイルレベルの強力な機能 （bisect／巻き戻し／救出）、ロックと WAL の診断、エージェント向けの安全なインターフェースを備えています。 汎用的な DB クライアントでは構造上対応できない機能です。

---

MCP — Claude に D1 への直接アクセスを許可する

Claude Code — プラグインをインストールすると、MCP サーバーと 5 つのスキル（ロック診断、安全な書き込み、 マイグレーションレビュー、フリートの一括チェック、破損からの復旧）が導入され、問題が発生したときに エージェントが使い方を学べます。

/plugin marketplace add croc100/Litescope
/plugin install litescope@litescope

MCP サーバーだけを使う場合は、1 行でインストールできます（読み取り専用）。

claude mcp add litescope -- litescope mcp

書き込みと D1 を有効にする場合（Litescope はすべての書き込みをドライランし、適用前に巻き戻しポイントを 記録します）。

claude mcp add litescope \
  -e CLOUDFLARE_API_TOKEN=your-token \
  -e CLOUDFLARE_ACCOUNT_ID=your-account-id \
  -- litescope mcp --allow-writes

Cursor — ワンクリックで追加： ➕ litescope を Cursor に追加 （読み取り専用でインストールされます。書き込みを有効にするには、mcp.json に --allow-writes と Cloudflare の環境変数を 追加してください）。

Claude Desktop／Windsurf／その他の MCP クライアント — 設定ファイルに直接追加します。

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

io.github.croc100/litescope としてMCP レジストリにも掲載されています。

続いて、Claude に次のように頼んでみましょう。

"List my D1 databases"
"Show me the schema of the users table in d1://abc-123"
"Delete every inactive user from d1://prod-db-id"     ← dry-run first: shows the
                                                        exact blast radius before
                                                        you approve the write
"Undo that — put it back the way it was"              ← one-call revert via the
                                                        rewind_token from the write
"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"

読み取り専用ツール（常に利用可能）

ツール	機能
litescope_d1_list	アカウント内のすべての D1 データベースを一覧表示します（UUID、名前、DSN）
litescope_query	任意の D1 データベースまたはローカル SQLite ファイルに対して SELECT を実行します
litescope_schema	テーブル、列、インデックスを調査します
litescope_health	破損、WAL の肥大化、断片化を確認します
litescope_diff	任意の 2 つのソース間でスキーマと行数の差分を確認します
litescope_migrate_plan	マイグレーション SQL と影響範囲の分析を生成します
litescope_migrate_diff	マイグレーション SQL のみを生成します（影響範囲の分析なし）
litescope_advise	パフォーマンスを分析します（不足しているインデックス、フルテーブルスキャン）
litescope_check	参照データベースと照合してバックアップを検証します
litescope_fingerprint	スキーマのフィンガープリントでフリートをクラスタリングします
litescope_fleet_health	フリート全体の障害をトリアージします
litescope_locks	database is locked / SQLITE_BUSY を診断します（静的およびライブ）
litescope_snapshot_list	ローカルデータベースのポイントインタイムスナップショットを一覧表示します

litescope_query はトークン予算を管理します。max_rows の上限、columns による列の選択、切り詰めに関する報告により、大きなテーブルがエージェントの コンテキストウィンドウを超えることはありません。

書き込みツール（--allow-writes）

ツール	機能
litescope_query_write	データを変更する SQL — 既定ではドライランで、影響を受ける正確な行数と影響範囲の差分を表示します（D1 のドライランは取得したコピーで計測）。適用時は先に元に戻すためのポイントを記録し（ローカル：スナップショット、D1：Time Travel ブックマーク）、rewind_token として返します
litescope_write_undo	rewind_token を使って 1 回の呼び出しで書き込みを元に戻します — ローカルファイルと D1 の両方に対応し、トークンは発行対象のデータベースに紐付けられます
litescope_migrate_apply	マイグレーションを適用します — litescope_query_write と同じ可逆性の保証があります
litescope_autopilot	自律的に最適化します（ANALYZE、インデックス、VACUUM）— 既定ではドライランです
litescope_snapshot	ローカルデータベースのポイントインタイムバックアップを作成します
litescope_restore	スナップショットからローカルデータベースを復元します
litescope_rewind	D1 データベースを特定の時点に復元します（Time Travel）
litescope_d1_pull	D1 データベースをローカルの SQLite ファイルにダウンロードします
litescope_d1_create	新しい D1 データベースを作成します
litescope_d1_delete	D1 データベースを削除します（取り消し不可）

書き込みツールは、--allow-writes を指定してサーバーを起動しない限り無効です。すべての 書き込みは既定でドライランとなり、自動で記録された元に戻すためのポイントなしに 書き込みが確定することはありません。各層が保護する対象と、保護しない対象を含む詳細は セキュリティモデルをご覧ください。

プロンプトとリソース

ツールに加えて、MCP サーバーはプロンプトも公開します。これは、 diagnose_locked_database、review_migration、safe_optimize、 health_checkup などの定型ワークフローで、上記のツールを組み合わせて安全な 手順を作成します。また、リソースも公開します。データベースのスキーマ、 データディクショナリ、ライブの健全性情報、ライブのロック診断を指し、エージェントは ツール呼び出しを消費せずに読み取ることができ、基盤のファイルが変更されるたびに プッシュ更新を受け取るよう登録できます。litescope mcp ./app.db で接続するか、 litescope://schema/{source}、litescope://dictionary/{source}、 litescope://health/{source}、litescope://locks/{source} で任意のソースを指定します。

サーバーは、ステートレスなリビジョンであるMCP 2026-07-28を実装しています。 これには、server/discover、リクエストごとのプロトコルメタデータ、 resultType、キャッシュヒント（ttlMs / cacheScope）、subscriptions/listen ストリームが含まれます。また、ツールの注釈 （読み取り専用／破壊的操作のヒント）、構造化出力（structuredContent + outputSchema）、引数の補完にも対応しています。両世代に対応しているため、 引き続き initialize ハンドシェイクで開始するクライアントには、MCP 2025-06-18 を変更せずに提供し、古い MCP クライアントも引き続き利用できます。

インタラクティブビュー（MCP Apps）

4 つのツールは、MCP Apps 拡張機能（io.modelcontextprotocol/ui）を通じて、会話内に表示されるインタラクティブなパネルで回答します。

ツール	ビュー
litescope_locks	ロック診断 — 判定、各検出事項に対する正確な PRAGMA/DSN 修正方法、ライブロック調査
litescope_health	ヘルスパネル — 整合性、WAL、断片化、スナップショットのカバレッジ
litescope_query_write / litescope_migrate_apply	影響範囲 — ステートメントごとの影響行数、スキーマへの影響、巻き戻しトークン
litescope_fleet_health	フリートグリッド — すべてのデータベースを深刻度の高い順に表示し、詳細を確認できます

ビューはバイナリにコンパイルされた、自己完結型の単一ドキュメントです。ネットワークから何も読み込まないため、ホストの最も厳格な CSP が適用され、データベースの内容が iframe の外に漏れることはありません。また、書き込みを行うこともありません。書き込みを適用または取り消すボタンは、リクエストを会話に戻します。埋め込みパネル内のクリックは、ユーザーが本番環境への書き込みを承認したことにはならないためです。この拡張機能に対応していないホストでも、同じ結果がテキストで表示されます。

リモート／ホステッド（Streamable HTTP）

デフォルトでは、litescope mcp は stdio で通信します。ホステッド、リモート、または複数クライアントでのセットアップでは、代わりに Streamable HTTP トランスポートで提供します。

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

エンドポイント（デフォルトは /mcp）に JSON-RPC メッセージを POST します。最新のクライアントにはステートレス（セッションなし）で提供され、各リクエストには独自のプロトコルメタデータと標準の MCP-Protocol-Version / Mcp-Method / Mcp-Name ヘッダーが含まれます。また、変更通知は subscriptions/listen のレスポンスストリームで届きます。ハンドシェイク方式のクライアントには、引き続き Mcp-Session-Id ヘッダーを使ったセッションと、GET の SSE ストリームが提供されます。

一般公開する前に、アクセスを制限してください。--http-token（または LITESCOPE_MCP_TOKEN 環境変数）を設定すると、すべてのリクエストに Authorization: Bearer <token> が必要になります。また、--http-origin では、DNS リバインディング対策としてブラウザーの Origin を許可リストに登録できます（localhost は常に許可されます）。トークンを設定しない場合、エンドポイントは公開状態となり、サーバーが警告を出力します。

---

D1 — CLI 操作

巻き戻し — D1 タイムトラベル

# 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 — D1 とローカル 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 — 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 — D1 データベースを壊したコミットを特定する

D1 タイムトラベルを二分探索し、クエリが誤った結果を返し始めた正確なスナップショットを特定します。

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

gt:0（より大きい）、lt:N、eq:N、またはリテラル値を確認します。条件が最初に失敗したスナップショットウィンドウまで絞り込み、内容を調べるか、巻き戻せるようにします。

---

ローカル SQLite

doctor — ワンショット診断

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

整合性チェック、WAL／断片化の状態、インデックスアドバイザー、スキーマの lint を 1 つのコマンドにまとめています。対応が必要な場合は 1 で終了するため、CI の品質ゲートとして使用できます。

snapshot / restore — 指定時点のバックアップ

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>

スナップショットは、隣接する .litescope-snapshots/ ディレクトリに保存されます。復元時には整合性を確認し、事前に安全のためのスナップショットを取得します。これは、ローカルと Turso で D1 のタイムトラベルが提供する「バックアップしましたか？」という安全策と同じです。

autopilot — 自動最適化

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

ANALYZE と PRAGMA optimize を実行し、不足している外部キーインデックスを追加します。また、（--aggressive を指定すると）VACUUM を実行し、重複するインデックスを削除します。各処理について、わかりやすい言葉で説明します。デフォルトではドライランとなり、実際に変更を加える前に毎回、自動でスナップショットを取得します。

locks — 「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
litescope locks app.db --timeline             # recorded contention history
litescope locks app.db --timeline --since 24h

ジャーナルモード、busy_timeout、ロックモード、WAL の肥大化を調べ、正確な PRAGMA/DSN の修正方法を提示します。--live を指定すると、現在ロックを保持しているプロセスを特定します。--watch は、観測結果をすべてローカルの履歴ストアに記録します。続けて --timeline を実行すると、データベースごとの競合状況が集計されます。データベースが応答不能になった時間とその長さ、ロックを保持したプロセス、待ち時間のパーセンタイル、WAL のチェックポイントが追いついていたかどうかを確認できます。

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 — マイグレーションを生成して適用する

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 の安全性を確保する手順：適用前の整合性チェック → VACUUM INTO によるバックアップ → 単一トランザクション → 外部キーの検証 → 失敗時の自動ロールバック。

lint — スキーマのアンチパターン

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

ルール：no-primary-key、untyped-column、not-strict、autoincrement-overhead、non-integer-pk。

schema — スキーマと ERD を確認する

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

dump — ポータブルな SQL エクスポート

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

import / export — スプレッドシートと 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"

形式：CSV、TSV、JSON、Excel（.xlsx）。外部依存関係はありません。

monitor — スキーマのドリフト検出

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 — ローカルウェブダッシュボード

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

フリートのトポロジーマップ、ヘルストリアージ、スキーマのフィンガープリント、インタラクティブな ERD、ビジュアルクエリビルダー付きのページ分割データブラウザー、ドラッグ＆ドロップによるインポート、そしてビジュアル差分パネルを利用できます。任意の 2 つのデータベースを選んで、適用前にスキーマと行数の変更を確認できます。すべてローカルで動作し、アカウントは不要です。

---

フリート

数百のデータベースを一度に管理できます。Turso と 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 locks         # roll up "database is locked" contention, worst-first
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

すべてのプルリクエストで Litescope を実行し、スキーマの lint、ベースブランチとの差分確認、影響範囲のコメント投稿を行うことで、リスクの高いマイグレーションがレビューなしでマージされるのを防ぎます。

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

args には任意の Litescope コマンドを指定できます。Litescope が問題を検出すると、ジョブはゼロ以外の終了コードを返し、チェックは失敗します。 lint と diff を組み合わせたワークフローの全容については、 examples/github-actions/migration-ci.yml を参照してください。

入力	デフォルト	説明
args	—	実行する Litescope コマンド（必須）
version	latest	インストールするリリースタグ、または latest
comment	false	出力を固定 PR コメントとして投稿する
working-directory	.	実行するディレクトリ

---

インストール

Homebrew

brew install croc100/tap/litescope

npm / npx — JS および wrangler のユーザー向け。別途インストールする必要はありません：

npx litescope doctor app.db
npm install -g litescope

Go install

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

バイナリのダウンロード

macOS、Linux、Windows — リリース。

---

リモートソース

DSN	プロバイダー
./app.db or /path/to/file.db	ローカル SQLite ファイル
d1://DB_UUID	Cloudflare D1（環境変数：CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID）
d1://TOKEN@ACCOUNT_ID/DB_UUID	Cloudflare D1（明示的な認証情報）
turso://TOKEN@ORG/DBNAME	Turso

---

料金 — 無料で利用できるもの

ツールは無料です。料金が発生するのは、ダッシュボードの運用を当社に依頼する場合のみです。

	無料（OSS、AGPL-3.0）	クラウド（有料）
すべての CLI コマンド、MCP サーバー、フリート運用	✅	✅
litescope serve — ローカルウェブダッシュボード	✅	✅
独自のインフラでセルフホストするダッシュボード	✅	✅
当社が運用・保守するホスト型ダッシュボード	—	✅
メタデータの取り込み、保持、アラート管理	—	✅
組織の認証、チーム、SSO	—	✅
サポート SLA	—	✅

シンプルな方針です。ソフトウェアとすべての機能は無料で、永久にセルフホストできます。ダッシュボードのホスティングと運用を当社に任せたい場合にのみ、お支払いください。 ライセンスキーがないと使えない機能はありません。

ホスト型プランについては、litescope-site.pages.dev/pricing をご覧ください。

---

ライセンス

Litescope は AGPL-3.0 です。無料で使用、変更、セルフホストできます。ネットワークサービスとして提供する場合、AGPL により変更内容の共有が求められます。組織向けに商用ライセンス（AGPL の例外条項 + サポート SLA）もご利用いただけます。COMMERCIAL.md を参照するか、 [email protected] までメールでお問い合わせください。