Skip to main content
Glama
t09tanaka

TypeScript Rename Helper

by t09tanaka

@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.json from the target file path

  • Monorepo aware

    • Can merge edits from multiple tsconfig.json files 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-mcp

If you want the version pinned per repository, use a project-local install instead:

Project-local install:

npm i -D @t09tanaka/ts-rename-helper-mcp
pnpm add -D @t09tanaka/ts-rename-helper-mcp
yarn add -D @t09tanaka/ts-rename-helper-mcp

2. Add to your MCP client

Claude Code:

claude mcp add ts-rename-helper npx -- @t09tanaka/ts-rename-helper-mcp

OpenAI Codex:

codex mcp add ts-rename-helper npx -- @t09tanaka/ts-rename-helper-mcp

Other 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.json

  • For monorepos, workspaceRoot is optional but recommended when you want to scan multiple sibling TS projects deterministically

  • Prefer absolute paths for filePath, oldPath, newPath, oldDir, and newDir

  • For single-project repos, you can often omit projectRoot, workspaceRoot, and tsconfigPath

  • For monorepos, pass workspaceRoot when you want rename or move results to include sibling TS projects

  • If your repo uses non-standard config names such as tsconfig.app.json, pass tsconfigPath explicitly

How tsconfig is selected

When tsconfigPath is not provided, the server resolves the TypeScript project like this:

  1. Start from the target file path

  2. Walk upward looking for tsconfig.json

  3. Parse each candidate and choose the nearest one that actually includes the file

  4. If workspaceRoot is provided, also scan sibling tsconfig.json files 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:

  1. planRenameSymbol

  2. planFileMove

  3. planDirectoryMove

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 / character are 0-based (same as LSP).

  • filePath may be relative if projectRoot or workspaceRoot is provided. For global installs, absolute paths are recommended.

  • If tsconfigPath is omitted, the server walks upward from filePath and picks the nearest tsconfig.json that 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:

    1. Read each file

    2. Apply textEdits in a stable order (typically reverse-sorted by position)

    3. 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

  • fsMoves is only a suggestion – the agent/editor should perform the actual move.

  • edits should be applied after the move so that imports point to the new path.

  • If workspaceRoot is provided, the server scans sibling tsconfig.json files and merges import updates across the workspace.

  • tsconfigPath only selects the primary project explicitly; sibling projects still come from workspaceRoot discovery.


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 oldDir are treated as candidates for moves.

  • Internally this is typically implemented as repeated getEditsForFileRename calls.

  • If workspaceRoot is 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.ts

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

  1. Decide on an operation:

    • rename a symbol, or

    • move a file/directory

  2. Call the corresponding tool (planRenameSymbol, planFileMove, planDirectoryMove)

  3. Inspect the returned edits and fsMoves

  4. Apply fsMoves using its own filesystem tools

  5. Apply edits to the affected files

  6. Optionally run tsc or tests to validate


Limitations

  • TypeScript only JavaScript-only projects without tsconfig.json are 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.json discovery is convention-based The server currently discovers tsconfig.json files, not arbitrary tsconfig.*.json variants unless you pass tsconfigPath.

  • 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 tools
planDirectoryMoveA

Plan directory move with recursive import updates for all contained files. Returns edit plans and file move suggestions without modifying the filesystem.

ParametersJSON Schema
NameRequiredDescriptionDefault
projectRootNoOptional base directory for resolving relative paths and limiting tsconfig discovery
workspaceRootNoOptional monorepo root used to search multiple tsconfig.json files
tsconfigPathNoOptional explicit tsconfig.json path for the primary project
oldDirYesAbsolute path or path relative to projectRoot/workspaceRoot of the directory to move
newDirYesAbsolute path or path relative to projectRoot/workspaceRoot of the destination

TDQS

A3.5/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
projectRootNoOptional base directory for resolving relative paths and limiting tsconfig discovery
workspaceRootNoOptional monorepo root used to search multiple tsconfig.json files
tsconfigPathNoOptional explicit tsconfig.json path for the primary project
oldPathYesAbsolute path or path relative to projectRoot/workspaceRoot of the file to move
newPathYesAbsolute path or path relative to projectRoot/workspaceRoot of the destination

TDQS

A3.6/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
projectRootNoOptional base directory for resolving relative paths and limiting tsconfig discovery
workspaceRootNoOptional monorepo root used to search multiple tsconfig.json files
tsconfigPathNoOptional explicit tsconfig.json path
filePathYesAbsolute path or path relative to projectRoot/workspaceRoot
lineYes0-based line number of the symbol
characterYes0-based character position of the symbol
newNameYesThe new name for the symbol
findInStringsNoWhether to find occurrences in strings (default: false)
findInCommentsNoWhether to find occurrences in comments (default: false)

