Skip to main content
Glama
GNARC0TICS

ts-diagnostics-mcp

by GNARC0TICS
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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

Related MCP server: agent-workspace-mcp

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"
      ]
    }
  }
}

  1. 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:

Support

Made with ❤️ for AI agents working in TypeScript

Install Server
A
license - permissive license
A
quality
D
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/GNARC0TICS/ts-diagnostics-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server