# 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
```bash
npm install ts-refactor-mcp
```
Or install from source:
```bash
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):
```json
{
"mcpServers": {
"ts-refactor": {
"command": "npx",
"args": ["ts-refactor-mcp"]
}
}
}
```
Or use the built package:
```json
{
"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:**
```typescript
{
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):**
```typescript
{
applied: true;
filesModified: number;
moved: { from: string; to: string };
durationMs: number;
}
```
**Output (dry-run):**
```typescript
{
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:**
```typescript
// 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:**
```typescript
{
projectRoot: string; // Path to project root (where tsconfig.json is)
}
```
**Output:**
```typescript
{
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
1. **Persistent tsserver**: Keeps TypeScript's language server running between requests
2. **Atomic operations**: All import updates succeed or none do—no partial failures
3. **Uses project's TypeScript**: Spawns tsserver from your `node_modules/typescript`
4. **Battle-tested**: Uses the same `getEditsForFileRename` API 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
```bash
git clone https://github.com/schicks/ts-refactor-mcp.git
cd ts-refactor-mcp
npm install
```
### Run Tests
```bash
npm test # Run all tests
npm run test:watch # Watch mode
```
### Build
```bash
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 files
- `renameSymbol`: Rename a function/class across files
- `extractToFile`: Move a function to a new file
- Multi-root workspace support
- JavaScript-only project support
## Contributing
Pull requests welcome! Please:
1. Add tests for new functionality
2. Ensure all tests pass (`npm test`)
3. Follow existing code style
4. Update documentation
## License
MIT
## Credits
Built using:
- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) - MCP protocol implementation
- TypeScript's tsserver - Language service API
