DeltaScope
接入你的智能体
从发布者处安装。不是 PlugMCP 端点。
远程 URL 还是本机命令? 两种安装方式的区别
SQL audit for MySQL, TiDB, and PostgreSQL — works offline, or connect to the database for metadata-aware review.
The repository installer script is the generic portable installer. It resolves the same release archives CI publishes.
If GitHub API discovery is unavailable, it falls back to the public latest-release redirect; set DELTASCOPE_VERSION=vX.Y.Z to bypass discovery when needed.
curl -fsSL https://raw.githubusercontent.com/Fanduzi/DeltaScope/main/install.sh | sh
macOS can also use Homebrew:
brew tap Fanduzi/deltascope
brew install --cask deltascope
Pin a specific release:
curl -fsSL https://raw.githubusercontent.com/Fanduzi/DeltaScope/v0.511.1/install.sh | \
DELTASCOPE_VERSION=v0.511.1 sh
The MCP launcher fetches the deltascope-mcp binary for your platform. You do not need to install the CLI first. The launcher is npx -y --prefer-online @fanduzi/deltascope-mcp@latest.
Example mcp.json:
{
"mcpServers": {
"deltascope": {
"command": "npx",
"args": ["-y", "--prefer-online", "@fanduzi/deltascope-mcp@latest"]
}
}
}
More install options: MCP Quick Start.
Audit a risky DML statement:
deltascope audit --sql "delete from users"
Example excerpt:
Verdict: reject
Statements: 1
Blockers: 1
Warnings: 0
Notices: 0
Statement 1: DELETE
- [blocker] dml.where.require: UPDATE and DELETE statements must include a WHERE clause
Audit a CREATE TABLE statement:
deltascope audit --sql "create table tbl_users (id bigint unsigned not null auto_increment comment 'id', created_at datetime not null default current_timestamp comment 'created', updated_at datetime not null default current_timestamp on update current_timestamp comment 'updated', primary key (id)) comment='users' engine=InnoDB default charset=utf8mb4"
Example excerpt:
Verdict: review
Statements: 1
Blockers: 0
Warnings: 1
Notices: 0
Statement 1: CREATE TABLE
- [warning] ddl.column.default.require: column "id" should define a default value
Audit a file:
deltascope audit --file ./migrations/20260328_add_column.sql
Use JSON output for CI or agents:
deltascope audit \
--sql "create table tbl_users (id bigint unsigned not null auto_increment comment 'id', created_at datetime not null default current_timestamp comment 'created', updated_at datetime not null default current_timestamp on update current_timestamp comment 'updated', primary key (id)) comment='users' engine=InnoDB default charset=utf8mb4" \
--format json \
--fail-on warning
Example JSON shape:
{
"verdict": "review",
"summary": {
"statements": 1,
"blockers": 0,
"warnings": 1,
"notices": 0
},
"statements": [ ... ],
"context": {
"mode": "offline",
"dialect": "mysql",
"dialect_source": "default"
}
}
Audit a TiDB statement:
deltascope audit --dialect tidb --sql "alter table users add column email varchar(255) not null"
Audit a PostgreSQL CREATE TABLE with constraints:
deltascope audit \
--dialect postgresql \
--sql "create table orders (id bigint primary key, user_id bigint references users(id), amount numeric not null check (amount >= 0))"
When SQL looks like PostgreSQL but the dialect is set to MySQL, DeltaScope emits an advisory notice without auto-switching:
deltascope audit --sql "insert into users(id) values (1) returning id;"
To audit PostgreSQL SQL explicitly:
deltascope audit --dialect postgresql --sql "insert into users(id) values (1) returning id;"
Generate SARIF output for GitHub Code Scanning:
deltascope audit --file ./migrations.sql --format sarif > deltascope.sarif
Use CI-native output with any dialect:
deltascope audit --dialect postgresql --file ./migrations/20260409_add_index.sql --format github-actions
Write a short review summary to the GitHub Actions run page with --format github-summary:
deltascope audit --file ./migrations.sql --format github-summary --fail-on none >> "$GITHUB_STEP_SUMMARY"
For a complete GitHub Actions workflow that combines a config lint --strict gate, inline github-actions annotations, and a github-summary job summary, see github-actions.yml. Output formats are documented in cli.md.
For GitLab CI, use --format gitlab-codequality and publish gl-code-quality-report.json as a Code Quality artifact; see use-deltascope-in-gitlab-ci.md.
Validate a policy config in CI. A clean config prints Config OK; a config with only replacement-hazard warnings prints Config OK with warnings and exits 0. Add --strict to fail on those warnings:
deltascope config lint --file ./deltascope.yaml --strict
Follow up with deltascope config status to inspect a single rule's effective ON/OFF state.
Every tag publishes archives named deltascope_<version>_<os>_<arch>.tar.gz containing deltascope, deltascope-server, and deltascope-mcp. All archives support MySQL, TiDB, and PostgreSQL offline audit via --dialect mysql|tidb|postgresql. The installer script, Homebrew Cask, and npm MCP launcher all resolve platform-specific archives from GitHub Release assets. See the audit capability matrix for per-dialect coverage and release notes for version-by-version changes.
For a selective DML such as DELETE FROM users WHERE id = 42, DeltaScope may add an impact object to the statement result. The object is conservative by design and reports estimated_rows, estimated_ratio, risk_level, confidence, source, reason_codes, and optional notes.
{
"raw_sql": "DELETE FROM users WHERE id = 42",
"impact": {
"estimated_rows": 1,
"estimated_ratio": 0.0001,
"risk_level": "low",
"confidence": "high",
"source": "metadata",
"reason_codes": ["pk_equality"],
"notes": ["refined with table statistics"]
}
}
Offline mode uses SQL shape only. MySQL, TiDB, and PostgreSQL share the bounded single-table id = literal/parameter equality heuristic; PostgreSQL $1 placeholders are supported. Non-equality, OR, range, and unrecognized-column predicates remain unknown, while a missing WHERE remains a full-table estimate. Metadata-aware mode may refine the estimate with read-only table statistics. A live PostgreSQL EXPLAIN estimate remains source: plan and overrides the shape estimate. DeltaScope does not execute the DML and does not run EXPLAIN ANALYZE.
Audit with live metadata (instance-aware rules):
deltascope audit \
--sql "alter table orders add index idx_status (status)" \
--host 127.0.0.1 --port 3306 --user root --ask-password --database app
Metadata-aware audit with an explicit connect timeout (MySQL):
deltascope audit \
--sql "alter table users add column email varchar(255)" \
--dialect mysql \
--host 127.0.0.1 --port 3306 --user root --ask-password --database app \
--metadata-connect-timeout 5s
Metadata-aware audit with PostgreSQL:
deltascope audit \
--sql "alter table orders add column status text not null" \
--dialect postgresql \
--host 127.0.0.1 --port 5432 --user root --ask-password \
--database app --schema public \
--metadata-connect-timeout 5s
Metadata-aware audit over TLS:
deltascope audit \
--sql "alter table orders add column status text not null" \
--dialect postgresql \
--host pg.example.com --port 5432 --user root --ask-password \
--tls-mode enabled --tls-ca-file /etc/ssl/certs/pg-ca.pem \
--database app --schema public --metadata-connect-timeout 5s
Stock MySQL 8.4 auto-generated server certificates have no hostname-valid SAN. Supplying the
server's ca.pem establishes trust but does not make that certificate valid for localhost or an
IP address. For TLS metadata access, use a server certificate with a DNS/IP SAN matching --host
and the corresponding trusted CA; DeltaScope keeps hostname verification enabled.
See all shipped rules:
deltascope rules list
SQL mistakes are cheap to catch before they run and expensive after. DeltaScope gives you one consistent engine across local dev, CI, HTTP service, and MCP so the same policy applies everywhere — no per-tool rule duplication, no dialect surprises.
CREATE VIEW, DROP TABLE, TRUNCATE TABLE, and database/schema lifecycle DDL across MySQL, TiDB, and PostgreSQL.WHERE, LIMIT, ORDER BY, subqueries, join conditions, bulk insert patterns, denylisted objects, and conservative affected-row impact estimation.deltascope CLI, deltascope-server, deltascope-mcp, and pkg/deltascope.deltascope-mcp is the official MCP stdio server and exposes audit_sql, describe_rule, list_rules, and get_capabilities.No install required. The npm launcher fetches and runs the correct
deltascope-mcpbinary for your platform automatically.
Launcher requirements:
darwin or linux, amd64 or arm64Recommended launcher:
claude mcp add --scope user deltascope -- npx -y --prefer-online @fanduzi/deltascope-mcp@latest
codex mcp add deltascope -- npx -y --prefer-online @fanduzi/deltascope-mcp@latest
For raw stdio TOML, native deltascope-mcp, direct connection, connection_ref, proxy setup, and common errors, see Use DeltaScope MCP.
Run deltascope-mcp with runtime config for logging and metadata defaults:
deltascope-mcp -runtime-config /etc/deltascope/runtime.yaml
MCP stdout logging is forbidden to protect the stdio protocol. Runtime config can set output: file or output: stderr, but not stdout.
# ~/.config/deltascope/connections.yaml
connections:
local_mysql:
host: 127.0.0.1
port: 3306
user: root
password_env: MYSQL_PASSWORD
schema: app
dialect: mysql
connect_timeout: 5s
Both named connections and direct connection inputs accept connect_timeout. Empty or 0s falls back to the runtime config default. MySQL, TiDB, and PostgreSQL all support metadata connect timeout.
Works in Claude Code, Codex, Cursor, and 40+ AI coding agents. Install once, get inline SQL review in every session.
DeltaScope ships a universal AI agent skill for inline SQL review during AI coding sessions. The skill detects whether DeltaScope is installed locally, calls it to audit your SQL, and surfaces findings with fix suggestions — without leaving your AI coding session.
# Install via npx skills (Claude Code, Codex, Cursor and 40+ AI agents)
npx skills add Fanduzi/DeltaScope --skill deltascope-review -a claude-code
Install globally (available across all projects):
npx skills add Fanduzi/DeltaScope --skill deltascope-review -a claude-code -g
Keep the skill up to date:
npx skills update
Then invoke in any supported AI session:
/deltascope-review
Paste a SQL snippet or point to a file — the agent audits it with DeltaScope and suggests fixes. See skills/README.md for full setup and usage.
make test runs go test ./...make sql-corpus-gates runs the untagged MySQL/TiDB golden corpus and supported rule-and-dialect fixture coverage gatemake build produces all local binaries under bin/make build-linux produces Linux amd64 binaries under bin/make test-e2e-cli runs the Docker-backed metadata CLI smoke suitemake pg-unit-test-gates runs the PostgreSQL-tagged unit gate setmake pg-e2e-gates runs the Docker-backed PostgreSQL CLI, HTTP, and MCP suitesmake pg-confidence-gates runs the canonical PostgreSQL confidence closureRun the HTTP adapter over the same audit engine:
deltascope-server -listen 127.0.0.1:8083
Run with runtime config for logging and metadata defaults:
deltascope-server -listen 127.0.0.1:8083 -runtime-config /etc/deltascope/runtime.yaml
See docs/examples/runtime-config.yaml for a complete runtime config example.
Endpoints:
GET /healthzGET /versionPOST /v1/auditPOST /v1/audit supports both offline JSON audit requests and metadata-aware requests with a connection_id that references a named connection defined in the server's runtime config. HTTP requests cannot submit credentials directly. The HTTP response keeps the public audit result body and adds a context block. See the full contract in HTTP API reference.
The CLI retains direct connection flags (
--host,--port,--user,--password-env,--ask-password,--database,--schema,--tls-mode,--tls-ca-file). Theconnection_idboundary applies to HTTP only. MCP has no Query Access tool and retains its separate metadata-audit connection model.
{
"sql": "alter table users add column email varchar(255)",
"dialect": "mysql",
"connection_id": "local_mysql"
}
The connection_id references a named connection in the server's runtime config (see docs/examples/runtime-config.yaml). The named connection can define connect_timeout as a Go duration string (500ms, 5s, 1m). Empty or 0s falls back to the runtime config default. Invalid or negative values return a 400 error. MySQL, TiDB, and PostgreSQL all support metadata connect timeout.
result, err := deltascope.Audit(ctx, deltascope.Request{
SQL: "delete from users",
Dialect: deltascope.DialectMySQL,
})
The stable public API lives in pkg/deltascope.
DeltaScope keeps one audit path and exposes it through multiple entrypoints. Product-level and implementation-level diagrams live in docs/concept/architecture.md and docs/dev/architecture.md.
Offline-first SQL audit engine and MCP SQL audit server for MySQL, TiDB, and PostgreSQL DDL/DML changes.
工具
暂无工具列表。远程服务器在首次健康检查后会获得工具列表。
常见问题
在本页复制适用于 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 配置。它使用发布者的安装方式,而不是 PlugMCP 代理。
此记录未列出必需的环境变量。
DeltaScope 通过 stdio 在本地运行。
上次检查时间:2026-11-15。 Offline-first SQL audit engine and MCP SQL audit server for MySQL, TiDB, and PostgreSQL DDL/DML changes.