TypeScript MCP

A high-performance Model Context Protocol (MCP) server for TypeScript with native TSServer integration, advanced caching, connection pooling, and monorepo cross-file module resolution optimizations.

🚀 Performance Features

• Native TSServer Integration: Direct TypeScript compiler API communication for maximum performance
• Cross-File Module Resolution: Fixes critical module resolution failures in pnpm monorepos and complex workspaces
• File Caching: LRU cache with intelligent eviction for 30%+ performance gains
• Connection Pooling: Reuses TSServer connections to eliminate 2-3s startup overhead per request
• Incremental File Sync: Delta-based updates providing 95%+ speedup for file changes
• Sub-millisecond Response Times: Optimized for typical development workflows
• Memory Efficient: Configurable limits with automatic cleanup and health monitoring
• Monorepo Optimizations: Workspace-aware analysis for complex project structures with TypeScript project references

🎉 Success Story: Monorepo Cross-File Module Resolution

FIXED: Critical bug in TypeScript MCP v0.5.6 where cross-file module resolution failed in monorepos.

Problem: TypeScript MCP returned empty diagnostics arrays for files with actual TypeScript errors that tsc correctly identified, particularly in pnpm monorepos with project references.

Solution: Migrated from typescript-language-server to native TSServer with universal workspace-root connections.

Real-world validation from the Uplinq monorepo (pnpm + Turborepo + 20+ TypeScript projects):

✅ Cross-File Error Detection: Now correctly identifies module resolution failures across packages
✅ Complete Diagnostics: Returns actual TypeScript errors instead of empty arrays
✅ Workspace-Aware Analysis: TSServer properly sees project references and resolves imports
✅ Universal Compatibility: Works with pnpm, npm, yarn workspaces and TypeScript project references

Before Fix:

✗ getDiagnostics(): [] (empty - missed actual errors)
✗ Module resolution: Failed silently
✗ Cross-package imports: Not analyzed

After Fix:

✅ getDiagnostics(): [actual TypeScript errors with line/column positions]
✅ Module resolution: Works correctly across packages
✅ Cross-package imports: Fully analyzed and validated

The fix ensures TypeScript MCP provides the same error detection as running tsc directly while maintaining high performance.

Installation

npm install -g @uplinq/mcp-typescript

Usage

Stdio Transport (Default)

mcp-typescript --workspace /path/to/project

SSE Transport

mcp-typescript --workspace /path/to/project --sse 3000

Configuration

MCP Server Configuration

Add to your .mcp.json:

{
  "mcpServers": {
    "typescript": {
      "command": "mcp-typescript",
      "args": ["--workspace", "/path/to/project"]
    }
  }
}

For SSE transport:

{
  "mcpServers": {
    "typescript": {
      "command": "mcp-typescript",
      "args": ["--workspace", "/path/to/project", "--sse", "3000"]
    }
  }
}

Performance Configuration

Create .mcp.typescript.json in your project root to customize performance settings:

{
  "performance": {
    "fileCache": {
      "maxSize": 200,
      "maxAge": 600000,
      "maxMemory": 104857600
    },
    "connectionPool": {
      "maxConnections": 3,
      "maxIdleTime": 300000,
      "maxConnectionAge": 1800000,
      "healthCheckInterval": 30000
    }
  },
  "tsserver": {
    "requestTimeout": 15000,
    "maxRetries": 3,
    "retryDelayMs": 1000
  }
}

Configuration Reference

