ts-morph Refactoring Tools

Refactor TypeScript and JavaScript codebases using ts-morph. Supports renaming symbols and files, moving symbols, and searching for references.

ts-morphを利用して、TypeScript / JavaScript コードベースに対する AST ベースのリファクタリング操作を提供する MCP サーバーです。シンボル名の変更、ファイル/フォルダ名の変更、参照検索などを、プロジェクト全体の整合性を保ちながら行えます。

{ "mcpServers": { "mcp-tsmorph-refactor": { "command": "npx", "args": ["-y", "@sirosuzume/mcp-tsmorph-refactor"], "env": {} } } }

ロギングをカスタマイズする場合はロギング設定を参照してください。ローカルのソースから起動する場合は開発を参照してください。

- ユースケース: ファイル構成の変更に伴う import パスの修正。複数のファイル/フォルダを一度にリネーム/移動したい場合。
- 必要な情報: リネーム操作の配列renames: { oldPath: string, newPath: string }[]。
- 挙動:

- 参照解決には主にシンボル解析を用います。
- パスエイリアス（@/など）を含む参照は更新されますが、相対パスに変換されます。
- ディレクトリのインデックスを参照するインポート（例:../components）は、明示的なファイルパス（例:../components/index.tsx）に更新されます。
- 操作前にパスの衝突（既存パス・操作内の重複）をチェックします。

指定ファイル内の特定位置にあるシンボルの定義箇所と、プロジェクト全体でのすべての参照箇所を検索して一覧表示します。

- ユースケース: ある関数や変数の使用箇所の把握。リファクタリングの影響範囲の調査。
- 必要な情報: 対象ファイルのパス、シンボルの位置（行・列）。

指定したファイルまたはディレクトリ内のimport/export文に含まれるパスエイリアス（@/componentsなど）を、相対パス（../../componentsなど）に置換します。

- ユースケース: プロジェクトの移植性を高めたい、特定のコーディング規約に合わせたい場合。
- 必要な情報: 処理対象のファイルまたはディレクトリのパス。

指定したシンボル（関数・変数・クラス・インターフェース・型エイリアス・Enum）を別ファイルに移動し、プロジェクト全体の参照（import/export パスを含む）を自動的に更新します。

- ユースケース: 特定の機能を別ファイルに切り出してコード構成を変更したい場合。
- 必要な情報: 移動元・移動先のファイルパス、移動するシンボルの名前。同名シンボルがある場合は種類（declarationKindString）を指定して曖昧性を解消できます。
- 挙動: そのシンボル内でのみ使用される内部依存も一緒に移動します。移動元の他シンボルからも参照される依存は移動元に残り、必要に応じてexportが追加されて移動先でインポートされます。
- 注意: デフォルトエクスポート（export default）されたシンボルは移動できません。

関数・メソッド・アロー関数の引数を追加・削除・並べ替えし、プロジェクト内のすべての呼び出し箇所の引数を合わせて更新します。

- ユースケース: 呼び出し元が多い関数に必須引数を追加したい、import / 再エクスポート / メソッドチェーン経由で参照される関数の引数を削除・並べ替えたい場合。LLM の単発編集では取りこぼしが起きやすい更新を、型チェッカー経由で確実に反映します。
- 必要な情報: 対象ファイルのパス、関数名識別子の位置（行・列）、関数名、適用する操作の配列operations。
- 操作（operations）:

- add:index（省略時は末尾）に引数を挿入。argumentForCallersを指定すると各呼び出し箇所の同じ位置にそのテキストを挿入。省略時は呼び出し側を変更しない（末尾の optional / デフォルト引数専用）。
- remove:indexの引数を削除。その数以上の引数を渡している呼び出しから対応分を削除。
- reorder:newOrderに従って引数リストと各呼び出しを再構築。引数の数が一致しない呼び出しがあると失敗します。
- 操作は順に適用され、後続の操作は先行操作適用後の引数リストを参照します。

TypeScript / JavaScript ファイルの指定位置における、TypeChecker が推論した型・シンボル・宣言箇所を返します。

- ユースケース:tscを起動せずに「この変数 / 式 / 関数の実際の推論型は何か」を素早く確認したい場合。宣言ファイルをReadするより安価に型シグネチャを得たいとき。リファクタリング前に値の実際の形状を確認したいとき。
- 必要な情報: 対象ファイルのパス、検査する位置（行・列）。
- 注意: 空白やコメント行を指す場合はファイルレベルの推論型（例:typeof import("...")）が返り、通常は意図した結果ではありません。レスポンスのnodeKindを確認して識別子に再ターゲットしてください。多数の位置を一括で解析したい場合はtscを直接使ってください。

プロジェクト全体を走査し、宣言ファイルの外から参照されていないexportを候補として列挙します。

- 検出対象: インラインexport（export function/class/const/let/var/enum/interface/type）、export default（識別子・関数・クラス）、export = <Identifier>。
- 判定方法:findReferencesAsNodes()の結果から、同一ファイル内の参照・ExportDeclaration配下の参照（export { x } from "./y"等の純粋な再エクスポート）・node_modules内の参照を除外し、残り 0 件なら未使用候補とします。
- ユースケース: デッドコード掃除、モジュールの公開面の棚卸し。削除前には必ずfind_references_by_tsmorphでダブルチェックしてください。
- sameFileRefs（削除 vs unexport の判断）: 各候補に、同一ファイル内での参照数（宣言自身と再エクスポートサイトは除外）を添えます。報告される候補は定義上「宣言ファイルの外では未参照」なので、削除アクションはこの値で決まります。

