angular-signal-forms-migration-mcp

[!license](https://img.shields.io/ npm/l/angular-signal-forms-migration-mcp.svg)](./LICENSE)

一个 MCP 服务器，帮助 AI 编程代理将 Angular Reactive Forms 迁移到 Angular Signal Forms。

它会在你的代码库中找出 Reactive Forms 结构，区分出安全的机械性重命名和需要人的决策的重命名，并给出经过真实 Angular 版本验证的 before→after 方案，而不是凭记忆编造。

安装

要求 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

[!IMPORTANT] 不要 npm install 安装到你的 Angular 应用中。 它是由你的编辑器拉起的独立进程，不是项目所依赖的库。npx 会把它放在完全独立于项目之外的缓存中。

[!NOTE] 它只探测与建议，从不修改你的代码。 这里没有任何工具会写你的源文件，以后也不会有。服务器返回“发现结果”和“迁移方案”；由你的代理决定改哪些并执行编辑，所以每次改动仍然会走你平常的 code review 和版本控制。

Related MCP server: VA Form Generation MCP Server

它长什么样

> 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 解析方式看不到它，导入时会报成一个“缺依赖”的错误。

工

完整参数、响应格式和作用域限制见 docs/TOOLS.md。

这些方案是如何验证的

Signal Forms 很新，大多数模型的训练数据中都没有可靠地包含它——凭记忆写成的方案，错得看起来又像对。所以没有一种是这些凭记忆写。

方案会针对 Angular v22 验证：使用官方 Angular CLI MCP 服务器，并用 angular.dev 交叉确认，同时携带结构化出处（verifiedAgainstVersion、retrievedISO、sources），随工具响应一起发给你的代理，让它能判断建议的新旧。带有空白 sources 列表的方案便会 CI 失败。

凡是在文档中没有回答的地方，方案会在其 caveats 里直接说明，而不是自造答案——“UNVERIFIED — confirm ”，或在 Angular 根本没有 migration 路径时，标注 UNVERIFIED — tool-authored guidance（工具自己写的做法）。主要例子就是 RxJS 流层级：原语有文档且能编译，但在这些之间作选择是本工具的判断，而不是 Angular 的。当前 37 个方案中有 14 个带这类标记。这是输出中诚实的一部分，不是忽略，而且会有一个测试另行保障这个数字真实。

这些方案还可被编译。 CI 安装真实的 @angular/forms@22，并对覆盖全部方案 API 的 fixture 做类型检查，外加两个案例：

disabled(path, { when }) 作为 v22 的签名就是这么确立的——文档里既没有演示它，也没有演示嵌套的 schema() + apply() 组合。

这两个例子是 “记忆”会给记错的：

• 绑定指令是 [formField] / FormField——不是 [control] / Control，后者出现在 v21 预发布材料里，也是模型常出的错。

• disabled() / hidden() 在 v22 上加了对象参数形式，并把裸回调标为 @deprecated 而非移除——所以按 v21 的写法写来 v22 依然能编译，只是有警告。これは通过比较已产生的重载，而不是文档得出结论。

不同版本真正行为不同的方案带一个 VERSION-SENSITIVE 注释来指出每种版本形式，并由服务器针对项目检测到的版本来解析。读 caveats 数组，那里藏着树利角。

对新 Angular 新版本的重新验证过程在 [REVEREIFIC.html) 里。

它会在没有干干净净答案时告诉你

并非每个 Angular Reactive 模式都有 Signal Forms 对应物；假装那么做的迁移工具比不做还要糟。表单流根据 .pipe() 链中的 RxjS 运算符分成等级:

对困难这一档，会在“没有直接等价物”里直说，并给出三个真实策略——异步校验 rules、rxesource、或在 toObservable/toSignal 后保留 RxJS——而不是伪造一个不存在的一行式代码。

同理，addControl()/removeControl() 完全没有替代对应物：字段树是从 model signal 的类型派生得来的。它的路线方法三个实答，而不是找一个能编译不了的 API。

yes 不会做

• 改你的文件。 永远不，是按设计决定的。

• 证明你的迁移一定正确。 verify_migration 证明没有 已知 缺陷。请在 tscription 后运行它，而不是替代它。

• 迁移模板驱动表单。 ngModel 的迁移没有上游文档；猜它正是这个项目要避免的动手模式。

• 分析带 ${...} 替换的模板字符串，因为字符串里的内容不是 Angular 编译器看到的界面。而不带替换的一段内联 template: 字符串 会 被分析。

• 扫描 CSS/SCSS 或跨文件解析类型——探测只是单文件语法 pass，不是 ts. Program。

ROADMAP.md 跟踪这些; 迁移报告会在其自身 "Scope” 部分重复它们，而不是用总来误示完毕。

为什么不直接只用官方 Auther MCP

都用。 官方 @angular/cli MCP 服务器懂 Angular；这一个懂 迁移—你的代码里有哪些结构、哪些是机械的、哪些需要决策，以及替换的方案是什么。你的代理可以从这里取发现和建议，再到官方那确认当前及项目特定的事件。

状态

一直在副稳定。六个工具齐全的 with:

feature-complete through M16。六个工具发布，带：

• 基础构造、数组、运行时形状变化、异步 validators、自定义控件、三个 RxJS 层、读写表单状态、提交、模型形状限制、CSS 状态类、spec 迁移，以及 .html 模板层——绑定、状态读取、<selectmultiple> 阻塞问题，以及静默错误键更换。

传输是 stdio——stdout 只做 protocol，log 全部走 stderr。

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

License

MIT