| Configuration | Environment Variable | Default Value | Description | |---------------|---------------------|---------------|-------------| | TSServer Settings | | | | | tsserver.requestTimeout | MCP_TS_REQUEST_TIMEOUT | 10000 | Request timeout in milliseconds | | tsserver.maxRetries | MCP_TS_MAX_RETRIES | 2 | Maximum number of retries for failed requests | | tsserver.retryDelayMs | - | 1000 | Base delay between retries in milliseconds | | tsserver.maxRetryDelayMs | - | 5000 | Maximum delay between retries (with exponential backoff) | | tsserver.diagnosticsDelayMs | - | 1000 | Delay before processing diagnostics | | tsserver.enableLogging | MCP_TS_ENABLE_LOGGING | true | Enable/disable logging | | tsserver.logLevel | MCP_TS_LOG_LEVEL | "info" | Log level: 'debug', 'info', 'warn', 'error' | | tsserver.tsServerPath | MCP_TS_TS_SERVER_PATH | auto-detected | Path to native TypeScript server | | File Cache | | | | | performance.fileCache.maxSize | MCP_TS_CACHE_SIZE | 100 | Maximum number of files to cache | | performance.fileCache.maxAge | MCP_TS_CACHE_MAX_AGE | 300000 | Cache entry max age (5 minutes) | | performance.fileCache.maxMemory | MCP_TS_CACHE_MAX_MEMORY | 52428800 | Maximum cache memory usage (50MB) | | performance.fileCache.diagnosticsCacheMaxAge | - | 30000 | Diagnostics cache max age (30 seconds) | | Connection Pool | | | | | performance.connectionPool.maxConnections | MCP_TS_POOL_MAX_CONNECTIONS | 5 | Maximum concurrent TSServer connections | | performance.connectionPool.maxIdleTime | MCP_TS_POOL_MAX_IDLE_TIME | 300000 | Max idle time before connection cleanup (5 minutes) | | performance.connectionPool.maxConnectionAge | - | 3600000 | Maximum connection age (1 hour) | | performance.connectionPool.healthCheckInterval | - | 60000 | Health check interval (1 minute) | | Incremental Sync | | | | | performance.incrementalSync.enabled | - | true | Enable incremental file synchronization | | performance.incrementalSync.maxFileSize | - | 1048576 | Maximum file size for incremental updates (1MB) | | performance.incrementalSync.minChangeRatio | - | 0.1 | Minimum change ratio to trigger incremental update | | performance.incrementalSync.maxChangesPerUpdate | - | 100 | Maximum number of changes per incremental update | | performance.incrementalSync.useFastHash | - | true | Use fast hash for content comparison | | Workspace | | | | | workspace.autoDetect | - | true | Automatically detect workspace root | | workspace.patterns | - | ["/*.ts", "/.tsx", "**/.js", "**/*.jsx"] | File patterns to include in workspace |

Environment Variables

Override configuration with environment variables:

export MCP_TS_CACHE_SIZE=500
export MCP_TS_POOL_MAX_CONNECTIONS=5
export MCP_TS_REQUEST_TIMEOUT=20000

🏗️ Monorepo Support

Fast TypeScript MCP provides comprehensive support for monorepos with native TSServer integration:

