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