Skip to main content
Glama
ts-language-mcp

ts-language-mcp

by jgauffin

ts-language-mcp

npm version License: MIT GitHub issues GitHub stars

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_fixes and organize_imports surface 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, returned and truncated rather 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/project

MCP Client Configuration

Claude Code:

claude mcp add typescript -- npx ts-language-mcp /path/to/your/project

Claude 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 files

  • typescript://project/config - Current compiler options

  • typescript://file/{path} - Read a single file's content

Tools

Tools marked by name accept symbol in place of line/column.

Category

Tool

Description

Navigation

get_definition

Jump from usage to declaration (by name, returns all declarations)

get_type_definition

Jump to a symbol's type rather than the symbol (by name)

get_references

Find all usages with read/write classification (by name, paged)

get_implementations

Find concrete implementations of interfaces (by name)

get_call_hierarchy

Trace function callers / callees (by name)

get_type_hierarchy

Navigate inheritance chains (by name)

Type Intelligence

get_hover

Type info and JSDoc (by name)

get_signature

Function parameter help (by name)

Code Structure

get_symbols

Flat list of symbols in a file (paged)

get_outline

Hierarchical file structure

get_imports

List all imports with details

Semantic Search

find

AST search by name pattern, kind, scope (paged)

get_workspace_symbols

Fast fuzzy symbol search

Diagnostics

get_diagnostics

Errors/warnings for a file, TypeScript + ESLint

get_all_diagnostics

Project-wide diagnostics, including tsconfig errors

get_completions

Context-aware completions

Refactoring

get_code_fixes

The compiler's own fixes for an error (by name)

apply_code_fix

Apply a fix and write it to disk (by name)

organize_imports

Sort imports and drop unused ones

rename_preview

Preview rename impact (by name)

rename_symbol

Execute rename across project, written to disk (by name)

format_document

Format with built-in formatter, written to disk

Code Quality

calculate_metrics

Cyclomatic complexity and LOC per function/file

detect_duplication

Structurally duplicated code blocks

find_indirection_hotspots

Symbols reached through deep call chains

get_module_dependencies

What a file imports and what imports it

quality_report

Top offenders across all quality categories

Efficiency

analyze_position

Combined analysis in one call (by name)

batch_analyze

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 mode

License

MIT

Available Tools

29 tools
analyze_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

    A3.6/5.0

    Scored across 29 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Exposes 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.
      9
      297 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A 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 npm
      AGPL 3.0
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants to navigate and edit TypeScript/JavaScript source by named declarations, reading symbols, imports, diagnostics, and replacing code via the TypeScript AST.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding agents to perform structural code operations on TypeScript/TSX projects—finding symbols and references and renaming them semantically while preserving source.
      27 npm
      MIT