lsp-mcp

What is lsp-mcp?

lsp-mcp is a Model Context Protocol (MCP) server designed to bridge the gap between Large Language Models (LLMs) and Language Server Protocol (LSP) servers. It allows LLMs to interact with LSP servers to obtain rich context information, such as hover details, code completion suggestions, and code actions, thereby enhancing the LLM's ability to provide accurate code-related assistance.

How to use lsp-mcp?

To use lsp-mcp, you first need to install Node.js (v16 or later) and npm. You can then build the server by cloning the repository, installing dependencies (npm install), and running the build command (npm run build).

To run the MCP server, you execute it via npx and provide the language, path to the LSP executable, and any LSP arguments:

npx tritlo/lsp-mcp <language> /path/to/lsp [lsp-args...]

For example:

npx tritlo/lsp-mcp haskell /usr/bin/haskell-language-server-wrapper lsp

Important: With version 0.2.0 and later, you must explicitly start the LSP server by calling the start_lsp tool before using any LSP functionality. This ensures proper initialization with the correct root directory.

Key Features of lsp-mcp

lsp-mcp offers a comprehensive set of features to facilitate interaction between LLMs and LSP servers:

MCP Tools

• get_info_on_location: Retrieve hover information at a specific file location.
• get_completions: Obtain code completion suggestions.
• get_code_actions: Get code actions for a specified range.
• open_document: Open a file in the LSP server for analysis.
• close_document: Close a file in the LSP server.
• get_diagnostics: Get diagnostic messages (errors, warnings) for open files.
• start_lsp: Start the LSP server with a specified root directory.
• restart_lsp_server: Restart the LSP server without restarting the MCP server.
• set_log_level: Change the server's logging verbosity level at runtime.

MCP Resources

• lsp-diagnostics://: Access diagnostic messages with real-time updates via subscriptions.
• lsp-hover://: Retrieve hover information at specific file locations.
• lsp-completions://: Get code completion suggestions at specific positions.

Additional Features

• Comprehensive logging system with multiple severity levels.
• Colorized console output for better readability.
• Runtime-configurable log level.
• Detailed error handling and reporting.
• Simple command-line interface.
• Support for language-specific extensions to enhance capabilities (e.g., Haskell extension).

Use Cases of lsp-mcp

lsp-mcp is primarily designed to empower LLMs with enhanced code understanding and generation capabilities. Specific use cases include:

• Intelligent Code Suggestions: LLMs can leverage LSP completions to provide more accurate and context-aware code suggestions.
• Automated Code Refactoring: By utilizing code actions, LLMs can suggest and apply automated refactorings.
• Contextual Code Explanations: LLMs can use hover information to explain code elements and their purpose.
• Real-time Error Detection and Correction: Access to diagnostics allows LLMs to identify and potentially suggest fixes for errors and warnings.
• Building AI-powered Development Tools: Developers can integrate lsp-mcp into their AI-driven tools to provide richer code interaction.

FAQ about lsp-mcp

Q: What are the prerequisites for running lsp-mcp? A: You need Node.js (v16 or later) and npm. For the demo server, GHC (8.10 or later) and Cabal (3.0 or later) are also required.

Q: How do I start the LSP server with lsp-mcp? A: You must explicitly call the start_lsp tool with the desired root directory before using any other LSP functionality.

Q: How can I view detailed debug logs? A: You can use the claude --mcp-debug flag when running Claude to see all MCP traffic, or change the log level at runtime using the set_log_level tool to debug.

Q: What is the difference between using MCP Tools and MCP Resources? A: Both approaches provide the same data in the same format. Tools offer a direct way to fetch information, while resources provide a more RESTful approach. Diagnostic resources also support subscriptions for real-time updates.

Q: Can I extend lsp-mcp for other languages? A: Yes, lsp-mcp supports language-specific extensions. You can create a new TypeScript file in src/extensions/ and implement the Extension interface to provide custom tools, resource handlers, and prompts for your desired language.

LSP MCP Server

