What can you do with this server?

Use this MCP server to perform TypeScript-aware refactorings and code-quality tasks via tsserver, with previews and detailed edit reports. * File operations: rename, move, or batch-move TypeScript/JavaScript files while auto-updating imports. * Code quality: organize imports, apply TypeScript's preferred fixes (fix_all), and remove unused imports/variables/functions safely. * Refactoring: rename symbols; extract functions, constants, or variables; move top-level declarations to another/new file; infer explicit return types. * Workspace: find type-aware references; refactor a module by moving it then organizing/fixing touched files; clean up a codebase (optionally deleting unused files via tsr); restart tsserver. * Every editing operation supports preview: true, paths must be absolute, and responses list changed files and each edit.

Which integrations are available for this server?

Supports refactoring JavaScript files alongside TypeScript, offering operations such as renaming variables, extracting functions, organizing imports, and code cleanup within JavaScript projects. Provides comprehensive refactoring tools for TypeScript codebases, enabling type-aware operations like renaming symbols, extracting functions/constants, organizing imports, and finding references with compiler-grade accuracy.

How do I use mcp-refactor-typescript?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-refactor-typescript rename function getUser to fetchUser in src/services.ts" 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.

mcp-refactor-typescript

by Stefan-Nitu

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

NPM Version NPM Downloads CI Status MIT Licensed

MCP Refactor TypeScript

An MCP server that gives MCP clients TypeScript's own refactorings: rename symbols, move files and declarations, extract functions and constants, organize imports and apply quick fixes. It drives tsserver, the TypeScript language service editors use, so TypeScript computes every edit; the server writes the edits to disk and reports each one.

Renames and moves update imports and references across the project.
Every operation that edits files accepts preview: true, which returns the edits without writing them.
Each response lists the changed files and every edit: line, column, old text, new text.

Installation

npm install -g mcp-refactor-typescript

This installs the mcp-refactor-typescript command. You can also run the server through npx without installing it (see Quick Start).

From source:

git clone https://github.com/Stefan-Nitu/mcp-refactor-typescript.git
cd mcp-refactor-typescript
bun install
bun run build

The server runs on Node.js 18 or later. Developing it needs Bun 1.3.8 or later.

Which TypeScript it uses

Your project does not need TypeScript installed: the server ships TypeScript 5.9. When a typescript package resolves from the directory the server was launched in, that copy is used instead, so edits match the version the project compiles with; TypeScript 4.9 and later work. TypeScript 7 no longer ships tsserver, so a project on 7 gets the bundled 5.9.

The project should have a tsconfig.json: tsserver uses it to know which files belong to the project.

Related MCP server: TypeScript Tools MCP

Quick Start

Claude Desktop

Add the server to Claude Desktop's configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-refactor-typescript": {
      "command": "npx",
      "args": ["-y", "mcp-refactor-typescript"]
    }
  }
}

If you installed it globally:

{
  "mcpServers": {
    "mcp-refactor-typescript": {
      "command": "mcp-refactor-typescript"
    }
  }
}

Restart Claude Desktop to load it.

MCP Inspector

Try the tools interactively in the MCP Inspector:

npx @modelcontextprotocol/inspector npx -y mcp-refactor-typescript

If you installed it globally:

npx @modelcontextprotocol/inspector mcp-refactor-typescript

The Inspector prints the URL to open in your browser.

To list the tools from the command line instead:

npx @modelcontextprotocol/inspector --cli npx mcp-refactor-typescript@latest --method tools/list --connect-timeout 60000

--connect-timeout gives npx time to download the package on the first run.

Paths must be absolute

Every path parameter (filePath, sourcePath, destinationPath, each entry of files, targetFolder, directory) must be an absolute path. A relative or empty path is rejected with an error that names the parameter and the server's working directory. A relative path would resolve against that directory, which is wherever the MCP client launched it and not necessarily the checkout being edited: an agent working in a git worktree would otherwise change the main checkout. rename_file's name is a bare filename and entrypoints are regex patterns, so neither is a path. Up to 2.3.0, relative paths were accepted.

Tools

The server exposes 4 tools covering 16 operations. The operation argument picks the operation within a tool.

Tool	Operations
`file_operations`	`rename_file`, `move_file`, `batch_move_files`
`code_quality`	`organize_imports`, `fix_all`, `remove_unused`
`refactoring`	`rename`, `extract_function`, `extract_constant`, `extract_variable`, `move_to_file`, `infer_return_type`
`workspace`	`find_references`, `refactor_module`, `cleanup_codebase`, `restart_tsserver`

