angular-signal-forms-migration-mcp

MCP-сервер, который помогает ИИ-агенту по написанию кода мигрировать 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

[!IMPORTANT] Не выполняйте npm install этого пакета в свой проект Angular. Это отдельный процесс, который запускает ваш редактор, а не библиотека, от которой зависит ваш проект. npx хранит его в кэше полностью вне вашего проекта.

[!NOTE] Сервер обнаруживает и подсказывает. Он никогда не изменяет ваш код. Здесь нет инструмента, который пишет в ваши исходные файлы, и никогда не будет. Сервер возвращает находки и рецепты; ваш агент решает, что менять, и вносит изменения, так что каждое изменение по-прежнему проходит через ваше обычное ревью и систему контроля версий.

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 с помощью официального MCP-сервера Angular CLI, перекрёстно сверяются с angular.dev и несут структурированную информацию о происхождении (verifiedAgainstVersion, retrievedISO, sources), которая приходит в ответе инструмента, чтобы ваш агент мог судить, насколько совет актуален. Рецепт с пустым списком sources не проходит CI.

По вопросам, на которые документация отвечает, рецепт прямо говорит в caveats, а не выдумывает ответ: UNVERIFIED — подтверждать по <url>, или UNVERIFIED — руководство, созданное инструментом для случаев, когда у Angular нет задокументированного маршрута (основной пример — три уровня RxJS-потоков: примитивы задокументированы и компилируются, но выбор между ними — суждение этого инструмента, а не Angular). 14 из 37 рецептов сейчас отмечены таким маркером. Это честная часть вывода, а не недоработка — и тест сохраняет это число актуальным.

Рецепты также компилируются. CI устанавливает настоящий @angular/forms@22 и проверяет типы на примерах, которые используют все API из рецептов, так что рецепт, либо вызывающий функцию, которого нет, либо с неверной формой аргументов, валит сборку. Именно так была установлена сигнатура v22 disabled(path, { when }); документация не демонстрирует ни её, ни вложенную композицию schema() + apply().

Две вещи, в которых память ошибается:

• Связывающая директива — это есть [formField] / FormField, а не [control] / Control, которая встречалась в материтах предрелиза v21 и именно её воспроизводят модели.

• disabled() / hidden() в v22 получили форму объекта параметров и пометили голый колбэк @deprecated, а не удалили его, поэтому правило, рассчитанное на v21, статья компилируется, но с предупреждением. Это установлено сравнением поставляемых перегрузок, а не по гайдам.

Рецепты, поведение которых действительно различается между релизами, несут маркер VERSION-SENSITIVE, в котором указано, какую форму принимпонентное то или иная версия; сервер выбирает нужный вариант под обнаруженную версию вашего проекта. Читайте массив caveats — там находятся все острые углы.

Процедура повторной проверки при новом релизе Angular: REVERIFICATION.md.

Он сообщает, когда нет однозначного ответа

Не у каждого паттерна Reactive Forms есть аналог в Signal Forms, и миграционный инструмент, который делает вид, что это не так, хуже, чем никакой. Формные потоки классифицируются по набору RxJS-операторов в цепи .pipe():

Для сложного уровня рецепт прямо это говорит и предлагает три настоящие стратегии — асинхронные правила валидации, rxResource или хранение RxJS за toObservable/toSignal, — а не выдуманную однострочную замену, которая не существует.

Как и addControl() / removeControl() вообще не имеют аналога: дерево полей выводится из типа сигнала модели. Рецепт объясняет три реальных варианта вместо того, чтобы подразумевать API, которое не скомпилируется.

Что он делать не будет

• Редактировать ваши файлы. Не будет никогда, намеренно и навсегда.

• Доказывать, что миграция корректна. verify_migration доказывает отсутствие известных дефектов. Запускайте его после tsc, а не вместо него.

• Мигрировать шаблонные формы. Миграция ngModel не задокументирована вышестоящим проектом; угадывать её — это ровно тот режим отказа, ради которого существует этот проект.

• Читать шаблон-литералы с подстановкой ${...}, И их текст — это не то, что видит компилятор Angular. Местове инлайн-строки template: без подстановок сканируются.

• Сканировать CSS/SCSS или резолвить типы между файлами; это однофайловой синтаксический проход, а не ts.Program.

ROADMAP.md отслеживает это; миграционный отчёт повторяет их в своём разделе «Scope», чтобы общее количество не создавало иллюзию полноты.

Почему не просто официальный Angular MCP-сервер?

Используйте оба. Официальный MCP-сервер @angular/cli разбирается в Angular; этот разбирается в миграции — какие конструкции есть в вашем коде, какие из них механические, а какие требуют решения, и что является проверенной заменой. Ваш агент может взять находки и рецепты здесь, затем свериться сей с актуальной там версией проекта перед внесением управлений.

Статус

Функциональная версия завершена на M16. Работает шесть инструментов с проверенными рецептами, покрытыми базовые конструкции, массивы, изменение формы в рантайме, асинхронные валидаторы, пользовательские контролы, три уровня RxJS-потоков, чтение и запись состояния формы, отправка, ограничения формы модели, CSS-классы статусов, миграция спец-файлов и шаблонный слой .html — привязки, чтение состояния, блокировку <select multiple> и скрытое переименование ключа ошибок.

Транспорт — stdio, поэтому stdout зарезервирован для протокола, а вся диагностикилicense идёт в stderr.

Вклад и локальная разработка: CONTRIBUTING.md.

Лицензия

MIT