angular-signal-forms-migration-mcp

angular-signal-forms-migration-mcp

AI コーディングエージェントによる Angular Reactive Forms から Angular Signal Forms への移行を支援する MCP サーバーです。

コードベース内の 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 でキャッシュを消去してください。

サーバーは 1 日に 1 回、新しいバージョンがあるかどうかも確認し、stderr に 1 行の通知を書き込みます。この確認は頻度が制限され、2 秒でタイムアウトし、stdout には一切触れず、失敗しても何も出力しません。無効にするには、上記の設定ブロックに "env": { "SIGNAL_FORMS_MCP_NO_UPDATE_CHECK": "1" } を追加してください。実際に実行されているバージョンを確認するには、次のようにします。

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

重要

Angular アプリにこれを npm install しないでください。 これはエディターが起動する独立したプロセスであり、プロジェクトが依存するライブラリではありません。npx はプロジェクトの外部にあるキャッシュに保存します。

メモ

検出して助言するだけです。コードを編集することはありません。 ソースファイルを書き換えるツールはなく、今後も追加されません。サーバーは検出結果と手順を返し、変更する内容を決めて編集するのはエージェントです。そのため、すべての変更に通常のレビューとバージョン管理が適用されます。

使用イメージ

> 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 はパッケージの exports のサブパスです。従来の node 解決では認識できず、依存関係が見つからないように見えるエラーでインポートに失敗します。

ツール

ツール	回答する内容
find_form_candidates	Reactive Forms の構文はどこにあり、どれに人の判断が必要ですか？
get_signalforms_recipe	この構文の、検証済みの移行前→移行後は何ですか？
analyze_migration_complexity	この作業の規模はどれくらいで、どのファイルから始めるべきですか？
get_migration_report	全体を 1 つの Markdown ドキュメントとして提示してください。
verify_migration	すでに移行しました。このコードはコンパイルできても、何がまだ間違っていますか？
get_angular_upgrade_plan	v21 より前を使っています。これをサポートするバージョンにするにはどうすればよいですか？

パラメーター、レスポンス形式、対象範囲の制限について詳しくは、docs/TOOLS.md を参照してください。

レシピの検証方法

Signal Forms は登場したばかりで、どのモデルの学習データにも確実に含まれているわけではありません。記憶を頼りに書かれたレシピは、一見正しそうに見えても間違っています。そのため、ここにあるレシピはすべて検証済みです。

レシピは公式の Angular CLI MCP サーバーを使用して Angular v22 で検証し、angular.dev と照合しています。また、構造化された出典情報（verifiedAgainstVersion、retrievedISO、sources）を付与し、ツールの応答に含めているため、エージェントはアドバイスがどの程度最新かを判断できます。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() の組み合わせも示されていません。

記憶違いが起きやすく、検証で判明した点を 2 つ紹介します。

• バインディングディレクティブは [formField] / FormField です。[control] / Control ではありません。 こちらは v21 のプレリリース資料に登場し、モデルが再現しがちな形式です。
• v22 では disabled() / hidden() にオプションオブジェクト形式が追加され、引数だけのコールバックは削除されずに @deprecated とマークされました。そのため、v21 形式のルールもコンパイルはできますが、警告が表示されます。このことはガイドではなく、公開されたオーバーロードを比較して確認しました。

リリース間で動作が実際に異なるレシピには、それぞれのバージョンでの形式を明記した VERSION-SENSITIVE 注意事項が付いており、サーバーはプロジェクトで検出されたバージョンに応じてレシピを解決します。caveats 配列を確認してください。 注意すべき点はそこに記載されています。

新しい Angular リリースに向けた再検証の手順は、REVERIFICATION.md を参照してください。

明確な答えがない場合は、そのことを伝えます

Reactive Forms のパターンすべてに Signal Forms の同等機能があるわけではなく、あるかのように装う移行ツールは、ツールがないよりも悪いものです。フォームストリームは .pipe() チェーン内の RxJS オペレーターに基づいて分類されます。

ティア	オペレーター	回答
trivial	なし／引数なしの subscribe	computed()、実際の副作用には effect()
moderate	map、filter、debounceTime、distinctUntilChanged、…	computed() ＋ debounce() スキーマルール
hard	switchMap、combineLatest、withLatestFrom、forkJoin、…	直接の同等機能なし

hard ティアの場合、レシピはそのことを明確に伝え、存在しないワンライナーをでっち上げるのではなく、実際に使える 3 つの方法、すなわち非同期バリデーションルール、rxResource、または toObservable / toSignal の背後で RxJS を使い続ける方法を提示します。

同様に、addControl() / removeControl() には対応する機能がまったくありません。フィールドツリーはモデルシグナルの型から導出されます。レシピでは、コンパイルできない API があるかのように示唆するのではなく、実際に使える 3 つの方法を説明します。

対応しないこと

• ファイルを編集すること。 設計上、今後も対応しません。
• 移行が正しいことを証明すること。 verify_migration が証明するのは、既知の 不具合がないことです。tsc の実行後に使い、tsc の代わりにはしないでください。
• テンプレート駆動フォームを移行すること。 ngModel の移行方法は上流で文書化されていません。 推測で対応すれば、このプロジェクトが回避しようとしている失敗そのものになります。
• ${...} の置換を含むテンプレートリテラルを読み取ること。 そのテキストは Angular コンパイラーが見るものとは異なるためです。置換を含まないインラインの template: 文字列はスキャンされます。
• CSS/SCSS をスキャンすること、またはファイルをまたいで型を解決すること。 検出は 単一ファイルの構文パスであり、ts.Program ではありません。

ROADMAP.md でこれらを管理しています。移行レポートでも、合計数からすべてに対応していると誤解されないよう、独自の「範囲」セクションで繰り返し説明しています。

公式 Angular MCP サーバーだけでは不十分な理由

両方を使ってください。公式の @angular/cli MCP サーバーは Angular に関する情報を提供しますが、こちらは 移行 に関する情報を提供します。コード内にどの構文があるか、機械的に移行できるものは何か、判断が必要なものは何か、検証済みの置き換え方法は何かが分かります。エージェントはここから検出結果や手順を取得し、編集前に、最新の情報やプロジェクト固有の情報が必要なものを公式サーバーで確認できます。

ステータス

M16 までの機能が完成しています。6 つのツールを提供しており、基本的な構文、配列、実行時の形状変更、非同期バリデーター、カスタムコントロール、3 つの RxJS ストリーム層、フォーム状態の読み取りと書き込み、送信、モデル形状の制約、CSS の状態クラス、spec ファイルの移行、そして .html テンプレート層（バインディング、状態の読み取り、<select multiple> のブロッカー、通知されないエラーキーの名前変更）を網羅した、ドキュメントで検証済みの手順を備えています。

トランスポートには stdio を使用しているため、stdout はプロトコル専用で、すべてのログは stderr に出力されます。

貢献とローカル開発については、CONTRIBUTING.md を参照してください。

ライセンス

MIT