z-mcp-vb-migration

基于 @modelcontextprotocol/sdk 实现的 MCP stdio 服务，用于将 Android 项目中的 kotlinx.android.synthetic 迁移到 ViewBinding。

可在 Cursor 等 AI 编程客户端中通过 MCP 工具批量扫描并迁移 Kotlin 文件。

使用

在项目根目录创建 .cursor/mcp.json：

{
  "mcpServers": {
    "z-mcp-vb-migration": {
      "command": "npx",
      "args": ["-y", "z-mcp-vb-migration", "--stdio", "--android-module=app"]
    }
  }
}

--android-module 为 Android 模块名，相对 Cursor 工作目录（项目根）解析，如 app 对应 {项目根}/app。

提供的工具

| 工具名 | 说明 | | ------ | ---- | | vb_list_kt_files | 扫描项目中仍使用 synthetic 的 Kotlin 文件，返回待迁移列表 | | vb_migrate_kt_file | 迁移指定的 Kotlin 文件到 ViewBinding（自动处理第一个主布局） |

使用示例

列出项目中所有需要迁移 ViewBinding 的 Kotlin 文件

迁移 xxx/Activity.kt 到 ViewBinding

先扫描待迁移文件，再逐个迁移

AI 迁移工作流（推荐）

让 AI 批量迁移、少跑 Gradle，可显著节省时间：

1. 先扫描：vb_list_kt_files 获取待迁移列表
2. 批量迁移：连续调用 vb_migrate_kt_file 迁移多个文件（如 5～10 个一批）
3. 不要每迁一个就打包：禁止 assembleDebug / installDebug / 打 APK
4. 批次结束后再编译一次：

   ./gradlew :app:compileDebugKotlin

   只校验 Kotlin 编译，比全量打包快很多
5. 仅在用户要求或编译报错时再跑完整构建

在 Cursor 中加规则（可选）

在 Android 项目 .cursor/rules/vb-migration.mdc 中写入：

---
description: ViewBinding 迁移时不要频繁打包
globs: **/*.kt
---

使用 z-mcp-vb-migration 迁移 ViewBinding 时：
- 单文件迁移后不要运行 assembleDebug / installDebug
- 批量迁移完成后执行 compileDebugKotlin 验证即可
- 用户未明确要求时不要启动 Gradle 全量构建

迁移说明

• 自动替换控件 ID（tv_title → binding.tvTitle），并补全无 android:id 的 <include>
• 自动修改基类与泛型：
  • BaseActivity → BaseActivityVB<XxxBinding>
  • BaseMvpActivity<P> → BaseMvpActivityVB<P, XxxBinding>
  • BaseFragment / BaseMvpFragment 同理
• 自动删除 Activity 的 getContentView()，添加 getViewBinding()
• Fragment 保留 getLayoutId()（与 getViewBinding() 并存，适配项目基类）
• 自动将 *Adapter.data = 转为 setNewInstance(...)
• 成员变量与视图 id 同名时跳过替换，并在 warnings 中提示
• 迁移结果包含 warnings 字段（合成引用遗漏、非法 this::binding.xxx 等）
• 仅自动迁移第一个主布局（通过 getContentView / getLayoutId / setContentView 或文件名推断）
• 多主布局时其余主布局需手动处理；代码 inflate 的子布局（如 item 布局）不会自动迁移