An MCP (Model Context Protocol) server for interacting with LSP (Language Server Protocol) interface. This server acts as a bridge that allows LLMs to query LSP Hover and Completion providers.

Overview

The MCP Server works by:

1. Starting an LSP client that connects to a LSP server
2. Exposing MCP tools that send requests to the LSP server
3. Returning the results in a format that LLMs can understand and use

This enables LLMs to utilize LSPs for more accurate code suggestions.

Configuration:

{
  "mcpServers": {
    "lsp-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "tritlo/lsp-mcp",
        "<language-id>",
        "<path-to-lsp>",
        "<lsp-args>"
      ]
    }
  }
}

Features

MCP Tools

• get_info_on_location: Get hover information at a specific location in a file
• get_completions: Get completion suggestions at a specific location in a file
• get_code_actions: Get code actions for a specific range in a file
• open_document: Open a file in the LSP server for analysis
• close_document: Close a file in the LSP server
• get_diagnostics: Get diagnostic messages (errors, warnings) for open files
• start_lsp: Start the LSP server with a specified root directory
• restart_lsp_server: Restart the LSP server without restarting the MCP server
• set_log_level: Change the server's logging verbosity level at runtime

MCP Resources

• lsp-diagnostics:// resources for accessing diagnostic messages with real-time updates via subscriptions
• lsp-hover:// resources for retrieving hover information at specific file locations
• lsp-completions:// resources for getting code completion suggestions at specific positions

Additional Features

• Comprehensive logging system with multiple severity levels
• Colorized console output for better readability
• Runtime-configurable log level
• Detailed error handling and reporting
• Simple command-line interface

Prerequisites

• Node.js (v16 or later)
• npm

For the demo server:

• GHC (8.10 or later)
• Cabal (3.0 or later)

Installation

Building the MCP Server

1. Clone this repository:

   git clone https://github.com/your-username/lsp-mcp.git
   cd lsp-mcp
   

2. Install dependencies:

   npm install
   

3. Build the MCP server:

   npm run build
   

Testing

The project includes integration tests for the TypeScript LSP support. These tests verify that the LSP-MCP server correctly handles LSP operations like hover information, completions, diagnostics, and code actions.

Running Tests

To run the TypeScript LSP tests:

npm test

or specifically:

npm run test:typescript

Test Coverage

The tests verify the following functionality:

• Initializing the TypeScript LSP with a mock project
• Opening TypeScript files for analysis
• Getting hover information for functions and types
• Getting code completion suggestions
• Getting diagnostic error messages
• Getting code actions for errors

The test project is located in test/ts-project/ and contains TypeScript files with intentional errors to test diagnostic feedback.

Usage

Run the MCP server by providing the path to the LSP executable and any arguments to pass to the LSP server:

npx tritlo/lsp-mcp <language> /path/to/lsp [lsp-args...]

For example:

npx tritlo/lsp-mcp haskell /usr/bin/haskell-language-server-wrapper lsp

Important: Starting the LSP Server

With version 0.2.0 and later, you must explicitly start the LSP server by calling the start_lsp tool before using any LSP functionality. This ensures proper initialization with the correct root directory, which is especially important when using tools like npx:

{
  "tool": "start_lsp",
  "arguments": {
    "root_dir": "/path/to/your/project"
  }
}

Logging

The server includes a comprehensive logging system with 8 severity levels:

• debug: Detailed information for debugging purposes
• info: General informational messages about system operation
• notice: Significant operational events
• warning: Potential issues that might need attention
• error: Error conditions that affect operation but don't halt the system
• critical: Critical conditions requiring immediate attention
• alert: System is in an unstable state
• emergency: System is unusable

By default, logs are sent to:

1. Console output with color-coding for better readability
2. MCP notifications to the client (via the notifications/message method)

Viewing Debug Logs

For detailed debugging, you can:

1. Use the claude --mcp-debug flag when running Claude to see all MCP traffic between Claude and the server:

   claude --mcp-debug
   

