angular-signal-forms-migration-mcp

angular-signal-forms-migration-mcp

一个 MCP 服务，可帮助 AI 编码 Agent 将 Angular Reactive Forms 迁移到 Angular Signal Forms。

它会查找代码库中的 Reactive Forms 结构，将安全的机械式重命名与需要人工判断的部分区分开来，并提供迁移前→后的方案；这些方案经过真实 Angular 版本验证，而非凭记忆编写。

安装

需要 Node.js 20+。无需克隆——npx 会按需获取。

claude mcp add signal-forms-migration -- npx -y angular-signal-forms-migration-mcp@latest

也可以将其添加到任意 MCP 客户端配置中：

{
  "mcpServers": {
    "signal-forms-migration": {
      "command": "npx",
      "args": ["-y", "angular-signal-forms-migration-mcp@latest"]
    }
  }
}

@latest 会让 npx 在每次启动时重新解析版本，因此重启编辑器即可获取新版本。不加它，npx 会一直使用最初缓存的版本——请将配置改为 @latest，或使用 npm cache clean --force 清除缓存。

该服务还会每天检查一次是否有新版本，并向 stderr 写入一行提示。检查会进行限流，2 秒后超时，不会触碰 stdout，且任何失败都不会输出信息。若要关闭此功能，请在上方配置代码块中添加 "env": { "SIGNAL_FORMS_MCP_NO_UPDATE_CHECK": "1" }。若要查看实际运行的版本：

npx angular-signal-forms-migration-mcp@latest --version

重要

不要将此服务 npm install 到你的 Angular 应用中。 它是由编辑器启动的独立进程，而不是项目依赖的库。npx 会将它保存在项目外部的缓存中。

说明

它只检测并提供建议，不会编辑你的代码。 此处没有任何会写入源文件的工具，今后也不会有。该服务返回发现结果和迁移方案；由你的 Agent 决定要更改什么并进行编辑，因此每项更改仍会经过正常的审查和版本控制流程。

效果预览

> Migrate the forms in src/app/checkout to Signal Forms.

  1. find_form_candidates { path: ".../src/app/checkout" }
     → 9 findings across 2 files: 6 mechanical, 3 judgment
       (the FormArray of line items is judgment — its shape changes)
  2. get_signalforms_recipe { construct: "FormBuilder.group" }
     → before/after + caveats
  3. the agent applies the edits, you review the diff
  4. verify_migration { path: ".../checkout.component.ts" }
     → traps that compile and are still wrong

提供建议前会检查的前提条件

迁移报告会首先列出导致迁移无法进行的因素，因为无法执行的计划比没有计划更糟：

1. Angular 21+。 @angular/forms/signals 在 v21 之前不存在。低于此版本时，该服务会返回升级计划，而不是迁移计划。
2. 声明的版本与已安装的版本一致。 如果在较新的 node_modules 上检出旧分支，版本就会跨越 v21 的界线。若按已安装的版本迁移，那么下一次 npm ci 会将你还原到目标 API 不存在的版本——因此，该服务不会擅自选择，而会说明情况。
3. moduleResolution 能识别 exports（bundler、node16 或 nodenext）。 @angular/forms/signals 是 package-exports 子路径；旧版 node 解析机制无法识别它，导入时会报错，看起来像是缺少依赖。

工具

工具	它能回答的问题
find_form_candidates	Reactive Forms 结构在哪里？哪些需要人工判断？
get_signalforms_recipe	此结构经过验证的迁移前→后方案是什么？
analyze_migration_complexity	这项工作有多大？应该从哪个文件开始？
get_migration_report	将全部内容整理成一份 Markdown 文档。
verify_migration	我已经完成迁移——哪些代码虽然能编译，但仍然有问题？
get_angular_upgrade_plan	我的版本低于 v21。如何升级到支持此功能的版本？

完整参数、响应格式和适用范围：docs/TOOLS.md。

配方如何经过验证

Signal Forms 是新技术，任何模型的训练数据中都不一定可靠地包含它——凭记忆编写的配方可能错得看起来却很正确。因此，这些配方都不是凭记忆编写的。

配方使用官方 Angular CLI MCP 服务，针对 Angular v22 进行验证，并与 angular.dev 交叉核对；配方还附带结构化溯源信息（verifiedAgainstVersion、retrievedISO、sources），这些信息会随工具响应一起提供，以便你的 Agent 判断建议有多新。sources 列表为空的配方会导致 CI 失败。

