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

Использование:

В файле 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" } } // ... 他のサーバー設定 ... } }
Перезапустите или перезагрузите клиент MCP (например, Cursor).
Убедитесь, что журнал выводится в .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 — рекомендуемый стандартный процесс выпуска, поскольку он обеспечивает четкое соответствие между историей и версиями.

Обновить версию: Измените version в package.json (например, 0.3.0 ).
Зафиксировать и отправить: зафиксировать изменения в package.json и отправить их в основную ветку.
Создать тег и отправить: создает тег Git (с префиксом v ), соответствующий версии, и отправляет его.
git tag v0.3.0 git push origin v0.3.0
Автоматизация: отправка тега запускает рабочий процесс Release Package , который собирает, тестирует и публикует пакет в npm.
Проверка: проверьте статус вашего рабочего процесса на вкладке «Действия» и проверьте ваш пакет на npmjs.com.

Примечания

Согласованность версий: при запуске push-уведомления тега имя тега (например, v0.3.0 ) должно точно соответствовать version в package.json (например, 0.3.0 ). Если совпадений нет, рабочий процесс завершится неудачей.
Предварительная проверка: хотя ваш рабочий процесс CI включает этапы сборки и тестирования, мы рекомендуем запускать pnpm run build и pnpm run test локально перед обновлением версии, чтобы выявить потенциальные проблемы на ранней стадии.

лицензия

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

MCP ts-morph Refactoring Tools

Integrations