locksmith

Locksmith 🔒

データベースをロックする前に、危険な SQL マイグレーションを検出する MCP サーバーです。

ほとんどのマイグレーションは無害に見えますが、本番環境を停止させることがあります。単純な CREATE INDEX は、作成にかかる間、すべての書き込みをブロックします。ALTER COLUMN ... TYPE は ACCESS EXCLUSIVE ロックの下でテーブル全体を書き換えます。SET NOT NULL はすべての行をスキャンします。どの操作が安全なのか、そして危険な操作を安全にする書き換え方法は、シニアエンジニアの頭の中にある知識です。

Locksmith は、その知識を LLM エージェント（または人間）が呼び出せるツールとして実装します。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 サーバーを使う理由

エージェントはロックのセマンティクスを推論できることがあります。しかし、その推論は再現可能ではなく、テスト、監査、あるいは無人のデプロイを承認するための信頼できる方法にもなりません。同じプロンプトでも、ある実行ではテーブルを書き換える 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	critical	CONCURRENTLY を指定しない CREATE INDEX（書き込みをブロック）
index-concurrently-in-transaction	critical	BEGIN/COMMIT 内の CONCURRENTLY（Postgres が拒否）
add-column-not-null-no-default	critical	デフォルト値のない ADD COLUMN NOT NULL（失敗／書き換えが発生）
alter-column-type	critical	ALTER COLUMN ... TYPE（テーブル全体を書き換え）
add-column-volatile-default	warning	ADD COLUMN ... DEFAULT now() など（テーブルを書き換え）
set-not-null	warning	SET NOT NULL（排他ロックの下で全件スキャン）
add-foreign-key-validating	warning	NOT VALID を指定しない ADD FOREIGN KEY（両方のテーブルをロック）
add-check-constraint-no-not-valid	warning	NOT VALID を指定しない ADD CHECK（全件スキャン）
drop-column-or-table	warning	破壊的な操作で、デプロイ済みのコードが動作しなくなる
rename-column-or-table	warning	実行中のアプリケーションコードが動作しなくなる

ルールの抑制

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）については、ルールが正規化されたテキストにフォールバックします。解析できないステートメントは「手動で確認してください」という注記に切り替わります。リンターは、理解できない入力に対して処理を失敗させません。
• ルールを合成できます。 各ルールは、専用ファイルにメタデータを含む純粋関数です。ルールの追加は、1 ファイルの変更とレジストリへの 1 行の追加で済みます。
• 証明ツールではなく、アドバイザリーです。 Locksmith はレビューを補完します。assumeLargeTables はデフォルトで true に設定されており、警告を出す方向に動作します。

ロードマップ

• ホスト型デプロイ向けのリモート（Streamable HTTP）トランスポート。
• 対応する方言の追加（MySQL、SQLite）。
• 既知の小規模テーブルに関する検出結果を抑制する、オプションのライブ DB イントロスペクション。
• 同じエンジンを使用して PR をゲートする GitHub Action。

ライセンス

MIT