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

обзор

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

Related MCP server: TypeScript Rename Helper

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

Этот сервер 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 ) , обновляются до явного пути к файлу (например, ../components/index.tsx ) .

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

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

• ПРИМЕЧАНИЕ (известное ограничение): В настоящее время ссылки на экспорт по умолчанию формы 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 будет автоматически использоваться последняя установленная вами версия.

{
 "mcpServers": {
 "mcp-tsmorph-refactor": { // 任意のサーバー名
 "command": "npx",
 "args": ["-y", "@sirosuzume/mcp-tsmorph-refactor"],
 "env": {} // 必要に応じてロギング設定などを追加
 }
 }
}

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

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

# 依存関係のインストール (初回のみ)
pnpm install

# TypeScript コードのビルド
pnpm run build

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

{
 "mcpServers": {
 "mcp-tsmorph-refactor-dev": { // 開発用など、別の名前を推奨
 "command": "node",
 // プロジェクトルートからの相対パスまたは絶対パス
 "args": ["/path/to/your/local/repo/dist/index.js"],
 "env": {
 // 開発時のデバッグログ設定など
 "LOG_LEVEL": "debug"
 }
 }
 }
}

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

Уровень выходных данных и место назначения журнала операций сервера можно контролировать с помощью следующих переменных среды. Установите его в блоке 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 ):

// ... (mcp.json の他の設定)
 "env": {
 "LOG_LEVEL": "debug", // デバッグレベルのログを
 "LOG_OUTPUT": "file", // ファイルに出力
 "LOG_FILE_PATH": "/Users/yourname/logs/mcp-tsmorph.log" // ログファイルのパス指定
 }
// ...

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

Предпосылки

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

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

настраивать

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

git clone https://github.com/sirosuzume/mcp-tsmorph-refactor.git
cd mcp-tsmorph-refactor
pnpm install

Строить

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

pnpm build

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

тест

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

pnpm test

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

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

# Lintチェック
pnpm lint

# Lint修正
pnpm lint:fix

# フォーマット
pnpm format

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

Если вы хотите подробно проверить последовательность запуска, стандартный ввод/вывод и вывод ошибок сервера 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. Подробную информацию смотрите в файле ЛИЦЕНЗИЯ .

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?
• Reddit Discussion
Related Servers

Tools

• change_signature_by_tsmorphA
• find_references_by_tsmorphA
• find_unused_exports_by_tsmorphA
• get_type_at_position_by_tsmorphA
• move_symbol_to_file_by_tsmorphA
• remove_path_alias_by_tsmorphA
• rename_filesystem_entry_by_tsmorphA
• rename_symbol_by_tsmorphA