• pnpm workspaces + Turborepo with TypeScript project references
• npm/yarn workspaces with complex project structures
• Multiple apps (apps/*) and packages (packages/*)
• Infrastructure projects (infra/, lambdas/, scripts/)

Workspace Detection

The server automatically detects monorepos by analyzing:

1. pnpm-workspace.yaml: pnpm workspace configuration
2. TypeScript Project References: tsconfig.json with references array
3. package.json workspaces: npm/yarn workspace patterns
4. Scoring-based Selection: Finds the best workspace root automatically

Monorepo Optimizations

Universal workspace-root TSServer connections ensure:

• Proper Module Resolution: TSServer sees all project references and resolves cross-package imports
• Workspace-Aware Analysis: Maintains full cross-package visibility for diagnostics and navigation
• Universal Compatibility: Works with all monorepo tools (pnpm, npm, yarn, Turborepo, Lerna)
• Cross-File Error Detection: Correctly identifies module resolution failures across packages

Supported Monorepo Structures

✅ pnpm + Turborepo:

monorepo/
├── apps/
│   ├── web/          # Next.js app
│   ├── admin/        # Admin app  
│   └── mobile/       # React Native app
├── packages/
│   ├── ui/           # Component library
│   ├── core/         # Business logic
│   ├── auth/         # Authentication
│   └── ...          # Additional packages
├── lambdas/          # AWS Lambda functions
├── infra/            # Infrastructure as code
├── scripts/          # Build/deployment scripts
├── pnpm-workspace.yaml
└── turbo.json

✅ TypeScript Project References:

monorepo/
├── packages/
│   ├── shared/
│   │   └── tsconfig.json
│   └── app/
│       └── tsconfig.json  # references: ["../shared"]
└── tsconfig.json         # references: ["packages/*"]

✅ npm/yarn Workspaces:

monorepo/
├── packages/
└── package.json     # workspaces: ["packages/*"]

Performance Benefits

• Correct Error Detection: Returns actual TypeScript errors instead of empty arrays
• Cross-Package Analysis: Full module resolution across all workspace packages
• Native Performance: Direct TSServer communication eliminates wrapper overhead
• Universal Compatibility: Works with all monorepo configurations automatically

Tools

⚡ Fast Operations (Safe for Frequent Use)

• diagnostics: Get TypeScript errors, warnings, and hints with line/column positions
• hover: Get type information and documentation for symbols
• definition: Go to definition of variables, functions, classes, types, etc.
• references: Find all references to a symbol across the project
• implementation: Go to implementation of interface/abstract methods
• typeDefinition: Go to type definition rather than variable declaration

🔍 Moderate Operations (Use with Pagination)

• symbols: Get all symbols in a file or search workspace symbols (supports pagination)
• rename: Safely rename symbols across all files in the project

🔄 Variable Performance Operations

• completion: Get IntelliSense completion suggestions with type info (supports pagination)
  • Note: May be slower in complex files with many imports. Use pagination to limit response size.

⏳ Slow Operations (Use Sparingly)

• codeActions: Get quick fixes, refactoring suggestions, and auto-imports
  • Warning: Can be slow (10-20s) in complex files with many imports. Use only for specific debugging tasks.
• signatureHelp: Get function parameter help and signatures
  • Warning: Can timeout (10-20s) in complex files with many imports. Use only when analyzing specific function calls.

Performance Guidelines for LLM Agents

Recommended Workflow:

1. Start with fast operations (⚡) for exploration and navigation
2. Use moderate operations (🔍) with pagination for broader searches
3. Use variable operations (🔄) with small limits for IntelliSense features
4. Reserve slow operations (⏳) for specific debugging or when the user explicitly requests them

Example Agent Strategy:

✅ Good: Use hover + definition + references frequently for code understanding
✅ Good: Use symbols with limit=20 for quick overviews
⚠️  Careful: Use completion with limit=10 for targeted suggestions
❌ Avoid: Using codeActions or signatureHelp in tight loops

Pagination Support

Large result sets from completion and symbols tools support pagination to handle massive TypeScript projects:

Completion Pagination:

{
  "filePath": "/path/to/file.ts",
  "line": 10,
  "character": 5,
  "limit": 50,
  "offset": 0,
  "sortText": "myVar"
}

Symbols Pagination:

{
  "query": "Component",
  "limit": 100,
  "offset": 0,
  "kind": "class"
}

Response includes pagination metadata:

{
  "items": [...],
  "total": 1247,
  "hasMore": true,
  "offset": 0,
  "limit": 50
}

Code Modification

• rename: Safely rename symbols across all files in the project

Testing

Comprehensive Test Suite

Run the complete test suite (60 tests covering all components):

npm test

Performance Benchmarks

Run performance benchmarks (8 benchmark tests):

npm test -- tests/performance/benchmark.test.ts

Legacy Performance Testing

Test current performance features:

npm run build
node quick-perf-test.js

Expected results with native TSServer, caching, pooling, and incremental sync:

✅ First: ~300ms (initial TSServer connection)
✅ Second: ~200ms (30%+ speedup from caching)
✅ File changes: ~1ms (95%+ speedup from incremental sync)
✅ No changes: ~0ms (instant detection)
✅ Concurrent: ~200ms (connection reuse)
✅ Cross-file errors: Correctly detected (was broken in v0.5.6)

Development

npm install
npm run build
npm test              # Run comprehensive test suite
npm run dev -- --workspace /path/to/project

Test Coverage

• Unit Tests: Complete coverage of all core components
  • FileCache (LRU algorithm, memory management, eviction)
  • ConnectionPool (lifecycle, health checks, cleanup)
  • IncrementalSyncManager (diff algorithm, hash detection)
  • ConfigManager (environment variables, validation)
• Integration Tests: End-to-end MCP server functionality
• Performance Benchmarks: Realistic performance validation with thresholds

Architecture

• File Cache (src/file-cache.ts): LRU cache with memory management
• Connection Pool (src/connection-pool.ts): TSServer connection lifecycle management
• Incremental Sync (src/incremental-sync.ts): Delta-based file synchronization
• TSServer Manager (src/tsserver-manager.ts): Orchestrates caching, pooling, and incremental updates
• Config Manager (src/config-manager.ts): Handles configuration and environment variables