ts-language-mcp
ts-language-mcp exposes TypeScript compiler intelligence over MCP so AI coding agents can navigate, understand, diagnose, refactor, and assess TypeScript projects by symbol name or file/line/column.
Navigate code: find definitions, type definitions, references with read/write classification, implementations, call hierarchy, and type hierarchy.
Inspect types: get hover type info/JSDoc, function signatures, and context-aware completions.
Explore structure: list file symbols, hierarchical outlines, imports, AST symbol search with glob/regex/kind filters, and fuzzy workspace symbol search.
Check diagnostics: get per-file or project-wide TypeScript + ESLint errors/warnings, including tsconfig errors and optional unused-code suggestions.
Refactor and write: preview/apply compiler code fixes, organize/remove unused imports, preview/execute project-wide renames, and format files to disk.
Analyze quality: calculate cyclomatic complexity/LOC, detect structural duplication, find indirection hotspots, inspect module dependencies/coupling, and generate combined quality reports.
Batch work: run combined analysis for one position or batch analyze multiple positions in one call.
Address symbols conveniently: use
symbol: "Container.member"instead of coordinates, with ambiguity errors and paged/truncated results for large outputs.Read project resources: list indexed files, view compiler options, and read individual file contents via MCP resources.
Provides TypeScript code intelligence tools for AI coding agents, including navigation, type information, code structure, semantic search, diagnostics, and refactoring capabilities via direct TypeScript compiler API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ts-language-mcp get definition of UserService"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ts-language-mcp
A TypeScript code intelligence server for AI coding agents via MCP (Model Context Protocol).
Why Use This?
AI coding agents working with TypeScript treat code as text — reading entire files, grepping for patterns, guessing at types. ts-language-mcp exposes TypeScript's own compiler intelligence through MCP tools:
Raw File Access | ts-language-mcp |
Read entire file to find a function | Ask for it by name, no coordinates needed |
Grep for usage patterns | Get all references with read/write classification and their source lines |
Guess at types from context | Get exact types with full generic resolution |
Hope renames don't break things | Preview and execute renames across files |
Hand-write the fix for a compiler error | Apply the compiler's own quick fix |
Unlike LSP-based alternatives, ts-language-mcp uses the TypeScript compiler API directly — zero config, deeper intelligence (AST search, batch analysis, executable renames, project-wide diagnostics), and no external LSP server required.
Built for agents, not editors
Address symbols by name. Every position-based tool accepts
symbol: "UserService.getUser"instead of a line and column. An ambiguous name returns the candidates rather than silently picking one, and an out-of-range coordinate is an error rather than a quiet answer about the wrong code.Results carry their source line. References, definitions, implementations and hierarchy results include the code they point at, so there is no follow-up file read just to see what was found.
Fixes come from the compiler.
get_code_fixesandorganize_importssurface TypeScript's own edits, including the correct import path, instead of leaving an agent to guess one.Large results say they are large. Tools that can return unbounded lists report
total,returnedandtruncatedrather than quietly cutting off.
Related MCP server: code-dev-intel
Quick Start
# Analyze current directory
npx ts-language-mcp
# Analyze specific project
npx ts-language-mcp /path/to/typescript/project
# Custom server name
npx ts-language-mcp --name my-ts-server /path/to/projectMCP Client Configuration
Claude Code:
claude mcp add typescript -- npx ts-language-mcp /path/to/your/projectClaude Desktop, Cline, etc.:
{
"mcpServers": {
"typescript": {
"command": "npx",
"args": ["ts-language-mcp", "/path/to/your/project"]
}
}
}The target project needs a tsconfig.json and TypeScript source files. The server auto-loads compiler options, honours include/exclude, and re-checks changed files on each request (throttled; there is no filesystem watcher).
Resources
typescript://project/files- List all indexed project filestypescript://project/config- Current compiler optionstypescript://file/{path}- Read a single file's content
Tools
Tools marked by name accept symbol in place of line/column.
Category | Tool | Description |
| Jump from usage to declaration (by name, returns all declarations) | |
| Jump to a symbol's type rather than the symbol (by name) | |
| Find all usages with read/write classification (by name, paged) | |
| Find concrete implementations of interfaces (by name) | |
| Trace function callers / callees (by name) | |
| Navigate inheritance chains (by name) | |
Type Intelligence |
| Type info and JSDoc (by name) |
| Function parameter help (by name) | |
Code Structure |
| Flat list of symbols in a file (paged) |
| Hierarchical file structure | |
| List all imports with details | |
Semantic Search |
| AST search by name pattern, kind, scope (paged) |
| Fast fuzzy symbol search | |
Diagnostics |
| Errors/warnings for a file, TypeScript + ESLint |
| Project-wide diagnostics, including tsconfig errors | |
| Context-aware completions | |
| The compiler's own fixes for an error (by name) | |
| Apply a fix and write it to disk (by name) | |
| Sort imports and drop unused ones | |
| Preview rename impact (by name) | |
| Execute rename across project, written to disk (by name) | |
| Format with built-in formatter, written to disk | |
Code Quality |
| Cyclomatic complexity and LOC per function/file |
| Structurally duplicated code blocks | |
| Symbols reached through deep call chains | |
| What a file imports and what imports it | |
| Top offenders across all quality categories | |
Efficiency |
| Combined analysis in one call (by name) |
| Analyze multiple positions at once (by name) |
Writes to disk
rename_symbol, format_document, apply_code_fix and organize_imports (with apply: true) modify files on disk. Everything else is read-only; rename_preview and organize_imports without apply show the edits without making them.
Development
npm test # Run tests once
npm run test:watch # Run tests in watch mode
npm run build # Build
npm run dev # Watch modeLicense
MIT
Available Tools
29 toolsanalyze_positionA
Get comprehensive analysis at a position: hover info, definition, references, diagnostics, and signature help in one call.
Inputs: file, line, column, symbol.
apply_code_fixA
Apply one of the fixes returned by get_code_fixes and write it to disk. Set applyToAll to fix every occurrence of the same problem in the file. Target it either by "symbol" name (preferred: no need to know coordinates) or by explicit file/line/column.
Inputs: fixName (required), file, line, column, +2 more.
batch_analyzeB
Get hover, definition, references, diagnostics, and signature for multiple positions in one call. Use the "include" parameter to select which analyses to run (default: all).
Inputs: positions (required), include.
calculate_metricsA
Calculate code quality metrics: cyclomatic complexity per function, lines of code per function/file. Identifies complexity hotspots. Omit "file" for project-wide analysis.
Inputs: file, topN.
detect_duplicationA
Detect duplicate code blocks by comparing AST structure fingerprints. Matches are exact structural duplicates, ignoring identifier and literal values, so renamed copies are found but near-misses with an extra statement are not.
Inputs: file, minNodes, minStatements.
findA
Search for symbols in the AST by name pattern and kind. Supports glob patterns (*Service), regex (/^get/), and filtering by symbol kind (function, class, interface, string, comment, etc.) and export status.
Inputs: path, kinds, limit, query, +3 more.
find_indirection_hotspotsA
Find symbols most heavily accessed through layers of indirection (A → B → C). Returns worst offenders ranked by score with full call chains. Useful for identifying hidden coupling and deeply wrapped dependencies.
Inputs: skip, take, maxDepth, includeTests, +2 more.
format_documentA
Format a TypeScript/JavaScript file using TypeScript's built-in formatter and write the result to disk. Pass includeContent to also get the formatted text back.
Inputs: file (required), options, includeContent.
get_all_diagnosticsA
Get TypeScript + ESLint errors and warnings for all files in the project. Useful for checking project health after changes. Results are sorted by severity (errors first) and capped at the top 50 most severe by default — summary.total reflects the true total and summary.truncated indicates when the cap was hit.
Inputs: limit, severity, includeEslint, includeSuggestions.
get_call_hierarchyA
Get call hierarchy for a function/method. Direction: "incoming" shows who calls this, "outgoing" shows what this calls. Target it either by "symbol" name (preferred: no need to know coordinates) or by explicit file/line/column.
Inputs: direction (required), file, line, column, +1 more.
get_code_fixesB
Get the fixes TypeScript itself proposes for the errors at a position, such as adding a missing import, adding a missing member, or removing unused code. Prefer this over hand-writing a fix for a reported diagnostic: the compiler already knows the exact edit, including the correct import path. Target it either by "symbol" name (preferred: no need to know coordinates) or by explicit file/line/column.
Inputs: file, line, column, symbol, +1 more.
get_completionsC
Get code completion suggestions at a position. Context-aware suggestions.
Inputs: file, line, column, symbol.
get_definitionA
Find where a symbol is defined. Jump from usage to declaration. Target it either by "symbol" name (preferred: no need to know coordinates) or by explicit file/line/column.
Inputs: file, line, column, symbol.
get_diagnosticsA
Get TypeScript + ESLint errors and warnings for a file. ESLint results are included when ESLint is installed in the target project. Results are sorted by severity and capped at the top 50 most severe by default.
Inputs: file (required), limit, includeEslint, includeSuggestions.
get_hoverA
Get type information and documentation for a symbol. Returns the type signature and any JSDoc comments. Target it either by "symbol" name (preferred: no need to know coordinates) or by explicit file/line/column.
Inputs: file, line, column, symbol.
get_implementationsB
Find all implementations of an interface or abstract method. Useful for understanding polymorphic code. Target it either by "symbol" name (preferred: no need to know coordinates) or by explicit file/line/column.
Inputs: file, line, column, symbol.
get_importsA
List all imports in a file with their details (named imports, defaults, namespaces).
Inputs: file (required).
get_module_dependenciesA
Show what a file imports and what imports it, resolved through the TypeScript compiler so tsconfig "paths" aliases and package entry points are handled correctly. Covers static imports, re-exports, dynamic import() and require(). Includes efferent/afferent coupling and instability.
Inputs: file (required), direction, includeExternal.
get_outlineB
Get hierarchical structure/outline of a file. Returns nested symbols with their ranges.
Inputs: file (required).
get_referencesA
Find all usages of a symbol across the project. Each reference includes its kind: "definition", "read", or "write", and the source line it sits on. Target it either by "symbol" name (preferred: no need to know coordinates) or by explicit file/line/column.
Inputs: file, line, limit, column, +3 more.
get_signatureA
Get function signature help when cursor is inside a function call's parentheses. Shows parameter names, types, and which parameter is active based on cursor position.
Inputs: file, line, column, symbol.
get_symbolsA
List all symbols (functions, classes, etc.) defined in a file as a flat list. For hierarchical/nested structure, use get_outline instead.
Inputs: file (required), limit, offset.
get_type_definitionA
Jump to the declaration of a symbol's TYPE rather than of the symbol itself. For const u = getUser() this lands on the User interface, where get_definition lands on the variable. Target it either by "symbol" name (preferred: no need to know coordinates) or by explicit file/line/column.
Inputs: file, line, column, symbol.
get_type_hierarchyA
Get type hierarchy for a class/interface. Direction: "supertypes" shows parents, "subtypes" shows implementations/extensions. Target it either by "symbol" name (preferred: no need to know coordinates) or by explicit file/line/column.
Inputs: direction (required), file, line, column, +1 more.
get_workspace_symbolsA
Fast symbol search across the workspace by name. Faster than the find tool for simple name lookups. Supports fuzzy matching.
Inputs: query (required), maxResults.
organize_importsA
Sort a file's imports and drop unused ones, using TypeScript's own organizer. Previews the edits by default; pass apply to write them to disk.
Inputs: file (required), apply.
quality_reportA
Combined code quality report: worst complexity hotspots, most coupled/unstable modules, and duplicate code blocks — top offenders across all categories in one call.
Inputs: topN.
rename_previewA
Preview what locations would change when renaming a symbol. Shows all affected files and positions without making changes.
Inputs: newName (required), file, line, column, +1 more.
rename_symbolA
Rename a symbol across the project, writing the changes to disk. Handles shorthand properties and aliased imports correctly. Returns summary of files modified and total changes made. Target it either by "symbol" name (preferred: no need to know coordinates) or by explicit file/line/column.
Inputs: newName (required), file, line, column, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 29 tools
Several tools serve overlapping purposes, making it ambiguous for an agent to choose. For instance, `get_symbols`, `find`, `get_workspace_symbols`, and `get_outline` all retrieve symbol information but with different levels of detail; `get_code_fixes` and `apply_code_fix` are tightly coupled; and `get_diagnostics` and `get_all_diagnostics` are very similar in functionality, differing only in scope.
The naming is largely consistent, following a `verb_noun` pattern throughout, which aids predictability. Minor deviations include `batch_analyze` instead of `analyze_batch`, and `find` and `quality_report` which lack nouns, but these are readable and do not significantly harm overall consistency.
With 29 tools, the count is on the higher side but still within a reasonable range given the broad scope of TypeScript language services covered. Each tool serves a specific analytical or transformation purpose, so the density is justified, though some consolidation could reduce potential overlap.
The tool set covers an extensive range of language server capabilities including navigation, code actions, refactoring, diagnostics, and quality analysis. Minor gaps include a lack of tools for symbolic renaming previews being integrated with the rename tool itself, but overall the surface is comprehensive for static analysis and transformation tasks.
Maintenance
Related MCP Connectors
Coding agents in multi-service codebases routinely rebuild existing helpers, trust stale type definitions, and modify API contracts without knowing who consumes them. Carrick solves this by indexing your entire TypeScript ecosystem across service and repository boundaries. By integrating deeply with the TypeScript compiler, Carrick traces every route, type, and cross-service call while recording function behaviour so agents search by intent rather than name. Delivered via MCP for AI agents and LSP for IDEs, Carrick ensures models see existing endpoints and utilities before generating new code. The scanner is source-available and runs from your CLI or CI pipeline.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Stateless TS/JS compiler facts for agents: references, imports, impact. No repo index or OAuth.
Related MCP Servers
- AlicenseBqualityDmaintenanceExposes TypeScript Language Server Protocol functionality to AI agents, enabling them to query types at specific positions, find definitions and references, get diagnostics, run type tests, and type-check inline code just like in an IDE.9297 npm3MIT
- AlicenseNot gradedqualityBmaintenanceA self-hosted MCP and HTTP server for TypeScript code intelligence, providing AI agents with fast semantic code navigation tools like finding definitions, references, implementations, file outlines, dependency graphs, and search.185 npmAGPL 3.0
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to navigate and edit TypeScript/JavaScript source by named declarations, reading symbols, imports, diagnostics, and replacing code via the TypeScript AST.-
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents to perform structural code operations on TypeScript/TSX projects—finding symbols and references and renaming them semantically while preserving source.27 npmMIT