Operations

Operations that act on code take filePath, a 1-based line and text: the first occurrence of text on that line that is not part of a longer identifier is the symbol or expression to act on, so user never selects username. Every operation that edits files also takes preview. ? marks an optional parameter.

Operation	Parameters	What it does
`rename_file`	`sourcePath`, `name`	Renames a file in its directory (`name` is the new filename) and updates imports of it.
`move_file`	`sourcePath`, `destinationPath`	Moves a file to `destinationPath` (a full path including the filename) and updates imports.
`batch_move_files`	`files`, `targetFolder`	Moves each file into `targetFolder`, one at a time, updating imports. A file that fails is reported and the others still move.
`organize_imports`	`filePath`	Sorts the file's imports and removes unused ones.
`fix_all`	`filePath`	Gives each error in the file the one fix TypeScript prefers, in rounds until no fixable error is left, at most 10. A fix can edit other files. Like `remove_unused`, it keeps an unused declaration that may have side effects.
`remove_unused`	`filePath`	Removes unused imports, variables and functions, also under `noUnusedLocals` and `noUnusedParameters`. Keeps an unused declaration whose initializer may have side effects, such as `const server = app.listen(3000)`, and names it in the message.
`rename`	`filePath`, `line`, `text`, `name`	Renames a symbol and every reference to it.
`extract_function`	`filePath`, `line`, `text`, `name`?	Extracts `text` into a function, at module scope when TypeScript offers it.
`extract_constant`	`filePath`, `line`, `text`, `name`?	Extracts `text` into a `const` in the enclosing scope.
`extract_variable`	`filePath`, `line`, `text`, `name`?	Same edit as `extract_constant`: a `const` in the enclosing scope.
`move_to_file`	`filePath`, `line`, `text`, `destinationPath`?	Moves a top-level declaration to `destinationPath`, or to a new file named after it, and updates imports.
`infer_return_type`	`filePath`, `line`, `text`	Adds an explicit return type to a function.
`find_references`	`filePath`, `line`, `text`	Lists every reference to a symbol, grouped by file. Changes nothing.
`refactor_module`	`sourcePath`, `destinationPath`	`move_file`, then `organize_imports` and `fix_all` on the files the move touched, including the module at its new location.
`cleanup_codebase`	`directory`, `deleteUnusedFiles`?, `entrypoints`?	Runs `organize_imports` on every `.ts` and `.tsx` file under `directory`, skipping `node_modules`, `dist` and dot-directories. With `deleteUnusedFiles: true` it first runs tsr, which removes unused exports and deletes files not reachable from `entrypoints`.
`restart_tsserver`	none	Stops tsserver and starts a new one.

The extract operations generate a name when name is omitted. docs/OPERATIONS.md has examples for each operation; clients can also read it from the server as the operations://catalog resource.

Response Format

Every call returns one text item holding JSON:

{
  "tool": "refactoring",
  "operation": "rename",
  "status": "success",
  "message": "Renamed to \"getUserProfile\"",
  "data": {
    "filesChanged": [
      {
        "file": "user.ts",
        "path": "/path/to/project/src/user.ts",
        "edits": [
          { "line": 1, "column": 17, "old": "getUser", "new": "getUserProfile" }
        ]
      },
      {
        "file": "main.ts",
        "path": "/path/to/project/src/main.ts",
        "edits": [
          { "line": 3, "column": 13, "old": "getUser", "new": "getUserProfile" },
          { "line": 1, "column": 10, "old": "getUser", "new": "getUserProfile" }
        ]
      }
    ],
    "nextActions": [
      "organize_imports - Clean up import statements",
      "fix_all - Fix any type errors from rename"
    ]
  }
}

status is "success" or "error". On "error" the MCP result also carries isError: true, which is what clients check.
message summarizes the result. For find_references it is the result: the references, grouped under each file's absolute path.
data.filesChanged has one entry per changed file: file is the file name, path the absolute path, and each edit gives the 1-based line and column in the file as it was before the operation, the old text and the new text. The exception is a fix_all that took more than one round: each round's edits refer to the text the rounds before it left. Within a file, edits are usually listed bottom-up, the order they are applied in. filesChanged is empty on failure and for operations that change nothing.
data.preview appears only with preview: true: { "filesAffected": 2, "estimatedTime": "< 1s", "command": "Run again with preview: false to apply changes" }. estimatedTime is a fixed estimate, not a measurement.
data.nextActions appears when the operation suggests follow-up operations.

