The MCP ts-morph Refactoring Tools server enables automated refactoring and code analysis for TypeScript and JavaScript projects using the ts-morph
library. It provides:
Rename Symbols: Rename variables, functions, and classes while automatically updating all references across the project
Rename Files/Folders: Rename filesystem entries and update all related import/export paths
Find References: Locate all usage sites and the definition of a specific symbol within the project
Remove Path Aliases: Convert path aliases (e.g.,
@/components
) to relative paths in import/export statementsMove Symbols: Relocate symbols between files while maintaining references
Dry Run: Preview changes before applying them
Test Connection: Verify connection to the MCP server is working correctly
The server integrates with editor extensions like Cursor for seamless refactoring workflows.
Enables AST-based code refactoring operations for JavaScript files including symbol renaming, file/folder renaming with automatic import path updates, and reference finding.
Provides a Node.js-based refactoring server that can be integrated with editor extensions like Cursor to perform code transformations.
Provides refactoring capabilities for TypeScript codebases including symbol renaming, finding references, and updating import paths, all performed using AST-based analysis.
MCP ts-morph Refactoring Tools
概要
この MCP サーバーは、ts-morph を利用して TypeScript および JavaScript のコードベースに対するリファクタリング操作を提供します。 Cursor などのエディタ拡張機能と連携し、シンボル名の変更、ファイル/フォルダ名の変更、参照箇所の検索などを AST (Abstract Syntax Tree) ベースで行うことができます。
提供される機能
この MCP サーバーは以下のリファクタリング機能を提供します。各機能は ts-morph
を利用して AST を解析し、プロジェクト全体の整合性を保ちながら変更を行います。
シンボル名の変更 (rename_symbol_by_tsmorph
)
- 機能: 指定されたファイル内の特定の位置にあるシンボル (関数、変数、クラス、インターフェースなど) の名前を、プロジェクト全体で一括変更します。
- ユースケース: 関数名や変数名を変更したいが、参照箇所が多く手作業での変更が困難な場合。
- 必要な情報: プロジェクトの
tsconfig.json
パス、対象ファイルのパス、シンボルの位置 (行・列)、現在のシンボル名、新しいシンボル名
ファイル/フォルダ名の変更 (rename_filesystem_entry_by_tsmorph
)
- 機能: 指定された複数のファイルおよび/またはフォルダの名前を変更し、プロジェクト内のすべての
import
/export
文のパスを自動的に更新します。 - ユースケース: ファイル構成を変更し、それに伴って import パスを修正したい場合。複数のファイル/フォルダを一度にリネーム/移動したい場合。
- 必要な情報: プロジェクトの
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
)
- 機能: 指定されたファイルまたはディレクトリ内の
import
/export
文に含まれるパスエイリアス (@/components
など) を、相対パス (../../components
など) に置換します。 - ユースケース: プロジェクトの移植性を高めたい場合や、特定のコーディング規約に合わせたい場合。
- 必要な情報: プロジェクトの
tsconfig.json
パス、処理対象のファイルまたはディレクトリのパス。
シンボルのファイル間移動 (move_symbol_to_file_by_tsmorph
)
- 機能: 指定されたシンボル(関数、変数、クラス、インターフェース、型エイリアス、Enum)を現在のファイルから指定された別のファイルに移動します。移動に伴い、プロジェクト全体の参照(インポート/エクスポートパスを含む)を自動的に更新します。
- ユースケース: コードの構成を変更するために、特定の機能を別のファイルに切り出したい場合。
- 必要な情報: プロジェクトの
tsconfig.json
パス、移動元のファイルパス、移動先のファイルパス、移動するシンボルの名前。必要に応じてシンボルの種類 (declarationKindString
) を指定すると、同名シンボルの曖昧性を解消できます。 - 備考: シンボルの内部依存関係(そのシンボル内でのみ使用される他の宣言)も一緒に移動します。移動元ファイルに残る他のシンボルからも参照されている依存関係は移動元に残り、必要に応じて
export
が追加され、移動先ファイルでインポートされます。 - 注意: デフォルトエクスポート (
export default
) されたシンボルはこのツールでは移動できません。
環境構築
利用者向け (npm パッケージとして利用する場合)
mcp.json
に以下のように設定を追加します。npx
コマンドを使用することで、インストール済みの最新バージョンが自動的に利用されます。
開発者向け (ローカルで開発・実行する場合)
ローカルでソースコードからサーバーを起動する場合は、まずビルドが必要です。
ビルド後、mcp.json
で以下のように設定して node
で直接実行できます。
ロギング設定 (環境変数)
サーバーの動作ログは、以下の環境変数で出力レベルや出力先を制御できます。mcp.json
の env
ブロックで設定します。
LOG_LEVEL
: ログの詳細度を設定します。- 利用可能なレベル:
fatal
,error
,warn
,info
(デフォルト),debug
,trace
,silent
- 例:
"LOG_LEVEL": "debug"
- 利用可能なレベル:
LOG_OUTPUT
: ログの出力先を指定します。console
(デフォルト): 標準出力にログを出力します。開発環境 (NODE_ENV !== 'production'
) でpino-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
またはpackage.json
のvolta
フィールドを参照) - pnpm (バージョンは
package.json
のpackageManager
フィールドを参照)
セットアップ
リポジトリをクローンし、依存関係をインストールします。
ビルド
TypeScript コードを JavaScript にコンパイルします。
ビルド成果物は dist
ディレクトリに出力されます。
テスト
ユニットテストを実行します。
リンティングとフォーマット
コードの静的解析とフォーマットを行います。
デバッグ用ラッパーの使用
開発中に MCP サーバーの起動シーケンスや標準入出力、エラー出力を詳細に確認したい場合、プロジェクトの scripts
ディレクトリに配置されている mcp_launcher.js
を使用できます。
このラッパースクリプトは、本来の 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
):- MCP クライアント (例: Cursor) を再起動またはリロードします。
- プロジェクトルートの
.logs/mcp_launcher.log
にログが出力されるのを確認してください。 また、MCP サーバー自体のログも、設定されていれば (例:.logs/mcp-ts-morph.log
) 確認できます。
このラッパーを使用することで、MCP サーバーが期待通りに起動しない場合の原因究明に役立ちます。
npm への公開
このパッケージは、GitHub Actions ワークフロー (.github/workflows/release.yml
) を介して npm に自動的に公開されます。
前提条件
- NPM トークン: 公開権限を持つ npm アクセストークンが、リポジトリの Actions secrets (
Settings
>Secrets and variables
>Actions
) にNPM_TOKEN
という名前で設定されていることを確認してください。 - バージョン更新: 公開前に、
package.json
のversion
フィールドをセマンティックバージョニング (SemVer) に従って更新してください。
公開方法
リリースワークフローをトリガーするには、Git タグのプッシュを使用します。
方法: Git タグのプッシュ (リリース時に推奨)
- 想定される用途: 通常のバージョンリリース(メジャー、マイナー、パッチ)。Git の履歴とバージョンが明確に対応するため、標準的なリリースプロセスとして推奨されます。
- バージョン更新:
package.json
のversion
を変更します (例:0.3.0
)。 - コミット & プッシュ:
package.json
の変更をコミットし、main ブランチにプッシュします。 - タグ作成 & プッシュ: バージョンに一致する Git タグ (
v
プレフィックス付き) を作成し、プッシュします。 - 自動化: タグをプッシュすると
Release Package
ワークフローがトリガーされ、パッケージのビルド、テスト、npm への公開が行われます。 - 確認: Actions タブでワークフローのステータスを確認し、npmjs.com でパッケージを確認します。
注意事項
- バージョンの一貫性: タグプッシュでトリガーする場合、タグ名 (例:
v0.3.0
) はpackage.json
のversion
(例:0.3.0
) と完全に一致する必要があります。一致しない場合、ワークフローは失敗します。 - 事前チェック: CI ワークフローにはビルドとテストのステップが含まれていますが、潜在的な問題を早期に発見するために、バージョンを更新する前にローカルで
pnpm run build
とpnpm run test
を実行することをお勧めします。
ライセンス
このプロジェクトは MIT ライセンスの下で公開されています。詳細は LICENSE ファイルをご覧ください。
local-only server
The server can only run on the client's local machine because it depends on local resources.
Tools
Provides TypeScript and JavaScript code refactoring operations using ts-morph, allowing AST-based symbol renaming, file/folder renaming, reference searching, and path alias removal when integrated with editor extensions like Cursor.
Related Resources
Related MCP Servers
- AsecurityAlicenseAqualityA TypeScript tool that ranks files in your codebase by importance, tracks dependencies, and provides file summaries to help understand code structure through Cursor's Model Context Protocol.Last updated -14223GPL 3.0
- AsecurityAlicenseAqualityA specialized server that provides advanced TypeScript code manipulation and analysis capabilities, enabling refactoring, navigation, diagnostics, and module analysis through Claude.Last updated -113,130363MIT License
- AsecurityAlicenseAqualityProvides tools for analyzing project structures, searching through codebases, managing dependencies, and performing file operations with advanced filtering capabilities.Last updated -61601MIT License
- AsecurityAlicenseAqualityProvides AI agents with powerful JavaScript/TypeScript code analysis and transformation capabilities using the tree-hugger-js library.Last updated -12481MIT License