MCP Diagnostics Extension

Uma extensão do VS Code que fornece problemas de diagnóstico em tempo real, como erros e avisos, por meio do Model Context Protocol.

GitHub

Experimente este MCPPatrocinado

Documentação

Extensão de Diagnóstico MCP

🏆 Uma extensão VS Code pronta para produção que expõe problemas de diagnóstico (erros, avisos, etc.) em tempo real via Protocolo de Contexto de Modelo (MCP) para consumo contínuo por agentes de IA e ferramentas habilitadas para MCP.

🎯 CONQUISTAS EXCEPCIONAIS

🏆 Padrões de Qualidade de Classe Mundial

✅ 810 Testes Passando - Cobertura abrangente de testes com 0 falhas (1 ignorado)
✅ 97,99% de Cobertura de Declarações - Superando os padrões da indústria (meta de 95%+)
✅ Arquitetura Pronta para Produção - Arquitetura Limpa com injeção de dependência
✅ Pipeline CI/CD Profissional - Testes multiplataforma e lançamentos automatizados
✅ Zero Dependências Externas - Implementações nativas para máxima confiabilidade

🚀 Excelência em Desempenho

⚡ <2s de Ativação da Extensão - Desempenho de inicialização ultrarrápido
⚡ <500ms de Processamento de Diagnóstico - Monitoramento de problemas em tempo real
⚡ <100ms de Resposta da Ferramenta MCP - Integração instantânea com agentes de IA
💾 <50MB de Uso de Memória Base - Utilização eficiente de recursos
📊 Suporte a Workspaces com 10.000+ Arquivos - Capacidade em escala empresarial

🔧 Implementação Técnica Avançada

🎯 Arquitetura Orientada a Eventos - Acoplamento flexível via padrões EventEmitter
🛡️ Tratamento Robusto de Erros - Mecanismos abrangentes de recuperação de erros
📈 Monitoramento de Desempenho - Métricas integradas e otimização
🔄 Sincronização em Tempo Real - Atualizações de diagnóstico ao vivo via notificações MCP
🌐 Compatibilidade Multiplataforma - Suporte para Windows, macOS, Linux com tratamento inteligente de spawn

✨ Recursos Mais Recentes (v1.4.0)

🔧 Utilitários Multiplataforma - Detecção inteligente de plataforma e tratamento de opções de spawn
⚙️ Validação de Configuração - Validação e aprimoramento automáticos de configurações de clientes MCP
📊 Sistema de Exportação Aprimorado - Exportação contínua de dados de diagnóstico para integração com servidor MCP independente
🎨 Exibição de Status Melhorada - Melhores indicadores visuais e relatórios de erros
🛠️ Configuração Automatizada - Registro do servidor MCP com um clique em diferentes ambientes

🚀 NOVO: v1.4.0 - Injeção Automática de Servidor e Diagnóstico Avançado

🤖 Registro Automático do Servidor MCP - Implantação e configuração com um clique em VS Code, Cursor e outros clientes MCP
📊 Análise de Diagnóstico Multiplataforma - Análise aprimorada de TypeScript e ESLint com varredura de workspace em segundo plano
⚙️ Gerenciador de Configuração - Injeção atômica de configuração com recursos de backup e reversão
🔧 Utilitários de Instalação do Servidor - Implantação automatizada de servidor empacotado com gerenciamento de versões
🛠️ Sistema de Comandos Aprimorado - Novo comando configureServer para configuração automatizada do MCP
📈 Monitoramento de Desempenho Melhorado - Gerenciamento avançado de temporizadores e prevenção de vazamentos de memória
🌐 Suporte Multiplataforma Aprimorado - Tratamento nativo de opções de spawn para Windows, macOS e Linux
🧪 Cobertura Abrangente de Testes - 810 testes com 97,99% de cobertura, incluindo testes E2E e de integração

🚀 O que é isso?

A Extensão de Diagnóstico MCP conecta o poderoso sistema de diagnóstico do VS Code ao Protocolo de Contexto de Modelo, permitindo que agentes de IA acessem seus problemas de código em tempo real. Seja depurando erros de TypeScript, avisos de ESLint ou problemas de linters personalizados, esta extensão torna todas as informações de diagnóstico instantaneamente disponíveis para suas ferramentas de IA.

