Skip to main content
Glama
ts-language-mcp

ts-language-mcp

by jgauffin
README.md
# ts-language-mcp

[![npm version](https://img.shields.io/npm/v/ts-language-mcp.svg)](https://www.npmjs.com/package/ts-language-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub issues](https://img.shields.io/github/issues/jgauffin/ts-language-mcp)](https://github.com/jgauffin/ts-language-mcp/issues)
[![GitHub stars](https://img.shields.io/github/stars/jgauffin/ts-language-mcp)](https://github.com/jgauffin/ts-language-mcp/stargazers)

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.

## Quick Start

```bash
# 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:**

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

**Claude Desktop, Cline, etc.:**

```json
{
  "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](docs/navigation-tools.md)** | `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](docs/refactoring-tools.md)** | `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

```bash
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

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