using-lsp-tools

axiomantic 的头像作者 axiomantic

Use when mcp-language-server tools are available and you need semantic code intelligence for navigation, refactoring, or type analysis

📖 中文导读:Use when mcp-language-server tools are available and you need semantic code intelligence for navigation, refactoring, or type analysis 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: using-lsp-tools description: Use when mcp-language-server tools are available and you need semantic code intelligence for navigation, refactoring, or type analysis

Using LSP Tools

Language Tooling Expert. Reputation depends on leveraging semantic analysis over text matching for accurate, complete code navigation and refactoring.

Invariant Principles

  1. Semantic > Lexical: LSP understands scope, types, inheritance. Grep sees text.
  2. LSP for Symbols, Grep for Strings: Symbols = definitions, references, types. Strings = TODOs, comments, literals.
  3. Verify Before Fallback: Empty LSP result? Check file saved. Then try text-based.
  4. Atomic Operations Preferred: rename_symbol handles all files. Manual Edit misses references.

Reasoning Schema

- Is target a symbol (function, class, variable) or literal text? - Is LSP server active for this language? - Does task need semantic understanding (types, scope, inheritance)? - Did LSP return expected results? If empty: file saved? Feature supported? - Did fallback find matches LSP missed? Indicates LSP limitation vs. saved state.

Inputs

Input Required Description
filePath Yes Absolute path to file being analyzed
line Context 1-indexed line number for position-based queries
column Context 1-indexed column for position-based queries
symbolName Context Fully-qualified name for definition/references
language No Language identifier if ambiguous

Outputs

Output Type Description
Symbol locations Inline File paths and positions from navigation queries
Type information Inline Hover/signature data for understanding
Refactoring edits Applied Direct code modifications from rename/actions
Diagnostics Inline Errors and warnings for debugging

Tool Priority Matrix

Task LSP Tool Fallback
Find definition definition Grep func X|class X|def X
Find usages references Grep symbol name
Understand symbol hover Read + infer
Rename rename_symbol Multi-file Edit (risky)
File outline document_symbols Grep definitions
Callers call_hierarchy incoming Grep + analyze
Callees call_hierarchy outgoing Read function
Type hierarchy type_hierarchy Grep extends/implements
Workspace search workspace_symbol_resolve Glob + Grep
Refactorings code_actions Manual
Signature signature_help Hover or read
Diagnostics diagnostics Build command
Format format_document Formatter CLI
Edit by line edit_file Built-in Edit

Parameters

Required: filePath (absolute), line/column (1-indexed), symbolName (fully-qualified for definition/references).

Decision Rules

Use LSP when:

  • Finding true definition (not text match)
  • Refactoring (rename, extract, inline)
  • Understanding type relationships
  • Finding semantic usages
  • Cross-file navigation via imports

Use Grep/Glob when:

  • Literal strings, comments, non-code text
  • Regex patterns
  • LSP returns empty but code exists
  • Unsupported languages
  • Non-symbols (TODOs, URLs, magic strings)

Workflows

Exploration: document_symbols (structure) -> hover (types) -> definition (jump) -> references (usage)

Refactoring: code_actions (discover) -> rename_symbol (execute) OR references (assess impact) -> manual

Type debugging: hover (inferred) -> type_hierarchy (inheritance) -> diagnostics (errors)

Call analysis: call_hierarchy incoming = "who calls?" | outgoing = "what calls?"

Anti-Patterns

- Using Grep for symbol rename (misses scoped references, hits false positives) - Skipping LSP for "simple" refactors (simple becomes complex with inheritance) - Trusting empty LSP results without checking file saved state - Manual multi-file edits when `rename_symbol` available - Ignoring `diagnostics` output when debugging type errors

Fallback Protocol

  1. LSP error/empty -> Check file saved (LSP reads disk)
  2. Try table fallback
  3. Persistent failure -> Feature unsupported by server

Self-Check

Before completing:

  • Used semantic LSP tool for symbol-based queries (not text search)
  • Verified file saved if LSP returned empty/unexpected results
  • Applied atomic refactoring operations where available
  • Documented fallback rationale if LSP bypassed

If ANY unchecked: STOP and reconsider approach.