locksmith

Locksmith 🔒

一个 MCP 服务，可在危险的 SQL 迁移锁定数据库之前将其拦截。

大多数迁移看起来无害，却会导致生产环境宕机：普通的 CREATE INDEX 会在构建期间阻塞所有写入；ALTER COLUMN ... TYPE 会在 ACCESS EXCLUSIVE 锁下重写整张 表；SET NOT NULL 会扫描每一行。哪些操作安全，以及如何通过重写让危险操作变安全，这些知识 都存在资深工程师的脑海中。

Locksmith 将这些知识编码为一项工具，LLM Agent（或人工）都可以调用。提供一段 PostgreSQL 迁移代码，它会返回 PASS / REVIEW / BLOCK 判定、针对每条风险语句的发现 （会获取哪种锁，为什么 危险），以及具体的安全改写方案。

🛑 BLOCK — do not ship as written

## 🛑 CREATE INDEX without CONCURRENTLY  `create-index-non-concurrent` (line 5)
> `CREATE INDEX idx_users_email ON users (email)`
Problem: This index build will block all writes to the table until it completes.
Lock taken: SHARE (blocks writes)
Fix: Build the index with CREATE INDEX CONCURRENTLY, which does not block writes.
Suggested rewrite:
  CREATE INDEX CONCURRENTLY idx_users_email ON users (email)

为什么要用 MCP 服务？

Agent 通常能够推理锁语义，但无法做到可重复，也无法以可测试、可审计、可信的方式在无人监督的情况下拦截部署。同一条提示词可能一次批准会重写表的 ALTER，下一次却将其标记出来，或者在一段较长的迁移中完全漏掉。Locksmith 将这种概率性能力变为确定、经过测试的工具：锁语义只需验证一次（依据 PostgreSQL 文档和解析器的实际行为，并通过测试套件锁定每条规则），此后每次运行的结果都相同，返回相同的判定和可直接粘贴的修复方案——因此，“审查这段迁移”不再是猜测。

功能

工具

• analyze_migration(sql, assumeLargeTables?) → 判定 + 发现 + 安全改写方案 （同时提供便于阅读的 Markdown 和经过验证的结构化输出）。
• explain_lock(query) → 说明给定的 Postgres 锁模式会阻塞什么，以及哪些操作会获取该锁。

资源

• locksmith://lock-matrix — PostgreSQL 表级锁兼容性矩阵。
• locksmith://rules — 完整规则目录（id、严重性、理由），格式为 JSON。

提示词

• review-migration — 分析迁移，并将风险总结为 PR 评论。

规则目录

规则	严重性	检查内容
create-index-non-concurrent	严重	CREATE INDEX 未使用 CONCURRENTLY（会阻塞写入）
index-concurrently-in-transaction	严重	在 BEGIN/COMMIT 中使用 CONCURRENTLY（Postgres 会拒绝）
add-column-not-null-no-default	严重	ADD COLUMN NOT NULL 未指定默认值（会失败／重写）
alter-column-type	严重	ALTER COLUMN ... TYPE（会完整重写表）
add-column-volatile-default	警告	ADD COLUMN ... DEFAULT now() 等（会重写表）
set-not-null	警告	SET NOT NULL（会在排他锁下进行完整扫描）
add-foreign-key-validating	警告	ADD FOREIGN KEY 未使用 NOT VALID（会锁定两张表）
add-check-constraint-no-not-valid	警告	ADD CHECK 未使用 NOT VALID（会进行完整扫描）
drop-column-or-table	警告	具有破坏性 + 会导致已部署的代码失效
rename-column-or-table	警告	会导致正在运行的应用代码失效

禁用规则

像 eslint 一样，在行内确认接受某项刻意承担的风险：

-- locksmith:disable create-index-non-concurrent
CREATE INDEX idx_users_email ON users (email);

单独使用 -- locksmith:disable 会禁用下一条语句的所有规则。

安装与运行

无需克隆或构建——直接通过 npm 运行：

npx locksmith-mcp

与 Claude Code 配合使用

claude mcp add locksmith -- npx -y locksmith-mcp

也可以添加到任何 MCP 客户端配置中（Claude Desktop 等）：

{
  "mcpServers": {
    "locksmith": { "command": "npx", "args": ["-y", "locksmith-mcp"] }
  }
}

改为从源代码运行

git clone https://github.com/cxk280/locksmith.git && cd locksmith
npm install && npm run build
# then point your client at:  node /absolute/path/to/locksmith/dist/index.js

使用 MCP Inspector 试用

npx @modelcontextprotocol/inspector npx -y locksmith-mcp

然后使用 examples/dangerous.sql 的内容调用 analyze_migration。

开发

npm run dev    # run from source with tsx
npm test       # vitest: per-rule + golden tests on examples/

设计说明

• 确定性。 不依赖时钟、随机性或网络——输入相同的 SQL，输出相同的判定结果。 因此它易于测试，也能安全地用于 CI。
• 混合解析。 解析器支持时，将语句解析为 AST（pgsql-ast-parser）；对于解析器无法建模的 Postgres 子句（NOT VALID、CONCURRENTLY），规则会退回到规范化文本。无法解析的语句会降级为“需手动审核”提示——对于无法理解的输入，检查器绝不会直接判定通过。
• 规则可组合。 每条规则都是纯函数，其元数据与规则本身放在同一个文件中；新增规则只需修改一个文件，并在注册表中添加一行。
• 提供建议，而非证明。 Locksmith 用于辅助审核；assumeLargeTables 默认为 true，因此倾向于标记问题。

路线图

• 为托管部署提供远程（Streamable HTTP）传输方式。
• 支持更多方言（MySQL、SQLite）。
• 可选的实时数据库内省功能，用于抑制已知小型表上的发现项。
• 提供一个 GitHub Action，封装相同引擎以对 PR 进行门禁检查。

许可证

MIT