MCP ts-morph Refactoring Tools

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.

Environment construction

Add the following settings to mcp.json .

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 ):

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 }[] ).
• Note : It will update references while preserving the original path format, including path aliases (such as @/ ) and relative index imports (paths containing . or .. ). It will also check for path collisions (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.

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.

(Add any other features)

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:

Build

Compiles TypeScript code into JavaScript.

The build artifacts are output to dist directory.

test

Run the unit tests.

Linting and formatting

It statically analyzes and formats your code.

license

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