TypeScript Diagnostics MCP

Live TypeScript type checking without constant recompilation - A Model Context Protocol (MCP) server that provides real-time TypeScript diagnostics with intelligent caching, perfect for AI agents working in TypeScript codebases.

The Problem

When multiple AI agents work simultaneously in a TypeScript codebase, they often run tsc or type-check commands repeatedly, causing:

• Massive performance degradation - Each agent triggers full recompilation
• System slowdown - Multiple concurrent TypeScript processes consume CPU/memory
• Redundant work - Same files get type-checked repeatedly
• Poor agent responsiveness - Agents wait for slow compilation before proceeding

The Solution

ts-diagnostics-mcp runs TypeScript's compiler in watch mode once, maintaining a live cache of diagnostics that all agents can query instantly:

• 80-95% faster than running tsc repeatedly
• Single background process serves all agents
• Instant queries - milliseconds instead of seconds
• Monorepo support - handles multiple packages seamlessly
• Smart caching - LRU cache with file-level granularity

Features

• Real-time TypeScript diagnostics via MCP
• Monorepo support - Auto-detects pnpm, yarn, npm workspaces, Rush, Lerna
• Intelligent caching - LRU cache with configurable size limits
• Package filtering - Query diagnostics by workspace package
• Fast queries - has_errors() in microseconds
• Watch mode - TypeScript Compiler API with incremental builds
• Zero configuration - Auto-detects project structure
• Flexible - Works with single projects and monorepos

Installation

No installation required! Just configure and run via npx.

Claude Desktop

1. Edit your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this configuration:

{
  "mcpServers": {
    "ts-diagnostics": {
      "command": "npx",
      "args": [
        "-y",
        "ts-diagnostics-mcp@latest",
        "/absolute/path/to/your/typescript/project"
      ]
    }
  }
}

3. Restart Claude Desktop

Claude Code (CLI)

Add to your .mcp.json:

{
  "mcpServers": {
    "ts-diagnostics": {
      "command": "npx",
      "args": [
        "-y",
        "ts-diagnostics-mcp@latest",
        "/absolute/path/to/your/typescript/project"
      ]
    }
  }
}

Alternative: Global Install

If you prefer a global installation:

npm install -g ts-diagnostics-mcp

Then configure with:

{
  "mcpServers": {
    "ts-diagnostics": {
      "command": "ts-diagnostics-mcp",
      "args": ["/absolute/path/to/your/project"]
    }
  }
}

Quick Start

1. Configure (see Installation above)

2. Start Using in Claude

Hey Claude, check if there are any TypeScript errors in the project.

Claude will use the has_errors tool to instantly check without running tsc!

Usage Examples

For AI Agents

# Quick error check (microseconds)
Tool: has_errors
Result: { "hasErrors": true }

# Get all errors across project
Tool: get_all_diagnostics
Result: { errors: 12, warnings: 3, diagnostics: [...] }

# Check specific file
Tool: get_file_diagnostics
Args: { "filePath": "src/server/auth.ts" }

# Get diagnostics for specific package (monorepo)
Tool: get_package_diagnostics
Args: { "packageName": "@degentalk/server" }

# Get summary counts
Tool: get_diagnostic_count
Result: { errors: 12, warnings: 3, suggestions: 0 }

# List available packages
Tool: list_packages
Result: { packages: ["@degentalk/app", "@degentalk/server", ...] }

Available MCP Tools

Tool	Description	Speed
has_errors	Boolean check for errors	Instant (μs)
get_diagnostic_count	Get error/warning counts	Instant (μs)
get_all_diagnostics	Get all diagnostics	Fast (ms)
get_file_diagnostics	Get diagnostics for specific file	Fast (ms)
get_package_diagnostics	Get diagnostics for package	Fast (ms)
get_watch_status	Check watch process status	Instant
get_cache_stats	View cache performance	Instant
list_packages	List monorepo packages	Instant
clear_cache	Clear diagnostic cache	Instant

Configuration

Auto-Detection (Default)

No configuration needed! The server auto-detects:

• Monorepo type (pnpm, yarn, npm, Rush, Lerna)
• Workspace packages
• TypeScript configs

Custom Configuration

Create .ts-diagnostics.json in your project root:

{
  "maxCacheSize": 100,
  "debounceMs": 500,
  "enableIncrementalMode": true,
  "autoDetectWorkspaces": true,
  "ignorePatterns": [
    "**/*.test.ts",
    "**/*.spec.ts",
    "**/test/**",
    "**/migrations/**"
  ]
}

