Content
# MCP Diagnostics Extension
<!-- Marketplace & Distribution Badges -->
[](https://marketplace.visualstudio.com/items?itemName=newbpydev.mcp-diagnostics-extension)
[](https://marketplace.visualstudio.com/items?itemName=newbpydev.mcp-diagnostics-extension)
[](https://marketplace.visualstudio.com/items?itemName=newbpydev.mcp-diagnostics-extension)
[](https://marketplace.visualstudio.com/items?itemName=newbpydev.mcp-diagnostics-extension)
<!-- Build & Quality Badges -->
[](https://github.com/newbpydev/mcp-diagnostics-extension/actions/workflows/ci-cd.yml)
[](https://github.com/newbpydev/mcp-diagnostics-extension/actions/workflows/release.yml)
[](https://github.com/newbpydev/mcp-diagnostics-extension/actions)
[](https://github.com/newbpydev/mcp-diagnostics-extension/actions)
<!-- Technology & Standards Badges -->
[](https://www.typescriptlang.org/)
[](https://code.visualstudio.com/)
[](https://github.com/modelcontextprotocol/typescript-sdk)
[](https://nodejs.org/)
<!-- License & Security Badges -->
[](https://opensource.org/licenses/MIT)
[](https://github.com/newbpydev/mcp-diagnostics-extension/security/policy)
[](https://github.com/newbpydev/mcp-diagnostics-extension/network/dependencies)
<!-- Project Status & Community Badges -->
[](https://github.com/newbpydev/mcp-diagnostics-extension/releases)
[](https://github.com/newbpydev/mcp-diagnostics-extension/issues)
[](https://github.com/newbpydev/mcp-diagnostics-extension/stargazers)
[](https://conventionalcommits.org/)
---
**🏆 A production-ready VS Code extension that exposes diagnostic problems (errors, warnings, etc.) in real-time via the Model Context Protocol (MCP) for seamless consumption by AI agents and MCP-enabled tools.**
## 🎯 **EXCEPTIONAL ACHIEVEMENTS**
### **🏆 World-Class Quality Standards**
- **✅ 810 Tests Passing** - Comprehensive test coverage with 0 failures (1 skipped)
- **✅ 97.99% Statement Coverage** - Exceeding industry standards (95%+ target)
- **✅ Production-Ready Architecture** - Clean Architecture with dependency injection
- **✅ Professional CI/CD Pipeline** - Multi-platform testing and automated releases
- **✅ Zero External Dependencies** - Native implementations for maximum reliability
### **🚀 Performance Excellence**
- **⚡ <2s Extension Activation** - Lightning-fast startup performance
- **⚡ <500ms Diagnostic Processing** - Real-time problem monitoring
- **⚡ <100ms MCP Tool Response** - Instant AI agent integration
- **💾 <50MB Memory Baseline** - Efficient resource utilization
- **📊 10,000+ File Workspace Support** - Enterprise-scale capability
### **🔧 Advanced Technical Implementation**
- **🎯 Event-Driven Architecture** - Loose coupling via EventEmitter patterns
- **🛡️ Robust Error Handling** - Comprehensive error recovery mechanisms
- **📈 Performance Monitoring** - Built-in metrics and optimization
- **🔄 Real-time Synchronization** - Live diagnostic updates via MCP notifications
- **🌐 Cross-Platform Compatibility** - Windows, macOS, Linux support with intelligent spawn handling
### **✨ Latest Features (v1.4.0)**
- **🔧 Cross-Platform Utilities** - Smart platform detection and spawn option handling
- **⚙️ Configuration Validation** - Automatic validation and enhancement of MCP client configurations
- **📊 Enhanced Export System** - Continuous diagnostic data export for standalone MCP server integration
- **🎨 Improved Status Display** - Better visual indicators and error reporting
- **🛠️ Automated Setup** - One-click MCP server registration across different environments
### **🚀 NEW: v1.4.0 - Auto-Server Injection & Advanced Diagnostics**
- **🤖 Automatic MCP Server Registration** - One-click deployment and configuration across VS Code, Cursor, and other MCP clients
- **📊 Cross-Platform Diagnostic Analysis** - Enhanced TypeScript and ESLint analysis with background workspace scanning
- **⚙️ Configuration Manager** - Atomic configuration injection with backup and rollback capabilities
- **🔧 Server Installation Utilities** - Automated bundled server deployment with version management
- **🛠️ Enhanced Command System** - New `configureServer` command for automated MCP setup
- **📈 Improved Performance Monitoring** - Advanced timer management and memory leak prevention
- **🌐 Enhanced Cross-Platform Support** - Native spawn option handling for Windows, macOS, and Linux
- **🧪 Comprehensive Test Coverage** - 810 tests with 97.99% coverage including E2E and integration tests
## 🚀 What is this?
The MCP Diagnostics Extension bridges VS Code's powerful diagnostic system with the Model Context Protocol, enabling AI agents to access your code problems in real-time. Whether you're debugging TypeScript errors, ESLint warnings, or custom linter issues, this extension makes all diagnostic information instantly available to your AI tools.
### Why was this built?
- **🤖 AI-First Development**: Modern development increasingly relies on AI assistance. This extension ensures your AI tools have complete visibility into your codebase health.
- **⚡ Real-time Integration**: No more manually copying error messages or explaining problems to AI tools - they see everything instantly.
- **🔧 Universal Diagnostics**: Works with any VS Code diagnostic provider (TypeScript, ESLint, custom linters, etc.)
- **📊 Enhanced Productivity**: AI agents can provide more contextual help when they understand your current problems.
### What problem does it solve?
Before this extension, AI agents couldn't see your VS Code problems panel, making it difficult for them to:
- Understand compilation errors when suggesting fixes
- Provide relevant solutions for linting issues
- Help with project-wide diagnostic patterns
- Assist with debugging based on current error state
### Key Features Learned & Implemented
- **🔍 Real-time Diagnostics Monitoring**: Automatically captures all diagnostic problems from VS Code's Problems panel using advanced event debouncing (300ms configurable)
- **🤖 MCP Server Integration**: Exposes diagnostics through standardized MCP tools and resources with comprehensive filtering capabilities
- **⚡ Performance Optimized**: Handles large workspaces efficiently with smart caching and memory management (97.99% test coverage)
- **🏢 Multi-workspace Support**: Seamlessly works with complex project structures and multiple workspace folders
- **📡 Real-time Notifications**: Pushes diagnostic changes instantly to connected MCP clients with structured payloads
- **🎨 Enhanced Status Bar**: Color-coded status bar with red (errors), orange (warnings), green (clean) backgrounds and real-time updates
- **🎛️ Command Palette**: Full integration with VS Code commands for server management and detailed status viewing with webview
- **🔧 Highly Configurable**: Customizable port, debounce timing, logging options, and performance settings
- **🚀 Automatic Registration**: One-click setup with intelligent MCP server registration across different environments
- **🧪 Test Workspace**: Comprehensive testing environment with intentional errors for validation (810 tests passing)
- **🛡️ Robust Error Handling**: Graceful degradation and comprehensive error recovery mechanisms
- **🌐 Cross-Platform Support**: Native Windows, macOS, and Linux compatibility with platform-specific optimizations
## 📦 Installation
### From VS Code Marketplace (Recommended)
1. **Open VS Code**
2. **Go to Extensions** (Ctrl+Shift+X / Cmd+Shift+X)
3. **Search for** "MCP Diagnostics Extension"
4. **Click Install**
5. **Reload VS Code** if prompted
The extension will automatically activate and register itself as an MCP server.
### From VSIX File
1. Download the latest `.vsix` file from [GitHub Releases](https://github.com/newbpydev/mcp-diagnostics-extension/releases)
2. Open VS Code
3. Run command: `Extensions: Install from VSIX...`
4. Select the downloaded file
### From Source (Development)
```bash
# Clone the repository
git clone https://github.com/newbpydev/mcp-diagnostics-extension.git
cd mcp-diagnostics-extension
# Install dependencies
npm install
# Compile TypeScript
npm run compile
# Launch Extension Development Host
# Press F5 in VS Code or run:
code --extensionDevelopmentPath=.
```
## 🚀 Quick Start
### 1. **Installation & Activation**
After installing from the marketplace, the extension automatically:
- ✅ Activates when VS Code starts
- ✅ Registers as an MCP server
- ✅ Starts monitoring diagnostics
- ✅ Shows status in the status bar
### 2. **Verify It's Working**
Look for the status bar item: `$(bug) MCP: XE YW` (X errors, Y warnings)
### 3. **Connect Your MCP Client**
Add to your MCP client configuration:
```json
{
"mcpServers": {
"vscode-diagnostics": {
"command": "node",
"args": ["scripts/mcp-server.js"],
"cwd": "/path/to/mcp-diagnostics-extension",
"env": {
"NODE_ENV": "production",
"MCP_DEBUG": "false"
}
}
}
}
```
### 4. **Start Using MCP Tools**
Your AI agent can now access three powerful tools:
- `getProblems` - Get all diagnostics with filtering
- `getProblemsForFile` - Get problems for specific files
- `getWorkspaceSummary` - Get workspace-wide statistics
## 🚀 **AUTO-DEPLOYMENT & ONE-CLICK SETUP** (Sprint 4 Feature)
### **⚡ Automatic MCP Server Registration**
The extension now features **one-click automatic setup** that eliminates all manual configuration! This breakthrough feature automatically:
- ✅ **Deploys bundled MCP server** to user directory with proper permissions
- ✅ **Injects configuration** into Cursor IDE and other MCP clients
- ✅ **Validates deployment** with atomic operations and backup creation
- ✅ **Cross-platform support** with Windows/macOS/Linux compatibility
- ✅ **Error recovery** with graceful fallback to manual setup
### **🎯 How Auto-Deployment Works**
```mermaid
graph TD
A[🔧 User Runs Configure Server Command] --> B[📋 Progress Notification Shown]
B --> C[📦 Deploy Bundled Server]
C --> D{🔍 Server Exists?}
D -->|No| E[📂 Create Installation Directory]
D -->|Yes| F[📋 Check Version]
F -->|Newer| E
F -->|Same/Older| G[✅ Skip Deployment]
E --> H[📋 Copy Server Binary]
H --> I[🔐 Set Executable Permissions]
I --> J[📄 Persist Manifest]
J --> K[🔧 Inject Configuration]
G --> K
K --> L[🔍 Locate Config File]
L --> M{📁 Config Exists?}
M -->|Yes| N[📋 Load & Validate]
M -->|No| O[📄 Create Default Config]
N --> P[🔄 Deep Merge Configurations]
O --> P
P --> Q[💾 Atomic Write Operation]
Q --> R[✅ Backup Creation]
R --> S[📋 Validate Final Config]
S --> T[🎉 Success Notification]
%% Error Paths
C -.->|Error| U[❌ Deployment Failed]
K -.->|Error| V[❌ Configuration Failed]
U --> W[📖 Show Manual Setup Guide]
V --> W
%% Styling
classDef success fill:#d4edda,stroke:#155724,color:#155724
classDef error fill:#f8d7da,stroke:#721c24,color:#721c24
classDef process fill:#cce5ff,stroke:#004085,color:#004085
class T success
class U,V,W error
class A,B,C,E,H,I,J,K,L,N,O,P,Q,R,S process
```
### **📋 Auto-Configuration Injection Process**
```mermaid
sequenceDiagram
participant User
participant ExtensionCommands
participant ServerDeployment
participant McpServerRegistration
participant FileSystem
participant VSCode
User->>ExtensionCommands: Execute "Configure Server"
ExtensionCommands->>VSCode: Show Progress Notification
Note over ExtensionCommands,ServerDeployment: Phase 1: Server Deployment
ExtensionCommands->>ServerDeployment: deployBundledServer()
ServerDeployment->>FileSystem: Check installation directory
FileSystem-->>ServerDeployment: Directory status
ServerDeployment->>FileSystem: Atomic copy & permissions
FileSystem-->>ServerDeployment: Deployment complete
ServerDeployment-->>ExtensionCommands: Server path
Note over ExtensionCommands,McpServerRegistration: Phase 2: Configuration Injection
ExtensionCommands->>McpServerRegistration: injectConfiguration()
McpServerRegistration->>FileSystem: Locate config file (priority order)
FileSystem-->>McpServerRegistration: Config path
McpServerRegistration->>FileSystem: Load existing config
FileSystem-->>McpServerRegistration: Config data
McpServerRegistration->>McpServerRegistration: Deep merge with validation
McpServerRegistration->>FileSystem: Atomic write with backup
FileSystem-->>McpServerRegistration: Write complete
McpServerRegistration-->>ExtensionCommands: Configuration complete
ExtensionCommands->>VSCode: Success notification
VSCode-->>User: "MCP server configured successfully!"
Note over User,VSCode: Alternative: Error Handling
ExtensionCommands->>VSCode: Error notification (if failed)
VSCode-->>User: Show manual setup guide
```
### **🏗️ Auto-Deployment Architecture**
```mermaid
graph LR
subgraph "📦 Bundled Assets"
A[scripts/mcp-server.js]
B[Server Manifest]
C[Configuration Template]
end
subgraph "🔧 Core Components"
D[ServerInstallUtils]
E[ServerDeployment]
F[McpServerRegistration]
G[ExtensionCommands]
end
subgraph "💾 User Environment"
H[~/.mcp-diagnostics/]
I[.cursor/mcp.json]
J[IDE Configuration]
end
subgraph "🛡️ Safety Features"
K[Atomic Operations]
L[Backup Creation]
M[Version Validation]
N[Permission Checks]
end
A --> D: Bundled Server
D --> E: Installation Utils
E --> F: Deployment Service
F --> G: Registration Service
G --> H: Deploy to User Dir
F --> I: Inject Config
I --> J: Configure IDE
K --> E: Ensure Atomicity
L --> F: Create Backups
M --> E: Version Control
N --> D: Security Checks
%% Styling
classDef bundled fill:#fff3cd,stroke:#856404,color:#856404
classDef core fill:#cce5ff,stroke:#004085,color:#004085
classDef user fill:#d4edda,stroke:#155724,color:#155724
classDef safety fill:#f8d7da,stroke:#721c24,color:#721c24
class A,B,C bundled
class D,E,F,G core
class H,I,J user
class K,L,M,N safety
```
### **⚙️ Configuration File Priorities**
```mermaid
graph TD
A[🔍 Configuration Discovery] --> B[📁 Check Workspace .cursor/mcp.json]
B --> C{✅ Exists?}
C -->|Yes| D[🎯 Use Workspace Config]
C -->|No| E[📁 Check User Home .cursor/mcp.json]
E --> F{✅ Exists?}
F -->|Yes| G[🏠 Use User Config]
F -->|No| H[📄 Create New Configuration]
D --> I[🔄 Load & Parse JSON]
G --> I
H --> J[📋 Generate Default Config]
J --> I
I --> K[✅ Validate with Zod Schema]
K --> L[🔄 Deep Merge with Diagnostics Server]
L --> M[💾 Atomic Write with Backup]
%% Styling
classDef primary fill:#007bff,stroke:#ffffff,color:#ffffff
classDef success fill:#28a745,stroke:#ffffff,color:#ffffff
classDef process fill:#17a2b8,stroke:#ffffff,color:#ffffff
class D,G primary
class H,J,M success
class I,K,L process
```
### **🎛️ One-Click Setup Commands**
#### **`MCP Diagnostics: Configure Server`** ⚡
**The magic command that does everything automatically!**
Access via Command Palette (Ctrl+Shift+P / Cmd+Shift+P):
1. **Search**: "MCP Diagnostics: Configure Server"
2. **Click**: Command executes automatically
3. **Watch**: Progress notification shows deployment status
4. **Result**: Either success notification OR manual setup guide
**What it does:**
- ✅ Deploys server to `~/.mcp-diagnostics/mcp-server.js`
- ✅ Sets proper executable permissions (Unix/Linux)
- ✅ Creates version manifest for future upgrades
- ✅ Locates your MCP configuration file (workspace → user home)
- ✅ Preserves existing MCP servers during injection
- ✅ Validates configuration with JSON schema
- ✅ Creates backup before any changes
- ✅ Provides manual setup fallback if automatic fails
### **📊 Cross-Platform Deployment Support**
| Platform | Install Path | Executable | Spawn Options |
| ----------- | --------------------------------- | --------------- | ------------------------ |
| **Windows** | `%USERPROFILE%\.mcp-diagnostics\` | ❌ Not required | `shell: true` (required) |
| **macOS** | `~/.mcp-diagnostics/` | ✅ `chmod +x` | `shell: false` |
| **Linux** | `~/.mcp-diagnostics/` | ✅ `chmod +x` | `shell: false` |
### **🛡️ Security & Reliability Features**
#### **Atomic Operations**
```typescript
// All file operations are atomic to prevent corruption
1. Write to temporary file (.tmp)
2. Validate written content
3. Atomic rename to final location
4. Clean up temporary files
```
#### **Backup Strategy**
```typescript
// Automatic backup creation before any changes
- Original config → config.backup
- Malformed config → config.malformed.backup
- Restore on validation failure
```
#### **Version Management**
```typescript
// Smart version detection and upgrade handling
- Compare semantic versions (1.2.3 format)
- Skip deployment if same/older version
- Automatic upgrade for newer versions
```
### **🚨 Error Handling & Recovery**
The auto-deployment system includes comprehensive error handling:
| Error Type | Recovery Strategy |
| --------------------- | ------------------------------------------------ |
| **Permission Denied** | Show manual setup with elevated privileges guide |
| **Disk Space** | Alert user and provide cleanup recommendations |
| **Network Issues** | Use bundled assets with offline deployment |
| **Config Corruption** | Create backup and initialize fresh configuration |
| **Version Conflicts** | Smart merge with user preference preservation |
### **📈 Performance Metrics**
Sprint 4 auto-deployment meets strict performance requirements:
- ⚡ **Deployment Time**: <2 seconds for complete setup
- ⚡ **Configuration Injection**: <500ms including validation
- ⚡ **Memory Usage**: <10MB additional during deployment
- ⚡ **File Operations**: Atomic with <100ms overhead
- ⚡ **Cross-Platform**: Universal compatibility with intelligent spawn detection
---
## 🛠️ Usage Guide
### Available Commands
Access via Command Palette (Ctrl+Shift+P / Cmd+Shift+P):
- **`MCP Diagnostics: Show Status`** - Opens detailed status webview with:
- Server connection status
- Problem statistics by severity and source
- File-by-file breakdown
- Workspace folder information
- Performance metrics
- **`MCP Diagnostics: Restart Server`** - Restarts the MCP server with progress indication
- **`MCP Diagnostics: Show Setup Guide`** - Opens comprehensive setup guide for MCP client configuration
### MCP Tools Reference
#### 🔍 `getProblems` - Universal Problem Query
Get all diagnostic problems with powerful filtering options:
```json
{
"name": "getProblems",
"arguments": {
"filePath": "/path/to/file.ts", // Optional: filter by specific file
"severity": "Error", // Optional: Error, Warning, Information, Hint
"workspaceFolder": "my-project", // Optional: filter by workspace
"source": "typescript", // Optional: filter by diagnostic source
"limit": 100, // Optional: limit results (default: 1000)
"offset": 0 // Optional: pagination offset
}
}
```
**Example Response:**
```json
{
"content": [
{
"type": "text",
"text": "[{\"filePath\":\"/workspace/src/app.ts\",\"severity\":\"Error\",\"message\":\"Cannot find name 'foo'\",\"range\":{\"start\":{\"line\":10,\"character\":5},\"end\":{\"line\":10,\"character\":8}},\"source\":\"typescript\",\"workspaceFolder\":\"/workspace\",\"code\":\"2304\"}]"
}
]
}
```
#### 📄 `getProblemsForFile` - File-Specific Diagnostics
Get all problems for a specific file:
```json
{
"name": "getProblemsForFile",
"arguments": {
"filePath": "/absolute/path/to/file.ts"
}
}
```
#### 📊 `getWorkspaceSummary` - Workspace Statistics
Get comprehensive workspace diagnostic statistics:
```json
{
"name": "getWorkspaceSummary",
"arguments": {
"groupBy": "severity" // Optional: severity, source, workspaceFolder
}
}
```
**Example Response:**
```json
{
"content": [
{
"type": "text",
"text": "{\"totalProblems\":15,\"byFile\":{\"app.ts\":3,\"utils.ts\":2},\"bySeverity\":{\"Error\":5,\"Warning\":10},\"bySource\":{\"typescript\":8,\"eslint\":7},\"byWorkspace\":{\"main\":15},\"timestamp\":\"2024-01-15T10:30:00.000Z\"}"
}
]
}
```
### MCP Resources
Dynamic resources providing structured access to diagnostic data:
- **`diagnostics://summary`** - Overall workspace problems summary
- **`diagnostics://file/{encodedFilePath}`** - Problems for specific file
- **`diagnostics://workspace/{encodedWorkspaceName}`** - Problems for specific workspace
### Real-time Notifications
The server automatically sends `problemsChanged` notifications when diagnostics change:
```json
{
"method": "notifications/message",
"params": {
"level": "info",
"data": {
"type": "problemsChanged",
"uri": "/path/to/file.ts",
"problemCount": 3,
"problems": [...],
"timestamp": "2024-01-15T10:30:00.000Z"
}
}
}
```
## ⚙️ Configuration
Customize the extension via VS Code settings (`Ctrl+,` / `Cmd+,`):
```json
{
"mcpDiagnostics.server.port": 6070,
"mcpDiagnostics.debounceMs": 300,
"mcpDiagnostics.enableDebugLogging": false,
"mcpDiagnostics.enablePerformanceLogging": false,
"mcpDiagnostics.maxProblemsPerFile": 1000,
"mcpDiagnostics.debug.logLevel": "info",
"mcpDiagnostics.showAutoRegistrationNotification": true
}
```
### Configuration Options
| Setting | Type | Default | Description |
| ---------------------------------- | ------- | ------- | --------------------------------------------------- |
| `server.port` | number | 6070 | MCP server port (1024-65535) |
| `debounceMs` | number | 300 | Debounce interval for diagnostic events (50-5000ms) |
| `enableDebugLogging` | boolean | false | Enable detailed debug logging |
| `enablePerformanceLogging` | boolean | false | Enable performance metrics logging |
| `maxProblemsPerFile` | number | 1000 | Maximum problems to track per file (1-10000) |
| `debug.logLevel` | string | "info" | Logging level (error, warn, info, debug) |
| `showAutoRegistrationNotification` | boolean | true | Show MCP server registration notifications |
## 🧪 Testing & Development
### **🏆 Exceptional Test Coverage Achievement**
The extension has achieved **world-class testing standards**:
- **✅ 810 Tests Passing** - Comprehensive test suite with 0 failures (1 skipped)
- **✅ 97.99% Statement Coverage** - Exceeding industry standards
- **✅ 34 Test Suites** - Organized, maintainable test structure across all components
- **✅ Cross-Platform Testing** - Validated on Windows, macOS, and Linux environments
- **✅ Comprehensive E2E Testing** - Full extension workflow validation
### Real vs Mock Server
The extension provides **two operational modes**:
#### 🔴 **Real VS Code Extension** (Production Mode)
- **Purpose**: Production use with actual VS Code diagnostics
- **Data Source**: Live VS Code Problems panel
- **Activation**: Automatic when extension is installed
- **Use Case**: Real development workflows with AI agents
#### 🔧 **Development Tools**
- **Package Validation**: `scripts/validate-package.sh` - Automated package integrity checks
- **Asset Conversion**: `scripts/convert-assets.js` - Visual asset optimization utilities
### Test Workspace
The extension includes `test-workspace/` with intentional errors:
- **`example.ts`**: TypeScript errors (type mismatches, undefined variables, invalid assignments)
- **`utils.js`**: ESLint warnings (unused variables, style issues, best practice violations)
**To test the extension:**
1. **Launch Extension Development Host** (Press F5 in VS Code)
2. **Open test workspace** or any workspace with diagnostic issues
3. **View Problems panel** (Ctrl+Shift+M) to see real diagnostics
4. **Use MCP tools** to query the diagnostic data
5. **Check status bar** for live error/warning counts
### Development Setup
```bash
# Install dependencies
npm install
# Run tests (810 tests)
npm test
# Run tests with coverage
npm run test:coverage
# Lint code
npm run lint
# Format code
npm run format
# Compile TypeScript
npm run compile
# Package extension
npm run package
# Run CI checks
npm run ci:check
```
## 🔧 MCP Client Configuration
The extension provides a **universal MCP server** that works with all major MCP-enabled environments. The server runs as a standalone Node.js process and provides real-time diagnostic data from your workspace.
### 🎯 **Universal Configuration Pattern**
All MCP clients use the same basic configuration pattern with environment-specific variations:
```json
{
"mcpServers": {
// or "servers" for some clients
"vscode-diagnostics": {
"command": "node",
"args": ["scripts/mcp-server.js"],
"cwd": "/path/to/mcp-diagnostics-extension",
"env": {
"NODE_ENV": "production",
"MCP_DEBUG": "false"
}
}
}
}
```
### 📁 **Configuration File Locations**
| Environment | Configuration File | Format |
| ------------------ | ---------------------------- | -------------------------------- |
| **Cursor IDE** | `.cursor/mcp.json` | `mcpServers` |
| **VS Code** | `.vscode/mcp.json` | `servers` (with `type: "stdio"`) |
| **Windsurf** | `.windsurf/mcp.json` | `servers` |
| **Claude Desktop** | `claude_desktop_config.json` | `mcpServers` |
### MCP Client Configuration Examples
#### Cursor IDE
```json
// .cursor/mcp.json or cursor-mcp-config.json
{
"mcpServers": {
"vscode-diagnostics": {
"command": "node",
"args": ["scripts/mcp-server.js"],
"cwd": "/path/to/mcp-diagnostics-extension",
"env": {
"NODE_ENV": "production",
"MCP_DEBUG": "false"
}
}
}
}
```
#### VS Code with MCP Extension
```json
// .vscode/mcp.json
{
"servers": {
"vscode-diagnostics": {
"type": "stdio",
"command": "node",
"args": ["scripts/mcp-server.js"],
"cwd": "/path/to/mcp-diagnostics-extension",
"env": {
"NODE_ENV": "production",
"MCP_DEBUG": "false"
}
}
}
}
```
#### Windsurf IDE
```json
// .windsurf/mcp.json
{
"servers": {
"vscode-diagnostics": {
"command": "node",
"args": ["scripts/mcp-server.js"],
"cwd": "/path/to/mcp-diagnostics-extension",
"env": {
"NODE_ENV": "production",
"MCP_DEBUG": "false"
}
}
}
}
```
#### Claude Desktop
```json
// claude_desktop_config.json
{
"mcpServers": {
"vscode-diagnostics": {
"command": "node",
"args": ["scripts/mcp-server.js"],
"cwd": "/path/to/mcp-diagnostics-extension",
"env": {
"NODE_ENV": "production",
"MCP_DEBUG": "false"
}
}
}
}
```
#### Custom MCP Client
```typescript
import { Client } from '@modelcontextprotocol/client';
const client = new Client({
name: 'my-client',
version: '1.0.0',
});
// Connect to extension
await client.connect({
command: 'node',
args: ['scripts/mcp-server.js'],
cwd: '/path/to/mcp-diagnostics-extension',
env: {
NODE_ENV: 'production',
MCP_DEBUG: 'false',
},
});
// Use tools
const problems = await client.callTool({
name: 'getProblems',
arguments: { severity: 'Error' },
});
```
### 🚀 **MCP Server Features**
The `scripts/mcp-server.js` provides:
- **🔍 Real-time Diagnostics**: Live TypeScript and ESLint analysis
- **📊 VS Code Integration**: Automatic import of VS Code Problems panel data
- **⚡ Performance Optimized**: Cached results with smart refresh logic
- **🛡️ Error Recovery**: Graceful fallback when VS Code data unavailable
- **🔧 Configurable**: Environment variables for debugging and behavior control
### 🌍 **Environment Variables**
| Variable | Default | Description |
| ------------------ | ------------- | --------------------------------------------- |
| `NODE_ENV` | `development` | Set to `production` for optimized performance |
| `MCP_DEBUG` | `false` | Enable detailed debug logging |
| `REFRESH_INTERVAL` | `30000` | Cache refresh interval in milliseconds |
| `MAX_PROBLEMS` | `10000` | Maximum number of problems to cache |
### 🔄 **Data Sources**
The MCP server intelligently combines multiple data sources:
1. **VS Code Export** (Primary): Real-time data from the extension
2. **TypeScript Compiler** (Fallback): Direct `tsc` analysis
3. **ESLint** (Fallback): Direct ESLint analysis
4. **Cached Results** (Performance): Smart caching with automatic refresh
```
## 📚 Documentation
### Additional Resources
- **[MCP Server Guide](./MCP_SERVER_GUIDE.md)** - Comprehensive setup and configuration guide
- **[Quick Setup Guide](./QUICK_SETUP.md)** - Fast-track installation instructions
- **[Troubleshooting Guide](./TROUBLESHOOTING.md)** - Common issues and solutions
- **[Contributing Guide](./.github/CONTRIBUTING.md)** - Development and contribution guidelines
- **[Changelog](./CHANGELOG.md)** - Version history and release notes
- **[Security Policy](./.github/SECURITY.md)** - Security reporting and policies
### API Documentation
Comprehensive TypeScript documentation is available for all public APIs:
- **[DiagnosticsWatcher API](./src/core/diagnostics/)** - Core diagnostic monitoring
- **[MCP Tools API](./src/infrastructure/mcp/)** - MCP server implementation
- **[Extension Commands API](./src/commands/)** - VS Code command integration
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](./.github/CONTRIBUTING.md) for details.
### Quick Contribution Steps
1. **Fork the repository**
2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
3. **Make changes** following our coding standards
4. **Run tests**: `npm test` (all 810 tests must pass)
5. **Lint code**: `npm run lint`
6. **Commit changes**: `npm run commit` (uses conventional commits)
7. **Push to branch**: `git push origin feature/amazing-feature`
8. **Open a Pull Request**
### Development Requirements
- Node.js 22.x or higher
- VS Code 1.96.0 or higher
- TypeScript 5.8.3 or higher
## 🐛 Troubleshooting
### Common Issues
#### Extension Not Activating
1. Check VS Code version compatibility (requires 1.96.0+)
2. Look for activation errors in Developer Tools Console
3. Try reloading VS Code window (Ctrl+Shift+P → "Reload Window")
#### MCP Connection Issues
1. Verify MCP client configuration paths
2. Check that the extension is active (status bar shows MCP status)
3. Restart the MCP server: Command Palette → "MCP Diagnostics: Restart Server"
#### No Diagnostics Showing
1. Ensure you have files with actual errors/warnings open
2. Check VS Code Problems panel (Ctrl+Shift+M) - MCP data comes from here
3. Verify diagnostic providers (TypeScript, ESLint) are working
For more detailed troubleshooting, see our [Troubleshooting Guide](./TROUBLESHOOTING.md).
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
## 🙏 Acknowledgments
- **VS Code Team** - For the excellent extension API and diagnostic system
- **Model Context Protocol** - For the innovative protocol enabling AI agent integration
- **TypeScript Team** - For the robust type system and development experience
- **Jest Community** - For the comprehensive testing framework
- **Open Source Community** - For the tools and libraries that make this project possible
---
**🚀 Ready to supercharge your AI-assisted development workflow? Install the MCP Diagnostics Extension today and give your AI agents complete visibility into your codebase health!**
```
