js-tools — TypeScript Refactoring via MCP

Programmatic TypeScript refactoring tools that replace manual mcp_edit workflows. These tools understand the AST, update all imports project-wide, and support dry-run previews.

Always prefer these over manual file edits for any TypeScript structural change.

Smell-to-Tool Routing

When you detect a code smell, use this table to pick the right tool instead of reaching for mcp_edit:

Smell	Tool	Why not manual?
Same function/component in N files	typescript_extract_shared	Removes all copies, creates shared module, updates imports across project
Function/export belongs in a different file	typescript_move_symbols	Moves code + rewrites every import automatically
File over 300-400 lines, mixed concerns	typescript_split_file	Splits by strategy, creates barrel, updates imports
Need to rename a variable/function/class	typescript_rename	Finds re-exports, type-only usages, barrel references that grep misses
Messy imports after refactoring	typescript_organize_imports	Removes unused, sorts, groups in one pass
Directory needs an index.ts	typescript_create_barrel	Scans exports, separates types, handles default exports
Class method too complex / needs testing	typescript_extract_method	Transforms this references to instance param, preserves async/generics
Need to check what breaks before a change	typescript_find_references	Catches re-exports and inherited methods that grep misses
What type does TypeScript infer here?	typescript_get_type	Like IDE hover, accessible programmatically
Where is this symbol actually defined?	typescript_go_to_definition	Resolves through barrels and re-exports to actual source
What classes implement this interface?	typescript_find_implementations	Distinguishes declarations from implementations (grep cannot)
What methods does this class have?	typescript_list_members	Returns typed signatures with line:column for each member
What does this method depend on via this?	typescript_analyze_deps	Dependency tree with circular ref detection
Unsure which tool to use	typescript_suggest_refactor	Describe smell in English, get tool + pre-filled args
TypeScript errors / does it compile?	typescript_check	Structured errors with file:line:column, filterable by error code

Key Principle: dry_run First

Every destructive tool defaults to dry_run=true. Always preview, then apply:

1. Call tool with dry_run=true → review changes
2. If good, call again with dry_run=false → apply

Auto-Detection

All tools auto-detect project_root (walks up to find tsconfig.json) and tsconfig when omitted. You only need to pass file-specific parameters — the tools figure out the project context.

Common Workflows

Deduplicate code across files

1. typescript_extract_shared(symbol_name, source_files, target_file)
2. typescript_organize_imports on each modified file
3. typescript_check to verify

Break up a large file

1. typescript_split_file(source_file, strategy="group-by-kind")
2. typescript_create_barrel(directory) if needed
3. typescript_check to verify

Move exports between files

1. typescript_find_references first (blast radius check)
2. typescript_move_symbols(source_file, symbol_names, target_file)
3. typescript_organize_imports on affected files
4. typescript_check to verify

Safe rename

1. typescript_find_references (see all usages)
2. typescript_rename(file, line, column, new_name, dry_run=true)
3. Review preview, then dry_run=false

Extract and reorganize a class

1. typescript_list_members(file, class_name) → see structure
2. typescript_analyze_deps(file, class_name, method_name) → see coupling
3. typescript_extract_method(source_file, class_name, method_name, target_file)

Split Strategies

typescript_split_file supports three strategies:

Strategy	Creates	Best for
one-per-export	One file per export (groups dependents)	Utility files with independent exports
group-by-kind	functions.ts, types.ts, classes.ts	Mixed-concern files
group-by-prefix	user-utils.ts, order-utils.ts	Prefixed naming conventions

Barrel Export Styles

typescript_create_barrel supports three styles:

Style	Output	Auto-selected when
named	export { foo, bar } from './file.js'	5 or fewer exports
star	export * from './file.js'	More than 5 exports
auto	Chooses named or star	Default behavior

Reference Files

File	Contents
references/tool-catalog.md	Every tool's parameters, edge cases, and error handling
references/refactoring-workflows.md	Multi-step workflow recipes with real examples