Errors

A failed operation has the same shape with "status": "error" and an empty filesChanged. The message says what failed and what to try:

{
  "tool": "refactoring",
  "operation": "rename",
  "status": "error",
  "message": "Text \"getUsr\" not found on line 1\n\nLine content: export function getUser(id: string) {\n\nTry:\n  1. Check the text matches exactly (case-sensitive)\n  2. Ensure you're on the correct line",
  "data": { "filesChanged": [] }
}

Invalid input comes back in one of two forms, both with isError: true:

A parameter of the wrong type, a relative path, an unknown operation, or a missing parameter that every operation of the tool needs is rejected by the MCP SDK before the server sees the call. The content is plain text, not JSON: MCP error -32602: Input validation error: Invalid arguments for tool refactoring: Invalid input: expected number, received string at line
A parameter that only some operations need, such as line for find_references, is checked by the server and reported in the JSON shape above, with a message such as "Invalid input:\n • line is required for find_references\n\nCheck the input parameters and try again".

docs/ERROR-HANDLING.md covers every failure path.

Examples

These are the params of an MCP tools/call request. Replace /path/to/project with the absolute path of your project.

Preview a rename

{
  "name": "refactoring",
  "arguments": {
    "operation": "rename",
    "filePath": "/path/to/project/src/user.ts",
    "line": 10,
    "text": "getUser",
    "name": "getUserProfile",
    "preview": true
  }
}

The response lists the edits and nothing is written. Send it again without preview to apply them.

Extract a function

{
  "name": "refactoring",
  "arguments": {
    "operation": "extract_function",
    "filePath": "/path/to/project/src/calculate.ts",
    "line": 15,
    "text": "x + y",
    "name": "addNumbers"
  }
}

text has to sit on the one line, so an extraction covers at most one line.

Move a declaration to another file

{
  "name": "refactoring",
  "arguments": {
    "operation": "move_to_file",
    "filePath": "/path/to/project/src/utils.ts",
    "line": 10,
    "text": "parseConfig",
    "destinationPath": "/path/to/project/src/config/parser.ts"
  }
}

Move several files

{
  "name": "file_operations",
  "arguments": {
    "operation": "batch_move_files",
    "files": [
      "/path/to/project/src/utils/string.ts",
      "/path/to/project/src/utils/number.ts"
    ],
    "targetFolder": "/path/to/project/src/lib"
  }
}

Each file keeps its name. The files move one after another, not as one transaction: if one fails, the others still move and the message lists the failure.

Delete unused files

{
  "name": "workspace",
  "arguments": {
    "operation": "cleanup_codebase",
    "directory": "/path/to/project",
    "deleteUnusedFiles": true,
    "entrypoints": ["src/main\\.ts$", "src/cli\\.ts$", ".*\\.test\\.ts$"],
    "preview": true
  }
}

With deleteUnusedFiles: true, directory must be the project root: the directory that contains the tsconfig.json tsr reads. The server refuses any other directory, because without that tsconfig.json tsr falls back to default compiler options and can judge files that are in use unreachable, then delete them.
entrypoints is required with deleteUnusedFiles: true. Each entry is a regular expression matched against each file's absolute path (its real path, when the project is reached through a symlink); a file not reachable through imports from a matching file is deleted. Nothing imports a test file, so list your test files too.
The server checks entrypoints before tsr runs: each must be a valid regular expression, and together they must match a source file other than a .d.ts among the files tsconfig.json includes. tsr also counts every .d.ts file as an entrypoint, so patterns that matched nothing else would leave it deleting everything those files do not import.
The preview runs tsr without writing and reports what it would change, or that it found nothing to remove. Any tsr failure is reported as a failure.
A real run that fails part-way is not rolled back: what tsr or the import sweep has already written or deleted stays that way.
Without deleteUnusedFiles, the operation only organizes imports, and directory can be any directory.

Development

Layout

src/
├── index.ts                       MCP server: registers the tools and the operations://catalog resource
├── operation-name.ts              Operation names
├── registry.ts                    Builds every operation around one tsserver client
├── tools/                         The four tools and their input schemas
├── operations/                    One file per operation
│   └── shared/                    Edit application, file discovery, file moves, tsserver readiness, side-effect guard
├── language-servers/typescript/   tsserver client, message parser, tsserver lookup
├── resources/                     Serves docs/OPERATIONS.md
└── utils/                         Logger (stderr), telemetry, validation messages
scripts/fresh-install-smoke-test.mjs   Installs the packed server and refactors a project that has no TypeScript

