LSP Conduit Service for Contextual Analysis

This document details the code-analyzer-protocol-bridge, an intermediary layer engineered to translate Model Context Protocol (MCP) invocations into standardized Language Server Protocol (LSP) queries. This facilitates large language models (LLMs) in obtaining real-time, rich semantic understanding of source code.

Core Operation

The conduit server operates by establishing an active LSP client connection. It then exposes a set of MCP endpoints that proxy requests (like textDocument/hover or textDocument/completion) to the underlying LSP server, subsequently translating the raw LSP responses into an LLM-digestible format.

Configuration Schema

To instantiate this service, the following structure is required within the MCP configuration block:

{ "mcpServers": { "code-analyzer-protocol-bridge": { "type": "stdio", "command": "npx", "args": [ "tritlo/lsp-mcp", "", "", "" ] } } }

Exposed MCP Interfaces

Operational Tools (Methods)

• fetch_semantic_hint: Retrieves contextual documentation or type information upon cursor hover.
• propose_code_substitutions: Generates lists of potential code completions for the current insertion point.
• retrieve_refactoring_options: Fetches available code transformations or fixes for a selected code segment.
• document_lifecycle_register: Notifies the LSP server that a file is now being actively analyzed (opened).
• document_lifecycle_deregister: Notifies the LSP server that analysis of a file is concluded (closed).
• fetch_static_analysis_report: Queries for immediate diagnostic feedback (errors, warnings) associated with open documents.
• initiate_lsp_session: Starts the connection sequence to the external LSP daemon, defining the project root.
• reset_lsp_session: Forces a termination and restart of the remote LSP daemon process only.
• adjust_operational_verbosity: Modifies the internal logging detail level during runtime.

Data Access Resources (URIs)

• lsp-diagnostics:// prefixes: Used for subscribing to or fetching streams of code correctness reports.
• lsp-hover:// prefixes: Endpoints for obtaining point-in-time structural metadata.
• lsp-completions:// prefixes: Access points for gathering suggested code tokens.

Installation & Setup

Prerequisites include Node.js (version 16+) and npm.

To compile the conduit service from source:

bash git clone https://github.com/your-username/lsp-mcp.git cd lsp-mcp npm install npm run build

Execution Example

To activate the service, specifying the language context and the path to the associated language server (e.g., Haskell's HLS):

bash npx tritlo/lsp-mcp haskell /usr/local/bin/haskell-language-server --lsp-mode

Critical Initialization Step

Versions 0.2.0 and later require an explicit session initiation via the initiate_lsp_session tool before any data-fetching tools can be successfully invoked:

{ "tool": "initiate_lsp_session", "arguments": { "root_dir": "/absolute/path/to/workspace" } }

Logging Structure

The system employs an eight-tier logging hierarchy, ranging from verbose internal tracing (debug) to catastrophic failure notification (emergency). By default, the operational detail is set to info.

Logs are simultaneously routed to: 1. The console (with semantic coloring). 2. MCP notifications sent back to the primary client.

To observe all inter-process communication traffic, invoke the primary agent with a debug flag: bash claude --mcp-debug

API Detail: fetch_semantic_hint

Retrieves descriptive context for an entity under the cursor.

Parameters: - file_path: Absolute or relative path to the analyzed source file. - language_id: Identifier for the language context (e.g., "typescript"). - line: 1-indexed line coordinate. - column: 1-indexed character coordinate within the line.

API Detail: Resource Access (RESTful Paradigm)

Users can interact with data either through direct tool invocation or by querying structured resource URIs. Diagnostics are particularly suited for subscription-based monitoring via the resources/subscribe endpoint, provided the file has been registered using document_lifecycle_register.

Resource URI Template for Hover Data:

lsp-hover:///file/location?line={L}&column={C}&language_id={ID}

System Extensibility (Plugins)

The architecture supports loading language-specific modules (extensions/). When a language identifier (e.g., haskell) is provided at startup, the system automatically loads corresponding handlers for custom tools, resource templates, and specialized language prompts, namespacing all new functionality under the provided language ID.