move_symbol_to_file_by_tsmorph

Instructions

[Uses ts-morph] Moves a specified symbol (function, variable, class, etc.) and its internal-only dependencies to a new file, automatically updating all references across the project. Aids refactoring tasks like file splitting and improving modularity.

Analyzes the AST (Abstract Syntax Tree) to identify usages of the symbol and corrects import/export paths based on the new file location. It also handles moving necessary internal dependencies (those used only by the symbol being moved).

Usage

Use this tool for various code reorganization tasks:

Moving a specific function/class/variable: Relocate a specific piece of logic to a more appropriate file (e.g., moving a helper function from a general utils.ts to a feature-specific feature-utils.ts). This tool moves the specified symbol and its internal-only dependencies.
Extracting or Moving related logic (File Splitting/Reorganization): To split a large file or reorganize logic, move related functions, classes, types, or variables to a different file (new or existing) one by one using this tool. You will need to run this tool multiple times, once for each top-level symbol you want to move.
Improving modularity: Group related functionalities together by moving multiple symbols (functions, types, etc.) into separate, more focused files. Run this tool for each symbol you wish to relocate.

ts-morph parses the project based on tsconfig.json to resolve references and perform the move safely, updating imports/exports automatically.

Parameters

tsconfigPath (string, required): Absolute path to the project's root tsconfig.json
originalFilePath (string, required): Absolute path to the file currently containing the symbol to move.
targetFilePath (string, required): Absolute path to the destination file. Can be an existing file; if the path does not exist, a new file will be created.
symbolToMove (string, required): The name of the single top-level symbol you want to move in this execution.
declarationKindString (string, optional): The kind of the declaration (e.g., 'VariableStatement', 'FunctionDeclaration'). Recommended to resolve ambiguity if multiple symbols share the same name.
dryRun (boolean, optional): If true, only show intended changes without modifying files. Defaults to false.

Result

On success: Returns a message confirming the move and reference updates, including a list of modified files (or files that would be modified if dryRun is true).
On failure: Returns an error message (e.g., symbol not found, default export, AST errors).

Remarks

Moves one top-level symbol per execution: This tool is designed to move a single specified top-level symbol (and its internal-only dependencies) in each run. To move multiple related top-level symbols (e.g., several functions and types for file splitting), you need to invoke this tool multiple times, once for each symbol.
Default exports cannot be moved.
Internal dependency handling: Dependencies (functions, variables, types, etc.) used only by the moved symbol within the original file are moved along with it. Dependencies that are also used by other symbols remaining in the original file will stay, might gain an export keyword if they didn't have one, and will be imported by the new file where the symbol was moved. Symbols in the original file that are not dependencies of the moved symbol will remain untouched unless explicitly moved in a separate execution of this tool.
Performance: Moving symbols with many references in large projects might take time.

Input Schema

Name	Required	Description
`declarationKindString`	No	Optional. The kind of the declaration as a string (e.g., 'VariableStatement', 'FunctionDeclaration', 'ClassDeclaration', 'InterfaceDeclaration', 'TypeAliasDeclaration', 'EnumDeclaration'). Providing this helps resolve ambiguity if multiple symbols share the same name.
`dryRun`	No	If true, only show intended changes without modifying files.
`originalFilePath`	Yes	Absolute path to the file containing the symbol to move.
`symbolToMove`	Yes	The name of the single top-level symbol you want to move in this execution.
`targetFilePath`	Yes	Absolute path to the destination file. Can be an existing file; if the path does not exist, a new file will be created.
`tsconfigPath`	Yes	Absolute path to the project's tsconfig.json file. Essential for ts-morph.

Input Schema (JSON Schema)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false,
  "properties": {
    "declarationKindString": {
      "description": "Optional. The kind of the declaration as a string (e.g., 'VariableStatement', 'FunctionDeclaration', 'ClassDeclaration', 'InterfaceDeclaration', 'TypeAliasDeclaration', 'EnumDeclaration'). Providing this helps resolve ambiguity if multiple symbols share the same name.",
      "type": "string"
    },
    "dryRun": {
      "default": false,
      "description": "If true, only show intended changes without modifying files.",
      "type": "boolean"
    },
    "originalFilePath": {
      "description": "Absolute path to the file containing the symbol to move.",
      "type": "string"
    },
    "symbolToMove": {
      "description": "The name of the single top-level symbol you want to move in this execution.",
      "type": "string"
    },
    "targetFilePath": {
      "description": "Absolute path to the destination file. Can be an existing file; if the path does not exist, a new file will be created.",
      "type": "string"
    },
    "tsconfigPath": {
      "description": "Absolute path to the project's tsconfig.json file. Essential for ts-morph.",
      "type": "string"
    }
  },
  "required": [
    "tsconfigPath",
    "originalFilePath",
    "targetFilePath",
    "symbolToMove"
  ],
  "type": "object"
}

MCP ts-morph Refactoring Tools