Lsp MCP Server

LSP Server - REQUIRED FIRST STEP

BEFORE any code analysis, navigation, or codebase exploration, you MUST:

1. Run lsp_server_status to check running servers
2. If the relevant language server is NOT running → run lsp_start_server immediately
3. ONLY AFTER the LSP server is running, proceed with analysis

This is a hard requirement, not a preference. Do NOT skip this step.

LSP Tool Requirements

When LSP MCP tools are available, you MUST use them instead of alternatives:

Prohibited Patterns

When LSP is available, NEVER do these:

• NEVER use Grep to find function/class/symbol definitions
• NEVER use Grep to find where a symbol is referenced
• NEVER use Glob to find files containing a symbol name
• NEVER use Read to scan through a file looking for definitions
• NEVER use Bash with grep/rg/find for code navigation

These tools are still appropriate for:

• Searching for text/strings (not code symbols)
• Reading configuration files
• Reading documentation files
• File operations unrelated to code navigation

LSP Tool Quick Reference

lsp_server_status          # Check what's running
lsp_start_server           # Start a language server
lsp_goto_definition        # Jump to where symbol is defined
lsp_goto_type_definition   # Jump to type definition
lsp_find_references        # Find all usages of a symbol
lsp_find_implementations   # Find concrete implementations
lsp_workspace_symbols      # Search symbols across project
lsp_document_symbols       # Get outline of a file
lsp_hover                  # Get type/docs for symbol
lsp_signature_help         # Get function parameter hints
lsp_completions            # Get code completions
lsp_diagnostics            # Get errors/warnings for a file
lsp_workspace_diagnostics  # Get errors/warnings across project
lsp_file_exports           # Get public API of a module
lsp_file_imports           # Get imports/dependencies of a file
lsp_related_files          # Find connected files (imports/imported by)
lsp_rename                 # Rename symbol across codebase
lsp_code_actions           # Get/apply quick fixes and refactorings
lsp_call_hierarchy         # See callers and callees
lsp_type_hierarchy         # See type inheritance
lsp_format_document        # Format code
lsp_smart_search           # Combined: definition + refs + hover
lsp_find_symbol            # Find symbol by name with full context

这确保 Claude Code 将：
- 始终在分析代码之前启动 LSP 服务器。
- 使用语义 LSP 工具而不是基于文本的搜索进行代码导航。
- 仅在非代码搜索（字符串、配置文件、文档）时回退到 Grep/Glob。

### 高级用法
#### 可用工具示例
##### 导航工具
- **`lsp_goto_definition`**：导航到符号的定义位置。

Input:

• file_path: Absolute path to the source file
• line: Line number (1-indexed)
• column: Column number (1-indexed)

Output:

• definitions: Array of locations with path, line, column, and context

**示例提示**："Go to the definition of the function at line 42, column 10 in /project/src/utils.ts"

- **`lsp_goto_type_definition`**：导航到符号的类型定义位置。

Input:

• file_path: Absolute path to the source file
• line: Line number (1-indexed)
• column: Column number (1-indexed)

Output:

• definitions: Array of type definition locations

**示例提示**："Find the type definition for the variable at line 15, column 5 in /project/src/app.ts"

##### 引用工具
- **`lsp_find_references`**：查找工作区中符号的所有引用。

Input:

• file_path: Absolute path to the source file
• line: Line number (1-indexed)
• column: Column number (1-indexed)
• include_declaration: Whether to include the declaration (default: true)
• limit: Maximum results (default: 100, max: 500)
• offset: Skip results for pagination (default: 0)

Output:

• references: Array of locations
• total_count: Total number of references found
• has_more: Whether there are more results

**示例提示**："Find all references to the 'UserService' class in /project/src/services/user.ts at line 5"

- **`lsp_find_implementations`**：查找接口或抽象方法的所有实现。

Input:

• file_path: Absolute path to the source file
• line: Line number (1-indexed)
• column: Column number (1-indexed)
• limit: Maximum results (default: 50, max: 100)

Output:

• implementations: Array of implementation locations
• total_count: Total implementations found
• has_more: Whether there are more results

**示例提示**："Find all implementations of the interface at line 10 in /project/src/types.ts"

##### 信息工具
- **`lsp_hover`**：获取符号的悬停信息（类型信息、文档）。

Input:

• file_path: Absolute path to the source file
• line: Line number (1-indexed)
• column: Column number (1-indexed)

Output:

• contents: Markdown-formatted type information and documentation
• range: The range of the hovered symbol (optional)

**示例提示**："What is the type of the variable at line 25, column 8 in /project/src/main.ts?"

- **`lsp_signature_help`**：在调用表达式中获取函数/方法的签名信息。

Input:

• file_path: Absolute path to the source file
• line: Line number (1-indexed)
• column: Column number (1-indexed)

Output:

• signatures: Array of function signatures with parameters
• active_signature: Index of the active signature
• active_parameter: Index of the active parameter

**示例提示**："What are the parameters for the function call at line 30 in /project/src/api.ts?"

##### 符号工具
- **`lsp_document_symbols`**：获取文档中定义的所有符号（函数、类、变量等）。

Input:

• file_path: Absolute path to the source file

Output:

• symbols: Hierarchical array of symbols with name, kind, range, and children

**示例提示**："List all symbols in /project/src/components/Button.tsx"

- **`lsp_workspace_symbols`**：按名称在整个工作区中搜索符号。

Input:

• query: Search query (supports fuzzy matching)
• kinds: Filter by symbol kinds (optional): Class, Function, Interface, Variable, etc.
• limit: Maximum results (default: 50, max: 100)

Output:

• symbols: Array of matching symbols with path and location
• total_count: Total matches found
• has_more: Whether there are more results

**示例提示**："Search for all classes containing 'Service' in the workspace"

- **`lsp_find_symbol`**：按名称查找符号并获取其全面信息，无需文件路径。

Input:

• name: Symbol name to search for (supports fuzzy matching)
• kind: Filter to specific symbol kind (optional): Class, Function, Interface, etc.
• include: Array of what to include: 'hover', 'definition', 'references', 'implementations', 'incoming_calls', 'outgoing_calls' (default: ['hover', 'definition', 'references'])
• references_limit: Maximum references to return (default: 20)

Output:

• query: The symbol that was searched for
• match: The best matching symbol found
• matches_found: Number of total matches
• definition: Where the symbol is defined
• hover: Type information and documentation
• references: All usages of the symbol
• implementations: Implementations (for interfaces)
• incoming_calls: Functions that call this
• outgoing_calls: Functions this calls

**示例提示**："Find the UserService class and show me all its references"

##### 文件分析工具
- **`lsp_file_exports`**：获取文件的公共 API 表面，即所有导出的函数、类、接口和变量。

Input:

• file_path: Absolute path to the source file
• include_signatures: Include type signatures from hover (default: true, slower but more informative)

Output:

• file: The file path
• exports: Array of exported items with name, kind, line, column, and signature
• note: Additional information

**示例提示**："What does /project/src/utils/index.ts export?"

- **`lsp_file_imports`**：获取文件的所有导入和依赖项。

Input:

• file_path: Absolute path to the source file

Output:

• file: The file path
• imports: Array of imports with module, line, symbols, is_type_only, is_dynamic
• note: Additional information

**示例提示**："What modules does /project/src/api/client.ts import?"

- **`lsp_related_files`**：查找与给定文件相关的文件，即它导入的文件和导入它的文件。

Input:

• file_path: Absolute path to the source file
• relationship: Which relationships to include: 'imports', 'imported_by', or 'all' (default: 'all')

Output:

• file: The file path
• imports: Array of files this file imports
• imported_by: Array of files that import this file
• note: Additional information

**示例提示**："What files depend on /project/src/services/auth.ts?"

##### 诊断工具
- **`lsp_diagnostics`**：获取文件的缓存诊断信息（错误、警告）。

Input:

• file_path: Absolute path to the source file
• severity_filter: Filter by severity - 'all', 'error', 'warning', 'info', 'hint' (default: 'all')

Output:

• diagnostics: Array of diagnostics with range, severity, message, and code
• summary: Count of errors, warnings, info, and hints
• note: Information about diagnostic caching

**示例提示**："Show me all errors in /project/src/index.ts"

- **`lsp_workspace_diagnostics`**：获取工作区中所有打开文件的诊断信息。

Input:

• severity_filter: Filter by severity - 'all', 'error', 'warning', 'info', 'hint' (default: 'all')
• limit: Maximum diagnostics to return (default: 50, max: 200)
• group_by: How to group results - 'file' or 'severity' (default: 'file')

Output:

• items: Array of diagnostics with file, line, column, severity, message, and context
• total_count: Total diagnostics found
• returned_count: Number returned (may be limited)
• files_affected: Number of files with diagnostics
• summary: Count of errors, warnings, info, and hints
• note: Information about diagnostic caching