2. Change the log level at runtime using the set_log_level tool:

   {
     "tool": "set_log_level",
     "arguments": {
       "level": "debug"
     }
   }
   

The default log level is info, which shows moderate operational detail while filtering out verbose debug messages.

API

The server provides the following MCP tools:

get_info_on_location

Gets hover information at a specific location in a file.

Parameters:

• file_path: Path to the file
• language_id: The programming language the file is written in (e.g., "haskell")
• line: Line number
• column: Column position

Example:

{
  "tool": "get_info_on_location",
  "arguments": {
    "file_path": "/path/to/your/file",
    "language_id": "haskell",
    "line": 3,
    "column": 5
  }
}

get_completions

Gets completion suggestions at a specific location in a file.

Parameters:

• file_path: Path to the file
• language_id: The programming language the file is written in (e.g., "haskell")
• line: Line number
• column: Column position

Example:

{
  "tool": "get_completions",
  "arguments": {
    "file_path": "/path/to/your/file",
    "language_id": "haskell",
    "line": 3,
    "column": 10
  }
}

get_code_actions

Gets code actions for a specific range in a file.

Parameters:

• file_path: Path to the file
• language_id: The programming language the file is written in (e.g., "haskell")
• start_line: Start line number
• start_column: Start column position
• end_line: End line number
• end_column: End column position

Example:

{
  "tool": "get_code_actions",
  "arguments": {
    "file_path": "/path/to/your/file",
    "language_id": "haskell",
    "start_line": 3,
    "start_column": 5,
    "end_line": 3,
    "end_column": 10
  }
}

start_lsp

Starts the LSP server with a specified root directory. This must be called before using any other LSP-related tools.

Parameters:

• root_dir: The root directory for the LSP server (absolute path recommended)

Example:

{
  "tool": "start_lsp",
  "arguments": {
    "root_dir": "/path/to/your/project"
  }
}

restart_lsp_server

Restarts the LSP server process without restarting the MCP server. This is useful for recovering from LSP server issues or for applying changes to the LSP server configuration.

Parameters:

• root_dir: (Optional) The root directory for the LSP server. If provided, the server will be initialized with this directory after restart.

Example without root_dir (uses previously set root directory):

{
  "tool": "restart_lsp_server",
  "arguments": {}
}

Example with root_dir:

{
  "tool": "restart_lsp_server",
  "arguments": {
    "root_dir": "/path/to/your/project"
  }
}

open_document

Opens a file in the LSP server for analysis. This must be called before accessing diagnostics or performing other operations on the file.

Parameters:

• file_path: Path to the file to open
• language_id: The programming language the file is written in (e.g., "haskell")

Example:

{
  "tool": "open_document",
  "arguments": {
    "file_path": "/path/to/your/file",
    "language_id": "haskell"
  }
}

close_document

Closes a file in the LSP server when you're done working with it. This helps manage resources and cleanup.

Parameters:

• file_path: Path to the file to close

Example:

{
  "tool": "close_document",
  "arguments": {
    "file_path": "/path/to/your/file"
  }
}

get_diagnostics

Gets diagnostic messages (errors, warnings) for one or all open files.

Parameters:

• file_path: (Optional) Path to the file to get diagnostics for. If not provided, returns diagnostics for all open files.

Example for a specific file:

{
  "tool": "get_diagnostics",
  "arguments": {
    "file_path": "/path/to/your/file"
  }
}

Example for all open files:

{
  "tool": "get_diagnostics",
  "arguments": {}
}

set_log_level

Sets the server's logging level to control verbosity of log messages.

Parameters:

• level: The logging level to set. One of: debug, info, notice, warning, error, critical, alert, emergency.

Example:

{
  "tool": "set_log_level",
  "arguments": {
    "level": "debug"
  }
}

MCP Resources

In addition to tools, the server provides resources for accessing LSP features including diagnostics, hover information, and code completions:

Diagnostic Resources

The server exposes diagnostic information via the lsp-diagnostics:// resource scheme. These resources can be subscribed to for real-time updates when diagnostics change.

