使用说明
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.
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 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 |
|---|---|---|
| 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
Architecture
src/
index.ts # CLI entry point
server.ts # MCP server setup
language-service.ts # TypeScript Language Service wrapper
file-manager.ts # In-memory file cache, tsconfig-scoped refresh
symbol-resolver.ts # Resolves symbol names to file positions
ast-finder.ts # AST traversal for semantic search
position-utils.ts # Line/column to offset conversion
paths.ts # Cross-platform path normalization
yaml.ts # Token-efficient result serializer
version.ts # Package version, read from package.json
types.ts # Shared type definitions
resources.ts # MCP resource definitions
tools/
index.ts # Tool registry, request queue, path validation
schemas.ts # Shared JSON Schema fragments
paginate.ts # limit/offset with truncation reporting
navigation.ts # definitions, references, hierarchies
intelligence.ts # hover, signatures, completions, batch analysis
structure.ts # symbols, outline, imports, search
diagnostics.ts # TypeScript + ESLint diagnostics
refactoring.ts # renames, formatting, code fixes
quality.ts # complexity, duplication, coupling, dependencies
analyzers/
complexity-analyzer.ts, coupling-analyzer.ts,
duplication-detector.ts, indirection-analyzer.ts
License
MIT