**示例提示**："Show me all errors across the entire project"

##### 补全工具
- **`lsp_completions`**：在指定位置获取代码补全建议。

Input:

• file_path: Absolute path to the source file
• line: Line number (1-indexed)
• column: Column number (1-indexed)
• limit: Maximum suggestions (default: 20, max: 50)

Output:

• completions: Array of completion items with label, kind, detail, and documentation
• is_incomplete: Whether the list is incomplete

**示例提示**："What completions are available at line 15, column 10 in /project/src/app.ts?"

##### 重构工具
- **`lsp_rename`**：在工作区中重命名符号。

Input:

• file_path: Absolute path to the source file
• line: Line number (1-indexed)
• column: Column number (1-indexed)
• new_name: The new name for the symbol
• dry_run: Preview changes without applying (default: true)

Output:

• changes: Map of file paths to arrays of edits
• files_affected: Number of files that would be modified
• edits_count: Total number of edits
• applied: Whether changes were applied
• original_name: The original symbol name (if available)

**示例提示**："Rename the function 'getUserData' to 'fetchUserData' at line 20 in /project/src/api.ts (dry run first)"

- **`lsp_code_actions`**：在指定位置或范围内获取可用的代码操作（重构、快速修复），并可选择应用这些操作。

Input:

• file_path: Absolute path to the source file
• start_line: Start line number (1-indexed)
• start_column: Start column number (1-indexed)
• end_line: End line number (optional, defaults to start line)
• end_column: End column number (optional, defaults to start column)
• kinds: Filter by action kinds (optional): quickfix, refactor, refactor.extract, refactor.inline, source.organizeImports, etc.
• apply: If true, apply the action at action_index (default: false)
• action_index: Index of action to apply when apply=true (default: 0)

Output:

• actions: Array of available code actions with title, kind, and edits
• total_count: Number of available actions
• applied: The action that was applied (if apply=true and successful)

**示例提示**："What refactoring options are available for the function at line 50 in /project/src/utils.ts?"
**示例提示**："Apply the first quick fix for the error at line 15 in /project/src/api.ts"

- **`lsp_format_document`**：使用语言服务器的格式化功能格式化文档。

Input:

• file_path: Absolute path to the source file
• tab_size: Spaces per tab (default: 2)
• insert_spaces: Use spaces instead of tabs (default: true)
• apply: Apply formatting to file (default: false)

Output:

• edits: Array of formatting edits with range and new_text
• edits_count: Number of edits
• applied: Whether edits were applied

**示例提示**："Format /project/src/messy-file.ts using the language server"

##### 层次结构工具
- **`lsp_call_hierarchy`**：获取函数的调用层次结构，即调用该函数的函数和该函数调用的函数。

Input:

• file_path: Absolute path to the source file
• line: Line number (1-indexed)
• column: Column number (1-indexed)
• direction: 'incoming' (callers), 'outgoing' (callees), or 'both' (default: 'both')

Output:

• item: The call hierarchy item at the position
• incoming_calls: Array of functions that call this function
• outgoing_calls: Array of functions this function calls

**示例提示**："Show me all functions that call handleRequest at line 100 in /project/src/server.ts"

- **`lsp_type_hierarchy`**：获取类或接口的类型层次结构，即超类型和子类型。

Input:

• file_path: Absolute path to the source file
• line: Line number (1-indexed)
• column: Column number (1-indexed)
• direction: 'supertypes' (parents), 'subtypes' (children), or 'both' (default: 'both')

Output:

• item: The type hierarchy item at the position
• supertypes: Array of parent types/interfaces
• subtypes: Array of child types/implementations

**示例提示**："What classes implement the Repository interface at line 5 in /project/src/types.ts?"

##### 组合工具
- **`lsp_smart_search`**：在一次调用中结合多个 LSP 操作进行全面的符号搜索。

Input:

• file_path: Absolute path to the source file
• line: Line number (1-indexed)
• column: Column number (1-indexed)
• include: Array of what to include: 'hover', 'definition', 'references', 'implementations', 'incoming_calls', 'outgoing_calls' (default: ['hover', 'definition', 'references'])
• references_limit: Maximum references to return (default: 20)

Output:

• symbol_name: Name of the symbol
• hover: Type information and documentation
• definition: Where the symbol is defined
• references: All usages of the symbol
• implementations: Implementations (for interfaces)
• incoming_calls: Functions that call this
• outgoing_calls: Functions this calls