Resource URIs:

• lsp-diagnostics:// - Diagnostics for all open files
• lsp-diagnostics:///path/to/file - Diagnostics for a specific file

Important: Files must be opened using the open_document tool before diagnostics can be accessed.

Hover Information Resources

The server exposes hover information via the lsp-hover:// resource scheme. This allows you to get information about code elements at specific positions in files.

Resource URI format:

lsp-hover:///path/to/file?line={line}&column={column}&language_id={language_id}

Parameters:

• line: Line number (1-based)
• column: Column position (1-based)
• language_id: The programming language (e.g., "haskell")

Example:

lsp-hover:///home/user/project/src/Main.hs?line=42&column=10&language_id=haskell

Code Completion Resources

The server exposes code completion suggestions via the lsp-completions:// resource scheme. This allows you to get completion candidates at specific positions in files.

Resource URI format:

lsp-completions:///path/to/file?line={line}&column={column}&language_id={language_id}

Parameters:

• line: Line number (1-based)
• column: Column position (1-based)
• language_id: The programming language (e.g., "haskell")

Example:

lsp-completions:///home/user/project/src/Main.hs?line=42&column=10&language_id=haskell

Listing Available Resources

To discover available resources, use the MCP resources/list endpoint. The response will include all available resources for currently open files, including:

• Diagnostics resources for all open files
• Hover information templates for all open files
• Code completion templates for all open files

Subscribing to Resource Updates

Diagnostic resources support subscriptions to receive real-time updates when diagnostics change (e.g., when files are modified and new errors or warnings appear). Subscribe to diagnostic resources using the MCP resources/subscribe endpoint.

Note: Hover and completion resources don't support subscriptions as they represent point-in-time queries.

Working with Resources vs. Tools

You can choose between two approaches for accessing LSP features:

1. Tool-based approach: Use the get_diagnostics, get_info_on_location, and get_completions tools for a simple, direct way to fetch information.
2. Resource-based approach: Use the lsp-diagnostics://, lsp-hover://, and lsp-completions:// resources for a more RESTful approach.

Both approaches provide the same data in the same format and enforce the same requirement that files must be opened first.

Troubleshooting

• If the server fails to start, make sure the path to the LSP executable is correct
• Check the log file (if configured) for detailed error messages

License

MIT License

Extensions

The LSP-MCP server supports language-specific extensions that enhance its capabilities for different programming languages. Extensions can provide:

• Custom LSP-specific tools and functionality
• Language-specific resource handlers and templates
• Specialized prompts for language-related tasks
• Custom subscription handlers for real-time data

Available Extensions

Currently, the following extensions are available:

• Haskell: Provides specialized prompts for Haskell development, including typed-hole exploration guidance

Using Extensions

Extensions are loaded automatically when you specify a language ID when starting the server:

npx tritlo/lsp-mcp haskell /path/to/haskell-language-server-wrapper lsp

Extension Namespacing

All extension-provided features are namespaced with the language ID. For example, the Haskell extension's typed-hole prompt is available as haskell.typed-hole-use.

Creating New Extensions

To create a new extension:

1. Create a new TypeScript file in src/extensions/ named after your language (e.g., typescript.ts)

2. Implement the Extension interface with any of these optional functions:

   • getToolHandlers(): Provide custom tool implementations
   • getToolDefinitions(): Define custom tools in the MCP API
   • getResourceHandlers(): Implement custom resource handlers
   • getSubscriptionHandlers(): Implement custom subscription handlers
   • getUnsubscriptionHandlers(): Implement custom unsubscription handlers
   • getResourceTemplates(): Define custom resource templates
   • getPromptDefinitions(): Define custom prompts for language tasks
   • getPromptHandlers(): Implement custom prompt handlers

3. Export your implementation functions

The extension system will automatically load your extension when the matching language ID is specified.

Acknowledgments

• HLS team for the Language Server Protocol implementation
• Anthropic for the Model Context Protocol specification