angular-signal-forms-migration-mcp

An MCP server that helps an AI coding agent migrate Angular Reactive Forms to Angular Signal Forms.

It finds the Reactive Forms constructs in your codebase, separates the safe mechanical renames from the ones that need a human decision, and hands back before→after recipes that are verified against a real Angular release rather than written from memory.

Install

Requires Node.js 20+. Nothing to clone — npx fetches it on demand.

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

Or add it to any MCP client config:

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

@latest makes npx re-resolve on every launch, so restarting your editor picks up new releases. Without it, npx keeps serving whichever version it cached first — repoint the config at @latest, or clear the cache with npm cache clean --force.

The server also checks for a newer version once a day and writes a one-line notice to stderr. It is throttled, times out after 2 seconds, never touches stdout, and stays silent on any failure. To turn it off, add "env": { "SIGNAL_FORMS_MCP_NO_UPDATE_CHECK": "1" } to the config block above. To see what is actually running:

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

[!IMPORTANT] Do not npm install this into your Angular app. It is a standalone process your editor spawns, not a library your project depends on. npx keeps it in a cache outside your project entirely.

[!NOTE] It detects and advises. It never edits your code. There is no tool here that writes to your source files, and there never will be. The server returns findings and recipes; your agent decides what to change and makes the edits, so every change still goes through your normal review and version control.

What it looks like

> 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

Prerequisites it checks before advising anything

A migration report leads with the things that make migration impossible, because a plan you cannot execute is worse than no plan:

1. Angular 21+. @angular/forms/signals does not exist before v21. Below that the server returns an upgrade plan instead of a migration plan.
2. Declared and installed versions agree. An old branch checked out over newer node_modules straddles the v21 line. Migrating against what is installed means the next npm ci reverts you to a version where the target API is absent — so the server refuses to pick a side and says so.
3. moduleResolution is exports-aware (bundler, node16, or nodenext). @angular/forms/signals is a package-exports subpath; legacy node resolution cannot see it, and the import fails with an error that looks like a missing dependency.

Tools

Full parameters, response shapes and scope limits: docs/TOOLS.md.

How the recipes are verified

Signal Forms is new and is not reliably present in any model's training data — recipes written from memory are wrong in ways that look right. So none of these are.

Recipes are verified against Angular v22 using the official Angular CLI MCP server, cross-checked against angular.dev, and carry structured provenance (verifiedAgainstVersion, retrievedISO, sources) that ships in the tool response so your agent can judge how current the advice is. A recipe with an empty sources list fails CI.

Where the docs do not answer the question, the recipe says so in its caveats rather than inventing an answer — UNVERIFIED — confirm on <url>, or UNVERIFIED — tool-authored guidance where Angular documents no migration path at all (the RxJS stream tiers are the main case: the primitives are documented and compile, but choosing between them is this tool's judgement, not Angular's). 14 of 37 recipes currently carry such a marker. That is the honest part of the output, not an oversight — and a test keeps this number true.

The recipes also compile. CI installs a real @angular/forms@22 and typechecks fixtures exercising every API the recipes use, so a recipe naming a function that does not exist — or calling it with the wrong argument shape — fails the build. That is what established disabled(path, { when }) as the v22 signature; the docs demonstrate neither it nor the nested schema() + apply() composition.

Two things this caught that memory gets wrong:

• The binding directive is [formField] / FormField — not [control] / Control, which appeared in pre-release v21 material and is what models reproduce.
• disabled() / hidden() gained an options-object form on v22 and marked the bare callback @deprecated rather than removing it — so a v21-shaped rule still compiles, with a warning. Established by diffing the shipped overloads, not the guides.

Recipes whose behaviour genuinely differs across releases carry a VERSION-SENSITIVE caveat naming the form each version takes, and the server resolves them against your project's detected version. Read the caveats array — that is where the sharp edges live.

The re-verification procedure for a new Angular release is REVERIFICATION.md.

It tells you when there is no clean answer

Not every Reactive Forms pattern has a Signal Forms equivalent, and a migration tool that pretends otherwise is worse than none. Form streams are graded by the RxJS operators in their .pipe() chain:

For the hard tier the recipe says so outright and offers three real strategies — async validation rules, rxResource, or keeping RxJS behind toObservable/toSignal — rather than inventing a one-liner that does not exist.

Likewise addControl() / removeControl() have no counterpart at all: the field tree is derived from the model signal's type. The recipe explains the three actual answers instead of implying an API that would not compile.

What it will not do

• Edit your files. By design, permanently.
• Prove your migration is correct. verify_migration proves the absence of known defects. Run it after tsc, not instead of it.
• Migrate template-driven forms. ngModel migration is undocumented upstream; guessing it would be the exact failure mode this project exists to avoid.
• Read template literals with ${...} substitutions, because their text is not what the Angular compiler sees. Inline template: strings without substitutions are scanned.
• Scan CSS/SCSS, or resolve types across files — detection is a single-file syntactic pass, not a ts.Program.

ROADMAP.md tracks these; the migration report repeats them in its own "Scope" section rather than letting the totals imply completeness.

Why not just the official Angular MCP server?

Use both. The official @angular/cli MCP server knows about Angular; this one knows about migration — which constructs exist in your code, which are mechanical, which need a decision, and what the verified replacement is. Your agent can pull findings and recipes from here, then confirm anything current or project-specific there before it edits.

Status

Feature-complete through M16. Six tools ship, with doc-verified recipes covering basic constructs, arrays, runtime shape mutation, async validators, custom controls, the three RxJS stream tiers, reading and writing form state, submission, model-shape constraints, CSS status classes, spec-file migration, and the .html template layer — bindings, state reads, the <select multiple> blocker, and the silent error-key rename.

The transport is stdio, so stdout is reserved for the protocol and all logging goes to stderr.

Contributions and local development: CONTRIBUTING.md.

License

MIT