Commands

bun run build                # compile to dist/
bun run test                 # the whole suite; build first, two test files run dist/index.js
bun test --timeout 30000 src/operations/__tests__/rename.integration.test.ts   # one file
bun run check                # typecheck and lint
bun run test:fresh-install   # pack, install and run the server outside this repository

docs/TESTING.md explains the test layout and how to run subsets.

Architecture

One tsserver process serves every call, and calls run one at a time: a call that arrives while another is running waits for it to finish. The server starts tsserver at launch when there are TypeScript or JavaScript files in its working directory or up to two levels below it, and otherwise on the first call. Before each operation, the files the server has open in tsserver are re-synced with the disk, so changes made outside the server, in an editor or by git, are seen. An operation asks tsserver for edits, applies them to the file contents itself and writes the files. Logs go to stderr; stdout carries only the MCP protocol.

docs/ARCHITECTURE.md has the details.

Documentation

OPERATIONS.md: what each operation does, with examples. Also served as the operations://catalog resource.
ARCHITECTURE.md: how a tool call reaches tsserver, and how edits are computed and written.
ERROR-HANDLING.md: how failures are reported to clients.
TESTING.md: test layout, conventions and how to run the tests.
DEV_NOTES.md: past mistakes and the rules they left behind.
TDD.md: the test-first workflow contributions follow.
MCP-TYPESCRIPT-README.md: a copy of the MCP TypeScript SDK's README.

Troubleshooting

tsserver does not start

Operations fail with a message containing Could not spawn tsserver at <path>: … or tsserver at <path> exited with code …. <path> shows which TypeScript the server picked: the one that resolves from its working directory, or its bundled copy.

If <path> is in your project, check that project's TypeScript version: 4.9 and later work.
Set LOG_LEVEL=debug in the server's environment to log tsserver's stderr.
Call restart_tsserver to start a new tsserver.

"TypeScript is still indexing the project"

tsserver had not reported the project as loaded within 5 seconds. Call the operation again.

A rename or find_references misses files

A rename's message ends with a warning when indexing had not finished or file discovery timed out. Run the operation again.
tsserver only sees files that belong to a project: make sure the files are covered by a tsconfig.json.
Call restart_tsserver after changing tsconfig.json.

Imports are not updated after a move

tsserver updates import and export statements in the files it knows about (see above). It cannot follow a computed specifier such as import(`./${name}.js`).
Other string literals that hold the path, such as vi.mock('./service.js'), jest.mock(...) or require(...), are matched as text, and only when written as a path relative to the file that ends in .js.

Contributing

Fork the repository and create a branch.
Write a failing test first (docs/TDD.md), then make it pass.
Run bun run check, then bun run build and bun run test.
Open a pull request.

License

MIT. See LICENSE.

Model Context Protocol: the MCP specification and documentation
MCP TypeScript SDK: the SDK this server uses
MCP Servers: reference MCP server implementations

Available Tools

4 tools

code_qualityCode QualityA

Fix ALL TypeScript errors + organize imports + remove unused (<1s, 20+ issues).

vs Manual: Compiler-verified, preserves side-effects, finds hidden issues.

Use when: After refactoring or before commits. Use proactively.

ParametersJSON Schema

Name	Required	Description	Default
`operation`	Yes
`filePath`	Yes
`preview`	No

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already set readOnlyHint=false and destructiveHint=false. The description adds that the tool is fast (<1s) and finds hidden issues, but does not explain the modify-in-place behavior or potential side-effects beyond preserving side-effects. It adds some value but not extensive.

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?

Extremely concise: two short lines that front-load the action and rationale. No wasted words. Every sentence adds value.

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 3 parameters, no output schema, and sibling tools like refactoring, the description covers purpose and when-to-use but lacks parameter documentation and return value info. It is somewhat incomplete for an agent to fully understand usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. The description mentions operations (fix all, organize imports, remove unused) which map to the operation enum, but does not explain the filePath or preview parameters. Without these, an agent may not use the tool correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/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: fixing TypeScript errors, organizing imports, and removing unused code. It uses specific verbs and resources. However, it could better distinguish from sibling tools like refactoring, which might have overlapping capabilities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit usage guidance is provided: 'Use when: After refactoring or before commits. Use proactively.' This helps the agent decide when to invoke. It also compares to manual process. No explicit when-not to use, but the context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

