MCP Refactor TypeScript

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.

Overview

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:

• Type-Aware Refactoring - Uses TypeScript's compiler for accurate, safe transformations

• Cross-File Support - Automatically updates imports, exports, and references across your entire codebase

• Safe - Preview mode for all destructive operations

• Detailed Reporting - See exactly what changed with file paths and line numbers

Related MCP server: TypeScript Tools MCP

Installation

Via npm (Recommended)

npm install -g mcp-refactor-typescript

The package will be globally installed and available as mcp-refactor-typescript.

From Source

git clone https://github.com/Stefan-Nitu/mcp-refactor-typescript.git
cd mcp-refactor-typescript
bun install
bun run build

⚠️ Requires Bun v1.3.8+ (development) and Node.js v18+ (runtime)

Quick Start

With Claude Desktop

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.

With MCP Inspector

Test the server interactively:

npx @modelcontextprotocol/inspector npx -y mcp-refactor-typescript

Or if installed globally:

npx @modelcontextprotocol/inspector mcp-refactor-typescript

Open http://localhost:5173 to explore available tools and test refactoring operations.

Available Tools (v2.0)

The server exposes 4 grouped tools with 15 operations total. Each tool has a specific domain and uses the operation parameter to specify the action.

Tool Groups

Operations Reference

📖 Detailed Documentation: See docs/OPERATIONS.md for full examples, best practices, and workflow patterns for each operation. Also available via MCP resource operations://catalog.

Response Format

All tools return structured JSON:

{
  "tool": "refactoring",
  "operation": "rename",
  "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"
  ]
}

Example Usage

Rename a symbol

{
  "tool": "refactoring",
  "params": {
    "operation": "rename",
    "filePath": "src/user.ts",
    "line": 10,
    "text": "getUser",
    "name": "getUserProfile",
    "preview": false
  }
}

Organize imports

{
  "tool": "code_quality",
  "params": {
    "operation": "organize_imports",
    "filePath": "src/index.ts"
  }
}

Extract function

{
  "tool": "refactoring",
  "params": {
    "operation": "extract_function",
    "filePath": "src/calculate.ts",
    "line": 15,
    "text": "x + y",
    "name": "addNumbers"
  }
}

Find references

{
  "tool": "workspace",
  "params": {
    "operation": "find_references",
    "filePath": "src/utils.ts",
    "line": 5,
    "text": "helper"
  }
}

Advanced Usage

Preview Mode

All destructive operations support preview mode:

{
  "filePath": "src/user.ts",
  "line": 10,
  "column": 5,
  "name": "getUserProfile",
  "preview": true
}

Returns what would change without modifying any files.

Entry Points for Cleanup

Required when deleteUnusedFiles: true - prevents accidental deletion with wrong defaults.

Safe mode (organize imports only) uses automatic defaults. Aggressive mode requires explicit entry points:

{
  "operation": "cleanup_codebase",
  "directory": "src",
  "deleteUnusedFiles": true,
  "entrypoints": [
    "src/main\\.ts$",       // Main entry point
    "src/cli\\.ts$",        // CLI entry
    ".*\\.test\\.ts$",      // Test files (auto-included in defaults)
    "scripts/.*\\.ts$"      // Script files
  ]
}

⚠️ Files not reachable from entry points will be DELETED. Always use preview: true first.

Batch Operations

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.

Development

Project Structure

mcp-refactor-typescript/
├── src/
│   ├── index.ts                     # MCP server entry point
│   ├── operation-name.ts            # Operation name enum (single source of truth)
│   ├── registry.ts                  # Operation registry
│   ├── operations/                  # Refactoring operations
│   │   ├── 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

Testing

# Run all tests
bun test

# Run specific test file
bun test --filter rename

# Run in watch mode
bun test --watch

# Type checking
bun run typecheck

# Linting
bun run lint

Test Coverage

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

Requirements

• Node.js >= 18.0.0

• TypeScript project with tsconfig.json

• Valid TypeScript/JavaScript files

• ESM module resolution (.js extensions in imports)

Your project does not need TypeScript installed — the server ships its own. When your project does have one, that copy is used instead so refactors match the language version you compile with. Projects on TypeScript 7 fall back to the bundled TypeScript 5, because TypeScript 7 no longer ships the tsserver this server drives.

Architecture

The server uses TypeScript's native tsserver for all refactoring operations:

1. Server Starts: Detects TypeScript files and starts tsserver

2. Indexing: TypeScript indexes project files (1-5 seconds for most projects)

3. Operations: Each tool sends protocol messages to tsserver

4. Results: Changes are returned as structured JSON with full details

Key Design Decisions:

• Direct tsserver communication (not VS Code LSP)

• One tsserver instance shared across all operations

• All logging to stderr (MCP protocol compliance)

See docs/ARCHITECTURE.md for detailed architecture information.

Documentation

• OPERATIONS.md - Complete operations reference with examples

• 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

Troubleshooting

TypeScript Server Not Starting

If operations fail with "TypeScript server not running":

1. Check that you have TypeScript files in your project

2. Verify tsconfig.json exists and is valid

3. Run restart_tsserver tool to force a restart

4. Check logs in stderr for detailed error messages

Incomplete References

If find_references or rename misses some usages:

1. Wait for TypeScript to finish indexing (check for "Project loaded" in logs)

2. Ensure all files are included in tsconfig.json

3. Fix any TypeScript errors that might prevent analysis

4. Use restart_tsserver after making project configuration changes

Import Paths Not Updating

If move_file doesn't update some imports:

1. Ensure imports use .js extensions (ESM requirement)

2. Check that moved file is part of TypeScript project

3. Verify tsconfig.json module resolution settings

4. Look for dynamic imports that TypeScript can't analyze

Contributing

1. Fork the repository

2. Create a feature branch

3. Write tests first (TDD approach)

4. Implement the feature

5. Ensure all tests pass (bun test)

6. Run linting (bun run lint)

7. Submit a pull request

License

MIT

Related Projects

• Model Context Protocol - MCP specification and documentation

• MCP TypeScript SDK - SDK used by this server

• MCP Servers - Official MCP server implementations