Por que foi criada?

🤖 Desenvolvimento Focado em IA: O desenvolvimento moderno depende cada vez mais de assistência de IA. Esta extensão garante que suas ferramentas de IA tenham visibilidade completa da saúde do seu código.
⚡ Integração em Tempo Real: Chega de copiar manualmente mensagens de erro ou explicar problemas para ferramentas de IA - elas veem tudo instantaneamente.
🔧 Diagnóstico Universal: Funciona com qualquer provedor de diagnóstico do VS Code (TypeScript, ESLint, linters personalizados, etc.)
📊 Produtividade Aprimorada: Agentes de IA podem fornecer ajuda mais contextual quando entendem seus problemas atuais.

Qual problema ela resolve?

Antes desta extensão, agentes de IA não conseguiam ver o painel de problemas do VS Code, dificultando para eles:

Entender erros de compilação ao sugerir correções
Fornecer soluções relevantes para problemas de linting
Ajudar com padrões de diagnóstico em todo o projeto
Auxiliar na depuração com base no estado atual de erros

Recursos Principais Aprendidos e Implementados

🔍 Monitoramento de Diagnóstico em Tempo Real: Captura automaticamente todos os problemas de diagnóstico do painel de Problemas do VS Code usando debounce avançado de eventos (300ms configurável)
🤖 Integração com Servidor MCP: Expõe diagnósticos através de ferramentas e recursos MCP padronizados com recursos abrangentes de filtragem
⚡ Otimizado para Desempenho: Lida com workspaces grandes de forma eficiente com cache inteligente e gerenciamento de memória (97,99% de cobertura de testes)
🏢 Suporte a Múltiplos Workspaces: Funciona perfeitamente com estruturas de projeto complexas e múltiplas pastas de workspace
📡 Notificações em Tempo Real: Envia mudanças de diagnóstico instantaneamente para clientes MCP conectados com payloads estruturados
🎨 Barra de Status Aprimorada: Barra de status com código de cores - vermelho (erros), laranja (avisos), verde (limpo) - e atualizações em tempo real
🎛️ Paleta de Comandos: Integração completa com comandos do VS Code para gerenciamento do servidor e visualização detalhada de status com webview
🔧 Altamente Configurável: Porta personalizável, temporização de debounce, opções de registro e configurações de desempenho
🚀 Registro Automático: Configuração com um clique com registro inteligente do servidor MCP em diferentes ambientes
🧪 Workspace de Teste: Ambiente de teste abrangente com erros intencionais para validação (810 testes passando)
🛡️ Tratamento Robusto de Erros: Degradação graciosa e mecanismos abrangentes de recuperação de erros
🌐 Suporte Multiplataforma: Compatibilidade nativa com Windows, macOS e Linux com otimizações específicas de plataforma

📦 Instalação

Do VS Code Marketplace (Recomendado)

Abra o VS Code
Vá para Extensões (Ctrl+Shift+X / Cmd+Shift+X)
Pesquise por "MCP Diagnostics Extension"
Clique em Instalar
Recarregue o VS Code se solicitado

A extensão será ativada automaticamente e se registrará como um servidor MCP.

Do Arquivo VSIX

Baixe o arquivo .vsix mais recente de GitHub Releases
Abra o VS Code
Execute o comando: Extensions: Install from VSIX...
Selecione o arquivo baixado

Do Código-Fonte (Desenvolvimento)

# 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=.

🚀 Início Rápido

1. Instalação e Ativação

Após instalar do marketplace, a extensão automaticamente:

✅ Ativa quando o VS Code inicia
✅ Registra como servidor MCP
✅ Começa a monitorar diagnósticos
✅ Mostra o status na barra de status

2. Verifique se Está Funcionando

Procure o item na barra de status: $(bug) MCP: XE YW (X erros, Y avisos)

3. Conecte Seu Cliente MCP

Adicione à configuração do seu cliente MCP:

{
  "mcpServers": {
    "vscode-diagnostics": {
      "command": "node",
      "args": ["scripts/mcp-server.js"],
      "cwd": "/path/to/mcp-diagnostics-extension",
      "env": {
        "NODE_ENV": "production",
        "MCP_DEBUG": "false"
      }
    }
  }
}

4. Comece a Usar as Ferramentas MCP

Seu agente de IA agora pode acessar três ferramentas poderosas:

getProblems - Obter todos os diagnósticos com filtragem
getProblemsForFile - Obter problemas para arquivos específicos
getWorkspaceSummary - Obter estatísticas de todo o workspace

🚀 IMPLANTAÇÃO AUTOMÁTICA E CONFIGURAÇÃO COM UM CLIQUE (Recurso do Sprint 4)

⚡ Registro Automático do Servidor MCP

A extensão agora apresenta configuração automática com um clique que elimina toda a configuração manual! Este recurso inovador automaticamente:

✅ Implanta servidor MCP empacotado no diretório do usuário com permissões adequadas
✅ Injeta configuração no Cursor IDE e outros clientes MCP
✅ Valida a implantação com operações atômicas e criação de backup
✅ Suporte multiplataforma com compatibilidade Windows/macOS/Linux
✅ Recuperação de erros com fallback gracioso para configuração manual

🎯 Como Funciona a Implantação Automática

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

📋 Processo de Injeção de Configuração Automática

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

🏗️ Arquitetura da Implantação Automática

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

⚙️ Prioridades de Arquivos de Configuração

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

🎛️ Comandos de Configuração com Um Clique

`MCP Diagnostics: Configure Server` ⚡

O comando mágico que faz tudo automaticamente!

Acesse pela Paleta de Comandos (Ctrl+Shift+P / Cmd+Shift+P):

Pesquise: "MCP Diagnostics: Configure Server"
Clique: O comando executa automaticamente
Observe: A notificação de progresso mostra o status da implantação
Resultado: Notificação de sucesso OU guia de configuração manual

O que ele faz:

✅ Implanta o servidor em ~/.mcp-diagnostics/mcp-server.js
✅ Define permissões de executável adequadas (Unix/Linux)
✅ Cria manifesto de versão para atualizações futuras
✅ Localiza seu arquivo de configuração MCP (workspace → diretório do usuário)
✅ Preserva servidores MCP existentes durante a injeção
✅ Valida a configuração com esquema JSON
✅ Cria backup antes de qualquer alteração
✅ Fornece fallback de configuração manual se a automática falhar

📊 Suporte de Implantação Multiplataforma

Plataforma	Caminho de Instalação	Executável	Opções de Spawn
Windows	`%USERPROFILE%\.mcp-diagnostics\`	❌ Não necessário	`shell: true` (necessário)
macOS	`~/.mcp-diagnostics/`	✅ `chmod +x`	`shell: false`
Linux	`~/.mcp-diagnostics/`	✅ `chmod +x`	`shell: false`

🛡️ Recursos de Segurança e Confiabilidade

Operações Atômicas

// 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

Estratégia de Backup

// Automatic backup creation before any changes
- Original config → config.backup
- Malformed config → config.malformed.backup
- Restore on validation failure

Gerenciamento de Versões

// Smart version detection and upgrade handling
- Compare semantic versions (1.2.3 format)
- Skip deployment if same/older version
- Automatic upgrade for newer versions

🚨 Tratamento de Erros e Recuperação

O sistema de implantação automática inclui tratamento abrangente de erros:

Tipo de Erro	Estratégia de Recuperação
Permissão Negada	Mostrar configuração manual com guia de privilégios elevados
Espaço em Disco	Alertar o usuário e fornecer recomendações de limpeza
Problemas de Rede	Usar ativos empacotados com implantação offline
Corrupção de Configuração	Criar backup e inicializar configuração nova
Conflitos de Versão	Mesclagem inteligente com preservação das preferências do usuário

📈 Métricas de Desempenho

A implantação automática do Sprint 4 atende a requisitos rigorosos de desempenho:

⚡ Tempo de Implantação: <2 segundos para configuração completa
⚡ Injeção de Configuração: <500ms incluindo validação
⚡ Uso de Memória: <10MB adicionais durante a implantação
⚡ Operações de Arquivo: Atômicas com <100ms de sobrecarga
⚡ Multiplataforma: Compatibilidade universal com detecção inteligente de spawn

🛠️ Guia de Uso

Comandos Disponíveis

Acesse pela Paleta de Comandos (Ctrl+Shift+P / Cmd+Shift+P):

MCP Diagnostics: Show Status - Abre webview detalhado de status com:
- Status da conexão do servidor
- Estatísticas de problemas por gravidade e origem
- Detalhamento arquivo por arquivo
- Informações das pastas do workspace
- Métricas de desempenho
MCP Diagnostics: Restart Server - Reinicia o servidor MCP com indicação de progresso
MCP Diagnostics: Show Setup Guide - Abre guia abrangente de configuração para clientes MCP

Referência das Ferramentas MCP

🔍 `getProblems` - Consulta Universal de Problemas

Obtenha todos os problemas de diagnóstico com poderosas opções de filtragem:

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

Exemplo de Resposta:

{
  "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` - Diagnósticos Específicos de Arquivo

