TypeScript Tools MCP

TypeScript Tools MCP

A Model Context Protocol (MCP) server that provides TypeScript development tools for automated refactoring and code analysis.

Features

1. File Move with Import Updates (move_typescript_file)

Move TypeScript files while automatically updating all import paths across your codebase.

Parameters:

• source: Source file path
• destination: Destination file path
• updateImports: Whether to update import paths (default: true)

Features:

• Smart Index File Handling: When moving index.ts files, imports are updated to reference the directory instead of the full path
  • ./utils/index → ./helpers (when moving utils/index.ts to helpers/index.ts)
• Automatic Path Resolution: Handles various file extensions (.ts, .tsx) and index file patterns
• Project-wide Updates: Scans and updates all TypeScript files in the project

2. Symbol Rename (rename_typescript_symbol)

Rename variables, functions, types, interfaces, or classes with automatic reference updates throughout the codebase.

Parameters:

• filePath: Path to the file containing the symbol
• oldName: Current name of the symbol
• newName: New name for the symbol
• type: Type of symbol ('variable' | 'function' | 'type' | 'interface' | 'class')

3. File/Folder Rename (rename_file_or_folder)

Rename a file or folder and automatically update all import/export paths that reference it throughout the codebase.

Parameters:

• sourcePath: Path to the file or folder to rename
• destinationPath: New path for the file or folder
• updateImports: Whether to update import/export paths (default: true)

Features:

• Cascade Import Updates: Automatically updates all imports and exports that reference the renamed file/folder
• Directory Support: Can rename entire directories with all contained files
• Path Style Preservation: Maintains import style (with/without extensions, with/without /index)
• Dynamic Import Support: Updates dynamic import() statements in addition to static imports
• Project-wide Scope: Scans and updates all TypeScript files in the project

4. Dependency Analysis (analyze_typescript_dependencies)

Analyze file dependencies in both directions to understand code relationships.

Parameters:

• filePath: Path to the TypeScript file to analyze
• direction: Direction of analysis ('upstream' | 'downstream' | 'both')
  • upstream: Files that import the target file
  • downstream: Files that the target file imports
• includeTypes: Whether to include type-only imports (default: true)

5. Package.json Validation (validate_package_json)

Validate package.json configuration for type resolution, file existence, and proper exports setup.

Parameters:

• packageJsonPath: Path to the package.json file to validate
• checkTypes: Whether to check TypeScript type resolution (default: true)
• checkExports: Whether to validate exports field (default: true)
• checkTypesVersions: Whether to validate typesVersions field (default: true)

Validation includes:

• File Resolution: Validates that main, module, browser, types, bin fields point to existing files
• Type Resolution: Checks if types are properly configured and accessible
• Exports Validation: Ensures all export paths resolve to existing files
• TypesVersions: Validates typesVersions mappings for different TypeScript versions

6. Import Optimization (optimize_imports)

Optimize TypeScript import statements by removing unused imports, consolidating duplicates, separating types, and optimizing paths.

Parameters:

• filePath: Path to the TypeScript file to optimize
• removeUnused: Whether to remove unused imports (default: true)
• optimizeIndexPaths: Whether to remove /index suffixes from import paths (default: true)
• consolidateImports: Whether to consolidate multiple imports from the same module (default: true)
• separateTypeImports: Whether to separate type and value imports using import type (default: true)

Optimizations include:

• Unused Import Removal: Removes unused named imports and entire unused import statements
• Index Path Optimization: Converts ./utils/index to ./utils automatically
• Import Consolidation: Merges multiple import statements from the same module
• Type Import Separation: Separates type imports using import type { Type } syntax for better tree-shaking

7. Conditional Optimization (optimize_conditionals)

Optimize conditional statements by converting if-else chains to switch statements, flattening nested conditions, and simplifying boolean expressions.

Parameters:

• filePath: Path to the TypeScript file to optimize
• convertToSwitch: Whether to convert if-else chains to switch statements (default: true)
• flattenNestedConditions: Whether to flatten nested if statements (default: true)
• optimizeBoolean: Whether to optimize boolean expressions (default: true)

Optimizations include:

• If-Else to Switch: Converts if-else chains with 3+ equality comparisons to switch statements
• Nested Condition Flattening: Combines nested if statements using logical operators
• Boolean Expression Simplification: Removes redundant boolean comparisons and double negations

8. Dependency Visualization (visualize_dependencies)

Generate dependency graph visualization with circular dependency detection and module boundary analysis.

Parameters:

• rootPath: Root path of the project to analyze
• format: Output format ('mermaid' | 'json' | 'dot', default: 'mermaid')
• includeNodeModules: Whether to include node_modules in analysis (default: false)
• maxDepth: Maximum directory depth to analyze (default: 10)
• detectCircular: Whether to detect circular dependencies (default: true)

Features include:

• Dependency Graph Generation: Creates visual dependency graphs in Mermaid, DOT, or JSON format
• Circular Dependency Detection: Identifies and reports circular dependencies with severity levels
• Module Boundary Analysis: Analyzes import/export relationships and module structure
• Statistics: Provides metrics on file count, import count, dependency depth, and circular dependencies

9. Deletion Safety Check (check_deletable)

Analyze if a TypeScript file can be safely deleted by detecting all references to it throughout the codebase, including complex patterns like wildcard imports and re-exports.

Parameters:

• filePath: Path to the TypeScript file to check for deletion safety
• includeTypes: Whether to include type-only imports in analysis (default: true)
• generateTests: Whether to generate a [name].spec.ts test file in the same folder (default: false)
• createMocks: Whether to create __mocks__ folder structure with mock files (default: false)

Features include:

• Comprehensive Reference Detection: Finds all imports, exports, and dynamic imports that reference the target file
• Wildcard Import/Export Support: Detects export * from './file' and namespace imports like import * as Module from './file'
• Type-Only Import Handling: Can optionally exclude or include type-only imports in the analysis
• Test File Generation: Generates deletion safety test files with detailed analysis and usage simulation
• Mock Structure Creation: Creates __mocks__ folder with mock implementations for testing deletion scenarios
• Two-Phase Analysis: Separates analysis phase from execution phase for better control and testing

Installation

Installation

Command Line Usage

After building, you can use the ts-tools command directly:

Configuration

For Claude Desktop

1. Generate configuration snippet:

2. Automatic installation (macOS/Windows/Linux):

3. Manual installation: Add the generated configuration from mcp-config.json to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

Development

Requirements

• Bun runtime
• TypeScript project with tsconfig.json
• Node.js compatible environment