file_operationsFile OperationsA

Rename/move TypeScript files - auto-updates ALL imports (<1s, 47 refs across 12 files).

vs Edit/Bash: They break imports. This catches dynamic imports, mocks, re-exports.

Use when: Renaming/moving TS/JS files. Always use this, not mv/Edit.

ParametersJSON Schema

Name	Required	Description	Default
`operation`	Yes
`sourcePath`	No
`name`	No
`destinationPath`	No
`files`	No
`targetFolder`	No
`preview`	No

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate non-read-only and non-destructive behavior. The description adds critical behavioral context: auto-updates all imports, handles dynamic imports/mocks/re-exports, and provides speed and scope metrics (<1s, 47 refs across 12 files). No contradiction with annotations.

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 exceptionally concise: two sentences plus a usage line, front-loaded with the most important info. Every sentence adds unique value—function, contrast with alternatives, and explicit usage advice—with 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 7 parameters (1 required) and no output schema, the description covers the primary use case and performance but omits details on parameter combinations (e.g., when to use sourcePath+name vs files+targetFolder) and the preview parameter. It addresses key behavioral aspects but lacks full completeness for a tool of moderate complexity.

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 0% schema description coverage for 7 parameters, the description should compensate but only indirectly hints at parameters (e.g., 'Rename/move' implies operation, '47 refs' suggests batch moves). It does not explicitly describe individual parameters or their relationships, leaving gaps.

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 explicitly states the tool renames/moves TypeScript files and auto-updates imports, providing a specific verb and resource. It distinguishes itself from Edit/Bash by highlighting import-breaking behavior, and the performance metrics add clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes a clear directive: 'Use when: Renaming/moving TS/JS files. Always use this, not mv/Edit.' It also contrasts with Edit/Bash, explaining when not to use those alternatives, making the usage context explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

refactoringRefactoringA

Rename symbols, extract functions, or move symbols to files (auto-updates imports).

vs Edit: Updates ALL refs (imports, JSDoc, dynamic imports). Impossible by hand.

Use when: Renaming, extracting, or moving symbols between files. Always use this.

ParametersJSON Schema

Name	Required	Description	Default
`operation`	Yes
`filePath`	Yes
`line`	Yes
`text`	Yes
`name`	No
`destinationPath`	No
`preview`	No

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations (readOnlyHint=false, destructiveHint=false) are complemented by description that says tool 'Updates ALL refs (imports, JSDoc, dynamic imports). Impossible by hand.' This adds useful behavioral context beyond annotations.

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?

Concise four-sentence description, front-loaded with main actions, each sentence adds value. No redundancy.

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?

Covers purpose and usage well, but lacks details on return values, preview behavior, and error handling. Given 7 parameters and no output schema, more completeness would be beneficial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, the description does not explain individual parameters like 'line', 'text', 'destinationPath', etc. It only mentions operations and vague inputs, insufficient for agent to use correctly.

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 does renaming, extracting, and moving of symbols with automatic import updates. It distinguishes itself from an 'Edit' tool, providing differentiation from a sibling-like action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'Rename, extracting, or moving symbols between files. Always use this.' Also contrasts with 'Edit' tool, giving clear contextual guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

workspaceWorkspaceA

Destructive

Find references (type-aware) | Cleanup | Move+organize+fix | Restart tsserver.

vs grep: Finds dynamic imports, JSDoc, type-only imports grep misses. ⚠️ Can DELETE.

Use when: Before renaming/refactoring. Use find_references first to see impact.

ParametersJSON Schema

Name	Required	Description	Default
`operation`	Yes
`filePath`	No
`line`	No
`text`	No
`sourcePath`	No
`destinationPath`	No
`directory`	No
`deleteUnusedFiles`	No
`entrypoints`	No
`preview`	No

TDQS

A3.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description warns '⚠️ Can DELETE,' which aligns with the destructiveHint annotation and adds emphasis. It also explains advantages over grep (dynamic imports, JSDoc, type-only imports), providing behavioral context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise: three lines covering operations, comparison, and usage. It is front-loaded with key actions. Minor improvement possible by adding parameter hints without bloating.

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?