Obtenha todos os problemas para um arquivo específico:

{
  "name": "getProblemsForFile",
  "arguments": {
    "filePath": "/absolute/path/to/file.ts"
  }
}

📊 `getWorkspaceSummary` - Estatísticas do Workspace

Obtenha estatísticas abrangentes de diagnóstico do workspace:

{
  "name": "getWorkspaceSummary",
  "arguments": {
    "groupBy": "severity" // Optional: severity, source, workspaceFolder
  }
}

Exemplo de Resposta:

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

Recursos MCP

Recursos dinâmicos que fornecem acesso estruturado aos dados de diagnóstico:

diagnostics://summary - Resumo geral dos problemas do workspace
diagnostics://file/{encodedFilePath} - Problemas para arquivo específico
diagnostics://workspace/{encodedWorkspaceName} - Problemas para workspace específico

Notificações em Tempo Real

O servidor envia automaticamente notificações problemsChanged quando os diagnósticos mudam:

{
  "method": "notifications/message",
  "params": {
    "level": "info",
    "data": {
      "type": "problemsChanged",
      "uri": "/path/to/file.ts",
      "problemCount": 3,
      "problems": [...],
      "timestamp": "2024-01-15T10:30:00.000Z"
    }
  }
}

⚙️ Configuração

Personalize a extensão por meio das configurações do VS Code (Ctrl+, / Cmd+,):

{
  "mcpDiagnostics.server.port": 6070,
  "mcpDiagnostics.debounceMs": 300,
  "mcpDiagnostics.enableDebugLogging": false,
  "mcpDiagnostics.enablePerformanceLogging": false,
  "mcpDiagnostics.maxProblemsPerFile": 1000,
  "mcpDiagnostics.debug.logLevel": "info",
  "mcpDiagnostics.showAutoRegistrationNotification": true
}

Opções de Configuração

Configuração	Tipo	Padrão	Descrição
`server.port`	number	6070	Porta do servidor MCP (1024-65535)
`debounceMs`	number	300	Intervalo de debounce para eventos de diagnóstico (50-5000ms)
`enableDebugLogging`	boolean	false	Habilitar registro de depuração detalhado
`enablePerformanceLogging`	boolean	false	Habilitar registro de métricas de desempenho
`maxProblemsPerFile`	number	1000	Máximo de problemas a rastrear por arquivo (1-10000)
`debug.logLevel`	string	"info"	Nível de registro (error, warn, info, debug)
`showAutoRegistrationNotification`	boolean	true	Mostrar notificações de registro do servidor MCP

🧪 Testes e Desenvolvimento

🏆 Conquista Excepcional de Cobertura de Testes

A extensão alcançou padrões de teste de classe mundial:

