{"id":28810328,"url":"https://github.com/newbpydev/mcp-diagnostics-extension","last_synced_at":"2026-05-06T04:01:58.903Z","repository":{"id":297671870,"uuid":"997538895","full_name":"newbpydev/mcp-diagnostics-extension","owner":"newbpydev","description":"VS Code extension that exposes diagnostic problems via Model Context Protocol (MCP) for AI agents and tools","archived":false,"fork":false,"pushed_at":"2025-06-13T19:21:18.000Z","size":1127,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-13T20:29:26.232Z","etag":null,"topics":["ai-agent-tools","ai-tools","clean-architecture","diagnostic-tool","diagnostics","extension-development","jest","mcp","model-context-protocol","problems-panel","real-time-monitoring","tdd","testing","typescript","vscode","vscode-extension"],"latest_commit_sha":null,"homepage":"https://marketplace.visualstudio.com/items?itemName=newbpydev.mcp-diagnostics-extension","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/newbpydev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-06T17:46:44.000Z","updated_at":"2025-06-12T19:04:52.000Z","dependencies_parsed_at":"2025-06-06T19:38:04.148Z","dependency_job_id":null,"html_url":"https://github.com/newbpydev/mcp-diagnostics-extension","commit_stats":null,"previous_names":["newbpydev/mcp-diagnostics-extension"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/newbpydev/mcp-diagnostics-extension","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newbpydev%2Fmcp-diagnostics-extension","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newbpydev%2Fmcp-diagnostics-extension/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newbpydev%2Fmcp-diagnostics-extension/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newbpydev%2Fmcp-diagnostics-extension/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/newbpydev","download_url":"https://codeload.github.com/newbpydev/mcp-diagnostics-extension/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newbpydev%2Fmcp-diagnostics-extension/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32677933,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T02:33:58.958Z","status":"ssl_error","status_checked_at":"2026-05-06T02:33:39.611Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent-tools","ai-tools","clean-architecture","diagnostic-tool","diagnostics","extension-development","jest","mcp","model-context-protocol","problems-panel","real-time-monitoring","tdd","testing","typescript","vscode","vscode-extension"],"created_at":"2025-06-18T14:01:01.052Z","updated_at":"2026-05-06T04:01:58.892Z","avatar_url":"https://github.com/newbpydev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Diagnostics Extension\n\n\u003c!-- Marketplace \u0026 Distribution Badges --\u003e\n\n[![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/newbpydev.mcp-diagnostics-extension.svg?style=flat-square\u0026logo=visual-studio-code\u0026color=007ACC)](https://marketplace.visualstudio.com/items?itemName=newbpydev.mcp-diagnostics-extension)\n[![Downloads](https://img.shields.io/visual-studio-marketplace/d/newbpydev.mcp-diagnostics-extension.svg?style=flat-square\u0026color=brightgreen)](https://marketplace.visualstudio.com/items?itemName=newbpydev.mcp-diagnostics-extension)\n[![Rating](https://img.shields.io/visual-studio-marketplace/r/newbpydev.mcp-diagnostics-extension.svg?style=flat-square\u0026color=yellow)](https://marketplace.visualstudio.com/items?itemName=newbpydev.mcp-diagnostics-extension)\n[![Installs](https://img.shields.io/visual-studio-marketplace/i/newbpydev.mcp-diagnostics-extension.svg?style=flat-square\u0026color=blue)](https://marketplace.visualstudio.com/items?itemName=newbpydev.mcp-diagnostics-extension)\n\n\u003c!-- Build \u0026 Quality Badges --\u003e\n\n[![CI/CD Pipeline](https://img.shields.io/github/actions/workflow/status/newbpydev/mcp-diagnostics-extension/ci-cd.yml?style=flat-square\u0026logo=github\u0026label=CI%2FCD)](https://github.com/newbpydev/mcp-diagnostics-extension/actions/workflows/ci-cd.yml)\n[![Release Pipeline](https://img.shields.io/github/actions/workflow/status/newbpydev/mcp-diagnostics-extension/release.yml?style=flat-square\u0026logo=github\u0026label=Release)](https://github.com/newbpydev/mcp-diagnostics-extension/actions/workflows/release.yml)\n[![Tests](https://img.shields.io/badge/tests-810%20passing-brightgreen?style=flat-square\u0026logo=jest)](https://github.com/newbpydev/mcp-diagnostics-extension/actions)\n[![Test Coverage](https://img.shields.io/badge/coverage-97.99%25-brightgreen?style=flat-square\u0026logo=jest)](https://github.com/newbpydev/mcp-diagnostics-extension/actions)\n\n\u003c!-- Technology \u0026 Standards Badges --\u003e\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.8.3-blue.svg?style=flat-square\u0026logo=typescript)](https://www.typescriptlang.org/)\n[![VS Code Engine](https://img.shields.io/badge/VS%20Code-1.96.0+-007ACC?style=flat-square\u0026logo=visual-studio-code)](https://code.visualstudio.com/)\n[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.12.1-purple?style=flat-square)](https://github.com/modelcontextprotocol/typescript-sdk)\n[![Node.js](https://img.shields.io/badge/Node.js-22.x-green?style=flat-square\u0026logo=node.js)](https://nodejs.org/)\n\n\u003c!-- License \u0026 Security Badges --\u003e\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)\n[![Security Policy](https://img.shields.io/badge/Security-Policy-red?style=flat-square\u0026logo=shield)](https://github.com/newbpydev/mcp-diagnostics-extension/security/policy)\n[![Dependabot](https://img.shields.io/badge/Dependabot-enabled-brightgreen?style=flat-square\u0026logo=dependabot)](https://github.com/newbpydev/mcp-diagnostics-extension/network/dependencies)\n\n\u003c!-- Project Status \u0026 Community Badges --\u003e\n\n[![GitHub Release](https://img.shields.io/github/v/release/newbpydev/mcp-diagnostics-extension?style=flat-square\u0026logo=github)](https://github.com/newbpydev/mcp-diagnostics-extension/releases)\n[![GitHub Issues](https://img.shields.io/github/issues/newbpydev/mcp-diagnostics-extension?style=flat-square\u0026logo=github)](https://github.com/newbpydev/mcp-diagnostics-extension/issues)\n[![GitHub Stars](https://img.shields.io/github/stars/newbpydev/mcp-diagnostics-extension?style=flat-square\u0026logo=github)](https://github.com/newbpydev/mcp-diagnostics-extension/stargazers)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=flat-square)](https://conventionalcommits.org/)\n\n---\n\n**🏆 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.**\n\n## 🎯 **EXCEPTIONAL ACHIEVEMENTS**\n\n### **🏆 World-Class Quality Standards**\n\n- **✅ 810 Tests Passing** - Comprehensive test coverage with 0 failures (1 skipped)\n- **✅ 97.99% Statement Coverage** - Exceeding industry standards (95%+ target)\n- **✅ Production-Ready Architecture** - Clean Architecture with dependency injection\n- **✅ Professional CI/CD Pipeline** - Multi-platform testing and automated releases\n- **✅ Zero External Dependencies** - Native implementations for maximum reliability\n\n### **🚀 Performance Excellence**\n\n- **⚡ \u003c2s Extension Activation** - Lightning-fast startup performance\n- **⚡ \u003c500ms Diagnostic Processing** - Real-time problem monitoring\n- **⚡ \u003c100ms MCP Tool Response** - Instant AI agent integration\n- **💾 \u003c50MB Memory Baseline** - Efficient resource utilization\n- **📊 10,000+ File Workspace Support** - Enterprise-scale capability\n\n### **🔧 Advanced Technical Implementation**\n\n- **🎯 Event-Driven Architecture** - Loose coupling via EventEmitter patterns\n- **🛡️ Robust Error Handling** - Comprehensive error recovery mechanisms\n- **📈 Performance Monitoring** - Built-in metrics and optimization\n- **🔄 Real-time Synchronization** - Live diagnostic updates via MCP notifications\n- **🌐 Cross-Platform Compatibility** - Windows, macOS, Linux support with intelligent spawn handling\n\n### **✨ Latest Features (v1.4.0)**\n\n- **🔧 Cross-Platform Utilities** - Smart platform detection and spawn option handling\n- **⚙️ Configuration Validation** - Automatic validation and enhancement of MCP client configurations\n- **📊 Enhanced Export System** - Continuous diagnostic data export for standalone MCP server integration\n- **🎨 Improved Status Display** - Better visual indicators and error reporting\n- **🛠️ Automated Setup** - One-click MCP server registration across different environments\n\n### **🚀 NEW: v1.4.0 - Auto-Server Injection \u0026 Advanced Diagnostics**\n\n- **🤖 Automatic MCP Server Registration** - One-click deployment and configuration across VS Code, Cursor, and other MCP clients\n- **📊 Cross-Platform Diagnostic Analysis** - Enhanced TypeScript and ESLint analysis with background workspace scanning\n- **⚙️ Configuration Manager** - Atomic configuration injection with backup and rollback capabilities\n- **🔧 Server Installation Utilities** - Automated bundled server deployment with version management\n- **🛠️ Enhanced Command System** - New `configureServer` command for automated MCP setup\n- **📈 Improved Performance Monitoring** - Advanced timer management and memory leak prevention\n- **🌐 Enhanced Cross-Platform Support** - Native spawn option handling for Windows, macOS, and Linux\n- **🧪 Comprehensive Test Coverage** - 810 tests with 97.99% coverage including E2E and integration tests\n\n## 🚀 What is this?\n\nThe 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.\n\n### Why was this built?\n\n- **🤖 AI-First Development**: Modern development increasingly relies on AI assistance. This extension ensures your AI tools have complete visibility into your codebase health.\n- **⚡ Real-time Integration**: No more manually copying error messages or explaining problems to AI tools - they see everything instantly.\n- **🔧 Universal Diagnostics**: Works with any VS Code diagnostic provider (TypeScript, ESLint, custom linters, etc.)\n- **📊 Enhanced Productivity**: AI agents can provide more contextual help when they understand your current problems.\n\n### What problem does it solve?\n\nBefore this extension, AI agents couldn't see your VS Code problems panel, making it difficult for them to:\n\n- Understand compilation errors when suggesting fixes\n- Provide relevant solutions for linting issues\n- Help with project-wide diagnostic patterns\n- Assist with debugging based on current error state\n\n### Key Features Learned \u0026 Implemented\n\n- **🔍 Real-time Diagnostics Monitoring**: Automatically captures all diagnostic problems from VS Code's Problems panel using advanced event debouncing (300ms configurable)\n- **🤖 MCP Server Integration**: Exposes diagnostics through standardized MCP tools and resources with comprehensive filtering capabilities\n- **⚡ Performance Optimized**: Handles large workspaces efficiently with smart caching and memory management (97.99% test coverage)\n- **🏢 Multi-workspace Support**: Seamlessly works with complex project structures and multiple workspace folders\n- **📡 Real-time Notifications**: Pushes diagnostic changes instantly to connected MCP clients with structured payloads\n- **🎨 Enhanced Status Bar**: Color-coded status bar with red (errors), orange (warnings), green (clean) backgrounds and real-time updates\n- **🎛️ Command Palette**: Full integration with VS Code commands for server management and detailed status viewing with webview\n- **🔧 Highly Configurable**: Customizable port, debounce timing, logging options, and performance settings\n- **🚀 Automatic Registration**: One-click setup with intelligent MCP server registration across different environments\n- **🧪 Test Workspace**: Comprehensive testing environment with intentional errors for validation (810 tests passing)\n- **🛡️ Robust Error Handling**: Graceful degradation and comprehensive error recovery mechanisms\n- **🌐 Cross-Platform Support**: Native Windows, macOS, and Linux compatibility with platform-specific optimizations\n\n## 📦 Installation\n\n### From VS Code Marketplace (Recommended)\n\n1. **Open VS Code**\n2. **Go to Extensions** (Ctrl+Shift+X / Cmd+Shift+X)\n3. **Search for** \"MCP Diagnostics Extension\"\n4. **Click Install**\n5. **Reload VS Code** if prompted\n\nThe extension will automatically activate and register itself as an MCP server.\n\n### From VSIX File\n\n1. Download the latest `.vsix` file from [GitHub Releases](https://github.com/newbpydev/mcp-diagnostics-extension/releases)\n2. Open VS Code\n3. Run command: `Extensions: Install from VSIX...`\n4. Select the downloaded file\n\n### From Source (Development)\n\n```bash\n# Clone the repository\ngit clone https://github.com/newbpydev/mcp-diagnostics-extension.git\ncd mcp-diagnostics-extension\n\n# Install dependencies\nnpm install\n\n# Compile TypeScript\nnpm run compile\n\n# Launch Extension Development Host\n# Press F5 in VS Code or run:\ncode --extensionDevelopmentPath=.\n```\n\n## 🚀 Quick Start\n\n### 1. **Installation \u0026 Activation**\n\nAfter installing from the marketplace, the extension automatically:\n\n- ✅ Activates when VS Code starts\n- ✅ Registers as an MCP server\n- ✅ Starts monitoring diagnostics\n- ✅ Shows status in the status bar\n\n### 2. **Verify It's Working**\n\nLook for the status bar item: `$(bug) MCP: XE YW` (X errors, Y warnings)\n\n### 3. **Connect Your MCP Client**\n\nAdd to your MCP client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"vscode-diagnostics\": {\n      \"command\": \"node\",\n      \"args\": [\"scripts/mcp-server.js\"],\n      \"cwd\": \"/path/to/mcp-diagnostics-extension\",\n      \"env\": {\n        \"NODE_ENV\": \"production\",\n        \"MCP_DEBUG\": \"false\"\n      }\n    }\n  }\n}\n```\n\n### 4. **Start Using MCP Tools**\n\nYour AI agent can now access three powerful tools:\n\n- `getProblems` - Get all diagnostics with filtering\n- `getProblemsForFile` - Get problems for specific files\n- `getWorkspaceSummary` - Get workspace-wide statistics\n\n## 🚀 **AUTO-DEPLOYMENT \u0026 ONE-CLICK SETUP** (Sprint 4 Feature)\n\n### **⚡ Automatic MCP Server Registration**\n\nThe extension now features **one-click automatic setup** that eliminates all manual configuration! This breakthrough feature automatically:\n\n- ✅ **Deploys bundled MCP server** to user directory with proper permissions\n- ✅ **Injects configuration** into Cursor IDE and other MCP clients\n- ✅ **Validates deployment** with atomic operations and backup creation\n- ✅ **Cross-platform support** with Windows/macOS/Linux compatibility\n- ✅ **Error recovery** with graceful fallback to manual setup\n\n### **🎯 How Auto-Deployment Works**\n\n```mermaid\ngraph TD\n    A[🔧 User Runs Configure Server Command] --\u003e B[📋 Progress Notification Shown]\n    B --\u003e C[📦 Deploy Bundled Server]\n    C --\u003e D{🔍 Server Exists?}\n    D --\u003e|No| E[📂 Create Installation Directory]\n    D --\u003e|Yes| F[📋 Check Version]\n    F --\u003e|Newer| E\n    F --\u003e|Same/Older| G[✅ Skip Deployment]\n    E --\u003e H[📋 Copy Server Binary]\n    H --\u003e I[🔐 Set Executable Permissions]\n    I --\u003e J[📄 Persist Manifest]\n    J --\u003e K[🔧 Inject Configuration]\n    G --\u003e K\n    K --\u003e L[🔍 Locate Config File]\n    L --\u003e M{📁 Config Exists?}\n    M --\u003e|Yes| N[📋 Load \u0026 Validate]\n    M --\u003e|No| O[📄 Create Default Config]\n    N --\u003e P[🔄 Deep Merge Configurations]\n    O --\u003e P\n    P --\u003e Q[💾 Atomic Write Operation]\n    Q --\u003e R[✅ Backup Creation]\n    R --\u003e S[📋 Validate Final Config]\n    S --\u003e T[🎉 Success Notification]\n\n    %% Error Paths\n    C -.-\u003e|Error| U[❌ Deployment Failed]\n    K -.-\u003e|Error| V[❌ Configuration Failed]\n    U --\u003e W[📖 Show Manual Setup Guide]\n    V --\u003e W\n\n    %% Styling\n    classDef success fill:#d4edda,stroke:#155724,color:#155724\n    classDef error fill:#f8d7da,stroke:#721c24,color:#721c24\n    classDef process fill:#cce5ff,stroke:#004085,color:#004085\n\n    class T success\n    class U,V,W error\n    class A,B,C,E,H,I,J,K,L,N,O,P,Q,R,S process\n```\n\n### **📋 Auto-Configuration Injection Process**\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant ExtensionCommands\n    participant ServerDeployment\n    participant McpServerRegistration\n    participant FileSystem\n    participant VSCode\n\n    User-\u003e\u003eExtensionCommands: Execute \"Configure Server\"\n    ExtensionCommands-\u003e\u003eVSCode: Show Progress Notification\n\n    Note over ExtensionCommands,ServerDeployment: Phase 1: Server Deployment\n    ExtensionCommands-\u003e\u003eServerDeployment: deployBundledServer()\n    ServerDeployment-\u003e\u003eFileSystem: Check installation directory\n    FileSystem--\u003e\u003eServerDeployment: Directory status\n    ServerDeployment-\u003e\u003eFileSystem: Atomic copy \u0026 permissions\n    FileSystem--\u003e\u003eServerDeployment: Deployment complete\n    ServerDeployment--\u003e\u003eExtensionCommands: Server path\n\n    Note over ExtensionCommands,McpServerRegistration: Phase 2: Configuration Injection\n    ExtensionCommands-\u003e\u003eMcpServerRegistration: injectConfiguration()\n    McpServerRegistration-\u003e\u003eFileSystem: Locate config file (priority order)\n    FileSystem--\u003e\u003eMcpServerRegistration: Config path\n    McpServerRegistration-\u003e\u003eFileSystem: Load existing config\n    FileSystem--\u003e\u003eMcpServerRegistration: Config data\n    McpServerRegistration-\u003e\u003eMcpServerRegistration: Deep merge with validation\n    McpServerRegistration-\u003e\u003eFileSystem: Atomic write with backup\n    FileSystem--\u003e\u003eMcpServerRegistration: Write complete\n    McpServerRegistration--\u003e\u003eExtensionCommands: Configuration complete\n\n    ExtensionCommands-\u003e\u003eVSCode: Success notification\n    VSCode--\u003e\u003eUser: \"MCP server configured successfully!\"\n\n    Note over User,VSCode: Alternative: Error Handling\n    ExtensionCommands-\u003e\u003eVSCode: Error notification (if failed)\n    VSCode--\u003e\u003eUser: Show manual setup guide\n```\n\n### **🏗️ Auto-Deployment Architecture**\n\n```mermaid\ngraph LR\n    subgraph \"📦 Bundled Assets\"\n        A[scripts/mcp-server.js]\n        B[Server Manifest]\n        C[Configuration Template]\n    end\n\n    subgraph \"🔧 Core Components\"\n        D[ServerInstallUtils]\n        E[ServerDeployment]\n        F[McpServerRegistration]\n        G[ExtensionCommands]\n    end\n\n    subgraph \"💾 User Environment\"\n        H[~/.mcp-diagnostics/]\n        I[.cursor/mcp.json]\n        J[IDE Configuration]\n    end\n\n    subgraph \"🛡️ Safety Features\"\n        K[Atomic Operations]\n        L[Backup Creation]\n        M[Version Validation]\n        N[Permission Checks]\n    end\n\n    A --\u003e D: Bundled Server\n    D --\u003e E: Installation Utils\n    E --\u003e F: Deployment Service\n    F --\u003e G: Registration Service\n    G --\u003e H: Deploy to User Dir\n    F --\u003e I: Inject Config\n    I --\u003e J: Configure IDE\n\n    K --\u003e E: Ensure Atomicity\n    L --\u003e F: Create Backups\n    M --\u003e E: Version Control\n    N --\u003e D: Security Checks\n\n    %% Styling\n    classDef bundled fill:#fff3cd,stroke:#856404,color:#856404\n    classDef core fill:#cce5ff,stroke:#004085,color:#004085\n    classDef user fill:#d4edda,stroke:#155724,color:#155724\n    classDef safety fill:#f8d7da,stroke:#721c24,color:#721c24\n\n    class A,B,C bundled\n    class D,E,F,G core\n    class H,I,J user\n    class K,L,M,N safety\n```\n\n### **⚙️ Configuration File Priorities**\n\n```mermaid\ngraph TD\n    A[🔍 Configuration Discovery] --\u003e B[📁 Check Workspace .cursor/mcp.json]\n    B --\u003e C{✅ Exists?}\n    C --\u003e|Yes| D[🎯 Use Workspace Config]\n    C --\u003e|No| E[📁 Check User Home .cursor/mcp.json]\n    E --\u003e F{✅ Exists?}\n    F --\u003e|Yes| G[🏠 Use User Config]\n    F --\u003e|No| H[📄 Create New Configuration]\n\n    D --\u003e I[🔄 Load \u0026 Parse JSON]\n    G --\u003e I\n    H --\u003e J[📋 Generate Default Config]\n    J --\u003e I\n    I --\u003e K[✅ Validate with Zod Schema]\n    K --\u003e L[🔄 Deep Merge with Diagnostics Server]\n    L --\u003e M[💾 Atomic Write with Backup]\n\n    %% Styling\n    classDef primary fill:#007bff,stroke:#ffffff,color:#ffffff\n    classDef success fill:#28a745,stroke:#ffffff,color:#ffffff\n    classDef process fill:#17a2b8,stroke:#ffffff,color:#ffffff\n\n    class D,G primary\n    class H,J,M success\n    class I,K,L process\n```\n\n### **🎛️ One-Click Setup Commands**\n\n#### **`MCP Diagnostics: Configure Server`** ⚡\n\n**The magic command that does everything automatically!**\n\nAccess via Command Palette (Ctrl+Shift+P / Cmd+Shift+P):\n\n1. **Search**: \"MCP Diagnostics: Configure Server\"\n2. **Click**: Command executes automatically\n3. **Watch**: Progress notification shows deployment status\n4. **Result**: Either success notification OR manual setup guide\n\n**What it does:**\n\n- ✅ Deploys server to `~/.mcp-diagnostics/mcp-server.js`\n- ✅ Sets proper executable permissions (Unix/Linux)\n- ✅ Creates version manifest for future upgrades\n- ✅ Locates your MCP configuration file (workspace → user home)\n- ✅ Preserves existing MCP servers during injection\n- ✅ Validates configuration with JSON schema\n- ✅ Creates backup before any changes\n- ✅ Provides manual setup fallback if automatic fails\n\n### **📊 Cross-Platform Deployment Support**\n\n| Platform    | Install Path                      | Executable      | Spawn Options            |\n| ----------- | --------------------------------- | --------------- | ------------------------ |\n| **Windows** | `%USERPROFILE%\\.mcp-diagnostics\\` | ❌ Not required | `shell: true` (required) |\n| **macOS**   | `~/.mcp-diagnostics/`             | ✅ `chmod +x`   | `shell: false`           |\n| **Linux**   | `~/.mcp-diagnostics/`             | ✅ `chmod +x`   | `shell: false`           |\n\n### **🛡️ Security \u0026 Reliability Features**\n\n#### **Atomic Operations**\n\n```typescript\n// All file operations are atomic to prevent corruption\n1. Write to temporary file (.tmp)\n2. Validate written content\n3. Atomic rename to final location\n4. Clean up temporary files\n```\n\n#### **Backup Strategy**\n\n```typescript\n// Automatic backup creation before any changes\n- Original config → config.backup\n- Malformed config → config.malformed.backup\n- Restore on validation failure\n```\n\n#### **Version Management**\n\n```typescript\n// Smart version detection and upgrade handling\n- Compare semantic versions (1.2.3 format)\n- Skip deployment if same/older version\n- Automatic upgrade for newer versions\n```\n\n### **🚨 Error Handling \u0026 Recovery**\n\nThe auto-deployment system includes comprehensive error handling:\n\n| Error Type            | Recovery Strategy                                |\n| --------------------- | ------------------------------------------------ |\n| **Permission Denied** | Show manual setup with elevated privileges guide |\n| **Disk Space**        | Alert user and provide cleanup recommendations   |\n| **Network Issues**    | Use bundled assets with offline deployment       |\n| **Config Corruption** | Create backup and initialize fresh configuration |\n| **Version Conflicts** | Smart merge with user preference preservation    |\n\n### **📈 Performance Metrics**\n\nSprint 4 auto-deployment meets strict performance requirements:\n\n- ⚡ **Deployment Time**: \u003c2 seconds for complete setup\n- ⚡ **Configuration Injection**: \u003c500ms including validation\n- ⚡ **Memory Usage**: \u003c10MB additional during deployment\n- ⚡ **File Operations**: Atomic with \u003c100ms overhead\n- ⚡ **Cross-Platform**: Universal compatibility with intelligent spawn detection\n\n---\n\n## 🛠️ Usage Guide\n\n### Available Commands\n\nAccess via Command Palette (Ctrl+Shift+P / Cmd+Shift+P):\n\n- **`MCP Diagnostics: Show Status`** - Opens detailed status webview with:\n\n  - Server connection status\n  - Problem statistics by severity and source\n  - File-by-file breakdown\n  - Workspace folder information\n  - Performance metrics\n\n- **`MCP Diagnostics: Restart Server`** - Restarts the MCP server with progress indication\n\n- **`MCP Diagnostics: Show Setup Guide`** - Opens comprehensive setup guide for MCP client configuration\n\n### MCP Tools Reference\n\n#### 🔍 `getProblems` - Universal Problem Query\n\nGet all diagnostic problems with powerful filtering options:\n\n```json\n{\n  \"name\": \"getProblems\",\n  \"arguments\": {\n    \"filePath\": \"/path/to/file.ts\", // Optional: filter by specific file\n    \"severity\": \"Error\", // Optional: Error, Warning, Information, Hint\n    \"workspaceFolder\": \"my-project\", // Optional: filter by workspace\n    \"source\": \"typescript\", // Optional: filter by diagnostic source\n    \"limit\": 100, // Optional: limit results (default: 1000)\n    \"offset\": 0 // Optional: pagination offset\n  }\n}\n```\n\n**Example Response:**\n\n```json\n{\n  \"content\": [\n    {\n    \"type\": \"text\",\n    \"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\\\"}]\"\n    }\n  ]\n}\n```\n\n#### 📄 `getProblemsForFile` - File-Specific Diagnostics\n\nGet all problems for a specific file:\n\n```json\n{\n  \"name\": \"getProblemsForFile\",\n  \"arguments\": {\n    \"filePath\": \"/absolute/path/to/file.ts\"\n  }\n}\n```\n\n#### 📊 `getWorkspaceSummary` - Workspace Statistics\n\nGet comprehensive workspace diagnostic statistics:\n\n```json\n{\n  \"name\": \"getWorkspaceSummary\",\n  \"arguments\": {\n    \"groupBy\": \"severity\" // Optional: severity, source, workspaceFolder\n  }\n}\n```\n\n**Example Response:**\n\n```json\n{\n  \"content\": [\n    {\n    \"type\": \"text\",\n    \"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\\\"}\"\n    }\n  ]\n}\n```\n\n### MCP Resources\n\nDynamic resources providing structured access to diagnostic data:\n\n- **`diagnostics://summary`** - Overall workspace problems summary\n- **`diagnostics://file/{encodedFilePath}`** - Problems for specific file\n- **`diagnostics://workspace/{encodedWorkspaceName}`** - Problems for specific workspace\n\n### Real-time Notifications\n\nThe server automatically sends `problemsChanged` notifications when diagnostics change:\n\n```json\n{\n  \"method\": \"notifications/message\",\n  \"params\": {\n    \"level\": \"info\",\n    \"data\": {\n      \"type\": \"problemsChanged\",\n      \"uri\": \"/path/to/file.ts\",\n      \"problemCount\": 3,\n      \"problems\": [...],\n      \"timestamp\": \"2024-01-15T10:30:00.000Z\"\n    }\n  }\n}\n```\n\n## ⚙️ Configuration\n\nCustomize the extension via VS Code settings (`Ctrl+,` / `Cmd+,`):\n\n```json\n{\n  \"mcpDiagnostics.server.port\": 6070,\n  \"mcpDiagnostics.debounceMs\": 300,\n  \"mcpDiagnostics.enableDebugLogging\": false,\n  \"mcpDiagnostics.enablePerformanceLogging\": false,\n  \"mcpDiagnostics.maxProblemsPerFile\": 1000,\n  \"mcpDiagnostics.debug.logLevel\": \"info\",\n  \"mcpDiagnostics.showAutoRegistrationNotification\": true\n}\n```\n\n### Configuration Options\n\n| Setting                            | Type    | Default | Description                                         |\n| ---------------------------------- | ------- | ------- | --------------------------------------------------- |\n| `server.port`                      | number  | 6070    | MCP server port (1024-65535)                        |\n| `debounceMs`                       | number  | 300     | Debounce interval for diagnostic events (50-5000ms) |\n| `enableDebugLogging`               | boolean | false   | Enable detailed debug logging                       |\n| `enablePerformanceLogging`         | boolean | false   | Enable performance metrics logging                  |\n| `maxProblemsPerFile`               | number  | 1000    | Maximum problems to track per file (1-10000)        |\n| `debug.logLevel`                   | string  | \"info\"  | Logging level (error, warn, info, debug)            |\n| `showAutoRegistrationNotification` | boolean | true    | Show MCP server registration notifications          |\n\n## 🧪 Testing \u0026 Development\n\n### **🏆 Exceptional Test Coverage Achievement**\n\nThe extension has achieved **world-class testing standards**:\n\n- **✅ 810 Tests Passing** - Comprehensive test suite with 0 failures (1 skipped)\n- **✅ 97.99% Statement Coverage** - Exceeding industry standards\n- **✅ 34 Test Suites** - Organized, maintainable test structure across all components\n- **✅ Cross-Platform Testing** - Validated on Windows, macOS, and Linux environments\n- **✅ Comprehensive E2E Testing** - Full extension workflow validation\n\n### Real vs Mock Server\n\nThe extension provides **two operational modes**:\n\n#### 🔴 **Real VS Code Extension** (Production Mode)\n\n- **Purpose**: Production use with actual VS Code diagnostics\n- **Data Source**: Live VS Code Problems panel\n- **Activation**: Automatic when extension is installed\n- **Use Case**: Real development workflows with AI agents\n\n#### 🔧 **Development Tools**\n\n- **Package Validation**: `scripts/validate-package.sh` - Automated package integrity checks\n- **Asset Conversion**: `scripts/convert-assets.js` - Visual asset optimization utilities\n\n### Test Workspace\n\nThe extension includes `test-workspace/` with intentional errors:\n\n- **`example.ts`**: TypeScript errors (type mismatches, undefined variables, invalid assignments)\n- **`utils.js`**: ESLint warnings (unused variables, style issues, best practice violations)\n\n**To test the extension:**\n\n1. **Launch Extension Development Host** (Press F5 in VS Code)\n2. **Open test workspace** or any workspace with diagnostic issues\n3. **View Problems panel** (Ctrl+Shift+M) to see real diagnostics\n4. **Use MCP tools** to query the diagnostic data\n5. **Check status bar** for live error/warning counts\n\n### Development Setup\n\n```bash\n# Install dependencies\nnpm install\n\n# Run tests (810 tests)\nnpm test\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Lint code\nnpm run lint\n\n# Format code\nnpm run format\n\n# Compile TypeScript\nnpm run compile\n\n# Package extension\nnpm run package\n\n# Run CI checks\nnpm run ci:check\n```\n\n## 🔧 MCP Client Configuration\n\nThe 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.\n\n### 🎯 **Universal Configuration Pattern**\n\nAll MCP clients use the same basic configuration pattern with environment-specific variations:\n\n```json\n{\n  \"mcpServers\": {\n    // or \"servers\" for some clients\n    \"vscode-diagnostics\": {\n      \"command\": \"node\",\n      \"args\": [\"scripts/mcp-server.js\"],\n      \"cwd\": \"/path/to/mcp-diagnostics-extension\",\n      \"env\": {\n        \"NODE_ENV\": \"production\",\n        \"MCP_DEBUG\": \"false\"\n      }\n    }\n  }\n}\n```\n\n### 📁 **Configuration File Locations**\n\n| Environment        | Configuration File           | Format                           |\n| ------------------ | ---------------------------- | -------------------------------- |\n| **Cursor IDE**     | `.cursor/mcp.json`           | `mcpServers`                     |\n| **VS Code**        | `.vscode/mcp.json`           | `servers` (with `type: \"stdio\"`) |\n| **Windsurf**       | `.windsurf/mcp.json`         | `servers`                        |\n| **Claude Desktop** | `claude_desktop_config.json` | `mcpServers`                     |\n\n### MCP Client Configuration Examples\n\n#### Cursor IDE\n\n```json\n// .cursor/mcp.json or cursor-mcp-config.json\n{\n  \"mcpServers\": {\n    \"vscode-diagnostics\": {\n      \"command\": \"node\",\n      \"args\": [\"scripts/mcp-server.js\"],\n      \"cwd\": \"/path/to/mcp-diagnostics-extension\",\n      \"env\": {\n        \"NODE_ENV\": \"production\",\n        \"MCP_DEBUG\": \"false\"\n      }\n    }\n  }\n}\n```\n\n#### VS Code with MCP Extension\n\n```json\n// .vscode/mcp.json\n{\n  \"servers\": {\n    \"vscode-diagnostics\": {\n      \"type\": \"stdio\",\n      \"command\": \"node\",\n      \"args\": [\"scripts/mcp-server.js\"],\n      \"cwd\": \"/path/to/mcp-diagnostics-extension\",\n      \"env\": {\n        \"NODE_ENV\": \"production\",\n        \"MCP_DEBUG\": \"false\"\n      }\n    }\n  }\n}\n```\n\n#### Windsurf IDE\n\n```json\n// .windsurf/mcp.json\n{\n  \"servers\": {\n    \"vscode-diagnostics\": {\n      \"command\": \"node\",\n      \"args\": [\"scripts/mcp-server.js\"],\n      \"cwd\": \"/path/to/mcp-diagnostics-extension\",\n      \"env\": {\n        \"NODE_ENV\": \"production\",\n        \"MCP_DEBUG\": \"false\"\n      }\n    }\n  }\n}\n```\n\n#### Claude Desktop\n\n```json\n// claude_desktop_config.json\n{\n  \"mcpServers\": {\n    \"vscode-diagnostics\": {\n      \"command\": \"node\",\n      \"args\": [\"scripts/mcp-server.js\"],\n      \"cwd\": \"/path/to/mcp-diagnostics-extension\",\n      \"env\": {\n        \"NODE_ENV\": \"production\",\n        \"MCP_DEBUG\": \"false\"\n      }\n    }\n  }\n}\n```\n\n#### Custom MCP Client\n\n```typescript\nimport { Client } from '@modelcontextprotocol/client';\n\nconst client = new Client({\n  name: 'my-client',\n  version: '1.0.0',\n});\n\n// Connect to extension\nawait client.connect({\n  command: 'node',\n  args: ['scripts/mcp-server.js'],\n  cwd: '/path/to/mcp-diagnostics-extension',\n  env: {\n    NODE_ENV: 'production',\n    MCP_DEBUG: 'false',\n  },\n});\n\n// Use tools\nconst problems = await client.callTool({\n  name: 'getProblems',\n  arguments: { severity: 'Error' },\n});\n```\n\n### 🚀 **MCP Server Features**\n\nThe `scripts/mcp-server.js` provides:\n\n- **🔍 Real-time Diagnostics**: Live TypeScript and ESLint analysis\n- **📊 VS Code Integration**: Automatic import of VS Code Problems panel data\n- **⚡ Performance Optimized**: Cached results with smart refresh logic\n- **🛡️ Error Recovery**: Graceful fallback when VS Code data unavailable\n- **🔧 Configurable**: Environment variables for debugging and behavior control\n\n### 🌍 **Environment Variables**\n\n| Variable           | Default       | Description                                   |\n| ------------------ | ------------- | --------------------------------------------- |\n| `NODE_ENV`         | `development` | Set to `production` for optimized performance |\n| `MCP_DEBUG`        | `false`       | Enable detailed debug logging                 |\n| `REFRESH_INTERVAL` | `30000`       | Cache refresh interval in milliseconds        |\n| `MAX_PROBLEMS`     | `10000`       | Maximum number of problems to cache           |\n\n### 🔄 **Data Sources**\n\nThe MCP server intelligently combines multiple data sources:\n\n1. **VS Code Export** (Primary): Real-time data from the extension\n2. **TypeScript Compiler** (Fallback): Direct `tsc` analysis\n3. **ESLint** (Fallback): Direct ESLint analysis\n4. **Cached Results** (Performance): Smart caching with automatic refresh\n\n```\n\n## 📚 Documentation\n\n### Additional Resources\n\n- **[MCP Server Guide](./MCP_SERVER_GUIDE.md)** - Comprehensive setup and configuration guide\n- **[Quick Setup Guide](./QUICK_SETUP.md)** - Fast-track installation instructions\n- **[Troubleshooting Guide](./TROUBLESHOOTING.md)** - Common issues and solutions\n- **[Contributing Guide](./.github/CONTRIBUTING.md)** - Development and contribution guidelines\n- **[Changelog](./CHANGELOG.md)** - Version history and release notes\n- **[Security Policy](./.github/SECURITY.md)** - Security reporting and policies\n\n### API Documentation\n\nComprehensive TypeScript documentation is available for all public APIs:\n\n- **[DiagnosticsWatcher API](./src/core/diagnostics/)** - Core diagnostic monitoring\n- **[MCP Tools API](./src/infrastructure/mcp/)** - MCP server implementation\n- **[Extension Commands API](./src/commands/)** - VS Code command integration\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](./.github/CONTRIBUTING.md) for details.\n\n### Quick Contribution Steps\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/amazing-feature`\n3. **Make changes** following our coding standards\n4. **Run tests**: `npm test` (all 810 tests must pass)\n5. **Lint code**: `npm run lint`\n6. **Commit changes**: `npm run commit` (uses conventional commits)\n7. **Push to branch**: `git push origin feature/amazing-feature`\n8. **Open a Pull Request**\n\n### Development Requirements\n\n- Node.js 22.x or higher\n- VS Code 1.96.0 or higher\n- TypeScript 5.8.3 or higher\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n#### Extension Not Activating\n1. Check VS Code version compatibility (requires 1.96.0+)\n2. Look for activation errors in Developer Tools Console\n3. Try reloading VS Code window (Ctrl+Shift+P → \"Reload Window\")\n\n#### MCP Connection Issues\n1. Verify MCP client configuration paths\n2. Check that the extension is active (status bar shows MCP status)\n3. Restart the MCP server: Command Palette → \"MCP Diagnostics: Restart Server\"\n\n#### No Diagnostics Showing\n1. Ensure you have files with actual errors/warnings open\n2. Check VS Code Problems panel (Ctrl+Shift+M) - MCP data comes from here\n3. Verify diagnostic providers (TypeScript, ESLint) are working\n\nFor more detailed troubleshooting, see our [Troubleshooting Guide](./TROUBLESHOOTING.md).\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- **VS Code Team** - For the excellent extension API and diagnostic system\n- **Model Context Protocol** - For the innovative protocol enabling AI agent integration\n- **TypeScript Team** - For the robust type system and development experience\n- **Jest Community** - For the comprehensive testing framework\n- **Open Source Community** - For the tools and libraries that make this project possible\n\n---\n\n**🚀 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!**\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnewbpydev%2Fmcp-diagnostics-extension","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnewbpydev%2Fmcp-diagnostics-extension","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnewbpydev%2Fmcp-diagnostics-extension/lists"}