Инструменты рефакторинга MCP ts-morph

обзор

Этот сервер MCP использует ts-morph для выполнения операций рефакторинга для кодовых баз TypeScript и JavaScript. Он работает с расширениями редактора, такими как Cursor, позволяя переименовывать символы на основе AST, переименовывать файлы/папки и находить ссылки.

Предоставленные функции

Этот сервер MCP предоставляет следующие функции рефакторинга: каждая функция использует ts-morph для анализа AST и внесения изменений, сохраняя при этом согласованность во всем проекте.

Переименование символов ( rename_symbol_by_tsmorph )

• Что он делает : глобально переименовывает символ (функцию, переменную, класс, интерфейс и т. д.) в определенной позиции указанного файла во всем проекте.

• Вариант использования : Вы хотите изменить имя функции или переменной, но на нее существует много ссылок, и изменить ее вручную будет сложно.

• Требуемая информация : путь к проекту tsconfig.json , путь к целевому файлу, положение символа (строка и столбец), текущее имя символа, новое имя символа

Переименование файла/папки ( rename_filesystem_entry_by_tsmorph )

• Функция : переименовывает несколько указанных файлов и/или папок и автоматически обновляет пути во всех операторах import / export в проекте.

• Вариант использования : вы меняете структуру файла и хотите соответствующим образом изменить пути импорта. Если вы хотите переименовать/переместить несколько файлов/папок одновременно.

• Требуемая информация : путь к tsconfig.json проекта, массив операций переименования ( renames: { oldPath: string, newPath: string }[] ).