Default Ignore Patterns (always applied):

• **/node_modules/**
• **/dist/**
• **/build/**
• **/.git/**
• **/coverage/**
• **/.next/**
• **/.turbo/**
• **/.cache/**
• **/out/**
• **/*.min.js
• **/*.bundle.js
• **/.tsbuildinfo

Add your own patterns to exclude additional files from diagnostics.

Environment Variables

TS_DIAG_MAX_CACHE_SIZE=200     # Cache size in MB
TS_DIAG_DEBOUNCE_MS=300        # Debounce delay
TS_DIAG_INCREMENTAL=true       # Enable incremental builds
TS_DIAG_AUTO_DETECT=true       # Auto-detect workspaces

Manual Configuration

For complex setups, specify configs manually:

{
  "projectRoot": "/path/to/project",
  "tsConfigs": [
    {
      "configPath": "/path/to/packages/app/tsconfig.json",
      "name": "@myapp/app",
      "rootDir": "/path/to/packages/app"
    },
    {
      "configPath": "/path/to/packages/server/tsconfig.json",
      "name": "@myapp/server",
      "rootDir": "/path/to/packages/server"
    }
  ]
}

Monorepo Support

Supported Monorepo Tools

• ✅ pnpm workspaces (via pnpm-workspace.yaml)
• ✅ Yarn workspaces (via package.json workspaces)
• ✅ npm workspaces (via package.json workspaces)
• ✅ Rush (via rush.json)
• ✅ Lerna (via lerna.json)

Example: Monorepo Structure

# Project structure
my-monorepo/
├── packages/
│   ├── app/tsconfig.json
│   ├── server/tsconfig.json
│   ├── db/tsconfig.json
│   └── shared/tsconfig.json
├── pnpm-workspace.yaml
└── tsconfig.base.json

# Auto-detected configs:
# - @myapp/app
# - @myapp/server
# - @myapp/db
# - @myapp/shared

Agents can query specific packages:

Tool: get_package_diagnostics
Args: { "packageName": "@myapp/server" }

Performance Benchmarks

Scenario: 4 AI agents working on a TypeScript monorepo

Method	Time	CPU Usage	Result
Running tsc directly (4x)	~45s total	100% spike	System lag
Using ts-diagnostics-mcp	~2.3s first, <50ms cached	<15% steady	Smooth

Performance Gains:

• 95%+ reduction in type-check time (cached queries)
• 80%+ reduction in CPU usage
• Near-instant feedback for agents

Architecture

┌─────────────────────────────────────────────────┐
│  AI Agents (Claude, GPT, etc.)                  │
│  ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐       │
│  │Agent1│  │Agent2│  │Agent3│  │Agent4│       │
│  └──┬───┘  └──┬───┘  └──┬───┘  └──┬───┘       │
└─────┼────────┼────────┼────────┼──────────────┘
      │        │        │        │
      └────────┴────────┴────────┘
               │ MCP Protocol
      ┌────────▼──────────────────┐
      │  ts-diagnostics-mcp       │
      │  ┌─────────────────────┐  │
      │  │   Query Router      │  │
      │  │  (Package Filter)   │  │
      │  └─────────┬───────────┘  │
      │  ┌─────────▼───────────┐  │
      │  │  LRU Cache Layer    │  │
      │  │  (100MB default)    │  │
      │  └─────────┬───────────┘  │
      │  ┌─────────▼───────────┐  │
      │  │ TypeScript Watch    │  │
      │  │ (Compiler API)      │  │
      │  └─────────┬───────────┘  │
      └────────────┼───────────────┘
                   │
      ┌────────────▼───────────────┐
      │  TypeScript Source Files   │
      │  (Auto-recompiles)         │
      └────────────────────────────┘

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Development mode (watch)
pnpm dev

# Type check
pnpm typecheck

Testing Locally

# Build the MCP server
cd ts-diagnostics-mcp
npm install
npm run build

# Run directly with your project
node dist/index.js /path/to/your/typescript/project

Troubleshooting

MCP Server Not Responding

Check if the watch process is active:

Tool: get_watch_status

High Memory Usage

Reduce cache size:

export TS_DIAG_MAX_CACHE_SIZE=50

Diagnostics Out of Date

Clear the cache to force refresh:

Tool: clear_cache

Contributing

Contributions welcome! This is an open-source project.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License - see LICENSE file for details

Credits

Built with:

• TypeScript Compiler API
• Model Context Protocol SDK
• LRU Cache

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ for AI agents working in TypeScript