# mcp-change-risk

**变更风险与执行状态机** · MCP Server

> 把「这条 DDL 能不能上」变成可解释的分数，把「上了能不能退」变成强制门禁。

## 安装（按需，不必装其他 MCP）

```bash
pip install mcp-change-risk                        # 从 PyPI
pip install "./mcp-change-risk[mysql]"             # 从源码（在工具链根目录执行）；要连库就补驱动，或 [postgres]
```

会自动带上它需要的共享库：`sqltk-core`（连库/只读防护）、`sqltk-store`（变更事件落库）、`sqltk-know`（引擎阈值）。**不会**带其他 MCP。

## 挂到 MCP 客户端

```json
{
  "mcpServers": {
    "change-risk": {
      "command": "python",
      "args": ["-m", "change_risk"],
      "env": { "DBT_STORE": "~/.dbtoolchain" }
    }
  }
}
```

按你的客户端（Claude Desktop / Cursor / Cline 等）说明，把这段合并到对应的 `mcpServers` 配置里。

命令行调试（不挂客户端也能用）：

```bash
mcp-change-risk tools
mcp-change-risk call <tool> --args '{"sql": "SELECT 1"}'
```

## 工具（13）

| 工具 | 作用 |
|---|---|
| `abort_change` | 放弃一个尚未执行的变更，写入审计。**不执行、也不回滚任何 SQL**。 |
| `apply_change` | 按计划执行，全程留痕。**没有 approver 一律拒绝** |
| `assess_change` | DDL 风险 L0-L3、锁影响、推荐工具、前置条件。不连库也能评估。 |
| `change_report` | 单个变更的完整时间线证据链 —— 事故复盘和责任划分的依据。 |
| `change_status` | 查某个变更当前处在状态机哪一步（含审批人、风险等级与计划详情）。 |
| `dry_run_change` | ★ dry-run：真正执行一遍，看到真实影响行数与耗时，然后**强制回滚**。 |
| `estimate_impact` | 估算影响面：DML 用执行计划估算行数，查询类直接 COUNT。 |
| `execute_canary` | 受限灰度执行。必须有审批人，且必须已通过 dry-run。 |
| `generate_rollback` | 生成反向 DDL。**不可逆操作会明确说不可逆，而不是编造一条看起来能回滚的语句** |
| `list_changes` | 列出实例的变更记录，可按 state 过滤。 |
| `plan_change_execution` | 生成可审批的执行计划：步骤 + 检查点 + 回滚点，并持久化到档案。 |
| `precheck_change_window` | 变更窗口前置检查：长事务 / 复制延迟 / 关键参数 → go or no-go |
| `rollback_change` | 按 change_id 回滚到变更前状态。 |

## 闭环

`assess_change` 评估 → `generate_rollback` 回滚方案 → `precheck_change_window` 窗口预检 → `dry_run_change` → `execute_canary` 灰度 → `apply_change` / `rollback_change`

## Tier（冷启动保证）

评估为 `tier0`（因子模型 + 引擎知识）；`precheck` / `dry_run` 需连库（`tier1`）。每次状态迁移自动写 `change_event`，供事后与异常做时间关联。

## 边界：这个仓不做什么

只做变更的评估与执行编排。SQL 写法好坏归 `mcp-sql-review`，实例当时健不健康归 `mcp-dbwatch`。

## 开发

```bash
python tests/test_change_risk.py      # 不需要 pytest，也不需要数据库
```

## 许可

MIT © 2026 罗文星 —— 见 [LICENSE](LICENSE)。