Diagnostic Inspection & Indexing

Relevant source files

The following files were used as context for generating this wiki page:

• src/tools/diagnostics.ts
• src/tools/index-files.ts
• src/services/diagnostics-cache.ts
• src/schemas/tool-schemas.ts
• src/index.ts
• src/types.ts
• SKILL.md

Diagnostic Inspection & Indexing represents a core subsystem of the lsp-mcp-server designed to retrieve, filter, and manage code health data (errors, warnings, hints) emitted by Language Servers. This system bridges the push-based notification model of the Language Server Protocol (LSP) with the request-based tool model of the Model Context Protocol (MCP).

The subsystem is responsible for "warming up" the codebase through file indexing, which triggers the LSP's diagnostic engine, and providing tools to inspect these results at both the file and workspace levels. This process is essential because most LSP servers only publish diagnostics for files that have been explicitly opened or "touched" during the current session.
Sources: src/services/diagnostics-cache.ts:31-35, src/tools/index-files.ts:33-35, SKILL.md:121-125

Diagnostic Management Architecture

The system relies on a central cache that stores diagnostics received from language servers via publishDiagnostics notifications. Because diagnostics are push-based, the server must maintain an internal state to allow subsequent user queries to succeed.

Data Flow for Diagnostics

The diagram above shows how diagnostics move from the Language Server into the server's cache before being retrieved by tool handlers.
Sources: src/services/diagnostics-cache.ts:37-44, src/index.ts:468-472, CLAUDE.md:46-49

The Diagnostics Cache

The DiagnosticsCacheImpl provides a global storage for all active diagnostics. It tracks counts for errors, warnings, info messages, and hints across all files.

Feature	Implementation Detail
Storage	Uses a Map<string, Diagnostic[]> keyed by file URI.
Update Mechanism	Updated immediately upon receiving an LSP notification.
Clearing Logic	Clears specific entries on document close; clears all on server restart.
Summarization	Calculates total counts for various severity levels.

Sources: src/services/diagnostics-cache.ts:37-104, src/types.ts:257-278

Indexing and "Warm-up" Operations

Language servers typically do not scan the entire workspace automatically to prevent performance degradation. The lsp_index_files tool provides a manual trigger to "warm up" specific files.

Indexing Workflow

When lsp_index_files is called, the system performs a parallel "didOpen" operation for each provided path. This effectively "touches" the files, forcing the LSP server to analyze them and push diagnostics to the cache.

Tool Reference

Inspection Tools

Tool	Scope	Description
lsp_diagnostics	File	Retrieves cached diagnostics for a specific file. Requires the file to be opened.
lsp_workspace_diagnostics	Project	Aggregates all cached diagnostics across the session.
lsp_index_files	Batch	Opens multiple files to trigger the diagnostic publishing process.

Sources: src/index.ts:183-228, src/tools/diagnostics.ts:40-155

Input Schemas & Filtering

Diagnostics can be filtered by severity levels: all, error, warning, info, or hint. The system enforces a SEVERITY_ORDER to ensure that a filter for "warning" also includes "error" results.

const SEVERITY_ORDER = { error: 1, warning: 2, info: 3, hint: 4 };

Sources: src/tools/diagnostics.ts:37, src/schemas/tool-schemas.ts:114-129

Core Logic Implementation

Workspace Diagnostic Aggregation

The handleWorkspaceDiagnostics function iterates through all URIs in the diagnosticsCache. It attempts to retrieve file content from the documentManager or directly from the disk to provide "context lines" for each diagnostic entry.

// src/tools/diagnostics.ts:101-110
for (const uri of uris) {
    const diagnostics = ctx.diagnosticsCache.get(uri);
    if (diagnostics.length === 0) continue;

    const filePath = uriToPath(uri);
    filesWithDiagnostics.add(filePath);

    // Get file content for context lines
    let content = ctx.documentManager.getContent(uri);
    if (!content) {
      try {
        content = await readFile(filePath);
      } catch {
        content = '';
      }
    }
    // ... logic to filter and map results
}

Sources: src/tools/diagnostics.ts:101-137

Conclusion

Diagnostic Inspection & Indexing ensures that the AI model has access to semantic code health information without needing to run external compilers manually. By combining proactive indexing via lsp_index_files with the push-based caching mechanism in DiagnosticsCache, the system provides a low-latency view of errors and warnings across complex projects. Users must remember the "warm-up" rule: lsp_workspace_diagnostics only sees files that have been previously "touched" or indexed during the active session.
Sources: SKILL.md:158-164, src/services/diagnostics-cache.ts:31-35