**示例提示**："Give me a complete analysis of the processData function at line 75 in /project/src/processor.ts - definition, all references, and what calls it"

##### 服务器管理工具
- **`lsp_server_status`**：获取正在运行的语言服务器的状态。

Input:

• server_id: Specific server to check (optional, omit for all servers)

Output:

• servers: Array of server status objects with id, status, capabilities, uptime, etc.

**示例提示**："Show the status of all language servers"

- **`lsp_start_server`**：手动为特定工作区启动语言服务器。

Input:

• server_id: Server ID from configuration (e.g., 'typescript', 'python')
• workspace_root: Absolute path to the workspace/project root

Output:

• status: 'started'
• server_id: The server that was started
• workspace_root: The workspace root
• capabilities: List of supported capabilities

**示例提示**："Start the TypeScript language server for /home/user/my-project"

- **`lsp_stop_server`**：停止正在运行的语言服务器。

Input:

• server_id: Server ID to stop
• workspace_root: Workspace root (optional, omit to stop all instances)

Output:

• status: 'stopped'
• server_id: The server that was stopped
• was_running: Whether the server was actually running

**示例提示**："Stop the Python language server"

## 📚 详细文档
### 支持的语言
以下语言开箱即用：
| 语言 | 服务器 | 命令 | 文件扩展名 | 根模式 |
|----------|--------|---------|-----------------|---------------|
| **TypeScript/JavaScript** | typescript-language-server | `typescript-language-server --stdio` | `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs` | `tsconfig.json`, `jsconfig.json`, `package.json` |
| **Python** | pylsp | `pylsp` | `.py`, `.pyi` | `pyproject.toml`, `setup.py`, `requirements.txt`, `Pipfile` |
| **Rust** | rust-analyzer | `rust-analyzer` | `.rs` | `Cargo.toml` |
| **Go** | gopls | `gopls serve` | `.go` | `go.mod`, `go.work` |
| **C/C++** | clangd | `clangd --background-index` | `.c`, `.h`, `.cpp`, `.hpp`, `.cc`, `.cxx` | `compile_commands.json`, `CMakeLists.txt`, `Makefile` |
| **Ruby** | solargraph | `solargraph stdio` | `.rb`, `.rake`, `.gemspec` | `Gemfile`, `.ruby-version`, `Rakefile` |
| **PHP** | intelephense | `intelephense --stdio` | `.php`, `.phtml` | `composer.json`, `index.php` |
| **Elixir** | elixir-ls | `elixir-ls` | `.ex`, `.exs`, `.heex`, `.leex` | `mix.exs`, `.formatter.exs` |
| **Kotlin** | kotlin-lsp | `kotlin-lsp` | `.kt`, `.kts` | `build.gradle`, `build.gradle.kts`, `settings.gradle`, `settings.gradle.kts` |
| **Java** | jls | `jls` | `.java` | `pom.xml`, `build.gradle`, `build.gradle.kts`, `settings.gradle`, `settings.gradle.kts`, `BUILD`, `.classpath` |

