A Model Context Protocol (MCP) server that provides comprehensive TypeScript/JavaScript refactoring capabilities powered by the TypeScript compiler. Perform complex code transformations with compiler-grade accuracy and type-safety.
MCP Refactor TypeScript exposes TypeScript's powerful refactoring engine through the Model Context Protocol, enabling AI assistants and other MCP clients to perform sophisticated code transformations that would be impossible or error-prone to do manually.
Key Features:
- ✅ 15 Production-Ready Refactoring Tools - All operations fully implemented and tested
- 🎯 Type-Aware Refactoring - Uses TypeScript's compiler for accurate, safe transformations
- 🚀 Cross-File Support - Automatically updates imports, exports, and references across your entire codebase
- ⚡ Fast - Operations complete in <2s even for large codebases
- 🔒 Safe - Preview mode for all destructive operations
- 📝 Detailed Reporting - See exactly what changed with file paths and line numbers
npm install -g mcp-refactor-typescriptThe package will be globally installed and available as mcp-refactor-typescript.
git clone https://github.com/Stefan-Nitu/mcp-refactor-typescript.git
cd mcp-refactor-typescript
npm install
npm run build
⚠️ Requires Node.js v18.x or higher
Add to your Claude Desktop 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"]
}
}
}Or if installed globally:
{
"mcpServers": {
"mcp-refactor-typescript": {
"command": "mcp-refactor-typescript"
}
}
}Restart Claude Desktop and you'll have access to all refactoring tools.
Test the server interactively:
npx @modelcontextprotocol/inspector npx -y mcp-refactor-typescriptOr if installed globally:
npx @modelcontextprotocol/inspector mcp-refactor-typescriptOpen http://localhost:5173 to explore available tools and test refactoring operations.
All tools return JSON responses with detailed information about what changed:
| Tool | Description | Key Features |
|---|---|---|
| rename | Rename symbols across all files | Type-aware, updates imports/exports |
| move_file | Move files and update imports | Zero manual import fixing |
| batch_move_files | Move multiple files at once | Atomic operation, perfect for restructuring |
| organize_imports | Sort and remove unused imports | Preserves side-effects, type-only imports |
| fix_all | Auto-fix TypeScript errors | Compiler-grade fixes |
| remove_unused | Remove unused code | Safe, distinguishes side-effect code |
| find_references | Find all usages | Catches dynamic imports, JSDoc |
| extract_function | Extract code to function | Auto-detects parameters, return type |
| extract_constant | Extract literals to constants | Auto-detects optimal scope |
| extract_variable | Extract expressions to variables | Type inference, const/let detection |
| inline_variable | Inline variable values | Type-safe, handles scope correctly |
| infer_return_type | Add return type annotations | Perfect for complex types |
| refactor_module | Complete module refactoring | Move + organize + fix in one step |
| cleanup_codebase | Clean entire codebase | Remove unused exports + organize imports |
| restart_tsserver | Restart TypeScript server | Refresh after config changes |
All tools return structured JSON:
{
"tool": "operation_name",
"status": "success" | "error",
"message": "Human-readable summary",
"data": {
"filesChanged": ["list", "of", "modified", "files"],
"changes": [
{
"file": "filename.ts",
"path": "/absolute/path/filename.ts",
"edits": [
{
"line": 42,
"column": 10,
"old": "oldText",
"new": "newText"
}
]
}
]
},
"preview": { // Only when preview: true
"filesAffected": 5,
"estimatedTime": "< 1s",
"command": "Run again with preview: false to apply changes"
},
"nextActions": [ // Suggested follow-up operations
"organize_imports - Clean up import statements",
"fix_all - Fix any type errors"
]
}All destructive operations support preview mode:
{
"filePath": "src/user.ts",
"line": 10,
"column": 5,
"newName": "getUserProfile",
"preview": true
}Returns what would change without modifying any files.
Control what's considered "unused" when cleaning codebases:
{
"directory": "src",
"entrypoints": [
"main\\.ts$", // Main entry point
".*\\.test\\.ts$", // Test files
"scripts/.*\\.ts$" // Script files
]
}Anything not reachable from these entry points will be removed.
Move multiple files atomically:
{
"files": [
"src/utils/string.ts",
"src/utils/number.ts",
"src/utils/array.ts"
],
"targetFolder": "src/lib"
}All imports update automatically, all files move together or not at all.
mcp-refactor-typescript/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── operations/ # Refactoring operations
│ │ ├── registry.ts # Operation registry
│ │ ├── rename.ts # Rename operation
│ │ ├── move-file.ts # Move file operation
│ │ ├── extract-function.ts # Extract function operation
│ │ └── ... # Other operations
│ ├── language-servers/
│ │ └── typescript/ # TypeScript server client
│ │ ├── tsserver-client.ts # Direct tsserver communication
│ │ └── tsserver-types.ts # Protocol type definitions
│ └── utils/
│ ├── logger.ts # Pino logger (stderr only)
│ └── validation-error.ts # Zod error formatting
├── test/
│ └── fixtures/ # Test TypeScript files
└── docs/ # Architecture & testing docs
# Run all tests
npm test
# Run specific test file
npm test -- --run rename
# Run in watch mode
npm run test:watch
# Type checking
npm run typecheck
# Linting
npm run lint- 97 integration tests covering all operations
- Unit tests for validation, error handling, and edge cases
- E2E tests for server startup and initialization
- All tests use real TypeScript compiler (no mocks)
- Node.js >= 18.0.0
- TypeScript project with
tsconfig.json - Valid TypeScript/JavaScript files
- ESM module resolution (
.jsextensions in imports)
The server uses TypeScript's native tsserver for all refactoring operations:
- Server Starts: Detects TypeScript files and starts
tsserver - Indexing: TypeScript indexes project files (1-5 seconds for most projects)
- Operations: Each tool sends protocol messages to
tsserver - Results: Changes are returned as structured JSON with full details
Key Design Decisions:
- Direct
tsservercommunication (not VS Code LSP) - One
tsserverinstance shared across all operations - All logging to stderr (MCP protocol compliance)
See docs/ARCHITECTURE.md for detailed architecture information.
- ARCHITECTURE.md - MCP server architecture and patterns
- TESTING.md - Testing strategies and patterns
- TESTING-NOTES.md - Test workspace setup requirements
- ERROR-HANDLING.md - Error handling patterns
- MCP-TYPESCRIPT-README.md - TypeScript SDK reference
If operations fail with "TypeScript server not running":
- Check that you have TypeScript files in your project
- Verify
tsconfig.jsonexists and is valid - Run
restart_tsservertool to force a restart - Check logs in stderr for detailed error messages
If find_references or rename misses some usages:
- Wait for TypeScript to finish indexing (check for "Project loaded" in logs)
- Ensure all files are included in
tsconfig.json - Fix any TypeScript errors that might prevent analysis
- Use
restart_tsserverafter making project configuration changes
If move_file doesn't update some imports:
- Ensure imports use
.jsextensions (ESM requirement) - Check that moved file is part of TypeScript project
- Verify
tsconfig.jsonmodule resolution settings - Look for dynamic imports that TypeScript can't analyze
- Fork the repository
- Create a feature branch
- Write tests first (TDD approach)
- Implement the feature
- Ensure all tests pass (
npm test) - Run linting (
npm run lint) - Submit a pull request
See CLAUDE.md for development guidelines.
MIT
- Model Context Protocol - MCP specification and documentation
- MCP TypeScript SDK - SDK used by this server
- MCP Servers - Official MCP server implementations