Refactor MCP
Supports Java refactoring in Gradle projects by executing OpenRewrite recipes via the Gradle plugin.
Click on "Deploy 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., "@Refactor MCP Rename the UserService class to CustomerService"
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.
Refactor MCP
A Model Context Protocol (MCP) server for automated refactoring of Java and TypeScript/JavaScript codebases. Uses OpenRewrite for Java refactoring and ts-morph for TypeScript.
Features
Java Refactoring (via OpenRewrite)
Rename class - Rename a class and update all references across the codebase
Rename method - Rename a method and update all call sites
Rename field - Rename a field and update all usages
Move class - Move class(es) to a different package and update imports
Add/Remove/Reorder parameters - Modify method signatures and update all call sites
Java Record support - Full support for modifying Java record components (adds
nullto call sites)
TypeScript/JavaScript Refactoring (via ts-morph)
Rename symbol - Rename any symbol (class, function, variable, interface, type) and update all references
Move symbol - Move a symbol to a different file and update all imports
Rename file - Rename/move a file and update all imports
Extract function - Extract a code block into a new function with automatic parameter detection
Add/Remove parameters - Modify function signatures and update all call sites
Utilities
Detect project type - Automatically detect Java/TypeScript projects and their build systems
Related MCP server: ast-editor
Requirements
Node.js 18+
For Java refactoring: Maven or Gradle project with OpenRewrite plugin available
Installation
# Clone the repository
git clone https://github.com/YOUR_USERNAME/refactor-mcp.git
cd refactor-mcp
# Install dependencies
npm install
# Build
npm run buildConfiguration
Claude Code / Claude Desktop
Add to your Claude configuration file:
Claude Code (~/.claude/settings.json):
{
"mcpServers": {
"refactor": {
"command": "node",
"args": ["/path/to/refactor-mcp/build/index.js"]
}
}
}Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"refactor": {
"command": "node",
"args": ["/path/to/refactor-mcp/build/index.js"]
}
}
}Java Projects
For Java refactoring to work, your project needs the OpenRewrite Maven plugin in pom.xml:
<build>
<plugins>
<plugin>
<groupId>org.openrewrite.maven</groupId>
<artifactId>rewrite-maven-plugin</artifactId>
<version>5.44.0</version>
</plugin>
</plugins>
</build>Or for Gradle, add to build.gradle:
plugins {
id 'org.openrewrite.rewrite' version '6.25.0'
}Usage
All tools support a dryRun parameter (default: true) that previews changes without applying them.
Java Examples
Rename a class:
Rename com.example.UserService to com.example.CustomerServiceRename a method:
Rename method getUser to fetchUser in com.example.UserServiceMove classes to a new package:
Move all classes from com.example.old to com.example.newTypeScript Examples
Rename a symbol:
Rename UserService to CustomerService in the TypeScript projectMove a symbol to a different file:
Move the UserService class from user-service.ts to services/customer-service.tsExtract a function:
Extract lines 10-20 from utils.ts into a new function called processDataAvailable Tools
Tool | Description |
| Detect project type and build system |
| Rename a Java class |
| Rename a Java method |
| Rename a Java field |
| Move Java class(es) to a different package |
| Add a parameter to a Java method |
| Remove a parameter from a Java method |
| Reorder parameters in a Java method |
| Rename any TypeScript symbol |
| Move a symbol to a different file |
| Rename/move a TypeScript file |
| Extract code into a new function |
| Add a parameter to a function |
| Remove a parameter from a function |
Development
# Run in development mode
npm run dev
# Build
npm run build
# Run tests
npm testHow It Works
Java Refactoring
The server generates OpenRewrite recipe YAML files dynamically and executes them via the Maven/Gradle plugin. This ensures type-safe refactoring with proper handling of imports, references, and edge cases.
TypeScript Refactoring
Uses ts-morph to parse and manipulate the TypeScript AST directly. Changes are tracked and can be previewed as diffs before applying.
Java Records Support
Java records require special handling because they have implicit canonical constructors. When you modify a record's components, both the record declaration AND all call sites (new RecordName(...)) must be updated.
How Record Modification Works
When you use java_add_parameter, java_remove_parameter, or java_change_method_signature on a Java record (with methodName: "<init>" or the class name), the tool:
Detects the record - Automatically identifies if the target class is a Java record
Modifies the record declaration - Updates the record component list directly in the source file
Updates all call sites - Uses OpenRewrite's
AddNullMethodArgumentrecipe to addnullto allnew RecordName(...)expressions
Example: Adding a Component to a Record
// Before: public record Person(String name, int age) {}
// After: public record Person(String name, int age, String email) {}
// All call sites are updated:
// Before: new Person("John", 30)
// After: new Person("John", 30, null)Important Notes for Records
New parameters are added as
null- When adding a component, all existing call sites receivenullas the new argument value. You may need to update these manually if a different default is required.Use
<init>or<constructor>as methodName - Both work for targeting record constructorsDry run first - Always use
dryRun: trueto preview changes before applying
Technical Details: OpenRewrite Recipes
Understanding which OpenRewrite recipes are used helps when troubleshooting or extending the tool.
Declarations vs Call Sites
OpenRewrite has different recipes for modifying declarations (where methods/constructors are defined) vs call sites (where they are invoked):
What to Modify | Recipe | Handles |
Method declaration (add param to signature) |
| Declarations only |
Method/constructor calls (add argument) |
| Call sites (including |
Method/constructor calls (add literal) |
| Call sites (including |
Method/constructor calls (remove argument) |
| Call sites (including |
Method/constructor calls (reorder args) |
| Call sites (including |
Recipe Selection by Operation
Tool Operation | Regular Methods | Java Records |
Add parameter |
| Record utils + |
Remove parameter |
| Record utils + |
Reorder parameters |
| Record utils + |
Batch changes |
| Record utils + |
Method Patterns for Constructors
To target constructors in method patterns, use either:
com.example.MyClass <constructor>(..)- Recommendedcom.example.MyClass <init>(..)- Also works
Both patterns match new MyClass(...) expressions when used with call-site recipes.
License
MIT
Available Tools
16 toolsdetect_project_typeB
Detect Java/TypeScript project type, build system, and configuration
Inputs: projectPath (required).
java_add_parameterA
Add a new parameter to a Java method or record constructor and update all call sites. For Java records, use methodName "" or the class name to target the constructor - the tool auto-detects records and updates both the record declaration AND all "new RecordName(...)" call sites (adding null as the new argument value).
Inputs: className (required), methodName (required), projectPath (required), parameterName (required), +5 more.
java_change_method_signatureA
Change a Java method or record constructor signature with multiple parameter operations (add, remove, reorder) in a single refactoring. More efficient than calling individual tools when making multiple changes. For Java records, use methodName "" or the class name - the tool auto-detects records and updates both the record declaration AND all "new RecordName(...)" call sites (adding null for new parameters).
Inputs: className (required), methodName (required), projectPath (required), dryRun, +5 more.
java_move_classA
Move Java class(es) to a different package and update all imports using OpenRewrite
Inputs: newPackage (required), oldPackage (required), projectPath (required), dryRun, +2 more.
java_remove_parameterA
Remove a parameter from a Java method or record constructor and update all call sites. For Java records, use methodName "" or the class name - the tool auto-detects records and updates both the record declaration AND all "new RecordName(...)" call sites.
Inputs: className (required), methodName (required), projectPath (required), parameterIndex (required), +3 more.
java_rename_classB
Rename a Java class and update all references using OpenRewrite
Inputs: projectPath (required), newFullyQualifiedName (required), oldFullyQualifiedName (required), dryRun, +1 more.
java_rename_fieldB
Rename a Java field and update all references using OpenRewrite
Inputs: className (required), projectPath (required), newFieldName (required), oldFieldName (required), +2 more.
java_rename_methodA
Rename a Java method and update all call sites using OpenRewrite
Inputs: className (required), projectPath (required), newMethodName (required), oldMethodName (required), +3 more.
java_reorder_parametersA
Reorder parameters in a Java method or record constructor and update all call sites. For Java records, use methodName "" or the class name - the tool auto-detects records and updates both the record declaration AND all "new RecordName(...)" call sites.
Inputs: className (required), methodName (required), projectPath (required), newParameterOrder (required), +3 more.
typescript_add_parameterB
Add a new parameter to a TypeScript/JavaScript function and update all call sites
Inputs: functionName (required), tsconfigPath (required), parameterName (required), parameterType (required), +4 more.
typescript_change_function_signatureA
Change a TypeScript/JavaScript function signature with multiple parameter operations (add, remove) in a single refactoring. More efficient than calling individual tools when making multiple changes.
Inputs: functionName (required), tsconfigPath (required), dryRun, filePath, +2 more.
typescript_extract_functionB
Extract a code block into a new function, automatically determining parameters and return values
Inputs: endLine (required), filePath (required), startLine (required), functionName (required), +2 more.
typescript_move_symbolA
Move a TypeScript/JavaScript symbol to a different file and update all imports
Inputs: symbolName (required), tsconfigPath (required), sourceFilePath (required), targetFilePath (required), +1 more.
typescript_remove_parameterB
Remove a parameter from a TypeScript/JavaScript function and update all call sites
Inputs: functionName (required), tsconfigPath (required), parameterName (required), dryRun, +1 more.
typescript_rename_fileB
Rename or move a TypeScript/JavaScript file and update all imports
Inputs: newFilePath (required), oldFilePath (required), tsconfigPath (required), dryRun.
typescript_rename_symbolB
Rename any TypeScript/JavaScript symbol (class, function, variable, interface, type) and update all references
Inputs: newName (required), symbolName (required), tsconfigPath (required), dryRun, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Each tool targets a specific language (Java or TypeScript) and a distinct refactoring operation, with no overlap between them. The language prefix and descriptive operation names make it easy for an agent to select the correct tool.
All tools follow a consistent 'language_verb_noun' pattern using snake_case (e.g., java_add_parameter, typescript_rename_symbol). The naming is uniform and predictable across all 16 tools.
With 16 tools covering two languages and a balanced set of common refactorings (add/remove/reorder parameters, rename, move, extract), the count is well-scoped for a refactoring server. It feels neither sparse nor overwhelming.
The tool set covers essential refactorings for both Java and TypeScript, including parameter manipulation, renaming, moving, and extraction. However, it lacks some common operations like extract variable, inline, or change return type, which are minor gaps.
Maintenance
Related MCP Connectors
Repository knowledge graph MCP server for codebase understanding and debugging.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server for static security analysis of Android source code
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that provides TypeScript development tools for automated refactoring and code analysis.1-
- AlicenseAqualityBmaintenanceA robust, language-agnostic Model Context Protocol (MCP) server that provides AI coding agents with the ability to edit files surgically via Abstract Syntax Trees (AST) instead of relying on token-heavy, brittle search-and-replace or diff operations.2811MIT
- AlicenseNot gradedqualityCmaintenanceA stateful, AST-aware MCP server for structured code review workflows. It enables iterative review sessions with AST-based context localization and provides structured feedback with verdicts and patch suggestions for JavaScript/TypeScript code.1GPL 3.0
- AlicenseAqualityDmaintenanceA 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.4029 npm3MIT