TDQS

A3.9/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

  1. 3 tool updatesv0.1.0
    • ChangedplanDirectoryMove6 fields changed
      • changedInput schema / properties / newDir / description
        Previous value: -"Absolute path or path relative to projectRoot of the destination"New value: +"Absolute path or path relative to projectRoot/workspaceRoot of the destination"
      • changedInput schema / properties / oldDir / description
        Previous 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"
      • changedInput schema / properties / projectRoot / description
        Previous value: -"Absolute or relative path to the project root"New value: +"Optional base directory for resolving relative paths and limiting tsconfig discovery"
      • addedInput schema / properties / tsconfigPath
        Added value: +{
        +  "description": "Optional explicit tsconfig.json path for the primary project",
        +  "type": "string"
        +}
      • addedInput schema / properties / workspaceRoot
        Added value: +{
        +  "description": "Optional monorepo root used to search multiple tsconfig.json files",
        +  "type": "string"
        +}
      • changedInput schema / required
        Previous value: -[
        -  "projectRoot",
        -  "oldDir",
        -  "newDir"
        -]New value: +[
        +  "oldDir",
        +  "newDir"
        +]
    • ChangedplanFileMove6 fields changed
      • changedInput schema / properties / newPath / description
        Previous value: -"Absolute path or path relative to projectRoot of the destination"New value: +"Absolute path or path relative to projectRoot/workspaceRoot of the destination"
      • changedInput schema / properties / oldPath / description
        Previous 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"
      • changedInput schema / properties / projectRoot / description
        Previous value: -"Absolute or relative path to the project root"New value: +"Optional base directory for resolving relative paths and limiting tsconfig discovery"
      • addedInput schema / properties / tsconfigPath
        Added value: +{
        +  "description": "Optional explicit tsconfig.json path for the primary project",
        +  "type": "string"
        +}
      • addedInput schema / properties / workspaceRoot
        Added value: +{
        +  "description": "Optional monorepo root used to search multiple tsconfig.json files",
        +  "type": "string"
        +}
      • changedInput schema / required
        Previous value: -[
        -  "projectRoot",
        -  "oldPath",
        -  "newPath"
        -]New value: +[
        +  "oldPath",
        +  "newPath"
        +]
    • ChangedplanRenameSymbol5 fields changed
      • changedInput schema / properties / filePath / description
        Previous value: -"Absolute path or path relative to projectRoot of the file containing the symbol"New value: +"Absolute path or path relative to projectRoot/workspaceRoot"
      • changedInput schema / properties / projectRoot / description
        Previous value: -"Absolute or relative path to the project root"New value: +"Optional base directory for resolving relative paths and limiting tsconfig discovery"
      • addedInput schema / properties / tsconfigPath
        Added value: +{
        +  "description": "Optional explicit tsconfig.json path",
        +  "type": "string"
        +}
      • addedInput schema / properties / workspaceRoot
        Added value: +{
        +  "description": "Optional monorepo root used to search multiple tsconfig.json files",
        +  "type": "string"
        +}
      • changedInput schema / required
        Previous value: -[
        -  "projectRoot",
        -  "filePath",
        -  "line",
        -  "character",
        -  "newName"
        -]New value: +[
        +  "filePath",
        +  "line",
        +  "character",
        +  "newName"
        +]
  2. 3 tool updates
    • First observedplanDirectoryMove
    • First observedplanFileMove
    • First observedplanRenameSymbol

TDQS

A4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a distinct operation: directory moves, file moves, and symbol renames. There is no overlap in purpose.

Naming Consistency5/5

All tools follow a consistent 'plan' + specific noun pattern (DirectoryMove, FileMove, RenameSymbol), making them predictable.

Tool Count5/5

With only 3 tools, the server is tightly scoped to planning moves and renames, which is appropriate for its focused helper role.

Completeness5/5

The tool surface covers all necessary planning operations for TypeScript refactoring: directory moves, file moves, and symbol renames, with no glaring gaps.

Maintenance

ActivityInactive
ResponsivenessNo issues

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

Related MCP Servers

  • A
    license
    A
    quality
    B
    maintenance
    A 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.
    4
    75
    12
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    Enables querying a TypeScript codebase's graph for call flows, type relationships, and symbol locations without reading file bodies.
    -