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 | Jump directly to definition | | Grep for usage patterns | Get all references with read/write classification | | Guess at types from context | Get exact types with full generic resolution | | Hope renames don't break things | Preview and execute renames across files |

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.

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 and watches for file changes.

Resources

• typescript://project/files - List all indexed project files
• typescript://project/config - Current compiler options
• typescript://file/{path} - Read file content

Tools

| Category | Tool | Description | |----------|------|-------------| | Navigation | get_definition | Jump from usage to declaration | | | get_references | Find all usages with read/write classification | | | get_implementations | Find concrete implementations of interfaces | | | get_call_hierarchy | Trace function callers / callees | | | get_type_hierarchy | Navigate inheritance chains | | Type Intelligence | get_hover | Type info and JSDoc at a position | | | get_signature | Function parameter help | | Code Structure | get_symbols | Flat list of symbols in a file | | | get_outline | Hierarchical file structure | | | get_imports | List all imports with details | | Semantic Search | find | AST search by name pattern, kind, scope | | | get_workspace_symbols | Fast fuzzy symbol search | | Diagnostics | get_diagnostics | Errors/warnings for a file | | | get_all_diagnostics | Project-wide diagnostics | | | get_completions | Context-aware completions | | Refactoring | rename_preview | Preview rename impact | | | rename_symbol | Execute rename across project | | | format_document | Format with built-in formatter | | Efficiency | analyze_position | Combined analysis in one call | | | batch_analyze | Analyze multiple positions at once |

Development

npm test          # Run tests (watch)
npm run test:run  # Run tests once
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
  ast-finder.ts         # AST traversal for semantic search
  tools.ts              # MCP tool definitions and handlers
  resources.ts          # MCP resource definitions
  types.ts              # Shared type definitions

License

MIT