MCP ts-morph Refactoring Tools

overview

The MCP server leverages ts-morph to provide refactoring operations for TypeScript and JavaScript codebases, and works with editor extensions such as Cursor to allow AST-based (Abstract Syntax Tree)-based symbol renaming, file/folder renaming, find references, and more.

Related MCP server: TypeScript Rename Helper

Features provided

The MCP server provides the following refactoring features, each of which uses ts-morph to analyze the AST and make changes while maintaining consistency across the project:

Renaming symbols ( rename_symbol_by_tsmorph )

• What it does : Globally rename a symbol (function, variable, class, interface, etc.) at a specific position in a specified file across the entire project.

• Use case : You want to change the name of a function or variable, but there are many references to it and it would be difficult to change it manually.

• Required information : tsconfig.json path of the project, path of the target file, position of the symbol (line and column), current symbol name, new symbol name

Renaming a file/folder ( rename_filesystem_entry_by_tsmorph )

• Feature : Renames multiple specified files and/or folders and automatically updates the paths in all import / export statements in the project.

• Use cases : When you change file structure and want to modify import paths accordingly. When you want to rename/move multiple files/folders at once.

• Required information : project's tsconfig.json path, array of rename operations ( renames: { oldPath: string, newPath: string }[] ).

• remarks :

  • References are primarily resolved using symbol resolution.

  • References that contain path aliases (such as @/ ) will be updated but converted to relative paths .

  • Imports that reference a directory index file (e.g. ../components ) are updated to an explicit file path (e.g. ../components/index.tsx ) .

  • It also performs a path collision check (duplicates in existing paths and within the operation) before the rename operation.

• Note (Execution time): When working with many files and folders at once, or for very large projects, parsing and updating references can take some time.

• NOTE (known limitation): Currently, references to default exports of the form export default Identifier; may not be updated correctly.

Finding references ( find_references_by_tsmorph )

• What it does : Finds and lists the definition of a symbol at a particular location in a specified file, as well as all its references throughout the project.

• Use case : You want to understand where a function or variable is used. You want to investigate the impact of a refactoring.

• Required information : project's tsconfig.json path, target file path, symbol position (line, column).

Remove a path alias ( remove_path_alias_by_tsmorph )

• Function : Replaces path aliases (such as @/components ) in import / export statements in the specified file or directory with relative paths (such as ../../components ).

• Use case : You want to make your project more portable or to conform to specific coding standards.

• Required information : tsconfig.json path of the project, path of the file or directory to process.

Moving symbols between files ( move_symbol_to_file_by_tsmorph )

• What it does : Moves a specified symbol (function, variable, class, interface, type alias, enum) from the current file to another specified file, automatically updating references (including import/export paths) throughout the project along with the move.

• Use case : You want to extract certain functionality into a separate file to reorganize your code.

• Required information : tsconfig.json path of the project, source file path, destination file path, name of the symbol to move, and optionally a symbol kind ( declarationKindString ) to disambiguate symbols with the same name.

• NOTE : A symbol's internal dependencies (other declarations used only within that symbol) are moved along with it. Dependencies referenced by other symbols remaining in the source file will remain in the source and will be added as export (if necessary) and imported in the destination file.

• Note : symbols that are exported export default cannot be moved with this tool.

environment construction

For users (when using as an npm package)

Add the following settings to mcp.json . By using the npx command, the latest version installed will be automatically used.

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

For developers (for local development and execution)

If you want to run the server locally from source code, you need to build it first.

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

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

After building, you can run it directly in node by setting the following in mcp.json :

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

Logging Settings (Environment Variables)

The output level and destination of the server operation log can be controlled by the following environment variables. Set them in env block of mcp.json .

• LOG_LEVEL : Sets the log verbosity.

  • Available levels: fatal , error , warn , info (default), debug , trace , silent

  • Example: "LOG_LEVEL": "debug"

• LOG_OUTPUT : Specifies the log output destination.

  • console (default): Logs to standard output. If you are in a development environment ( NODE_ENV !== 'production' ) and have pino-pretty installed, the output will be formatted in a pretty way.

  • file : Outputs the log to the specified file. Set this to avoid impacting MCP clients.

  • Example: "LOG_OUTPUT": "file"

• LOG_FILE_PATH : If LOG_OUTPUT is set to file , this specifies the absolute path of the log file.

  • Default: [プロジェクトルート]/app.log

  • Example: "LOG_FILE_PATH": "/var/log/mcp-tsmorph.log"

Example config (in mcp.json ):

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

Developer Information

Prerequisites

• Node.js (for version, see .node-version or volta field in package.json )

• pnpm (see packageManager field in package.json for version)

set up

Clone the repository and install the dependencies:

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

Build

Compiles TypeScript code into JavaScript.

pnpm build

The build artifacts are output to dist directory.

test

Run the unit tests.

pnpm test

Linting and formatting

It statically analyzes and formats your code.

# Lintチェック
pnpm lint

# Lint修正
pnpm lint:fix

# フォーマット
pnpm format

Using the Debugging Wrapper

If you want to check the startup sequence, standard input/output, and error output of the MCP server in detail during development, you can use mcp_launcher.js , which is located in the scripts directory of the project.

This wrapper script launches the original MCP server process ( npx -y @sirosuzume/mcp-tsmorph-refactor ) as a child process and logs the launch information and output to .logs/mcp_launcher.log file in the project root.

How to use:

1. In the mcp.json file, change mcp-tsmorph-refactor server configuration as follows:

   • Set command to "node" .

   • In args , specify the path to scripts/mcp_launcher.js (for example, ["path/to/your_project_root/scripts/mcp_launcher.js"] ). You can also use a path relative to the project root ( ["scripts/mcp_launcher.js"] ).

   Example configuration ( 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. Restart or reload the MCP client (e.g. Cursor).

3. Check that the logs are output to .logs/mcp_launcher.log in your project root, and also to the MCP server's own log if configured (e.g. .logs/mcp-ts-morph.log ).

Using this wrapper can help you diagnose why your MCP server is not starting as expected.

Publishing to npm

This package will be automatically published to npm via a GitHub Actions workflow ( .github/workflows/release.yml ).

Prerequisites

• NPM token: Make sure you have an npm access token with public permissions set in your repository's Actions secrets ( Settings > Secrets and variables > Actions ) with the name NPM_TOKEN .

• Update your version: Before publishing, update the version field in package.json according to Semantic Versioning (SemVer).

How to publish

To trigger the release workflow, use a Git tag push.

How to: Push a Git tag (recommended for releases)

• Intended use: Regular version releases (major, minor, patch). This is the recommended standard release process since it provides a clear correspondence between Git history and versions.

1. Update version: Change version in package.json (e.g. 0.3.0 ).

2. Commit & Push: Commit the changes to package.json and push them to the main branch.

3. Create tag & push: Creates a Git tag (with v prefix) that matches the version and pushes it.

   git tag v0.3.0
   git push origin v0.3.0

4. Automation: Pushing a tag triggers the Release Package workflow, which builds, tests, and publishes the package to npm.

5. Verify: Check the status of your workflow in the Actions tab and verify your package on npmjs.com.

Precautions

• Version consistency: When triggering on a tag push, the tag name (e.g. v0.3.0 ) must exactly match version (e.g. 0.3.0 ) in package.json , or the workflow will fail.

• Pre-check: Although your CI workflow includes build and test steps, we recommend running pnpm run build and pnpm run test locally before updating your version to catch potential issues early.

license

This project is released under the MIT license, see the LICENSE file for details.