你可以通过提供自定义配置来添加其他语言（请参阅[配置](#配置)）。

### 配置
#### 配置文件
在以下位置之一创建配置文件（按优先级排序）：
1. `./.lsp-mcp.json`（当前目录）
2. `./lsp-mcp.json`（当前目录）
3. `~/.config/lsp-mcp/config.json`（XDG 配置）
4. `~/.lsp-mcp.json`（主目录）

或者设置 `LSP_CONFIG_PATH` 环境变量来指定自定义路径。

**示例配置：**
```json
{
  "servers": [
    {
      "id": "typescript",
      "extensions": [".ts", ".tsx", ".js", ".jsx"],
      "languageIds": ["typescript", "typescriptreact", "javascript", "javascriptreact"],
      "command": "typescript-language-server",
      "args": ["--stdio"],
      "rootPatterns": ["tsconfig.json", "package.json"]
    },
    {
      "id": "python",
      "extensions": [".py"],
      "languageIds": ["python"],
      "command": "pylsp",
      "args": [],
      "rootPatterns": ["pyproject.toml", "setup.py", "requirements.txt"]
    }
  ],
  "requestTimeout": 30000,
  "autoStart": true,
  "logLevel": "info",
  "idleTimeout": 1800000
}

配置选项

服务器配置

servers 数组中的每个服务器具有以下属性：

环境变量

安全特性

lsp-mcp-server 包含以下安全措施：

• 绝对路径强制：所有文件路径必须是绝对路径，以防止路径遍历攻击。
• 工作区边界验证：文件修改（重命名、格式化、代码操作）仅限于工作区根目录内。
• 文件大小限制：拒绝大于 10 MB 的文件，以防止内存耗尽。
• 无 shell 执行：语言服务器以 shell: false 方式启动，以防止命令注入。

使用示例与 Claude Code

基本导航

"I'm looking at /project/src/services/auth.ts. Can you tell me what the validateToken function at line 45 does? Use lsp_hover to get its documentation." "Go to the definition of UserRepository used at line 23, column 15 in /project/src/controllers/user.ts"

查找用法

"Find all places where the handleError function is called in my codebase. It's defined at line 10 in /project/src/utils/error.ts" "I want to refactor the Config interface. First, find all its implementations using lsp_find_implementations"

代码质量

"Check /project/src/index.ts for any TypeScript errors using lsp_diagnostics" "Show me all errors and warnings across the entire project using lsp_workspace_diagnostics"

安全重构

"I want to rename the getData function to fetchData. It's at line 50 in /project/src/api.ts. First do a dry run to see what would change." "The dry run looks good. Now apply the rename by setting dry_run to false."

代码探索

"List all the symbols in /project/src/models/User.ts to understand its structure" "Search the workspace for all classes that contain 'Controller' in their name" "Find the UserService class and tell me everything about it - definition, references, and what calls it"

文件分析

"What does /project/src/utils/index.ts export?" "What files depend on /project/src/services/auth.ts? Use lsp_related_files" "Show me all the imports in /project/src/api/client.ts"

补全

"What methods are available on the object at line 30, column 5 in /project/src/app.ts? Use lsp_completions"

代码操作和重构

"What refactoring options are available for the code selection from line 20 to 35 in /project/src/utils.ts?" "Organize imports in /project/src/components/App.tsx using lsp_code_actions with kinds filter for source.organizeImports" "Apply the first quick fix for the error at line 15 in /project/src/api.ts"

理解代码流程

"Show me the call hierarchy for the processOrder function at line 50 in /project/src/orders.ts - I want to see what calls it" "What does the authenticate function call? Use lsp_call_hierarchy with outgoing direction" "Show me the type hierarchy for the BaseRepository class - what are its subtypes?"

综合分析

"Give me a complete analysis of the UserService class at line 10 in /project/src/services/user.ts - I want definition, all references, implementations, and call hierarchy. Use lsp_smart_search"

格式化

"Format /project/src/unformatted.ts using the language server (preview first, don't apply)"

故障排除

未找到语言服务器

错误：Failed to start language server: typescript-language-server 解决方案：安装语言服务器：

npm install -g typescript-language-server typescript

无诊断信息显示

问题：lsp_diagnostics 返回空结果 解释：诊断信息是基于推送的。语言服务器在文件打开或更改时发送诊断信息。 解决方案：

1. 首先使用其他工具打开文件。
2. 等待服务器分析片刻。
3. 再次尝试。

服务器反复崩溃

问题：服务器不断崩溃并重启 解决方案：

1. 检查 LSP_LOG_LEVEL=debug 的详细日志。
2. 验证语言服务器是否正确安装。
3. 检查工作区是否有有效的配置（例如，TypeScript 的 tsconfig.json）。

位置错误

问题："Invalid position" 错误 注意：所有位置均从 1 开始计数（第一行是 1，第一列是 1），而不是从 0 开始。

路径错误

问题："File path must be absolute" 错误 注意：所有文件路径必须是绝对路径（例如，/home/user/project/src/file.ts，而不是 src/file.ts）。

超时错误

问题：请求超时 解决方案：增加超时时间：

export LSP_REQUEST_TIMEOUT=60000  # 60 seconds

或者在配置中设置：

{
  "requestTimeout": 60000
}

文件过大

问题："File too large" 错误 解释：为防止内存问题，拒绝大于 10 MB 的文件。 解决方案：处理较小的文件或将大文件拆分为模块。

开发

构建

npm run build        # Compile TypeScript
npm run dev          # Watch mode
npm run typecheck    # Type-check only

测试

npm test             # Run unit tests
npm run test:watch   # Watch mode

交互式测试

使用 MCP 检查器进行交互式测试：

npx @modelcontextprotocol/inspector node dist/index.js

代码检查

npm run lint         # Check for issues
npm run lint:fix     # Auto-fix issues