LSP MCP Server

LSP MCP 服务

一个用于与 LSP（Language Server Protocol）接口交互的 MCP（Model Context Protocol）服务。 该服务充当桥梁，让大模型能够查询 LSP 的 Hover 和 Completion 提供程序。

概述

该 MCP 服务的工作方式如下：

1. 启动一个连接到 LSP 服务的 LSP 客户端
2. 暴露向 LSP 服务发送请求的 MCP 工具
3. 以 LLM 能够理解和使用的方式返回结果

这使大模型能够利用 LSP 获得更准确的代码建议。

配置：

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

功能

MCP 工具

• get_info_on_location：获取文件中特定位置的悬停信息
• get_completions：获取文件中特定位置的补全建议
• get_code_actions：获取文件中特定范围的代码操作
• open_document：在 LSP 服务中打开文件以进行分析
• close_document：关闭 LSP 服务中的文件
• get_diagnostics：获取已打开文件的诊断消息（错误、警告）
• start_lsp：使用指定的根目录启动 LSP 服务
• restart_lsp_server：重启 LSP 服务而无需重启 MCP 服务
• set_log_level：在运行时更改服务的日志详细级别

MCP 资源

• lsp-diagnostics:// 资源，用于访问诊断消息，并通过订阅实现实时更新
• lsp-hover:// 资源，用于检索特定文件位置的悬停信息
• lsp-completions:// 资源，用于获取特定位置的代码补全建议

其他功能

• 具有多个严重级别、全面的日志系统
• 彩色化控制台输出，提升可读性
• 可在运行时配置的日志级别
• 详细的错误处理与报告
• 简单的命令行界面

前置条件

• Node.js（v16 或更高版本）
• npm

对于演示服务：

• GHC（8.10 或更高版本）
• Cabal（3.0 或更高版本）

安装

构建 MCP 服务

1. 克隆此仓库：

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

2. 安装依赖：

   npm install
   

3. 构建 MCP 服务：

   npm run build
   

测试

该项目包含针对 TypeScript LSP 支持的集成测试。这些测试验证 LSP-MCP 服务能够正确处理悬停信息、补全、诊断和代码操作等 LSP 操作。

运行测试

要运行 TypeScript LSP 测试：

npm test

或具体运行：

npm run test:typescript

测试覆盖范围

这些测试验证以下功能：

• 使用模拟项目初始化 TypeScript LSP
• 打开 TypeScript 文件以进行分析
• 获取函数和类型的悬停信息
• 获取代码补全建议
• 获取诊断错误消息
• 获取针对错误的代码操作

测试项目位于 test/ts-project/，其中包含带有故意错误的 TypeScript 文件，用于测试诊断反馈。

用法

通过提供 LSP 可执行文件的路径以及要传递给 LSP 服务的任何参数来运行 MCP 服务：

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

例如：

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

重要：启动 LSP 服务

从 0.2.0 及更高版本开始，你必须先调用 start_lsp 工具显式启动 LSP 服务，然后才能使用任何 LSP 功能。这可确保使用正确的根目录进行正确初始化，在使用 npx 等工具时尤为重要：

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

日志

该服务包含一个全面的日志系统，具有 8 个严重级别：

• debug：用于调试目的的详细信息
• info：有关系统运行的一般信息性消息
• notice：重要的运行事件
• warning：可能需要关注的潜在问题
• error：影响运行但不会导致系统停止的错误状况
• critical：需要立即关注的关键状况
• alert：系统处于不稳定状态
• emergency：系统不可用

默认情况下，日志会发送到：

1. 带有颜色编码的控制台输出，提升可读性
2. 发送给客户端的 MCP 通知（通过 notifications/message 方法）

查看调试日志

如需详细调试，你可以：

1. 在运行 Claude 时使用 claude --mcp-debug 标志，查看 Claude 与服务之间的所有 MCP 流量：

   claude --mcp-debug
   

2. 使用 set_log_level 工具在运行时更改日志级别：

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

默认日志级别为 info，它会显示适度的操作细节，同时过滤掉冗长的调试消息。

API

该服务提供以下 MCP 工具：

get_info_on_location

获取文件中特定位置的悬停信息。

参数：

• file_path：文件路径
• language_id：文件所使用的编程语言（例如 "haskell"）
• line：行号
• column：列位置

示例：

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

get_completions

获取文件中特定位置的补全建议。

参数：

• file_path：文件路径
• language_id：文件所使用的编程语言（例如 "haskell"）
• line：行号
• column：列位置

示例：

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

get_code_actions

获取文件中特定范围的代码操作。

参数：

• file_path：文件路径
• language_id：文件所使用的编程语言（例如 "haskell"）
• start_line：起始行号
• start_column：起始列位置
• end_line：结束行号
• end_column：结束列位置

示例：

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

使用指定的根目录启动 LSP 服务。必须先调用此工具，然后才能使用任何其他与 LSP 相关的工具。

参数：

• root_dir：LSP 服务的根目录（建议使用绝对路径）

示例：

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

restart_lsp_server

在不重启 MCP 服务的情况下重启 LSP 服务进程。这有助于从 LSP 服务问题中恢复，或应用对 LSP 服务配置的更改。

参数：

