ts-refactor-mcp
TypeScript-aware file refactoring for AI agents via the Model Context Protocol (MCP).
What is this?
An MCP server that enables AI coding agents to move TypeScript files while automatically updating all imports. When you move a file in VS Code, TypeScript's language server updates every import automatically. This tool exposes that same capability to AI agents through MCP.
The problem it solves: AI agents can move files, but they break imports. They either miss updates or waste tokens fixing them manually. This server does it correctly in one atomic operation.
Installation
npm install ts-refactor-mcp
Or install from source:
git clone https://github.com/schicks/ts-refactor-mcp.git
cd ts-refactor-mcp
npm install
npm run build
MCP Configuration
Add to your MCP client configuration (e.g., Claude Desktop):
{
"mcpServers": {
"ts-refactor": {
"command": "npx",
"args": ["ts-refactor-mcp"]
}
}
}
Or use the built package:
{
"mcpServers": {
"ts-refactor": {
"command": "node",
"args": ["/path/to/ts-refactor-mcp/dist/index.js"]
}
}
}
Available Tools
moveFile
Move a TypeScript file and update all imports automatically.
Input:
{
projectRoot: string; // Path to project root (where tsconfig.json is)
oldPath: string; // Current file path
newPath: string; // New file path
dryRun?: boolean; // If true, preview changes without applying
}
Output (when applied):
{
applied: true;
filesModified: number;
moved: { from: string; to: string };
durationMs: number;
}
Output (dry-run):
{
applied: false;
edits: Array<{
filePath: string;
textEdits: Array<{
start: { line: number; offset: number };
end: { line: number; offset: number };
newText: string;
}>;
}>;
wouldMove: { from: string; to: string };
filesModified: number;
}
Example:
// Move a file and update all imports
{
"projectRoot": "/home/user/my-project",
"oldPath": "/home/user/my-project/src/utils/helper.ts",
"newPath": "/home/user/my-project/src/lib/helper.ts",
"dryRun": false
}
// Preview changes first
{
"projectRoot": "/home/user/my-project",
"oldPath": "/home/user/my-project/src/utils/helper.ts",
"newPath": "/home/user/my-project/src/lib/helper.ts",
"dryRun": true
}
warmup
Pre-load a TypeScript project to speed up subsequent operations.
Input:
{
projectRoot: string; // Path to project root (where tsconfig.json is)
}
Output:
{
status: 'ready';
durationMs: number;
}
Why use this: First operation on a project takes 5-30 seconds while TypeScript loads. Call warmup at session start to pay this cost upfront. Subsequent operations complete in 10-100ms.
How it Works
- Persistent tsserver: Keeps TypeScript's language server running between requests
- Atomic operations: All import updates succeed or none do—no partial failures
- Uses project's TypeScript: Spawns tsserver from your
node_modules/typescript - Battle-tested: Uses the same
getEditsForFileRenameAPI that VS Code uses
Agent calls moveFile
↓
MCP Server
↓
tsserver.getEditsForFileRename() ← Same API VS Code uses
↓
Apply all edits atomically
↓
Move the file
↓
Return success
Performance
- Initial warmup: 5-30 seconds (large projects)
- Subsequent moves: 10-100ms
- Memory: Persistent tsserver process (~100-500MB depending on project size)
Requirements
- Node.js >= 18.0.0
- TypeScript project with
tsconfig.json - TypeScript installed in project's
node_modules
Development
Setup
git clone https://github.com/schicks/ts-refactor-mcp.git
cd ts-refactor-mcp
npm install
Run Tests
npm test # Run all tests
npm run test:watch # Watch mode
Build
npm run build # Compile TypeScript
npm run watch # Watch mode
Project Structure
src/
├── tsserver-client/ # Wrapper around tsserver process
├── edit-applier/ # Applies text edits to filesystem
├── mcp-server/ # MCP protocol implementation
└── types/ # Shared TypeScript types
__tests__/
├── tsserver-client/ # Unit tests for tsserver wrapper
├── edit-applier/ # Unit tests for edit applier
├── mcp-server/ # Integration tests for MCP server
├── acceptance.test.ts # End-to-end acceptance test
└── fixtures/ # Test fixtures
Architecture Decisions
Persistent tsserver Process
We keep tsserver running between requests. First request pays startup cost (5-30s), subsequent requests are fast (10-100ms). Without persistence, every move would reload the entire project.
Atomic Operations
All edits and the file move happen atomically. Either everything succeeds or nothing changes. This prevents broken intermediate states.
Project's Own TypeScript
We use the TypeScript version from your project's node_modules, not a global install. This ensures refactoring behavior matches your project's TypeScript version.
No State Management
When files change outside our server, we don't track it. If tsserver gets out of sync, call warmup again. Trying to maintain perfect sync is complex and unnecessary—tsserver handles file watching internally.
Limitations
- TypeScript only: Requires
tsconfig.json(JavaScript-only projects not supported) - One project at a time: One tsserver per tsconfig
- No directory moves: Currently only supports single file moves
- Cold starts: MCP server restart requires project warmup again
Future Enhancements
Potential future additions (not currently implemented):
moveDirectory: Move entire directories with all filesrenameSymbol: Rename a function/class across filesextractToFile: Move a function to a new file- Multi-root workspace support
- JavaScript-only project support
Contributing
Pull requests welcome! Please:
- Add tests for new functionality
- Ensure all tests pass (
npm test) - Follow existing code style
- Update documentation
License
MIT
Credits
Built using:
- @modelcontextprotocol/sdk - MCP protocol implementation
- TypeScript's tsserver - Language service API