Which integrations are available for this server?

Enables TypeScript-aware file and directory moves within a project by leveraging a persistent tsserver instance to automatically update imports and maintain project integrity.

How do I use ts-refactor-mcp?

1. Click on "Install 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., "@ts-refactor-mcp move src/utils.ts to src/lib/utils.ts and update all imports" 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.

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 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

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 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:

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

ts-refactor-mcp

ts-refactor-mcp

What is this?

Installation

MCP Configuration

Available Tools

`moveFile`

`warmup`

How it Works

Performance

Requirements

Development

Setup

Run Tests

Build

Project Structure

Architecture Decisions

Persistent tsserver Process

Atomic Operations

Project's Own TypeScript

No State Management

Limitations

Future Enhancements

Contributing

License

Credits

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API