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:

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.

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 (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
  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