• замечания :

  • Ссылки в основном разрешаются с использованием символьного разрешения.

  • Ссылки, содержащие псевдонимы путей (например, @/ ), будут обновлены, но преобразованы в относительные пути .

  • Импорты, ссылающиеся на файл индекса каталога (например, ../components ) , обновляются до явного пути к файлу (например, .

  • Он также выполняет проверку на наличие конфликтов путей (дубликатов в существующих путях и внутри операции) перед операцией переименования.

• Примечание (время выполнения): При работе с большим количеством файлов и папок одновременно или для очень больших проектов анализ и обновление ссылок может занять некоторое время.

• ПРИМЕЧАНИЕ (известное ограничение): В настоящее время ссылки на экспорт по умолчанию формы export default Identifier; могут быть обновлены некорректно.

Поиск ссылок ( find_references_by_tsmorph )

• Что он делает : находит и выводит на экран определение символа в определенном месте указанного файла, а также все ссылки на него в проекте.

• Вариант использования : Вы хотите знать, где используется функция или переменная. Вы хотите изучить область рефакторинга.

• Требуемая информация : путь к tsconfig.json проекта, путь к целевому файлу, положение символа (строка, столбец).

Удалить псевдоним пути ( remove_path_alias_by_tsmorph )

• Функция : Заменяет псевдонимы путей (например, @/components ) в операторах import / export в указанном файле или каталоге на относительные пути (например, ../../components ).

• Вариант использования : Вы хотите сделать свой проект более портативным или соответствовать определенным стандартам кодирования.

• Требуемая информация : tsconfig.json путь к проекту, путь к файлу или каталогу для обработки.

Перемещение символов между файлами ( move_symbol_to_file_by_tsmorph )

• Функция : Перемещает указанный символ (функцию, переменную, класс, интерфейс, псевдоним типа, перечисление) из текущего файла в другой указанный файл. Автоматически обновляйте ссылки по всему проекту (включая пути импорта/экспорта) по мере продвижения.

• Вариант использования : вы хотите извлечь определенную функциональность в отдельный файл, чтобы реорганизовать свой код.

• Требуемая информация : путь к tsconfig.json проекта, путь к исходному файлу, путь к целевому файлу, имя перемещаемого символа. При желании можно указать тип символа ( declarationKindString ), чтобы устранить неоднозначность символов с одинаковыми именами.

• Примечание : внутренние зависимости символа (другие объявления, используемые только внутри этого символа) перемещаются вместе с ним. Зависимости, на которые также ссылаются другие символы, оставшиеся в исходном файле, останутся в исходном файле, а export будут добавлены по мере необходимости и импортированы в целевой файл.

• Примечание : символы, экспортированные export default нельзя перемещать с помощью этого инструмента.

окружающая среда строительство

Для пользователей (при использовании как пакета npm)

Добавьте следующие настройки в mcp.json . При использовании команды npx будет автоматически использоваться последняя установленная вами версия.

Для разработчиков (для локальной разработки и исполнения)

Если вы хотите запустить сервер локально из исходного кода, вам необходимо сначала его собрать.

После сборки вы можете запустить его непосредственно в node , установив следующее в mcp.json :

Настройки ведения журнала (переменные среды)

Уровень выходных данных и место назначения журнала операций сервера можно контролировать с помощью следующих переменных среды. Установите его в блоке env mcp.json .

• LOG_LEVEL : Устанавливает уровень детализации журнала.

  • Доступные уровни: fatal , error , warn , info (по умолчанию), debug , trace , silent

  • Пример: "LOG_LEVEL": "debug"

• LOG_OUTPUT : указывает место назначения вывода журнала.

  • console (по умолчанию): выводит журнал на стандартный вывод. Если вы находитесь в среде разработки ( NODE_ENV !== 'production' ) и у вас установлен pino-pretty , вывод будет в формате pretty.

  • file : Выводит журнал в указанный файл. Установите этот параметр, чтобы избежать влияния на клиентов MCP.

  • Пример: "LOG_OUTPUT": "file"

• LOG_FILE_PATH : если для LOG_OUTPUT задано значение file , это указывает абсолютный путь к файлу журнала.

  • По умолчанию: [プロジェクトルート]/app.log

  • Пример: "LOG_FILE_PATH": "/var/log/mcp-tsmorph.log"

Пример конфигурации (в mcp.json ):

Информация для разработчиков

Предпосылки

• Node.js (версию см. в .node-version или volta в package.json )

• pnpm (версию см. в поле packageManager в package.json )

настраивать

Клонируйте репозиторий и установите зависимости:

Строить

Компилирует код TypeScript в JavaScript.

Артефакты сборки выводятся в каталог dist .

тест

Запустите модульные тесты.

Линтинг и форматирование

Он статически анализирует и форматирует ваш код.

Использование отладочной оболочки

Если вы хотите подробно проверить последовательность запуска, стандартный ввод/вывод и вывод ошибок сервера MCP во время разработки, вы можете использовать mcp_launcher.js , который находится в каталоге scripts проекта.

Этот скрипт-оболочка запускает исходный процесс сервера MCP ( npx -y @sirosuzume/mcp-tsmorph-refactor ) как дочерний процесс и регистрирует информацию о запуске и вывод в файле .logs/mcp_launcher.log в корне проекта.

Как использовать:

1. В файле mcp.json измените конфигурацию сервера mcp-tsmorph-refactor следующим образом:

   • Установите command на "node" .

   • В args укажите путь к scripts/mcp_launcher.js (например, ["path/to/your_project_root/scripts/mcp_launcher.js"] ). Вы также можете использовать путь относительно корня проекта ( ["scripts/mcp_launcher.js"] ).

   Пример конфигурации ( mcp.json ):

   { "mcpServers": { "mcp-tsmorph-refactor": { "command": "node", // scripts/mcp_launcher.js へのパス (プロジェクトルートからの相対パス or 絶対パス) "args": ["path/to/your_project_root/scripts/mcp_launcher.js"], "env": { // 元の環境変数設定はそのまま活かせます // 例: // "LOG_LEVEL": "trace", // "LOG_OUTPUT": "file", // "LOG_FILE_PATH": ".logs/mcp-ts-morph.log" } } // ... 他のサーバー設定 ... } }

2. Перезапустите или перезагрузите клиент MCP (например, Cursor).

3. Убедитесь, что журнал выводится в .logs/mcp_launcher.log в корне проекта. Вы также можете проверить журнал самого сервера MCP, если он настроен (например, .logs/mcp-ts-morph.log ).

Использование этой оболочки может помочь вам диагностировать, почему ваш сервер MCP не запускается должным образом.

Публикация в npm

Этот пакет будет автоматически опубликован в npm через рабочий процесс GitHub Actions ( .github/workflows/release.yml ).

Предпосылки

• Токен NPM: убедитесь, что у вас есть токен доступа npm с публичными разрешениями, установленными в секретах действий вашего репозитория ( Settings > Secrets and variables > Actions ) с именем NPM_TOKEN .

• Обновите версию: перед публикацией обновите поле version в package.json в соответствии с семантическим версионированием (SemVer).

Как опубликовать

Чтобы запустить рабочий процесс релиза, используйте отправку тега Git.

Как: отправить тег Git (рекомендуется для релизов)

• Предполагаемое использование: Регулярные выпуски версий (основные, второстепенные, исправленные). Git — рекомендуемый стандартный процесс выпуска, поскольку он обеспечивает четкое соответствие между историей и версиями.

1. Обновить версию: Измените version в package.json (например, 0.3.0 ).

2. Зафиксировать и отправить: зафиксировать изменения в package.json и отправить их в основную ветку.

3. Создать тег и отправить: создает тег Git (с префиксом v ), соответствующий версии, и отправляет его.

   git tag v0.3.0 git push origin v0.3.0

4. Автоматизация: отправка тега запускает рабочий процесс Release Package , который собирает, тестирует и публикует пакет в npm.

5. Проверка: проверьте вкладку «Действия» для определения статуса рабочего процесса и проверьте пакет на npmjs.com.

Меры предосторожности

• Согласованность версий: при запуске push-уведомления тега имя тега (например, v0.3.0 ) должно точно соответствовать version в package.json (например, 0.3.0 ). Если совпадений нет, рабочий процесс завершится неудачей.

• Предварительная проверка: хотя ваш рабочий процесс CI включает этапы сборки и тестирования, мы рекомендуем запускать pnpm run build и pnpm run test локально перед обновлением версии, чтобы выявить потенциальные проблемы на ранней стадии.

лицензия

Данный проект выпущен под лицензией MIT. Подробную информацию смотрите в файле ЛИЦЕНЗИЯ .