- sameFileRefs=0: 同一ファイル内でも未使用 →真のデッド。宣言ごと削除して安全（textHits=0も併せるとより確実）。
- sameFileRefs=1+: 同一ファイル内では使用中 →exportキーワードだけ不要。宣言は残すこと（消すと同一ファイル内参照が壊れる）。報告された宣言を一律削除するとビルドが壊れます。

サーバーの動作ログは環境変数で制御します。mcp.jsonのenvブロックで設定します。

LOG_OUTPUT=consoleかつ開発環境（NODE_ENV !== 'production'）でpino-prettyがインストールされている場合は、見やすい形式で出力されます。MCP クライアントへの標準出力の影響を避けたい場合はfileを指定してください。

{ "mcpServers": { "mcp-tsmorph-refactor": { "command": "npx", "args": ["-y", "@sirosuzume/mcp-tsmorph-refactor"], "env": { "LOG_LEVEL": "debug", "LOG_OUTPUT": "file", "LOG_FILE_PATH": "/Users/yourname/logs/mcp-tsmorph.log" } } } }

- Node.js（バージョンはpackage.jsonのvoltaフィールドを参照）
- pnpm（バージョンはpackage.jsonのpackageManagerフィールドを参照）

git clone https://github.com/sirosuzume/mcp-tsmorph-refactor.git cd mcp-tsmorph-refactor pnpm install pnpm build # dist/ に出力

pnpm test # テスト実行 pnpm test:watch # ウォッチモードでテスト pnpm check-types # 型チェック（コンパイルなし） pnpm lint # Lint チェック pnpm lint:fix # Lint 修正 pnpm format # フォーマット pnpm inspector # MCP Inspector でデバッグ

{ "mcpServers": { "mcp-tsmorph-refactor-dev": { "command": "node", "args": ["/path/to/your/local/repo/dist/index.js"], "env": { "LOG_LEVEL": "debug" } } } }

サーバーの起動シーケンスや標準入出力を詳細に確認したい場合は、scripts/mcp_launcher.jsを使います。本来のサーバープロセスを子プロセスとして起動し、起動情報や出力を.logs/mcp_launcher.logに記録します。

mcp.jsonのcommandを"node"、argsをscripts/mcp_launcher.jsへのパスに変更してクライアントを再起動すると、.logs/mcp_launcher.log（およびサーバー自身のログ）が確認できます。

{ "mcpServers": { "mcp-tsmorph-refactor": { "command": "node", "args": ["scripts/mcp_launcher.js"], "env": { "LOG_OUTPUT": "file", "LOG_FILE_PATH": ".logs/mcp-ts-morph.log" } } } }

このパッケージは GitHub Actions ワークフロー（.github/workflows/release.yml）を介して npm に自動公開されます。

Git タグがバージョンの単一の真実の source です。package.jsonのversionとsrc/version.tsのVERSIONはどちらも0.0.0-developmentに固定されており、リリースワークフローが tag から値を取り出して焼き込みます。手動で bump する必要はありません。

git checkout main && git pull --ff-only git tag v1.2.0 git push origin v1.2.0

- tag（v1.2.0）から VERSION（1.2.0）を抽出（strict SemVer のみ。プレリリース未サポート）
- placeholder バージョンのままpnpm test
- node scripts/release-version.mjs --bake 1.2.0でsrc/version.tsとpackage.jsonのversionを書き換え
- pnpm build
- dist/version.jsにexports.VERSION = "1.2.0";が含まれることをgrep -Fで確認
- _version_noteを package.json から除去
- pnpm publish --provenanceで npm へ公開（Trusted Publishing / OIDC）

完了後、npm view @sirosuzume/mcp-tsmorph-refactor versionで反映を確認してください。

npm Trusted Publishing が前提です。NPM_TOKENは廃止済みで、GitHub Actions の OIDC を介して publish されます（release.ymlのid-token: write参照）。

旧運用では「package.jsonの version を bump」「src/mcp/config.tsのserverInfo.versionを bump」「タグを打つ」の 3 手順のいずれかを忘れると不整合がリリースされていました（実際にズレた履歴あり）。新運用では開発中はずっと0.0.0-developmentのままで、リリース時に CI が tag を見て全箇所を更新するため、bump 忘れが構造的に発生しません。

CI（.github/workflows/ci.yml）は PR / main push のたびにnode scripts/release-version.mjs --checkを実行し、両ファイルが placeholder のままであることを確認します。手で bump した PR はここで失敗します。

- ワークフロー途中で失敗した場合はtag を削除せず、main に修正をマージしてから次のパッチタグ（vX.Y.(Z+1)）を打ってください（fix-forward）。
- 同じタグでの再 publish は npm の immutability により不可能なため、tag の上書きは無意味です。

このプロジェクトは MIT ライセンスの下で公開されています。詳細はLICENSEファイルをご覧ください。

An MCP server that gives AI agents deep understanding of C# codebases via Roslyn — type search, dependency graphs, usage analysis, and architecture overviews, all from a live in-memory compilation.