Given 10 parameters, no output schema, and multi-operation nature, the description lacks detail on operation-specific parameter usage, return values, and example invocations. Significant gaps exist.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries full burden. It mentions operations but provides no explanation of parameters like filePath, line, text, etc., leaving the agent without guidance on how to construct valid invocations.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly lists four distinct operations (find references, cleanup, move+organize+fix, restart tsserver) with a comparison to grep, indicating specific type-aware behavior. It does not explicitly differentiate from sibling tools, but the purpose is specific enough.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states 'Use when: Before renaming/refactoring. Use find_references first to see impact.' This gives clear usage context and a recommended order of operations, fully satisfying the dimension.

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.

4 tool updatesv2.1.0Jun 11, 2026
- First observedcode_quality
- First observedfile_operations
- First observedrefactoring
- First observedworkspace

Deploy Server

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A3.9/5.0

Scored 2026-06-12 14:11 across 4 tools

Disambiguation4/5

Tools have mostly distinct purposes: code_quality for fixing errors/organizing, file_operations for file moves, refactoring for symbol renaming/extraction, workspace for finding references and cleanup. Some overlap exists (e.g., workspace cleanup may overlap with code_quality), but descriptions clarify when to use each.

Naming Consistency3/5

All names use lowercase snake_case, but the pattern is inconsistent: code_quality (noun_quality) vs file_operations (noun_operations) vs refactoring (gerund) vs workspace (single noun). No verb_noun pattern, making it less predictable for agents.

Tool Count5/5

With 4 tools, the surface is well-scoped for a TypeScript refactoring server. Each tool covers a key area (code quality, file operations, symbol refactoring, workspace queries) without unnecessary bloat.

Completeness4/5

Core refactoring workflows are covered: error fixing, file renaming, symbol manipulation, and referencing. Minor gaps like formatting or running typechecker are absent, but the set is sufficient for common refactoring tasks.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

slhad-aha-mcp
ai.smithery
A TypeScript MCP server for Home Assistant, enabling programmatic management of entities, automati…
Home Automation & IoT App Automation
2
Svelte MCP A
dev.svelte
The official Svelte MCP server providing docs and autofixing tools for Svelte development
Developer Tools Documentation Access Code Analysis
42333
neverinfamous-memory-journal-mcp
ai.smithery
A MCP server built for developers enabling Git based project management with project and personal…
Version Control Developer Tools Project Management
320
smithery-ai-cookbook-ts-smithery-cli
ai.smithery
A simple Typescript MCP server built using the official MCP Typescript SDK and smithery/cli. This…
Developer Tools
213

Related MCP Servers

language-server-mcp
Code Analysis Developer Tools Autonomous Agents
alexwohletz
A
license
B
quality
D
maintenance
TypeScript-based MCP server designed to enhance code editing experiences by providing features such as hover information, code completion, and diagnostics.
Updated a year ago (2025-11-26 23:18 UTC)
3
24 npm
26
MIT
TypeScript Tools MCP
Developer Tools Code Analysis Code Execution
trkbt10
F
license
Not graded
quality
D
maintenance
A Model Context Protocol (MCP) server that provides TypeScript development tools for automated refactoring and code analysis.
Updated a year ago (2025-09-17 07:16 UTC)
1
-
ts-refactor-mcp
Developer Tools Code Analysis
schicks
A
license
A
quality
C
maintenance
An MCP server that enables AI agents to move TypeScript files and directories while automatically updating all affected imports using a persistent tsserver instance. This ensures atomic, error-free refactoring that maintains project integrity without manual intervention or wasted tokens.
Updated 9 months ago (2026-01-16 15:13 UTC)
2
30 npm
MIT
ts-mcp-server
Developer Tools Code Analysis
AndyLiner13
A
license
A
quality
D
maintenance
A lightweight MCP server that provides 40 tools for TypeScript/JavaScript refactoring and code intelligence, directly mapping to TypeScript's tsserver protocol commands for accurate structural changes and workspace analysis.
Updated 6 months ago (2026-04-07 05:38 UTC)
40
27 npm
3
MIT

MCP Refactor TypeScript

Installation

Which TypeScript it uses

Quick Start

Claude Desktop

MCP Inspector

Paths must be absolute

Tools

Operations

Response Format

Errors

Examples

Preview a rename

Extract a function

Move a declaration to another file

Move several files

Delete unused files

Development

Layout

Commands

Architecture

Documentation

Troubleshooting

tsserver does not start

"TypeScript is still indexing the project"

A rename or find_references misses files

Imports are not updated after a move

Contributing

License

Related Projects

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers