ts-mcp-server

A lightweight Model Context Protocol (MCP) server for TypeScript and JavaScript refactoring and code intelligence. Every tool maps directly to a tsserver protocol command — the output is the raw, unmodified response from TypeScript's compiler. Rename symbols, extract functions, move declarations between files, reorganize imports, navigate type hierarchies, explore call graphs, search symbols across your workspace, map AI-generated code into the right locations, discover which error codes have automatic fixes, and more — with every import, require, re-export, and reference updated automatically across your entire codebase.

Why

AI coding assistants can read and write code, but they struggle with structural changes that ripple across many files. Renaming a function, extracting a helper, moving a React component, or reorganizing a folder means updating every reference and import that touches it. Miss one and the build breaks.

ts-mcp-server gives any MCP-compatible client — VS Code Copilot, Claude Desktop, Cursor, Windsurf, Continue, and others — the ability to perform these refactors correctly and completely, using TypeScript's own compiler infrastructure.

Features

• 40 tools — each a 1:1 mapping to a native tsserver protocol command

Refactoring (14 tools)

• Rename symbols — variables, functions, classes, types, properties, interfaces, enums — all references updated across every file
• Rename / move files and folders — all import paths updated automatically
• Extract function — extract a code range into a new function with auto-detected parameters and return type
• Extract constant — extract an expression into a named constant with inferred type
• Extract type — extract an inline type annotation into a named type alias
• Infer return type — add an explicit return type annotation to a function, inferred by TypeScript
• Move symbol — move top-level declarations to another file, all imports rewired automatically
• Inline variable — replace all references with the variable's initializer and delete the declaration
• Organize imports — sort, coalesce, and remove unused imports
• Format — format a range of code according to TypeScript's formatting rules
• Get code fixes — retrieve available auto-fixes for specific diagnostics (missing imports, type mismatches, etc.)
• Get combined code fix — apply a fix-all action for a specific error code across a file
• Get diagnostics — retrieve type errors, warnings, and suggestions for any file
• Find all references — locate every usage of a symbol across the project
• Map code — map AI-generated code snippets into a file, replacing matching declarations by name or appending new ones
• Get supported code fixes — list every error code that has an available automatic fix, optionally scoped to a project

Code Intelligence (24 tools)

• Quick info — full type information, documentation, and JSDoc tags for any symbol (hover info)
• Navigation tree — complete hierarchical structure of a file (all declarations and their nesting)
• Go to definition — jump to where a symbol is declared
• Definition and bound span — like definition, but also returns the text span of the queried symbol
• Find source definition — navigate to actual TypeScript source instead of .d.ts declaration files
• Go to type definition — jump to the type's definition, not the variable's declaration
• Go to implementation — find concrete implementations of an interface or abstract class
• Navigate to symbol — workspace-wide symbol search by name
• File references — find every file that imports a given file (reverse dependency graph)
• Prepare call hierarchy — get call hierarchy entry point for a function/method
• Incoming calls — find all callers of a function ("who calls this?")
• Outgoing calls — find all callees of a function ("what does this call?")
• Project info — get tsconfig.json path, file list, and language service status
• Completion info — autocomplete suggestions at a position
• Completion entry details — full documentation and type signature for a completion item
• Signature help — function parameter info and overloads at a call site
• Document highlights — all occurrences of a symbol within a file, with read/write distinction
• Get applicable refactors — discover what refactorings are available at a position or selection
• Selection range — get semantically meaningful selection ranges for smart expand/shrink selection
• Move to refactoring suggestions — get suggested target files when moving a symbol
• Doc comment template — generate JSDoc comment template for a function/method
• Outlining spans — get foldable regions in a file
• Inlay hints — get inlay hints (parameter names, inferred types) for a range
• TODO comments — find all TODO/FIXME/HACK comments in a file

Design Principles

• Pure tsserver output — every tool returns the raw, unmodified tsserver response as JSON
• Preview mode — see exactly what would change before applying anything
• Automatic project discovery — tsconfig.json is detected automatically; no configuration needed
• Multi-project support — monorepos, project references, and composite builds work out of the box
• Cross-platform — Windows, macOS, and Linux

How It Works

Under the hood, ts-mcp-server communicates with TypeScript's tsserver over Node IPC — the same protocol that VS Code uses. Every tool is a thin wrapper that:

1. Passes your input directly to a tsserver protocol command
2. Returns the raw response — no formatting, no grouping, no filtering

Refactoring tools:

Tool	tsserver command(s)
rename	rename-full → renameLocations-full
renameFileOrDirectory	getEditsForFileRename-full
references	references
getDiagnostics	semanticDiagnosticsSync + suggestionDiagnosticsSync
organizeImports	organizeImports-full
getCodeFixes	getCodeFixes
extractFunction	getEditsForRefactor-full
extractConstant	getEditsForRefactor-full
extractType	getEditsForRefactor-full
inferReturnType	getEditsForRefactor-full
moveSymbol	getEditsForRefactor-full
inlineVariable	getEditsForRefactor-full
format	format
mapCode	mapCode
getSupportedCodeFixes	getSupportedCodeFixes

Code intelligence tools:

Tool	tsserver command
quickinfo	quickinfo
navtree	navtree
definition	definition
typeDefinition	typeDefinition
implementation	implementation
navto	navto
fileReferences	fileReferences
prepareCallHierarchy	prepareCallHierarchy
provideCallHierarchyIncomingCalls	provideCallHierarchyIncomingCalls
provideCallHierarchyOutgoingCalls	provideCallHierarchyOutgoingCalls
projectInfo	projectInfo
completionInfo	completionInfo
completionEntryDetails	completionEntryDetails
signatureHelp	signatureHelp
documentHighlights	documentHighlights
getApplicableRefactors	getApplicableRefactors
getCombinedCodeFix	getCombinedCodeFix
getOutliningSpans	getOutliningSpans
todoComments	todoComments
docCommentTemplate	docCommentTemplate
provideInlayHints	provideInlayHints
definitionAndBoundSpan	definitionAndBoundSpan
findSourceDefinition	findSourceDefinition
selectionRange	selectionRange
getMoveToRefactoringFileSuggestions	getMoveToRefactoringFileSuggestions

There is no regex, no custom path resolution, no heuristics, no output formatting. The TypeScript compiler does all the work.

Quick Start

Install

npx ts-mcp-server

Configure Your MCP Client

Add ts-mcp-server to your client's MCP configuration.

VS Code (.vscode/mcp.json):

{
  "servers": {
    "ts-mcp-server": {
      "command": "npx",
      "args": ["ts-mcp-server"]
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "ts-mcp-server": {
      "command": "npx",
      "args": ["ts-mcp-server"]
    }
  }
}

Cursor, Windsurf, Continue — follow each client's MCP server documentation using the same npx ts-mcp-server command.

Disabling Individual Tools

Every tool can be disabled individually by setting its name to "false" in the env block of your MCP configuration. Tools are enabled by default; only tools explicitly set to "false" are skipped at startup.

VS Code (.vscode/mcp.json):

{
  "servers": {
    "ts-mcp-server": {
      "command": "npx",
      "args": ["ts-mcp-server"],
      "env": {
        "todoComments": "false",
        "getOutliningSpans": "false",
        "docCommentTemplate": "false"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "ts-mcp-server": {
      "command": "npx",
      "args": ["ts-mcp-server"],
      "env": {
        "todoComments": "false",
        "getOutliningSpans": "false",
        "docCommentTemplate": "false"
      }
    }
  }
}

The tool name in env must exactly match the tool name as listed in the Tool Reference below (e.g., "quickinfo", "getDiagnostics", "extractFunction"). Any other value — including omitting the key entirely — leaves the tool enabled.

Tool Reference

rename

Rename a TypeScript/JavaScript symbol and update all references across the project.

Parameter	Type	Required	Description
file	string	✅	File path containing the symbol (absolute or relative to cwd)
line	number	✅	1-based line number where the symbol appears
offset	number	✅	1-based character offset on the line
newName	string	✅	New name for the symbol
preview	boolean	✅	If true, return changes without applying

Examples:

rename  file="src/utils/helpers.ts"  line=5  offset=17  newName="formatCurrency"
rename  file="src/components/Button.tsx"  line=10  offset=17  newName="PrimaryButton"
rename  file="src/types.ts"  line=3  offset=11  newName="UserProfile"
rename  file="src/utils/helpers.ts"  line=5  offset=17  newName="formatCurrency"  preview=true

---

renameFileOrDirectory

Rename or move a TypeScript/JavaScript file or directory and update all import paths across the project.

Parameter	Type	Required	Description
from	string	✅	Current file or directory path (absolute or relative to cwd)
to	string	✅	New file or directory path (absolute or relative to cwd)
preview	boolean	✅	If true, return changes without applying

Examples:

renameFileOrDirectory  from="src/utils/helpers.ts"  to="src/utils/string-helpers.ts"
renameFileOrDirectory  from="src/Button.tsx"  to="src/components/ui/Button.tsx"
renameFileOrDirectory  from="src/components/primitives"  to="src/components/ui"
renameFileOrDirectory  from="src/old-name.ts"  to="src/new-name.ts"  preview=true

---

references

Find all usages of a symbol across the project.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
line	number	✅	1-based line number where the symbol appears
offset	number	✅	1-based character offset on the line

Examples:

references  file="src/utils/helpers.ts"  line=5  offset=17
references  file="src/types.ts"  line=3  offset=11

---

getDiagnostics

Get all errors, warnings, and suggestions for a file. Returns semantic diagnostics and suggestion diagnostics as separate arrays.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)

Examples:

getDiagnostics  file="src/utils/helpers.ts"
getDiagnostics  file="src/components/Button.tsx"

Note: Unused-code diagnostics (unused variables, unused imports) only appear if your tsconfig.json has noUnusedLocals and/or noUnusedParameters enabled.

---

organizeImports

Sort, coalesce, and remove unused imports in a file.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
preview	boolean	✅	If true, return changes without applying

Examples:

organizeImports  file="src/utils/helpers.ts"
organizeImports  file="src/components/Button.tsx"  preview=true

---

getCodeFixes

Get available code fixes for specific error codes at a range in a file. Use getDiagnostics first to discover error codes and ranges, then pass them here.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
startLine	number	✅	1-based start line of the diagnostic range
startOffset	number	✅	1-based start character offset
endLine	number	✅	1-based end line of the diagnostic range
endOffset	number	✅	1-based end character offset
errorCodes	number[]	✅	Diagnostic error codes to get fixes for

Examples:

# Get fixes for a "Cannot find name" error (code 2304) at line 10
getCodeFixes  file="src/app.ts"  startLine=10  startOffset=1  endLine=10  endOffset=20  errorCodes=[2304]

# Get fixes for multiple error codes
getCodeFixes  file="src/app.ts"  startLine=5  startOffset=1  endLine=5  endOffset=30  errorCodes=[2304, 2552]

---

getCombinedCodeFix

Get a combined code fix that applies all instances of a fix across a file in one action. Returns the full set of file edits as a CombinedCodeActions response. Use getCodeFixes first to discover available fixId values, then pass the fixId here to get the combined fix for the whole file.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
fixId	string	✅	The fixId from a code fix (e.g., "fixMissingImport", "unusedIdentifier", "inferFromUsage")

Examples:

# Get the combined "add all missing imports" fix for a file
getCombinedCodeFix  file="src/app.ts"  fixId="fixMissingImport"

# Get the combined "remove all unused variables" fix for a file
getCombinedCodeFix  file="src/app.ts"  fixId="unusedIdentifier"

---

extractFunction

Extract a selected code range into a new function. TypeScript auto-detects parameters and return type. The response includes renameFilename / renameLocation so you can follow up with rename to give the function a meaningful name.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
startLine	number	✅	1-based start line of the selection
startOffset	number	✅	1-based start character offset
endLine	number	✅	1-based end line of the selection
endOffset	number	✅	1-based end character offset
preview	boolean	✅	If true, return changes without applying

Examples:

# Extract lines 10-15 into a function
extractFunction  file="src/app.ts"  startLine=10  startOffset=1  endLine=15  endOffset=1

# Preview the extraction
extractFunction  file="src/app.ts"  startLine=10  startOffset=1  endLine=15  endOffset=1  preview=true

---

extractConstant

Extract a selected expression into a named constant. TypeScript infers the type. The response includes renameFilename / renameLocation so you can follow up with rename to give the constant a meaningful name.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
startLine	number	✅	1-based start line of the expression
startOffset	number	✅	1-based start character offset
endLine	number	✅	1-based end line of the expression
endOffset	number	✅	1-based end character offset
preview	boolean	✅	If true, return changes without applying

Examples:

# Extract an expression into a constant
extractConstant  file="src/app.ts"  startLine=8  startOffset=12  endLine=8  endOffset=35

# Preview the extraction
extractConstant  file="src/app.ts"  startLine=8  startOffset=12  endLine=8  endOffset=35  preview=true

---

moveSymbol

Move top-level declarations (functions, classes, types, constants) to another file. All imports across the project are rewired automatically. If the target file doesn't exist, tsserver creates it.

Parameter	Type	Required	Description
file	string	✅	Source file path (absolute or relative to cwd)
startLine	number	✅	1-based start line of the declaration
startOffset	number	✅	1-based start character offset
endLine	number	✅	1-based end line of the declaration
endOffset	number	✅	1-based end character offset
targetFile	string	✅	Destination file path (absolute or relative to cwd)
preview	boolean	✅	If true, return changes without applying

Examples:

# Move a function to a utility file
moveSymbol  file="src/app.ts"  startLine=20  startOffset=1  endLine=35  endOffset=2  targetFile="src/utils/helpers.ts"

# Move a type to a shared types file
moveSymbol  file="src/components/Button.tsx"  startLine=1  startOffset=1  endLine=5  endOffset=2  targetFile="src/types.ts"

# Preview the move
moveSymbol  file="src/app.ts"  startLine=20  startOffset=1  endLine=35  endOffset=2  targetFile="src/utils/helpers.ts"  preview=true

---

inlineVariable

Inline a variable — replace all references with the variable's initializer and delete the declaration. Position must be on the variable name in its declaration or any usage.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
line	number	✅	1-based line number of the variable
offset	number	✅	1-based character offset on the line
preview	boolean	✅	If true, return changes without applying

Examples:

# Inline a variable
inlineVariable  file="src/app.ts"  line=12  offset=7

# Preview the inlining
inlineVariable  file="src/app.ts"  line=12  offset=7  preview=true

---

extractType

Extract an inline type annotation into a named type alias. Select the type span to extract. The response includes renameFilename / renameLocation so you can follow up with rename to give the type a meaningful name.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
startLine	number	✅	1-based start line of the type span
startOffset	number	✅	1-based start character offset
endLine	number	✅	1-based end line of the type span
endOffset	number	✅	1-based end character offset
preview	boolean	✅	If true, return changes without applying

Examples:

# Extract an inline object type into a type alias
# Given: function process(user: { id: number; name: string }) { ... }
# Select the span "{ id: number; name: string }"
extractType  file="src/app.ts"  startLine=5  startOffset=26  endLine=5  endOffset=56

# Preview the extraction
extractType  file="src/app.ts"  startLine=5  startOffset=26  endLine=5  endOffset=56  preview=true

---

inferReturnType

Add an explicit return type annotation to a function, inferred by TypeScript. Position must be on the function name or declaration keyword (function, async, arrow function variable name).

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
line	number	✅	1-based line number of the function
offset	number	✅	1-based character offset on the line
preview	boolean	✅	If true, return changes without applying

Examples:

# Add return type to a function that currently has none
# Given: function greet(name: string) { return `Hello, ${name}!`; }
# After: function greet(name: string): string { return `Hello, ${name}!`; }
inferReturnType  file="src/app.ts"  line=10  offset=10

# Preview the change
inferReturnType  file="src/app.ts"  line=10  offset=10  preview=true

quickinfo

Get the full type information, documentation, and JSDoc tags for the symbol at a given position. This is the "hover" info.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
line	number	✅	1-based line number
offset	number	✅	1-based character offset on the line

Examples:

quickinfo  file="src/utils/helpers.ts"  line=5  offset=17
quickinfo  file="src/types.ts"  line=3  offset=11

---

navtree

Get the complete hierarchical structure of a file — all classes, functions, variables, interfaces, type aliases, enums, and their nesting.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)

Examples:

navtree  file="src/utils/helpers.ts"
navtree  file="src/components/Button.tsx"

---

definition

Go to the definition of a symbol. Returns the file location(s) where the symbol is declared.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
line	number	✅	1-based line number
offset	number	✅	1-based character offset on the line

Examples:

definition  file="src/app.ts"  line=10  offset=5
definition  file="src/components/Button.tsx"  line=3  offset=15

---

typeDefinition

Navigate to the type's definition, not the variable's declaration. Given const user: UserProfile = ..., definition goes to the variable, but typeDefinition goes to the UserProfile interface.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
line	number	✅	1-based line number
offset	number	✅	1-based character offset on the line

Examples:

typeDefinition  file="src/app.ts"  line=10  offset=12
typeDefinition  file="src/services/api.ts"  line=5  offset=8

---

implementation

Find concrete implementations of an interface or abstract class. Given an interface Serializable, returns every class that implements it.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
line	number	✅	1-based line number
offset	number	✅	1-based character offset on the line

Examples:

implementation  file="src/types.ts"  line=1  offset=18
implementation  file="src/interfaces/repository.ts"  line=3  offset=18

---

navto

Workspace-wide symbol search by name. Takes a search string and returns matching symbols across all project files with their locations and kinds.

Parameter	Type	Required	Description
searchValue	string	✅	Symbol name or prefix to search for
file	string	—	Optional file for project context (absolute or relative to cwd)
maxResultCount	number	—	Maximum number of results to return
currentFileOnly	boolean	—	If true, only search the specified file

Examples:

navto  searchValue="User"  file="src/app.ts"
navto  searchValue="handle"  file="src/app.ts"  maxResultCount=10
navto  searchValue="Button"  file="src/components/Button.tsx"  currentFileOnly=true

---

fileReferences

Find every file that imports or references a given file. The reverse dependency graph for a single file.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)

Examples:

fileReferences  file="src/utils/helpers.ts"
fileReferences  file="src/types.ts"

---

prepareCallHierarchy

Get the call hierarchy item(s) at a position — the entry point for call hierarchy queries. Returns the function/method name, kind, file location, and spans.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
line	number	✅	1-based line number
offset	number	✅	1-based character offset on the line

Examples:

prepareCallHierarchy  file="src/services/api.ts"  line=10  offset=17
prepareCallHierarchy  file="src/utils/helpers.ts"  line=5  offset=17

---

provideCallHierarchyIncomingCalls

Find all functions/methods that call the function at the given position. Answers "who calls this?"

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
line	number	✅	1-based line number
offset	number	✅	1-based character offset on the line

Examples:

provideCallHierarchyIncomingCalls  file="src/services/api.ts"  line=10  offset=17
provideCallHierarchyIncomingCalls  file="src/utils/helpers.ts"  line=5  offset=17

---

provideCallHierarchyOutgoingCalls

Find all functions/methods that the function at the given position calls. Answers "what does this call?"

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
line	number	✅	1-based line number
offset	number	✅	1-based character offset on the line

Examples:

provideCallHierarchyOutgoingCalls  file="src/services/api.ts"  line=10  offset=17
provideCallHierarchyOutgoingCalls  file="src/utils/helpers.ts"  line=5  offset=17

---

projectInfo

Get the tsconfig.json path, the full list of files in the project, and whether the language service is active.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
needFileNameList	boolean	—	If true, include the list of all files in the project (default: true)

Examples:

projectInfo  file="src/app.ts"
projectInfo  file="src/app.ts"  needFileNameList=false

---

completionInfo

Get autocomplete suggestions at a position. Returns all possible completions with their kinds, sort text, and insert text. Useful for understanding what symbols, methods, or properties are available at a location.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
line	number	✅	1-based line number
offset	number	✅	1-based character offset on the line
prefix	string	—	Optional prefix to filter completions
triggerCharacter	string	—	Character that triggered completion (e.g., ., ", ', `, /, @, <, #, )

Examples:

completionInfo  file="src/app.ts"  line=10  offset=15
completionInfo  file="src/app.ts"  line=10  offset=15  prefix="get"
completionInfo  file="src/app.ts"  line=10  offset=15  triggerCharacter="."

---

completionEntryDetails

Get full details for specific completion entries — documentation, full type signature, JSDoc tags, and code actions (like auto-imports). Use as a follow-up to completionInfo.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
line	number	✅	1-based line number
offset	number	✅	1-based character offset on the line
entryNames	string[]	✅	Names of completion entries to get details for

Examples:

completionEntryDetails  file="src/app.ts"  line=10  offset=15  entryNames=["map","filter"]
completionEntryDetails  file="src/app.ts"  line=5  offset=10  entryNames=["useState"]

---

signatureHelp

Get function/method signature information at a call site. Returns parameter names, types, and documentation for each overload. Use when the cursor is inside function call parentheses.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
line	number	✅	1-based line number
offset	number	✅	1-based character offset (inside the function call parentheses)
triggerReason	object	—	Optional: { kind: "invoked" | "retrigger" | "characterTyped", triggerCharacter?: string }

Examples:

signatureHelp  file="src/app.ts"  line=12  offset=20
signatureHelp  file="src/app.ts"  line=12  offset=20  triggerReason={"kind":"invoked"}

---

documentHighlights

Find all occurrences of a symbol within a file (or set of files). Distinguishes between read and write references. More efficient than references when you only need local occurrences.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
line	number	✅	1-based line number
offset	number	✅	1-based character offset on the line
filesToSearch	string[]	—	Optional: limit search to these files

Examples:

documentHighlights  file="src/app.ts"  line=10  offset=5
documentHighlights  file="src/app.ts"  line=10  offset=5  filesToSearch=["src/app.ts","src/utils.ts"]

---

getApplicableRefactors

Discover what refactorings are available at a position or selection. Use before attempting a refactor to see what's possible. Returns a list of available refactors with their action names and descriptions.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
startLine	number	✅	1-based start line of the selection
startOffset	number	✅	1-based start character offset
endLine	number	✅	1-based end line of the selection
endOffset	number	✅	1-based end character offset
triggerReason	string	—	"invoked" or "implicit"

Examples:

getApplicableRefactors  file="src/app.ts"  startLine=10  startOffset=1  endLine=15  endOffset=1
getApplicableRefactors  file="src/app.ts"  startLine=8  startOffset=12  endLine=8  endOffset=35

---

docCommentTemplate

Generate a JSDoc comment template for a function, method, or class at a position. Returns the template text with @param, @returns, etc. based on the function signature.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
line	number	✅	1-based line number
offset	number	✅	1-based character offset on the line

Examples:

docCommentTemplate  file="src/utils/helpers.ts"  line=10  offset=1
docCommentTemplate  file="src/services/api.ts"  line=25  offset=10

---

getOutliningSpans

Get code folding regions for a file. Returns the hierarchical structure of code blocks including their kinds (comment, region, code, imports). Useful for understanding file structure and complexity.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)

Examples:

getOutliningSpans  file="src/app.ts"
getOutliningSpans  file="src/components/Button.tsx"

---

provideInlayHints

Get inlay hints (inline type annotations) for a range. Shows inferred types, parameter names at call sites, and return types. Useful for understanding what TypeScript infers without explicit type annotations.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
start	number	✅	Start offset (0-based character position)
length	number	✅	Length of range in characters

Examples:

# Get inlay hints for the first 1000 characters of a file
provideInlayHints  file="src/app.ts"  start=0  length=1000

# Get inlay hints for a specific range
provideInlayHints  file="src/utils/helpers.ts"  start=500  length=200

---

todoComments

Find all TODO, FIXME, HACK, and other configured comment markers in a file. Returns the location and text of each matching comment.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
descriptors	{text: string, priority: number}[]	✅	Array of comment markers to search for (e.g., TODO, FIXME)

Examples:

# Find all TODO and FIXME comments
todoComments  file="src/app.ts"  descriptors=[{"text":"TODO","priority":1},{"text":"FIXME","priority":0}]

# Find TODO, FIXME, and HACK comments
todoComments  file="src/app.ts"  descriptors=[{"text":"TODO","priority":2},{"text":"FIXME","priority":1},{"text":"HACK","priority":0}]

---

definitionAndBoundSpan

Like definition, but also returns the text span of the symbol being queried. Useful for understanding exactly which characters constitute the symbol.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
line	number	✅	1-based line number
offset	number	✅	1-based character offset on the line

Examples:

definitionAndBoundSpan  file="src/app.ts"  line=10  offset=5
definitionAndBoundSpan  file="src/types.ts"  line=3  offset=11

---

findSourceDefinition

Navigate to the actual TypeScript source instead of .d.ts declaration files. Useful when working with libraries that have source maps or when you want to see the implementation rather than just the type declarations.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
line	number	✅	1-based line number
offset	number	✅	1-based character offset on the line

Examples:

findSourceDefinition  file="src/app.ts"  line=10  offset=5
findSourceDefinition  file="src/services/api.ts"  line=3  offset=15

---

selectionRange

Get semantically meaningful selection ranges for smart expand/shrink selection. Returns nested spans that represent progressively larger syntactic constructs (expression → statement → block → function).

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
locations	{line: number, offset: number}[]	✅	Array of positions to get selection ranges for

Examples:

selectionRange  file="src/app.ts"  locations=[{"line":10,"offset":5}]
selectionRange  file="src/app.ts"  locations=[{"line":10,"offset":5},{"line":20,"offset":10}]

---

format

Format a range of code according to TypeScript's formatting rules. Applies consistent indentation, spacing, and line breaks.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
line	number	✅	1-based start line of the range
offset	number	✅	1-based start character offset
endLine	number	✅	1-based end line of the range
endOffset	number	✅	1-based end character offset
options	object	—	Formatting options (tabSize, indentSize, etc.)
preview	boolean	✅	If true, return changes without applying

Examples:

format  file="src/app.ts"  line=1  offset=1  endLine=50  endOffset=1
format  file="src/app.ts"  line=10  offset=1  endLine=20  endOffset=1  preview=true
format  file="src/app.ts"  line=1  offset=1  endLine=100  endOffset=1  options={"tabSize":4}

---

getMoveToRefactoringFileSuggestions

Get suggested target files when moving a symbol to another file. Returns both a suggested new file name and existing files that would be good destinations. Use this before moveSymbol to choose the best target location.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
startLine	number	✅	1-based start line of the declaration
startOffset	number	✅	1-based start character offset
endLine	number	✅	1-based end line of the declaration
endOffset	number	✅	1-based end character offset

Examples:

getMoveToRefactoringFileSuggestions  file="src/app.ts"  startLine=20  startOffset=1  endLine=35  endOffset=2
getMoveToRefactoringFileSuggestions  file="src/components/Button.tsx"  startLine=1  startOffset=1  endLine=5  endOffset=2

---

getSupportedCodeFixes

Returns the list of all error codes that have available automatic fixes. Use this as a discovery tool before calling getCodeFixes — it tells you which error codes tsserver can fix. Optionally scope the query to a specific file's project.

Parameter	Type	Required	Description
file	string	—	Optional file path (absolute or relative to cwd). If provided, scopes to the file's project.

Examples:

# Get all fixable error codes globally
getSupportedCodeFixes

# Get fixable error codes scoped to a specific project
getSupportedCodeFixes  file="src/app.ts"

---

mapCode

Map AI-generated code snippets into a file, replacing matching declarations by name or appending new ones. Designed for AI code generation workflows where you want to merge new code into an existing file without duplicating declarations.

Parameter	Type	Required	Description
file	string	✅	File path (absolute or relative to cwd)
contents	string[]	✅	Code snippets to map into the file. Each is parsed independently. Functions and classes are matched by name.
focusLocations	object[][]	—	Nested arrays of {start, end} spans (1-based line/offset) used to enable name-based matching. Without this, code is always appended to end of file.
preview	boolean	✅	If true, return changes without applying

How matching works:

• Without focusLocations → code is always appended to end of file (no matching attempted)
• With focusLocations → TypeScript searches for declarations with matching names in the pointed-to scope
• Matching works for: functions, classes, methods, interfaces (nodes with a .name property)
• Matching does NOT work for: const/let/var declarations (VariableStatement has no .name)
• When a match is found, the range from first to last matching statement is replaced
• When no match is found, code is appended to the end of the scope

Limitations:

• Calling with multiple contents entries only applies the first match — call once per declaration to replace multiple
• const/let/var replacements are not supported; use standard file editing instead

Examples:

# Replace an existing function (focusLocations enables name-based matching)
mapCode  file="src/utils.ts"  contents=["export function add(a: number, b: number, c = 0) { return a + b + c; }"]  focusLocations=[[{"start":{"line":1,"offset":1},"end":{"line":1,"offset":1}}]]

# Append a new function (no focusLocations — always appends)
mapCode  file="src/utils.ts"  contents=["export function multiply(a: number, b: number) { return a * b; }"]

# Preview before applying
mapCode  file="src/utils.ts"  contents=["export function add(a: number, b: number) { return a + b; }"]  focusLocations=[[{"start":{"line":1,"offset":1},"end":{"line":1,"offset":1}}]]  preview=true

Supported Languages & Frameworks

ts-mcp-server works with any project that TypeScript's language service understands:

• TypeScript (.ts, .tsx, .mts, .cts)
• JavaScript (.js, .jsx, .mjs, .cjs)
• React / Next.js / Remix / Astro
• Vue (script blocks)
• Node.js / Express / Fastify / NestJS
• Angular
• Svelte (script blocks)
• Electron
• React Native
• Monorepos (Turborepo, Nx, Lerna, pnpm workspaces)

If your project has a tsconfig.json (or jsconfig.json), it works.

System Requirements

Requirement	Version
Node.js	22 or later (current LTS)
TypeScript	6.x (installed automatically as a dependency)
OS	Windows, macOS, Linux

No additional dependencies or global tools are required. The server bundles everything it needs.

FAQ

Does it work without a tsconfig.json? Yes. TypeScript will create an inferred project, but explicit configuration gives better results.

Does it update package.json or non-code files? No. It updates TypeScript/JavaScript import and export statements, and path-related entries in tsconfig.json (files, include, exclude, paths).

Can I use it with JavaScript-only projects? Yes. Add a jsconfig.json (which is equivalent to tsconfig.json with allowJs: true) and the server will discover your project.

Does it work with path aliases (@/components/...)? Yes. tsserver resolves path aliases defined in tsconfig.json's paths and baseUrl settings.

Is the output modified or formatted? No. Every tool returns the raw, unmodified tsserver response serialized as JSON. Nothing is truncated, simplified, grouped, or filtered.