内容
# LSP-MCP 服务器 — 面向 LLM 的通用 IntelliSense
一款自动连接正确的 **语言服务器** （clangd、pyright、tsserver、gopls、rust-analyzer…）并为 Claude Code 提供全语言 IntelliSense 支持的 MCP 服务器，包括 **CUDA**：错误诊断、补全、类型信息和代码导航。
## 支持的语言
| 语言 | LSP 服务器 | 扩展名 |
|---|---|---|
| C / C++ / Qt / CUDA | clangd | .c .h .cpp .cxx .cc .hpp .hxx .hh .ipp .cu .cuh |
| Python | pyright / pylsp | .py .pyi |
| TypeScript / JavaScript | typescript-language-server | .ts .tsx .js .jsx .mjs .cjs |
| Go | gopls | .go |
| Rust | rust-analyzer | .rs |
| Java | jdtls | .java |
| Kotlin | kotlin-language-server | .kt .kts |
| Zig | zls | .zig |
| Lua | lua-language-server | .lua |
| Bash / Shell | bash-language-server | .sh .bash .zsh |
| CSS / SCSS / LESS | vscode-css-languageserver | .css .scss .less |
| HTML | vscode-html-languageserver | .html .htm |
| JSON | vscode-json-languageserver | .json .jsonc |
| CMake | cmake-language-server | .cmake |
服务器**自动选择**合适的 LSP 服务器，基于文件扩展名。打开 `.cpp` 文件 — clangd 启动。打开 `.py` 文件 — pyright 启动。所有操作均透明。
## 工作原理
```
Claude Code ──(MCP/stdio)──► lsp-mcp-server ──(LSP/JSON-RPC)──► clangd
│ pyright
│ tsserver
└── ServerPool ──────────────► gopls
(延迟启动， rust-analyzer
每个语言一个) ...
```
语言服务器**延迟启动** — 仅在请求该类型文件的第一个文件时启动。客户端在所有工具调用期间缓存并重用。
LLM 可以：
1. **编写前** — 通过 `get_completions` 和 `get_hover` 查询函数签名
2. **编写后** — 运行 `diagnose_file` 或 `diagnose_workspace` 查看错误
3. **重构期间** — 通过 `find_references` 查找所有用法
## 安装
### 选项 A：自动设置（推荐）
```bash
git clone https://github.com/goodwinka/lsp-mcp-server
cd lsp-mcp-server
bash install.sh
```
脚本构建服务器，检查已安装的语言服务器，并为当前项目生成 `.mcp.json`。
### 选项 B：手动设置
#### 1. 构建服务器
```bash
cd lsp-mcp-server
npm install
npm run build # 编译 TypeScript → dist/
# 或在没有构建步骤的情况下进行开发：
npm run dev # 直接通过 tsx 运行
```
#### 2. 安装所需的语言服务器
仅安装与您的项目相关的语言服务器：
```bash
# C++ / Qt
sudo apt install clangd # 或：brew install llvm
# Python
npm install -g pyright # 或：pip install pyright
# TypeScript / JavaScript
npm install -g typescript-language-server typescript
# Go
go install golang.org/x/tools/gopls@latest
# Rust
rustup component add rust-analyzer
# Bash
npm install -g bash-language-server
# CSS / HTML / JSON
npm install -g vscode-langservers-extracted
# CMake
pip install cmake-language-server
# 注意：仅适用于 .cmake 文件，不适用于 CMakeLists.txt
# Lua
brew install lua-language-server # macOS
# Linux：从 https://github.com/LuaLS/lua-language-server/releases 下载
# Java (Eclipse JDT LS)
# 下载并安装：https://github.com/eclipse-jdtls/eclipse.jdt.ls/releases
# 确保 `jdtls` 命令在 PATH 中可用
# Kotlin
# 从 https://github.com/fwcd/kotlin-language-server/releases 下载
# 确保 `kotlin-language-server` 在 PATH 中可用
# Zig
# 从 https://github.com/zigtools/zls/releases 下载
# 确保 `zls` 在 PATH 中可用
```
使用 `list_servers` 工具查看系统上已安装的内容。
#### 3. 连接到 Claude Code
**选项 A：项目配置** （项目根目录中的 `.mcp.json`）
```json
{
"mcpServers": {
"intellisense": {
"command": "node",
"args": ["/absolute/path/to/lsp-mcp-server/dist/index.js", "--project", "."]
}
}
}
```
**选项 B：全局配置** （`~/.claude/claude_desktop_config.json`）
```json
{
"mcpServers": {
"intellisense": {
"command": "node",
"args": [
"/absolute/path/to/lsp-mcp-server/dist/index.js",
"--project", "/path/to/your/project"
]
}
}
}
```
**选项 C：环境变量**
```json
{
"mcpServers": {
"intellisense": {
"command": "node",
"args": ["/absolute/path/to/lsp-mcp-server/dist/index.js"],
"env": {
"LSP_PROJECT_ROOT": "/path/to/your/project",
"LSP_MCP_DEBUG": "1"
}
}
}
}
```
## 可用工具
| 工具 | 描述 |
|---|---|
| `diagnose_file` | 文件磁盘上的编译错误/警告 |
| `diagnose_workspace` | 当前会话中所有打开的文件的错误/警告，跨所有语言服务器 |
| `get_completions` | 给定位置（基于 0 的行/字符）的补全 |
| `get_hover` | 符号的类型和文档 |
| `get_definitions` | 跳转到符号定义 |
| `find_references` | 查找项目中符号的所有用法 |
| `get_symbols` | 文件的符号树（类、函数、变量…） |
| `list_servers` | 显示所有语言、服务器状态（运行中 / 已安装 / 缺失） |
### diagnose_workspace
在一个调用中返回整个工作区的诊断摘要，无需文件内容。报告总错误和警告、受影响的文件数量以及每个文件的详细信息。
示例输出（干净）：
```
✅ 工作区干净 — 3 个文件已检查，无错误或警告
```
示例输出（有问题）：
```
发现 2 个错误，1 个警告，跨 1/3 个文件：
src/main.cpp 中发现 2 个诊断：
ERROR src/main.cpp:12:5 [clang]: 'QWidget' 中没有名为 'nonExistent' 的成员
WARN src/main.cpp:8:3 [clang]: 未使用的变量 'x'
```
## 使用示例
```
> 检查 src/mainwindow.cpp 中的错误
→ [clangd] diagnose_file("src/mainwindow.cpp")
> 检查所有打开的文件中的错误
→ diagnose_workspace()
> 检查 app/models.py
→ [pyright] diagnose_file("app/models.py")
> QTableView 有哪些方法？
→ 在 .cpp 文件上使用 get_completions，参数为 QTableView*
> 显示 pandas.read_csv 的签名
→ 在 .py 文件上使用 get_hover
> 有哪些服务器可用？
→ list_servers
```
## C++ / Qt 的提示
clangd 在项目根目录中有 `compile_commands.json` 时效果最佳：
```bash
# CMake
cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ..
# qmake 通过 Bear
bear -- make
# 或手动 — 在项目根目录中创建 .clangd 文件：
cat > .clangd << 'EOF'
CompileFlags:
Add:
- -std=c++17
- -I/usr/include/qt6
- -I/usr/include/qt6/QtCore
- -I/usr/include/qt6/QtWidgets
- -I/usr/include/qt6/QtGui
- -fPIC
EOF
```
**混合 C/C++ 项目**：`.clangd` 中的 `-std=c++17` 标志与纯 `.c` 文件不兼容。对于混合 `.c` 和 `.cpp` 的项目，请改用 `compile_commands.json`。
## CUDA 的提示
### CUDA C++（.cu，.cuh）
clangd 原生支持 CUDA（它基于 clang）。您需要安装 CUDA 工具包：
```bash
# 验证安装
nvcc --version
```
为了获得最佳的 IntelliSense 结果，请生成 `compile_commands.json`：
```bash
# 带有 CUDA 的 CMake
cmake -DCMAKE_CUDA_COMPILER=nvcc -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ..
```
或在项目根目录中创建 `.clangd` 文件：
```yaml
CompileFlags:
Add:
- --cuda-gpu-arch=sm_75
- --cuda-path=/usr/local/cuda
- -I/usr/local/cuda/include
- -std=c++17
```
如果没有 CUDA 工具包，clangd 将报告 `Cannot find CUDA installation`。请安装工具包以解决此问题。
### CUDA Python（CuPy、Numba、PyCUDA）
Python CUDA 库通过标准的 pyright 工作 — 无需特殊设置。
为了改善类型检查，请安装存根：
```bash
# CuPy — 存根在包中捆绑
pip install cupy-cuda12x # 或 cupy-cuda11x
# Numba
pip install numba
# PyCUDA
pip install pycuda
```
pyright 将自动从已安装的包中获取类型。
## Python 的提示
pyright 自动读取 `pyrightconfig.json` 和 `pyproject.toml`。对于虚拟环境，请在启动前激活 `venv`，或在配置文件中指定解释器路径：
```json
{
"venvPath": ".",
"venv": ".venv"
}
```
如果同时安装了 `pyright` 和 `pylsp`，**pyright** 将被使用（它在注册表中列出在前）。要使用 pylsp，请删除或重命名 `pyright-langserver`。
## TypeScript / JavaScript 的提示
`typescript-language-server` 在可用时使用项目的 `node_modules` 中的 TypeScript 编译器，否则会回退到全局安装的 `typescript`。
```bash
npm install -g typescript-language-server typescript
```
对于 monorepos 或具有 `tsconfig.json` 的项目，请在根目录外配置 `tsconfig.json` 路径 — tsserver 自动获取它。
## CLI
```
--project, -p <path> 项目根路径（必需）
--help, -h 显示帮助并退出
```
## 环境变量
| 变量 | 描述 |
|---|---|
| `LSP_PROJECT_ROOT` | 项目路径（如果未设置 `--project`） |
| `LSP_MCP_DEBUG=1` | 将语言服务器的 stderr 输出到 stdout |
## 故障排除
### 为我的文件选择了哪个服务器？
使用 `list_servers` 工具 — 它显示所有服务器、其状态和支持的扩展名。服务器根据文件扩展名自动选择。
### 同时安装了 pyright 和 pylsp
**pyright** 在注册表中列出在前，将用于 `.py` 文件。要使用 pylsp，请删除或重命名 `pyright-langserver`。
### CMakeLists.txt 未被诊断
`cmake-language-server` 仅适用于 `.cmake` 文件。`CMakeLists.txt` 不支持 — 这是当前基于扩展名的语言检测的限制。
### 服务器已启动，但无诊断信息出现
启用调试输出（`LSP_MCP_DEBUG=1`）并检查语言服务器的 stderr。对于 C++ 项目，请确保存在 `compile_commands.json` 或 `.clangd` 文件。
### 错误 "path is outside project root"
所有文件路径必须**相对于指定的项目根目录** `--project`。不接受绝对路径。
## 许可证
MIT
