内容
# Litescope
**优先使用 MCP 的云flare D1 和 SQLite 操作工具。**
[网站](https://litescope-site.pages.dev) · [路线图](ROADMAP.md) · [赞助](https://github.com/sponsors/croc100)
[](LICENSE)
[](go.mod)
[](https://developers.cloudflare.com/d1/)
[](https://turso.tech)
[](https://gcv-five.vercel.app/croc100/litescope)
[](https://glama.ai/mcp/servers/croc100/Litescope)
询问 Claude 关于您的 D1 数据库。倒回它。迁移它。与本地进行差异比较。所有操作均可从聊天界面进行。
**免费且开源（AGPL-3.0）** — 每个命令、每个舰队操作，均无需许可证密钥。
---
## MCP — 向 Claude 提供直接访问您的 D1 的权限
将 Litescope 添加到您的 Claude Desktop 或 Claude Code 配置中：
```json
{
"mcpServers": {
"litescope": {
"command": "litescope",
"args": ["mcp", "--allow-writes"],
"env": {
"CLOUDFLARE_API_TOKEN": "您的令牌",
"CLOUDFLARE_ACCOUNT_ID": "您的账户 ID"
}
}
}
}
```
然后询问 Claude：
```
"列出我的 D1 数据库"
"显示 d1://abc-123 中 users 表的架构"
"最近 7 天内有多少订单被下达？"
"2 点的部署出了问题 — 将 prod 回滚到 1:45pm"
"将本地 dev.db 与 d1://prod-db-id 进行差异比较，并显示迁移 SQL"
"将此迁移应用于 d1://prod-db-id"
```
### 只读工具（始终可用）
| 工具 | 功能 |
|---|---|
| `litescope_d1_list` | 列出账户中的所有 D1 数据库（UUID、名称、DSN） |
| `litescope_query` | 对任何 D1 数据库或本地 SQLite 文件运行 SELECT 语句 |
| `litescope_schema` | 检查表、列、索引 |
| `litescope_health` | 检查损坏、WAL 堆积、碎片 |
| `litescope_diff` | 两个源之间的架构和行数差异 |
| `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` 限制 + 列投影 + 截断报告 — 因此大表永远不会超出代理的上下文窗口。
### 写工具（ `--allow-writes` ）
| 工具 | 功能 |
|---|---|
| `litescope_query_write` | 变更 SQL — **默认干预运行**：测量确切影响的行数，自动快照，返回失败时的锁定医生补救 |
| `litescope_migrate_apply` | 应用迁移 — 默认干预运行，预迁移快照，结构化错误 |
| `litescope_autopilot` | 自主优化（ANALYZE，索引，VACUUM）— 默认干预运行 |
| `litescope_snapshot` | 取本地数据库的时间点备份 |
| `litescope_restore` | 从快照恢复本地数据库 |
| `litescope_rewind` | 将 D1 数据库恢复到某个时间点（时间旅行） |
| `litescope_d1_pull` | 将 D1 数据库下载到本地 SQLite 文件 |
| `litescope_d1_create` | 创建新的 D1 数据库 |
| `litescope_d1_delete` | 删除 D1 数据库（不可逆） |
### 提示和资源
除了工具外，MCP 服务器还公开 **提示** —诸如 `diagnose_locked_database`、`review_migration`、`safe_optimize` 和 `health_checkup` 之类的规范工作流程，它们将上述工具链接到一个安全计划中 — 以及 **资源**：数据库的架构和数据字典，可由代理在无需工具调用的情况下读取。使用 `litescope mcp ./app.db` 绑定一个资源，或通过 `litescope://schema/{source}` 和 `litescope://dictionary/{source}` 地址任意源。
服务器实现了 **MCP 2025-06-18**：工具注释（只读/破坏性提示）、结构化输出（`structuredContent` + `outputSchema`）、参数补全、资源变更订阅和服务器日志。
### 远程/托管（Streamable HTTP）
默认情况下，`litescope mcp` 使用 stdio。通过 Streamable HTTP 传输改为托管、远程或多客户端设置：
```bash
litescope mcp --http :7577 --http-token "$LITESCOPE_MCP_TOKEN"
```
向端点（默认为 `/mcp`）发送 JSON-RPC 消息，或打开一个 `GET` SSE 流以获取服务器通知；每个客户端通过 `Mcp-Session-Id` 头部获取自己的会话。
在公开之前，请锁定它： `--http-token` （或 `LITESCOPE_MCP_TOKEN` 环境变量）要求每个请求都具有 `Authorization: Bearer <token>`，并且 `--http-origin` 允许浏览器源（始终允许 localhost）进行 DNS 重新绑定保护。没有令牌，端点是开放的，服务器会打印警告。
---
## D1 — CLI 操作
### 回滚 — D1 时间旅行
```bash
# 恢复到之前的某个时间点
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"
# 列出可用的恢复点（30 天窗口 + 迁移时间戳）
litescope rewind list d1://DB_ID
```
### 拉取/推送 — 在 D1 和本地 SQLite 之间同步
```bash
# 下载 D1 → 本地（用于检查、备份或差异比较）
litescope d1 pull d1://DB_ID ./snapshot.db
# 上传本地 → D1（种子一个新数据库或从快照恢复）
litescope d1 push ./seed.db d1://DB_ID
litescope d1 push ./seed.db d1://DB_ID --drop-existing
```
### 迁移 — D1 上的架构更改
```bash
# 本地开发模式与实时 D1 的差异 — 生成迁移 SQL
litescope migrate local.db d1://DB_ID
# 直接将迁移应用于 D1
litescope migrate apply d1://DB_ID migration.sql
```
### 二分查找 — 查找哪个提交导致 D1 数据库出现问题
对 D1 时间旅行进行二进制搜索，以确定查询开始返回错误结果的确切快照：
```bash
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` — 一次性体检
```bash
litescope doctor app.db
litescope doctor app.db --deep # exhaustive integrity_check
litescope doctor app.db --format html -o report.html
```
将完整性检查、WAL/碎片健康检查、索引建议和架构检查结合在一个命令中。当需要关注时退出 **1** — 在 CI 中将其用作质量门控。
### `snapshot` / `restore` — 时间点备份
```bash
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/` 目录中。恢复是完整性检查的，并在恢复前进行预恢复安全快照 — 与 D1 从时间旅行获得的相同安全网，适用于本地和 Turso。
### `autopilot` — 自主优化
```bash
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` — 诊断“数据库被锁定”
```bash
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
```
检查 journal 模式、`busy_timeout`、锁定模式和 WAL 堆积，并规定确切的 PRAGMA/DSN 修复。 `--live` 确定当前持有锁定的进程。
### `diff` — 架构和数据差异
```bash
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` — 生成和应用迁移
```bash
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` — 架构反模式
```bash
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
```bash
litescope schema app.db
litescope schema app.db --erd # Mermaid ER diagram
```
### `dump` — 可移植的 SQL 导出
```bash
litescope dump app.db -o backup.sql
litescope dump app.db --schema-only
litescope dump app.db --table users
```
### `import` / `export` — 电子表格和 SQLite
```bash
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` — 架构漂移检测
```bash
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` — 本地 Web 仪表盘
```bash
litescope serve # opens http://127.0.0.1:7575
litescope serve --config litescope.fleet.yaml
```
舰队拓扑图、健康检查、架构指纹、交互式 ERD、分页数据浏览器，带有可视化查询生成器、拖放导入和 **可视化差异面板** — 选择任意两个数据库来审查架构和行数更改，然后再应用。完全本地，无需帐户。
---
## 舰队
一次管理数百个数据库。适用于 Turso 和 D1 的多租户应用而构建。
```bash
# 发现所有数据库
litescope fleet discover turso --org my-org --token $TURSO_API_TOKEN
litescope fleet discover d1 --account $CF_ACCOUNT_ID --token $CF_API_TOKEN
# 对整个舰队进行故障排查
litescope fleet health
litescope fleet fingerprint # cluster by schema — find drift before it bites
# 在整个舰队上进行迁移
litescope fleet migrate migration.sql --dry-run
litescope fleet migrate migration.sql --canary 5
litescope fleet migrate migration.sql
```
---
## CI — GitHub Action
在每个拉取请求上运行 Litescope — 检查架构、与基准分支的差异，并注释爆破半径，以免有风险的迁移在未经审查的情况下合并。
```yaml
- uses: croc100/Litescope@v1
with:
args: "lint app.db --strict"
comment: "true" # post the result as a sticky PR comment
```
`args` 是任意 Litescope 命令；如果 Litescope 标记某些内容，作业退出状态为非零，从而导致检查失败。参见
[examples/github-actions/migration-ci.yml](examples/github-actions/migration-ci.yml)
获取完整的 lint + diff 工作流程。
| 输入 | 默认值 | 描述 |
|---|---|---|
| `args` | — | 要运行的 Litescope 命令（必填） |
| `version` | `latest` | 要安装的发布标签，或 `latest` |
| `comment` | `false` | 将输出作为粘性 PR 评论发布 |
| `working-directory` | `.` | 运行目录 |
---
## 安装
**Homebrew**
```bash
brew install croc100/tap/litescope
```
**npm / npx** — 适用于 JS 和 `wrangler` 用户，无需单独安装：
```bash
npx litescope doctor app.db
npm install -g litescope
```
**Go 安装**
```bash
go install github.com/croc100/litescope/cmd/litescope@latest
```
**二进制下载**
macOS、Linux、Windows — [发布](https://github.com/croc100/Litescope/releases)。
---
## 远程源
| DSN | 提供商 |
|---|---|
| `./app.db` 或 `/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](https://turso.tech) |
---
## 许可证
Litescope 采用 **AGPL-3.0** 。免费使用、修改和自我托管。如果您将其作为网络服务提供，AGPL 要求您共享您的修改。对于组织，商业许可证（AGPL 例外 + 支持 SLA）可用 — 请参见 [COMMERCIAL.md](COMMERCIAL.md) 或发送电子邮件至
**dl_litescope@crode.net** 。
