TypeScript Rename Helper
This server provides compiler-grade TypeScript refactoring plans for coding agents without modifying the filesystem. It exposes three tools:
planRenameSymbol: Given a file path and 0-based line/character position, computes all text edits needed across the project to rename a TypeScript symbol (variable, function, class, etc.). Optionally includes occurrences in strings and comments.planFileMove: Given old and new file paths, returns all import path updates needed across the project plus a suggested filesystem move operation.planDirectoryMove: Recursively plans file moves and import path updates for all TypeScript/TSX files under a moved or renamed directory.
Key characteristics:
Read-only: Only returns edit plans and move suggestions — actual file writes are left to the agent or editor.
TypeScript Language Service: Uses compiler-grade analysis for accurate, type-safe results.
Monorepo support: Accepts a
workspaceRootparameter to merge edits across multipletsconfig.jsonprojects.Auto-discovers
tsconfig.json: Walks up from the target file path to find the relevant config, or accepts an explicit path.Compatible with MCP clients such as Claude Code and OpenAI Codex.
Provides compiler-grade symbol renaming and file/directory move planning using the TypeScript Language Service, computing all affected locations and import path updates without modifying files.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@TypeScript Rename Helperrename the fetchUser function to getUserData in src/api/user.ts at line 5"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@t09tanaka/ts-rename-helper-mcp
An MCP server that provides TypeScript symbol renaming and file/directory moves for coding agents.
This exists as a helper bridge: most current code agents can’t talk to the TypeScript Language Service (LSP) directly, so even a simple rename can be slow and error-prone.ts-rename-helper-mcp gives the agent compiler-grade rename/move plans without touching your filesystem.
⚠️ This project is intentionally narrow in scope and may become obsolete once agents can use LSPs directly.
Features
Type-safe symbol renaming
Uses the TypeScript Language Service to compute all affected locations
File move / rename planning
Returns edits for updated import paths across the project or workspace
Directory move / rename planning
Recursively plans file moves and import updates for all files under a directory
Global install friendly
Can resolve the appropriate
tsconfig.jsonfrom the target file path
Monorepo aware
Can merge edits from multiple
tsconfig.jsonfiles under a workspace
Read-only by design
MCP tools only return “edit plans” and suggested file moves
→ actual file writes are left to your editor/agent
Related MCP server: mcp-refactor-typescript
Installation
1. Install the package
Recommended for most users: global install
npm i -g @t09tanaka/ts-rename-helper-mcpIf you want the version pinned per repository, use a project-local install instead:
Project-local install:
npm i -D @t09tanaka/ts-rename-helper-mcppnpm add -D @t09tanaka/ts-rename-helper-mcpyarn add -D @t09tanaka/ts-rename-helper-mcp2. Add to your MCP client
Claude Code:
claude mcp add ts-rename-helper npx -- @t09tanaka/ts-rename-helper-mcpOpenAI Codex:
codex mcp add ts-rename-helper npx -- @t09tanaka/ts-rename-helper-mcpOther MCP clients (JSON config):
{
"mcpServers": {
"ts-rename-helper": {
"command": "npx",
"args": ["@t09tanaka/ts-rename-helper-mcp"]
}
}
}Requirements
Node.js 18+
A TypeScript project with a valid
tsconfig.jsonFor monorepos,
workspaceRootis optional but recommended when you want to scan multiple sibling TS projects deterministically
Recommended usage
Prefer absolute paths for
filePath,oldPath,newPath,oldDir, andnewDirFor single-project repos, you can often omit
projectRoot,workspaceRoot, andtsconfigPathFor monorepos, pass
workspaceRootwhen you want rename or move results to include sibling TS projectsIf your repo uses non-standard config names such as
tsconfig.app.json, passtsconfigPathexplicitly
How tsconfig is selected
When tsconfigPath is not provided, the server resolves the TypeScript project like this:
Start from the target file path
Walk upward looking for
tsconfig.jsonParse each candidate and choose the nearest one that actually includes the file
If
workspaceRootis provided, also scan siblingtsconfig.jsonfiles under that workspace and merge edit results when possible
The bundled server also tries to load the typescript package from the resolved project first, and falls back to its own bundled version if needed.
Tools
This MCP server exposes three tools:
planRenameSymbolplanFileMoveplanDirectoryMove
All tools are pure: they never modify files, they only return structured edit plans.
1. planRenameSymbol
Compute all edits needed to rename a symbol at a specific position.
Input
{
"filePath": "/absolute/path/to/project/src/foo/bar.ts",
"workspaceRoot": "/absolute/path/to/workspace", // optional
"projectRoot": "/absolute/path/to/project", // optional, mainly for relative paths / legacy clients
"tsconfigPath": "/absolute/path/to/project/tsconfig.json", // optional override
"line": 12, // 0-based
"character": 8, // 0-based
"newName": "fetchUserProfiles",
"findInStrings": false,
"findInComments": false,
}Output
{
"canRename": true,
"edits": [
{
"filePath": "/absolute/path/to/project/src/foo/bar.ts",
"textEdits": [
{
"range": {
"start": { "line": 12, "character": 4 },
"end": { "line": 12, "character": 20 },
},
"newText": "fetchUserProfiles",
},
],
},
{
"filePath": "/absolute/path/to/project/src/usage.ts",
"textEdits": [
{
"range": {
"start": { "line": 5, "character": 16 },
"end": { "line": 5, "character": 32 },
},
"newText": "fetchUserProfiles",
},
],
},
],
}If the symbol cannot be renamed:
{
"canRename": false,
"reason": "This symbol cannot be renamed.",
}Notes
line/characterare 0-based (same as LSP).filePathmay be relative ifprojectRootorworkspaceRootis provided. For global installs, absolute paths are recommended.If
tsconfigPathis omitted, the server walks upward fromfilePathand picks the nearesttsconfig.jsonthat actually includes the file.In monorepos, the server may merge rename locations from multiple TS projects under
workspaceRoot.If you want deterministic behavior in a large monorepo, prefer passing
workspaceRoot.Agents should:
Read each file
Apply
textEditsin a stable order (typically reverse-sorted by position)Write updated content back
2. planFileMove
Plan a file move/rename and compute all necessary import updates.
Input
{
"oldPath": "/absolute/path/to/project/src/feature/user/api.ts",
"newPath": "/absolute/path/to/project/src/features/user/api.ts",
"workspaceRoot": "/absolute/path/to/workspace", // optional
"projectRoot": "/absolute/path/to/project", // optional, mainly for relative paths / legacy clients
"tsconfigPath": "/absolute/path/to/project/tsconfig.json", // optional override for the primary project
}Output
{
"edits": [
{
"filePath": "/absolute/path/to/project/src/index.ts",
"textEdits": [
{
"range": {
"start": { "line": 3, "character": 0 },
"end": { "line": 3, "character": 50 },
},
"newText": "export * from './features/user/api';",
},
],
},
],
"fsMoves": [
{
"from": "/absolute/path/to/project/src/feature/user/api.ts",
"to": "/absolute/path/to/project/src/features/user/api.ts",
},
],
}Notes
fsMovesis only a suggestion – the agent/editor should perform the actual move.editsshould be applied after the move so that imports point to the new path.If
workspaceRootis provided, the server scans siblingtsconfig.jsonfiles and merges import updates across the workspace.tsconfigPathonly selects the primary project explicitly; sibling projects still come fromworkspaceRootdiscovery.
3. planDirectoryMove
Plan a directory move/rename and compute all necessary import updates for files under that directory.
Input
{
"oldDir": "/absolute/path/to/project/src/feature/auth",
"newDir": "/absolute/path/to/project/src/features/auth",
"workspaceRoot": "/absolute/path/to/workspace", // optional
"projectRoot": "/absolute/path/to/project", // optional, mainly for relative paths / legacy clients
"tsconfigPath": "/absolute/path/to/project/tsconfig.json", // optional override for the primary project
}Output
{
"edits": [
{
"filePath": "/absolute/path/to/project/src/router.tsx",
"textEdits": [
{
"range": {
"start": { "line": 10, "character": 20 },
"end": { "line": 10, "character": 49 },
},
"newText": "'./features/auth/routes'",
},
],
},
],
"fsMoves": [
{
"from": "/absolute/path/to/project/src/feature/auth/index.ts",
"to": "/absolute/path/to/project/src/features/auth/index.ts",
},
{
"from": "/absolute/path/to/project/src/feature/auth/hooks.ts",
"to": "/absolute/path/to/project/src/features/auth/hooks.ts",
},
],
}Notes
All TypeScript / TSX files under
oldDirare treated as candidates for moves.Internally this is typically implemented as repeated
getEditsForFileRenamecalls.If
workspaceRootis provided, the server also merges import updates from sibling TS projects in a monorepo.
Monorepo example
Given a workspace like this:
repo/
package.json
api/tsconfig.json
api/src/shared/user.ts
admin/tsconfig.json
admin/src/pages/users.tsIf admin/src/pages/users.ts imports api/src/shared/user.ts, you can move the API file with:
{
"oldPath": "/absolute/path/to/repo/api/src/shared/user.ts",
"newPath": "/absolute/path/to/repo/api/src/domain/user.ts",
"workspaceRoot": "/absolute/path/to/repo"
}With workspaceRoot set, the server can include import updates for both api and admin.
Typical agent flow
A coding agent integrating this MCP server would usually:
Decide on an operation:
rename a symbol, or
move a file/directory
Call the corresponding tool (
planRenameSymbol,planFileMove,planDirectoryMove)Inspect the returned
editsandfsMovesApply
fsMovesusing its own filesystem toolsApply
editsto the affected filesOptionally run
tscor tests to validate
Limitations
TypeScript only JavaScript-only projects without
tsconfig.jsonare not currently targeted.Project model is created per call (depending on implementation) For extremely large monorepos you may want to cache the server or run it close to the project root.
tsconfig.jsondiscovery is convention-based The server currently discoverstsconfig.jsonfiles, not arbitrarytsconfig.*.jsonvariants unless you passtsconfigPath.No actual file I/O via MCP This server never writes to disk; agents must handle file operations.
License
MIT © 2025 Takuto Tanaka
Available Tools
3 toolsplanDirectoryMoveA
Plan directory move with recursive import updates for all contained files. Returns edit plans and file move suggestions without modifying the filesystem.
| Name | Required | Description | Default |
|---|---|---|---|
| projectRoot | No | Optional base directory for resolving relative paths and limiting tsconfig discovery | |
| workspaceRoot | No | Optional monorepo root used to search multiple tsconfig.json files | |
| tsconfigPath | No | Optional explicit tsconfig.json path for the primary project | |
| oldDir | Yes | Absolute path or path relative to projectRoot/workspaceRoot of the directory to move | |
| newDir | Yes | Absolute path or path relative to projectRoot/workspaceRoot of the destination |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool plans without modifying the filesystem and returns edit plans and file move suggestions. However, it does not explain how optional parameters (projectRoot, workspaceRoot, tsconfigPath) affect behavior or what happens in edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first describes action and key behavior, second clarifies output and effect. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 5 parameters, the description is moderately complete. It covers purpose and non-destructive nature but omits details about return format (e.g., structure of edit plans) and when optional parameters are needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description does not add additional meaning to the parameters beyond what the schema already provides; it only states the overall behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'plan directory move' and the resource (directory) with key behavior: recursive import updates for contained files. It distinguishes itself from siblings (planFileMove moves a single file, planRenameSymbol renames a symbol).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit usage guidance is provided. The description does not mention when to use this tool over planFileMove or planRenameSymbol, nor any prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
planFileMoveA
Plan file move/rename with import path updates. Returns edit plans and file move suggestions without modifying the filesystem.
| Name | Required | Description | Default |
|---|---|---|---|
| projectRoot | No | Optional base directory for resolving relative paths and limiting tsconfig discovery | |
| workspaceRoot | No | Optional monorepo root used to search multiple tsconfig.json files | |
| tsconfigPath | No | Optional explicit tsconfig.json path for the primary project | |
| oldPath | Yes | Absolute path or path relative to projectRoot/workspaceRoot of the file to move | |
| newPath | Yes | Absolute path or path relative to projectRoot/workspaceRoot of the destination |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description bears full responsibility. It discloses non-destructive behavior ('without modifying the filesystem') and output type ('edit plans and file move suggestions'), but omits details like idempotency, error handling on missing paths, or whether it checks for destination conflicts. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence conveying the core function and behavior. No extraneous words; every part earns its place. Front-loaded with action and key features.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain return format or structure more fully. 'Returns edit plans and file move suggestions' is vague; an agent needs to know what fields or structure to expect. Parameter details are complete via schema, but output details are insufficient for a planning tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all parameters with descriptions, so baseline 3 applies. The description adds no extra context beyond the schema, such as required file existence or path resolution details. It neither harms nor significantly improves understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: planning file move/rename with import path updates, and explicitly distinguishes it from execution by noting it returns plans without modifying the filesystem. Sibling tools planDirectoryMove and planRenameSymbol indicate this is for individual files, providing clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for planning a move/rename without committing changes, but lacks explicit guidance on when to use versus siblings, prerequisites (e.g., file existence), or when not to use. The context of 'planning' is clear but not elaborated with conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
planRenameSymbolA
Compute edits to rename a TypeScript symbol at a specific position. Returns edit plans without modifying the filesystem.
| Name | Required | Description | Default |
|---|---|---|---|
| projectRoot | No | Optional base directory for resolving relative paths and limiting tsconfig discovery | |
| workspaceRoot | No | Optional monorepo root used to search multiple tsconfig.json files | |
| tsconfigPath | No | Optional explicit tsconfig.json path | |
| filePath | Yes | Absolute path or path relative to projectRoot/workspaceRoot | |
| line | Yes | 0-based line number of the symbol | |
| character | Yes | 0-based character position of the symbol | |
| newName | Yes | The new name for the symbol | |
| findInStrings | No | Whether to find occurrences in strings (default: false) | |
| findInComments | No | Whether to find occurrences in comments (default: false) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description explicitly states that the tool returns edit plans without modifying the filesystem, which is a key behavior. However, it does not mention error handling, permissions, or what happens if the symbol is not found, so it is not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler, front-loading the core purpose and key behavioral trait (no filesystem modification). Every word is justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 9 parameters and no output schema, the description conveys the essence but omits details like return format, error handling, or performance considerations. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all parameters. The description does not add meaningful extra information beyond what the schema already provides, so it meets baseline but does not improve parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool computes edits to rename a TypeScript symbol at a specific position. It distinguishes from sibling tools (planDirectoryMove, planFileMove) by focusing on symbol renaming and explicitly notes it returns plans without modifying filesystem.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool vs alternatives, but the sibling tools are for different operations (directory/file moves), so confusion is unlikely. No prerequisites or context are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
3 tool updates
v0.1.0- Changed
planDirectoryMove6 fields changed- changed
Input schema / properties / newDir / descriptionPrevious value: -"Absolute path or path relative to projectRoot of the destination"New value: +"Absolute path or path relative to projectRoot/workspaceRoot of the destination" - changed
Input schema / properties / oldDir / descriptionPrevious value: -"Absolute path or path relative to projectRoot of the directory to move"New value: +"Absolute path or path relative to projectRoot/workspaceRoot of the directory to move" - changed
Input schema / properties / projectRoot / descriptionPrevious value: -"Absolute or relative path to the project root"New value: +"Optional base directory for resolving relative paths and limiting tsconfig discovery" - added
Input schema / properties / tsconfigPathAdded value: +{ + "description": "Optional explicit tsconfig.json path for the primary project", + "type": "string" +} - added
Input schema / properties / workspaceRootAdded value: +{ + "description": "Optional monorepo root used to search multiple tsconfig.json files", + "type": "string" +} - changed
Input schema / requiredPrevious value: -[ - "projectRoot", - "oldDir", - "newDir" -]New value: +[ + "oldDir", + "newDir" +]
- Changed
planFileMove6 fields changed- changed
Input schema / properties / newPath / descriptionPrevious value: -"Absolute path or path relative to projectRoot of the destination"New value: +"Absolute path or path relative to projectRoot/workspaceRoot of the destination" - changed
Input schema / properties / oldPath / descriptionPrevious value: -"Absolute path or path relative to projectRoot of the file to move"New value: +"Absolute path or path relative to projectRoot/workspaceRoot of the file to move" - changed
Input schema / properties / projectRoot / descriptionPrevious value: -"Absolute or relative path to the project root"New value: +"Optional base directory for resolving relative paths and limiting tsconfig discovery" - added
Input schema / properties / tsconfigPathAdded value: +{ + "description": "Optional explicit tsconfig.json path for the primary project", + "type": "string" +} - added
Input schema / properties / workspaceRootAdded value: +{ + "description": "Optional monorepo root used to search multiple tsconfig.json files", + "type": "string" +} - changed
Input schema / requiredPrevious value: -[ - "projectRoot", - "oldPath", - "newPath" -]New value: +[ + "oldPath", + "newPath" +]
- Changed
planRenameSymbol5 fields changed- changed
Input schema / properties / filePath / descriptionPrevious value: -"Absolute path or path relative to projectRoot of the file containing the symbol"New value: +"Absolute path or path relative to projectRoot/workspaceRoot" - changed
Input schema / properties / projectRoot / descriptionPrevious value: -"Absolute or relative path to the project root"New value: +"Optional base directory for resolving relative paths and limiting tsconfig discovery" - added
Input schema / properties / tsconfigPathAdded value: +{ + "description": "Optional explicit tsconfig.json path", + "type": "string" +} - added
Input schema / properties / workspaceRootAdded value: +{ + "description": "Optional monorepo root used to search multiple tsconfig.json files", + "type": "string" +} - changed
Input schema / requiredPrevious value: -[ - "projectRoot", - "filePath", - "line", - "character", - "newName" -]New value: +[ + "filePath", + "line", + "character", + "newName" +]
3 tool updates
- First observed
planDirectoryMove - First observed
planFileMove - First observed
planRenameSymbol
TDQS
Scored across 3 tools
Each tool targets a distinct operation: directory moves, file moves, and symbol renames. There is no overlap in purpose.
All tools follow a consistent 'plan' + specific noun pattern (DirectoryMove, FileMove, RenameSymbol), making them predictable.
With only 3 tools, the server is tightly scoped to planning moves and renames, which is appropriate for its focused helper role.
The tool surface covers all necessary planning operations for TypeScript refactoring: directory moves, file moves, and symbol renames, with no glaring gaps.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Ask a codebase what calls what: search, blast radius, paths between symbols, and diffs.
Ship production-ready TypeScript code in half the time, at half the cost.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Translates a lockfile diff into a human-readable upgrade plan for npm, PyPI, and GitHub Actions.
Related MCP Servers
- AlicenseAqualityCmaintenanceProvides 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.82016MIT
- AlicenseAqualityBmaintenanceA TypeScript/JavaScript refactoring MCP server that uses the TypeScript compiler to perform safe, type-aware code transformations such as renaming, extracting functions, and organizing imports across your codebase.47512MIT
- AlicenseNot gradedqualityAmaintenanceProvides read-only code analysis and safe, reversible code refactoring with proven edit plans, previews, and rollback.5131MIT
- AlicenseNot gradedqualityCmaintenanceEnables querying a TypeScript codebase's graph for call flows, type relationships, and symbol locations without reading file bodies.-