• root_dir：（可选）LSP 服务的根目录。如果提供，服务将在重启后使用此目录进行初始化。

不带 root_dir 的示例（使用之前设置的根目录）：

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

带 root_dir 的示例：

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

open_document

在 LSP 服务中打开文件以进行分析。必须先调用此工具，然后才能访问诊断信息或对该文件执行其他操作。

参数：

• file_path：要打开的文件的路径
• language_id：文件所使用的编程语言（例如 "haskell"）

示例：

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

close_document

在完成对文件的操作后，在 LSP 服务中关闭该文件。这有助于管理资源和进行清理。

参数：

• file_path：要关闭的文件的路径

示例：

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

get_diagnostics

获取一个或所有已打开文件的诊断消息（错误、警告）。

参数：

• file_path：（可选）要获取诊断信息的文件的路径。如果未提供，则返回所有已打开文件的诊断信息。

针对特定文件的示例：

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

针对所有已打开文件的示例：

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

set_log_level

设置服务的日志记录级别，以控制日志消息的详细程度。

参数：

• level：要设置的日志记录级别。可为以下之一：debug、info、notice、warning、error、critical、alert、emergency。

示例：

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

MCP 资源

除工具外，该服务还提供用于访问 LSP 功能的资源，包括诊断信息、悬停信息和代码补全：

诊断资源

该服务通过 lsp-diagnostics:// 资源方案公开诊断信息。可以订阅这些资源，以便在诊断信息发生变化时实时获取更新。

资源 URI：

• lsp-diagnostics:// - 所有已打开文件的诊断信息
• lsp-diagnostics:///path/to/file - 特定文件的诊断信息

重要：必须先使用 open_document 工具打开文件，然后才能访问诊断信息。

悬停信息 资源

该服务通过 lsp-hover:// 资源方案暴露悬停信息。这让你可以获取文件中特定位置代码元素的信息。

资源 URI 格式：

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

参数：

• line：行号（从 1 开始）
• column：列位置（从 1 开始）
• language_id：编程语言（例如 "haskell"）

示例：

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

代码补全 资源

该服务通过 lsp-completions:// 资源方案暴露代码补全建议。这让你可以获取文件中特定位置的补全候选。

资源 URI 格式：

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

参数：

• line：行号（从 1 开始）
• column：列位置（从 1 开始）
• language_id：编程语言（例如 "haskell"）

示例：

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

列出可用资源

要发现可用资源，请使用 MCP resources/list 端点。响应将包含当前打开文件的所有可用资源，包括：

• 所有打开文件的诊断资源
• 所有打开文件的悬停信息模板
• 所有打开文件的代码补全模板

订阅资源更新

诊断资源支持订阅，以便在诊断发生变化时（例如文件被修改并出现新的错误或警告时）接收实时更新。使用 MCP resources/subscribe 端点订阅诊断资源。

注意：悬停和补全资源不支持订阅，因为它们表示的是时间点查询。

使用资源与使用工具

你可以选择两种方式来访问 LSP 功能：

1. 基于工具的方式：使用 get_diagnostics、get_info_on_location 和 get_completions 工具，以简单直接的方式获取信息。
2. 基于资源的方式：使用 lsp-diagnostics://、lsp-hover:// 和 lsp-completions:// 资源，以获得更符合 REST 风格的方式。

两种方式提供相同格式的相同数据，并强制执行相同的要求：必须先打开文件。

故障排除

• 如果服务启动失败，请确保 LSP 可执行文件的路径正确
• 检查日志文件（如果已配置）以获取详细错误信息

许可证

MIT License

扩展

LSP-MCP 服务支持特定语言的扩展，以增强其针对不同编程语言的能力。扩展可以提供：

• 自定义的 LSP 专用工具和功能
• 特定语言的资源处理器和模板
• 用于语言相关任务的专用提示词
• 用于实时数据的自定义订阅处理器

可用扩展

目前，以下扩展可用：

• Haskell：为 Haskell 开发提供专用提示词，包括 typed-hole 探索指南

使用扩展

当你在启动服务时指定语言 ID 后，扩展会自动加载：

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

扩展命名空间

所有由扩展提供的功能都以语言 ID 作为命名空间。例如，Haskell 扩展的 typed-hole 提示词可通过 haskell.typed-hole-use 使用。

创建新扩展

要创建新扩展：

1. 在 src/extensions/ 中创建一个以你的语言命名的新 TypeScript 文件（例如 typescript.ts）

2. 实现 Extension 接口，并提供以下任意可选函数：

   • getToolHandlers()：提供自定义工具实现
   • getToolDefinitions()：在 MCP API 中定义自定义工具
   • getResourceHandlers()：实现自定义资源处理程序
   • getSubscriptionHandlers()：实现自定义订阅处理程序
   • getUnsubscriptionHandlers()：实现自定义取消订阅处理程序
   • getResourceTemplates()：定义自定义资源模板
   • getPromptDefinitions()：为语言任务定义自定义提示词
   • getPromptHandlers()：实现自定义提示词处理程序

3. 导出你的实现函数

当指定匹配的语言 ID 时，扩展系统会自动加载你的扩展。

致谢

• HLS 团队提供 Language Server Protocol 实现
• Anthropic 提供 Model Context Protocol 规范