Skip to content
Back to search

lsp-mcp

An MCP server that lets you interact with LSP servers

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tritlo--lsp-mcp/badge.svg)](/listings/tritlo--lsp-mcp)

HTML

<a href="/listings/tritlo--lsp-mcp"><img src="/api/listings/tritlo--lsp-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 515 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # LSP MCP Server
  2. An MCP (Model Context Protocol) server for interacting with LSP (Language Server Protocol) interface.
  3. This server acts as a bridge that allows LLMs to query LSP Hover and Completion providers.
  4. ## Overview
  5. The MCP Server works by:
  6. 1. Starting an LSP client that connects to a LSP server
  7. 2. Exposing MCP tools that send requests to the LSP server
  8. 3. Returning the results in a format that LLMs can understand and use
  9. This enables LLMs to utilize LSPs for more accurate code suggestions.
  10. ## Configuration:
  11. ```json
  12. {
  13. "mcpServers": {
  14. "lsp-mcp": {
  15. "type": "stdio",
  16. "command": "npx",
  17. "args": [
  18. "tritlo/lsp-mcp",
  19. "<language-id>",
  20. "<path-to-lsp>",
  21. "<lsp-args>"
  22. ]
  23. }
  24. }
  25. }
  26. ```
  27. ## Features
  28. ### MCP Tools
  29. - `get_info_on_location`: Get hover information at a specific location in a file
  30. - `get_completions`: Get completion suggestions at a specific location in a file
  31. - `get_code_actions`: Get code actions for a specific range in a file
  32. - `open_document`: Open a file in the LSP server for analysis
  33. - `close_document`: Close a file in the LSP server
  34. - `get_diagnostics`: Get diagnostic messages (errors, warnings) for open files
  35. - `start_lsp`: Start the LSP server with a specified root directory
  36. - `restart_lsp_server`: Restart the LSP server without restarting the MCP server
  37. - `set_log_level`: Change the server's logging verbosity level at runtime
  38. ### MCP Resources
  39. - `lsp-diagnostics://` resources for accessing diagnostic messages with real-time updates via subscriptions
  40. - `lsp-hover://` resources for retrieving hover information at specific file locations
  41. - `lsp-completions://` resources for getting code completion suggestions at specific positions
  42. ### Additional Features
  43. - Comprehensive logging system with multiple severity levels
  44. - Colorized console output for better readability
  45. - Runtime-configurable log level
  46. - Detailed error handling and reporting
  47. - Simple command-line interface
  48. ## Prerequisites
  49. - Node.js (v16 or later)
  50. - npm
  51. For the demo server:
  52. - GHC (8.10 or later)
  53. - Cabal (3.0 or later)
  54. ## Installation
  55. ### Building the MCP Server
  56. 1. Clone this repository:
  57. ```
  58. git clone https://github.com/your-username/lsp-mcp.git
  59. cd lsp-mcp
  60. ```
  61. 2. Install dependencies:
  62. ```
  63. npm install
  64. ```
  65. 3. Build the MCP server:
  66. ```
  67. npm run build
  68. ```
  69. ## Testing
  70. 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.
  71. ### Running Tests
  72. To run the TypeScript LSP tests:
  73. ```
  74. npm test
  75. ```
  76. or specifically:
  77. ```
  78. npm run test:typescript
  79. ```
  80. ### Test Coverage
  81. The tests verify the following functionality:
  82. - Initializing the TypeScript LSP with a mock project
  83. - Opening TypeScript files for analysis
  84. - Getting hover information for functions and types
  85. - Getting code completion suggestions
  86. - Getting diagnostic error messages
  87. - Getting code actions for errors
  88. The test project is located in `test/ts-project/` and contains TypeScript files with intentional errors to test diagnostic feedback.
  89. ## Usage
  90. Run the MCP server by providing the path to the LSP executable and any arguments to pass to the LSP server:
  91. ```
  92. npx tritlo/lsp-mcp <language> /path/to/lsp [lsp-args...]
  93. ```
  94. For example:
  95. ```
  96. npx tritlo/lsp-mcp haskell /usr/bin/haskell-language-server-wrapper lsp
  97. ```
  98. ### Important: Starting the LSP Server
  99. 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:
  100. ```json
  101. {
  102. "tool": "start_lsp",
  103. "arguments": {
  104. "root_dir": "/path/to/your/project"
  105. }
  106. }
  107. ```
  108. ### Logging
  109. The server includes a comprehensive logging system with 8 severity levels:
  110. - `debug`: Detailed information for debugging purposes
  111. - `info`: General informational messages about system operation
  112. - `notice`: Significant operational events
  113. - `warning`: Potential issues that might need attention
  114. - `error`: Error conditions that affect operation but don't halt the system
  115. - `critical`: Critical conditions requiring immediate attention
  116. - `alert`: System is in an unstable state
  117. - `emergency`: System is unusable
  118. By default, logs are sent to:
  119. 1. Console output with color-coding for better readability
  120. 2. MCP notifications to the client (via the `notifications/message` method)
  121. #### Viewing Debug Logs
  122. For detailed debugging, you can:
  123. 1. Use the `claude --mcp-debug` flag when running Claude to see all MCP traffic between Claude and the server:
  124. ```
  125. claude --mcp-debug
  126. ```
  127. 2. Change the log level at runtime using the `set_log_level` tool:
  128. ```json
  129. {
  130. "tool": "set_log_level",
  131. "arguments": {
  132. "level": "debug"
  133. }
  134. }
  135. ```
  136. The default log level is `info`, which shows moderate operational detail while filtering out verbose debug messages.
  137. ## API
  138. The server provides the following MCP tools:
  139. ### get_info_on_location
  140. Gets hover information at a specific location in a file.
  141. Parameters:
  142. - `file_path`: Path to the file
  143. - `language_id`: The programming language the file is written in (e.g., "haskell")
  144. - `line`: Line number
  145. - `column`: Column position
  146. Example:
  147. ```json
  148. {
  149. "tool": "get_info_on_location",
  150. "arguments": {
  151. "file_path": "/path/to/your/file",
  152. "language_id": "haskell",
  153. "line": 3,
  154. "column": 5
  155. }
  156. }
  157. ```
  158. ### get_completions
  159. Gets completion suggestions at a specific location in a file.
  160. Parameters:
  161. - `file_path`: Path to the file
  162. - `language_id`: The programming language the file is written in (e.g., "haskell")
  163. - `line`: Line number
  164. - `column`: Column position
  165. Example:
  166. ```json
  167. {
  168. "tool": "get_completions",
  169. "arguments": {
  170. "file_path": "/path/to/your/file",
  171. "language_id": "haskell",
  172. "line": 3,
  173. "column": 10
  174. }
  175. }
  176. ```
  177. ### get_code_actions
  178. Gets code actions for a specific range in a file.
  179. Parameters:
  180. - `file_path`: Path to the file
  181. - `language_id`: The programming language the file is written in (e.g., "haskell")
  182. - `start_line`: Start line number
  183. - `start_column`: Start column position
  184. - `end_line`: End line number
  185. - `end_column`: End column position
  186. Example:
  187. ```json
  188. {
  189. "tool": "get_code_actions",
  190. "arguments": {
  191. "file_path": "/path/to/your/file",
  192. "language_id": "haskell",
  193. "start_line": 3,
  194. "start_column": 5,
  195. "end_line": 3,
  196. "end_column": 10
  197. }
  198. }
  199. ```
  200. ### start_lsp
  201. Starts the LSP server with a specified root directory. This must be called before using any other LSP-related tools.
  202. Parameters:
  203. - `root_dir`: The root directory for the LSP server (absolute path recommended)
  204. Example:
  205. ```json
  206. {
  207. "tool": "start_lsp",
  208. "arguments": {
  209. "root_dir": "/path/to/your/project"
  210. }
  211. }
  212. ```
  213. ### restart_lsp_server
  214. 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.
  215. Parameters:
  216. - `root_dir`: (Optional) The root directory for the LSP server. If provided, the server will be initialized with this directory after restart.
  217. Example without root_dir (uses previously set root directory):
  218. ```json
  219. {
  220. "tool": "restart_lsp_server",
  221. "arguments": {}
  222. }
  223. ```
  224. Example with root_dir:
  225. ```json
  226. {
  227. "tool": "restart_lsp_server",
  228. "arguments": {
  229. "root_dir": "/path/to/your/project"
  230. }
  231. }
  232. ```
  233. ### open_document
  234. Opens a file in the LSP server for analysis. This must be called before accessing diagnostics or performing other operations on the file.
  235. Parameters:
  236. - `file_path`: Path to the file to open
  237. - `language_id`: The programming language the file is written in (e.g., "haskell")
  238. Example:
  239. ```json
  240. {
  241. "tool": "open_document",
  242. "arguments": {
  243. "file_path": "/path/to/your/file",
  244. "language_id": "haskell"
  245. }
  246. }
  247. ```
  248. ### close_document
  249. Closes a file in the LSP server when you're done working with it. This helps manage resources and cleanup.
  250. Parameters:
  251. - `file_path`: Path to the file to close
  252. Example:
  253. ```json
  254. {
  255. "tool": "close_document",
  256. "arguments": {
  257. "file_path": "/path/to/your/file"
  258. }
  259. }
  260. ```
  261. ### get_diagnostics
  262. Gets diagnostic messages (errors, warnings) for one or all open files.
  263. Parameters:
  264. - `file_path`: (Optional) Path to the file to get diagnostics for. If not provided, returns diagnostics for all open files.
  265. Example for a specific file:
  266. ```json
  267. {
  268. "tool": "get_diagnostics",
  269. "arguments": {
  270. "file_path": "/path/to/your/file"
  271. }
  272. }
  273. ```
  274. Example for all open files:
  275. ```json
  276. {
  277. "tool": "get_diagnostics",
  278. "arguments": {}
  279. }
  280. ```
  281. ### set_log_level
  282. Sets the server's logging level to control verbosity of log messages.
  283. Parameters:
  284. - `level`: The logging level to set. One of: `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency`.
  285. Example:
  286. ```json
  287. {
  288. "tool": "set_log_level",
  289. "arguments": {
  290. "level": "debug"
  291. }
  292. }
  293. ```
  294. ## MCP Resources
  295. In addition to tools, the server provides resources for accessing LSP features including diagnostics, hover information, and code completions:
  296. ### Diagnostic Resources
  297. The server exposes diagnostic information via the `lsp-diagnostics://` resource scheme. These resources can be subscribed to for real-time updates when diagnostics change.
  298. Resource URIs:
  299. - `lsp-diagnostics://` - Diagnostics for all open files
  300. - `lsp-diagnostics:///path/to/file` - Diagnostics for a specific file
  301. Important: Files must be opened using the `open_document` tool before diagnostics can be accessed.
  302. ### Hover Information Resources
  303. 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.
  304. Resource URI format:
  305. ```
  306. lsp-hover:///path/to/file?line={line}&column={column}&language_id={language_id}
  307. ```
  308. Parameters:
  309. - `line`: Line number (1-based)
  310. - `column`: Column position (1-based)
  311. - `language_id`: The programming language (e.g., "haskell")
  312. Example:
  313. ```
  314. lsp-hover:///home/user/project/src/Main.hs?line=42&column=10&language_id=haskell
  315. ```
  316. ### Code Completion Resources
  317. The server exposes code completion suggestions via the `lsp-completions://` resource scheme. This allows you to get completion candidates at specific positions in files.
  318. Resource URI format:
  319. ```
  320. lsp-completions:///path/to/file?line={line}&column={column}&language_id={language_id}
  321. ```
  322. Parameters:
  323. - `line`: Line number (1-based)
  324. - `column`: Column position (1-based)
  325. - `language_id`: The programming language (e.g., "haskell")
  326. Example:
  327. ```
  328. lsp-completions:///home/user/project/src/Main.hs?line=42&column=10&language_id=haskell
  329. ```
  330. ### Listing Available Resources
  331. To discover available resources, use the MCP `resources/list` endpoint. The response will include all available resources for currently open files, including:
  332. - Diagnostics resources for all open files
  333. - Hover information templates for all open files
  334. - Code completion templates for all open files
  335. ### Subscribing to Resource Updates
  336. 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.
  337. Note: Hover and completion resources don't support subscriptions as they represent point-in-time queries.
  338. ### Working with Resources vs. Tools
  339. You can choose between two approaches for accessing LSP features:
  340. 1. Tool-based approach: Use the `get_diagnostics`, `get_info_on_location`, and `get_completions` tools for a simple, direct way to fetch information.
  341. 2. Resource-based approach: Use the `lsp-diagnostics://`, `lsp-hover://`, and `lsp-completions://` resources for a more RESTful approach.
  342. Both approaches provide the same data in the same format and enforce the same requirement that files must be opened first.
  343. ## Troubleshooting
  344. - If the server fails to start, make sure the path to the LSP executable is correct
  345. - Check the log file (if configured) for detailed error messages
  346. ## License
  347. MIT License
  348. ## Extensions
  349. The LSP-MCP server supports language-specific extensions that enhance its capabilities for different programming languages. Extensions can provide:
  350. - Custom LSP-specific tools and functionality
  351. - Language-specific resource handlers and templates
  352. - Specialized prompts for language-related tasks
  353. - Custom subscription handlers for real-time data
  354. ### Available Extensions
  355. Currently, the following extensions are available:
  356. - **Haskell**: Provides specialized prompts for Haskell development, including typed-hole exploration guidance
  357. ### Using Extensions
  358. Extensions are loaded automatically when you specify a language ID when starting the server:
  359. ```
  360. npx tritlo/lsp-mcp haskell /path/to/haskell-language-server-wrapper lsp
  361. ```
  362. ### Extension Namespacing
  363. 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`.
  364. ### Creating New Extensions
  365. To create a new extension:
  366. 1. Create a new TypeScript file in `src/extensions/` named after your language (e.g., `typescript.ts`)
  367. 2. Implement the Extension interface with any of these optional functions:
  368. - `getToolHandlers()`: Provide custom tool implementations
  369. - `getToolDefinitions()`: Define custom tools in the MCP API
  370. - `getResourceHandlers()`: Implement custom resource handlers
  371. - `getSubscriptionHandlers()`: Implement custom subscription handlers
  372. - `getUnsubscriptionHandlers()`: Implement custom unsubscription handlers
  373. - `getResourceTemplates()`: Define custom resource templates
  374. - `getPromptDefinitions()`: Define custom prompts for language tasks
  375. - `getPromptHandlers()`: Implement custom prompt handlers
  376. 3. Export your implementation functions
  377. The extension system will automatically load your extension when the matching language ID is specified.
  378. ## Acknowledgments
  379. - HLS team for the Language Server Protocol implementation
  380. - Anthropic for the Model Context Protocol specification

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.