# mcp-migration-diff

**国产化 / 跨库迁移差异** · MCP Server

> 迁移最容易翻车的不是语法，是「语法过了但语义变了」—— 这里把两者分开查。

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

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

会自动带上它需要的共享库：`sqltk-core`（方言/AST/计划）、`sqltk-store`（字典/校验记录）。**不会**带其他 MCP。

## 挂到 MCP 客户端

```json
{
  "mcpServers": {
    "migration-diff": {
      "command": "python",
      "args": ["-m", "migration_diff"],
      "env": { "DBT_STORE": "~/.dbtoolchain" }
    }
  }
}
```

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

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

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

## 工具（12）

| 工具 | 作用 |
|---|---|
| `check_charset_collation` | 字符集与排序规则差异检查。 |
| `check_null_semantics` | NULL / 空串 / 布尔语义差异检查 —— 最容易漏且最难查的一类。 |
| `check_object_parity` | 生成对象数量与定义比对的 SQL 清单（客户在自己环境执行）。 |
| `check_type_mapping` | 类型映射 + 精度溢出预警。 |
| `compare_data` | 生成两层数据比对计划：L1 全表计数+校验和（快），L2 抽样明细（只在 L1 不通过时做）。 |
| `detect_dialect_gap` | 列出所有目标库不支持的写法，按严重度排序。 |
| `estimate_rewrite_effort` | 按命中规则估算改造工作量（比拍脑袋有依据）。 |
| `generate_migration_report` | 迁移就绪度报告 —— 给项目经理看的汇总。 |
| `plan_migration` | 迁移批次编排：按依赖拓扑分批，标注可并行度与回滚批次。 |
| `record_migration_result` | 把本次迁移的发现写入共享档案 —— 跨项目积累可复用的迁移知识。 |
| `translate_sql` | 确定性改写。**改不动的不硬改，明确说明** |
| `verify_consistency` | 生成一致性校验 SQL 批次，并明确每条的执行顺序与判据。 |

## 闭环

`map_type` 类型映射 → `detect_dialect_gap` 语法 Gap → `translate_sql` 翻译 → `plan_consistency_check` 校验方案（L1 校验和 + L2 抽样）→ `check_object_parity` 对象对齐 → `estimate_effort` 工作量

## Tier（冷启动保证）

全部 `tier0`：不需要连库，拿建表语句和 SQL 就能出报告。

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

只做源库到目标库的差异与一致性校验。SQL 写法优化归 `mcp-sql-review`，口径定义归 `mcp-data-semantics`。

## 开发

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

## 许可

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