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

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

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:

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 - MCP protocol implementation
• TypeScript's tsserver - Language service API