如果文档没有回答问题，配方会在注意事项中明确说明，而不是编造答案——例如 UNVERIFIED — confirm on <url>；如果 Angular 完全没有记录迁移路径，则会使用 UNVERIFIED — tool-authored guidance（RxJS 流的各个层级是主要案例：这些基本构件有文档记录且可以编译，但如何在它们之间选择是本工具的判断，而非 Angular 的说法）。目前 37 个配方中有 14 个带有此类标记。这是输出诚实的一面，并非疏忽——而且有测试确保这个数字准确无误。

这些配方也能编译。 CI 会安装真实的 @angular/forms@22，并对测试样例进行类型检查，覆盖配方使用的每个 API；因此，配方若提及不存在的函数，或以错误的参数形式调用函数，都会导致构建失败。正是这项检查确认了 disabled(path, { when }) 是 v22 的签名；文档既没有展示这种用法，也没有展示嵌套的 schema() + apply() 组合。

这项检查发现了两处凭记忆容易搞错的地方：

• 绑定指令是 [formField] / FormField——不是 [control] / Control；后者曾出现在 v21 发布前的资料中，也是模型会复现的内容。
• v22 为 disabled() / hidden() 增加了选项对象形式，并将裸回调标记为 @deprecated，而非将其移除——因此，符合 v21 形式的规则仍能编译，只是会有警告。这是通过对比发布的重载定义确认的，而非依据指南得出。

行为确实会因版本而异的配方会附带 VERSION-SENSITIVE 注意事项，说明各版本采用的形式；服务会根据检测到的项目版本解析这些配方。请阅读 caveats 数组——其中列出了容易踩坑的地方。

新 Angular 版本的重新验证流程见 重新验证指南。

当没有明确答案时，它会告诉你

并非每种 Reactive Forms 模式都有对应的 Signal Forms 方案，假装有对应方案的迁移工具还不如没有。表单流根据其 .pipe() 链中的 RxJS 运算符分级：

层级	运算符	方案
简单	无 / 裸 subscribe	computed()，或在确实需要副作用时使用 effect()
中等	map、filter、debounceTime、distinctUntilChanged、……	computed() + debounce() schema 规则
困难	switchMap、combineLatest、withLatestFrom、forkJoin、……	没有直接对应项

对于困难级别，配方会直接说明这一点，并提供三种可行策略——异步验证规则、rxResource，或通过 toObservable/toSignal 保留 RxJS——而不是编造一个根本不存在的单行方案。

同样，addControl() / removeControl() 完全没有对应项：字段树是根据模型信号的类型推导出来的。配方会解释三种实际可行的方案，而不是暗示存在一个无法编译的 API。

不会做的事

• 编辑你的文件。 按设计，永远不会。
• 证明迁移正确。 verify_migration 只能证明不存在_已知_缺陷。请在运行 tsc 后运行它，而不是用它代替 tsc。
• 迁移模板驱动表单。 上游没有记录 ngModel 迁移；猜测迁移方式恰恰会重现本项目旨在避免的失败模式。
• 读取带有 ${...} 替换的模板字面量，因为其中的文本与 Angular 编译器看到的内容不同。没有替换内容的内联 template: 字符串会被扫描。
• 扫描 CSS/SCSS，或跨文件解析类型——检测是针对单个文件的语法扫描，而非 ts.Program。

ROADMAP.md 会跟踪这些事项；迁移报告也会在自己的“范围”部分重申这些限制，而不会让汇总数据暗示迁移已涵盖所有内容。

为什么不只用官方 Angular MCP 服务？

两者都用。官方 @angular/cli MCP 服务了解 Angular；这个服务了解_迁移_——你的代码中有哪些结构、哪些可以机械迁移、哪些需要做出选择，以及经过验证的替代方案是什么。你的 Agent 可以从这里获取发现结果和迁移方案，然后在编辑前到官方服务中确认当前信息或项目特定的信息。

状态

功能已完成至 M16。目前提供 6 个工具，并提供经文档验证的迁移方案，涵盖基本结构、数组、运行时形状变更、异步验证器、自定义控件、3 个 RxJS 流层级、表单状态的读取与写入、提交、模型形状约束、CSS 状态类、spec 文件迁移，以及 .html 模板层——绑定、状态读取、<select multiple> 阻塞项，以及静默的错误键重命名。

传输方式为 stdio，因此 stdout 专用于协议，所有日志都输出到 stderr。

贡献和本地开发：CONTRIBUTING.md。

许可证

MIT