✅ 810 Testes Passando - Suíte de testes abrangente com 0 falhas (1 ignorado)
✅ 97.99% de Cobertura de Declarações - Excedendo os padrões da indústria
✅ 34 Suítes de Teste - Estrutura de teste organizada e sustentável em todos os componentes
✅ Testes Multiplataforma - Validado em ambientes Windows, macOS e Linux
✅ Testes E2E Abrangentes - Validação completa do fluxo de trabalho da extensão

Servidor Real vs Mock

A extensão fornece dois modos operacionais:

🔴 Extensão Real do VS Code (Modo de Produção)

Propósito: Uso em produção com diagnósticos reais do VS Code
Fonte de Dados: Painel de Problemas ao vivo do VS Code
Ativação: Automática quando a extensão é instalada
Caso de Uso: Fluxos de trabalho reais de desenvolvimento com agentes de IA

🔧 Ferramentas de Desenvolvimento

Validação de Pacote: scripts/validate-package.sh - Verificações automatizadas de integridade do pacote
Conversão de Ativos: scripts/convert-assets.js - Utilitários de otimização de ativos visuais

Workspace de Teste

A extensão inclui test-workspace/ com erros intencionais:

example.ts: Erros de TypeScript (incompatibilidades de tipo, variáveis indefinidas, atribuições inválidas)
utils.js: Avisos do ESLint (variáveis não utilizadas, problemas de estilo, violações de boas práticas)

Para testar a extensão:

Inicie o Host de Desenvolvimento da Extensão (Pressione F5 no VS Code)
Abra o workspace de teste ou qualquer workspace com problemas de diagnóstico
Veja o painel de Problemas (Ctrl+Shift+M) para ver diagnósticos reais
Use as ferramentas MCP para consultar os dados de diagnóstico
Verifique a barra de status para contagens ao vivo de erros/avisos

Configuração de Desenvolvimento

# 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

🔧 Configuração do Cliente MCP

A extensão fornece um servidor MCP universal que funciona com todos os principais ambientes habilitados para MCP. O servidor é executado como um processo Node.js independente e fornece dados de diagnóstico em tempo real do seu workspace.

🎯 Padrão de Configuração Universal

Todos os clientes MCP usam o mesmo padrão básico de configuração com variações específicas do ambiente:

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

📁 Locais dos Arquivos de Configuração

Ambiente	Arquivo de Configuração	Formato
Cursor IDE	`.cursor/mcp.json`	`mcpServers`
VS Code	`.vscode/mcp.json`	`servers` (com `type: "stdio"`)
Windsurf	`.windsurf/mcp.json`	`servers`
Claude Desktop	`claude_desktop_config.json`	`mcpServers`

Exemplos de Configuração do Cliente MCP

Cursor IDE

// .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 com Extensão MCP

// .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

// .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

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

Cliente MCP Personalizado

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' },
});

🚀 Recursos do Servidor MCP

O scripts/mcp-server.js fornece:

🔍 Diagnósticos em Tempo Real: Análise ao vivo de TypeScript e ESLint
📊 Integração com VS Code: Importação automática dos dados do painel de Problemas do VS Code
⚡ Otimizado para Desempenho: Resultados em cache com lógica de atualização inteligente
🛡️ Recuperação de Erros: Fallback gracioso quando os dados do VS Code não estão disponíveis
🔧 Configurável: Variáveis de ambiente para depuração e controle de comportamento

🌍 Variáveis de Ambiente

Variável	Padrão	Descrição
`NODE_ENV`	`development`	Defina como `production` para desempenho otimizado
`MCP_DEBUG`	`false`	Habilitar registro de depuração detalhado
`REFRESH_INTERVAL`	`30000`	Intervalo de atualização do cache em milissegundos
`MAX_PROBLEMS`	`10000`	Número máximo de problemas para armazenar em cache

🔄 Fontes de Dados

O servidor MCP combina inteligentemente várias fontes de dados:

Exportação do VS Code (Primária): Dados em tempo real da extensão
Compilador TypeScript (Fallback): Análise direta do tsc
ESLint (Fallback): Análise direta do ESLint
Resultados em Cache (Desempenho): Cache inteligente com atualização automática


## 📚 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!**