lsp-understand

---

name: lsp-understand description: Deep-dive exploration of unfamiliar code — given a symbol or file, builds a complete Code Map showing type info, implementations, call hierarchy (2-level depth limit), all references, and source. Broader than lsp-explore: accepts files, synthesizes multi-symbol relationships, and produces a navigable dependency map. argument-hint: "[symbol-name | file-path]" user-invocable: true allowed-tools: mcp__lsp__inspect_symbol mcp__lsp__go_to_implementation mcp__lsp__find_callers mcp__lsp__find_references mcp__lsp__get_symbol_source mcp__lsp__list_symbols mcp__lsp__open_document mcp__lsp__go_to_symbol mcp__lsp__get_server_capabilities license: MIT compatibility: Requires the agent-lsp MCP server (github.com/blackwell-systems/agent-lsp) metadata: required-capabilities: hoverProvider optional-capabilities: implementationProvider callHierarchyProvider referencesProvider documentSymbolProvider workspaceSymbolProvider

Requires the agent-lsp MCP server.

lsp-understand

Deep-dive exploration of unfamiliar code — given a symbol or file, synthesizes hover info, implementations, call hierarchy (bounded to 2 levels), all references, and source into a structured Code Map.

Read-only — does not modify any files.

---

Differentiation from lsp-explore

/lsp-explore is a single-symbol pass: given one symbol name, it runs hover + implementations + call hierarchy + references and produces a per-symbol report. Use lsp-explore for quick "what is this one thing" questions.

/lsp-understand is broader in three ways:

1. Accepts a file path as input — explores all exported symbols in that file as a group (Mode B), rather than requiring a single symbol name.
2. Synthesizes cross-symbol relationships — produces a dependency map showing how entry points call each other, share callers, or implement the same interface, rather than isolated per-symbol reports.
3. Enforces a 2-level call hierarchy depth limit — prevents infinite recursion in deeply connected code.

Use lsp-understand for "how does this module work as a whole."

---

Input — Two Modes

Mode A (symbol): User provides a symbol name in dot notation (e.g., "codec.Encode", "Handler.ServeHTTP").

Mode B (file): User provides an absolute file path. All exported symbols in the file become the entry points.

---

Prerequisites

Call mcp__lsp__get_server_capabilities before Step 2 to determine which capabilities are available. Skip steps that require missing capabilities:

• go_to_implementation: skip Step 2b if implementationProvider: false
• find_callers: skip Steps 2c and 2d if callHierarchyProvider: false; note in the Code Map output that call hierarchy was unavailable

---

Step 1 — Entry Point Resolution

Mode A: Single Symbol

Call mcp__lsp__go_to_symbol to locate the symbol definition:

mcp__lsp__go_to_symbol({
  "symbol_path": "<dot-notation name>",   // e.g. "codec.Encode"
  "workspace_root": "<root>"              // optional
})
→ returns: file_path, line, column (1-indexed)

Record file_path, line, and column. If go_to_symbol returns nothing, report:

Symbol not found: <name> Check the dot-notation path (e.g. "Package.Symbol") and ensure the workspace root covers the file.

Stop immediately — do not proceed to Step 2.

The single symbol becomes the sole entry point.

Mode B: File Path

Call mcp__lsp__open_document then mcp__lsp__list_symbols:

mcp__lsp__open_document({ "file_path": "<absolute path>" })

mcp__lsp__list_symbols({ "file_path": "<absolute path>" })
→ returns: list of symbols with kind, line, column

Filter to exported symbols:

• Go: uppercase first letter
• TypeScript/JavaScript: export keyword
• Rust: pub visibility

Cap at 10 exported symbols maximum. If more than 10 are found, prioritize top-level functions and types; skip constants and variables.

Each filtered symbol becomes an entry point with its file_path, line, and column.

---

Step 2 — Per-Symbol Analysis

For each entry point, run the following sub-steps. Where possible, parallelize calls within each step.

2a — Type Info and Docs

Call mcp__lsp__inspect_symbol using position_pattern with the @@ marker (see references/patterns.md):

mcp__lsp__inspect_symbol({
  "file_path": "<file>",
  "position_pattern": "<symbol@@name>",
  "line_scope_start": <line - 5>,
  "line_scope_end": <line + 5>
})
→ returns: hover text with type signature and doc comment

Store result as hover_text. If the call fails or returns nothing, set hover_text to an empty string. Do not stop.

2b — Implementations (capability-gated)

If implementationProvider is available in server capabilities:

mcp__lsp__go_to_implementation({
  "file_path": "<file>",
  "line": <line>,
  "column": <column>
})
→ returns: list of concrete implementation locations

Skip if capability is absent. Record "not supported by this server" rather than stopping.

2c — Incoming Call Hierarchy (bounded to 2 levels)

If callHierarchyProvider is available:

Level 1 — Direct callers:

mcp__lsp__find_callers({
  "file_path": "<file>",
  "line": <line>,
  "column": <column>,
  "direction": "incoming"
})
→ returns: list of direct caller functions with file and line

Level 2 — Callers of callers:

For each Level 1 caller, call mcp__lsp__find_callers once more:

mcp__lsp__find_callers({
  "file_path": "<caller file>",
  "line": <caller line>,
  "column": <caller column>,
  "direction": "incoming"
})
→ returns: Level 2 callers

STOP at Level 2 — do not recurse further under any circumstances.

If Level 2 callers > 10: summarize by count and file, do not list individually.

2d — Outgoing Calls (Level 1 only)

If callHierarchyProvider is available:

mcp__lsp__find_callers({
  "file_path": "<file>",
  "line": <line>,
  "column": <column>,
  "direction": "outgoing"
})
→ returns: list of functions this symbol calls

Level 1 only — no recursion.

2e — All References

mcp__lsp__find_references({
  "file_path": "<file>",
  "line": <line>,
  "column": <column>,
  "include_declaration": false
})
→ returns: every usage site across the workspace

Group by file and count distinct files.

2f — Source

mcp__lsp__get_symbol_source({
  "file_path": "<file>",
  "line": <line>,
  "column": <column>
})
→ returns: implementation body

---

Step 3 — Synthesize Relationships

After analyzing all entry points, identify cross-symbol relationships:

• Internal calls: Which entry points call each other? (from outgoing calls in Step 2d)
• Shared callers: Which entry points are called by the same Level 1 callers?
• Shared interface: Which entry points implement the same interface? (from Step 2b)

This synthesis step is what distinguishes /lsp-understand from running multiple /lsp-explore calls. The output is a dependency map, not isolated per-symbol reports.

---

Step 4 — Output: Code Map

Produce a structured Code Map with these sections:

## Code Map: <target>

### Summary
<2-3 sentence description of what this code does, synthesized from
hover docs and source reading>

### Symbols (<N> analyzed)

#### <SymbolName>
- **Type:** <type signature from hover>
- **Source:** <file:line>
- **Incoming callers (L1):** <list; count only if > 5>
- **Incoming callers (L2):** <summarized; e.g., "called by 3 HTTP handlers">
- **Outgoing calls:** <what this symbol calls>
- **Implements:** <interface name, if applicable>
- **References:** N sites across M files

### Dependency Relationships
<symbols that call each other, as a simple text diagram or list>
e.g.:
  HandlerA → Parse → Validate
  HandlerB → Parse

### Entry Points to This Code
<top-level callers that are NOT in this file — where does outside code
call in?>

### Depth-limit Note
Call hierarchy stopped at 2 levels. <N> additional callers exist beyond
Level 2 — use /lsp-explore on specific symbols to drill deeper.

---

Depth Control Rules

These limits are hard constraints — never exceed them:

• Incoming call hierarchy recursion stops at Level 2
• Outgoing calls: Level 1 only, no recursion
• If Level 2 callers > 10: summarize by count and file, do not list individually
• Do NOT follow call chains beyond these limits under any circumstances

---

Example

Goal: understand how the file pkg/codec/encoder.go works as a whole

Step 1 — Mode B (file path)
  open_document: pkg/codec/encoder.go
  list_symbols: pkg/codec/encoder.go
  → exported symbols: Encoder (type), Encode (func), Reset (func), NewEncoder (func)
  → 4 exported symbols (under 10 cap)

get_server_capabilities
  → go_to_implementation: supported
  → find_callers: supported

Step 2 — Per-symbol analysis (run in parallel across symbols)

  Symbol: NewEncoder (pkg/codec/encoder.go:12)
    inspect_symbol → "func NewEncoder(w io.Writer) *Encoder"
    go_to_implementation → 0 (concrete function)
    find_callers incoming L1 → 5 callers
    find_callers incoming L2 → 3 callers of those callers
    find_callers outgoing → calls: bufio.NewWriter
    find_references → 5 sites in 3 files
    get_symbol_source → implementation body

  Symbol: Encode (pkg/codec/encoder.go:28)
    inspect_symbol → "func (e *Encoder) Encode(v any) error"
    go_to_implementation → implements codec.Encoder interface
    find_callers incoming L1 → 8 callers (listed)
    find_callers incoming L2 → > 10: "12 additional callers across 5 files"
    find_callers outgoing → calls: NewEncoder, e.w.Flush
    find_references → 8 sites in 5 files
    get_symbol_source → implementation body

  (similar for Encoder type and Reset func...)

Step 3 — Synthesize relationships
  - Encode calls NewEncoder (internal dependency)
  - NewEncoder and Encode share callers in cmd/main.go
  - Encode implements codec.Encoder interface

## Code Map: pkg/codec/encoder.go

### Summary
This file implements a streaming JSON encoder backed by a buffered writer.
NewEncoder constructs an Encoder wrapping any io.Writer; Encode serializes
values and flushes. Reset allows reuse without allocation.

### Symbols (4 analyzed)

#### NewEncoder
- **Type:** func NewEncoder(w io.Writer) *Encoder
- **Source:** pkg/codec/encoder.go:12
- **Incoming callers (L1):** cmd.main, app.Start, loader.Load, test.Setup, bench.Run
- **Incoming callers (L2):** 3 callers across 2 files
- **Outgoing calls:** bufio.NewWriter
- **Implements:** n/a
- **References:** 5 sites across 3 files

#### Encode
- **Type:** func (e *Encoder) Encode(v any) error
- **Source:** pkg/codec/encoder.go:28
- **Incoming callers (L1):** 8 callers (cmd/main.go, internal/app.go, ...)
- **Incoming callers (L2):** 12 additional callers across 5 files (depth limit reached)
- **Outgoing calls:** NewEncoder, e.w.Flush
- **Implements:** codec.Encoder
- **References:** 8 sites across 5 files

...

### Dependency Relationships
  cmd.main → NewEncoder → bufio.NewWriter
  cmd.main → Encode → NewEncoder
  Encode → Reset

### Entry Points to This Code
- cmd.main (cmd/main.go:14)
- app.Start (internal/app.go:31)
- loader.Load (internal/loader.go:55)

### Depth-limit Note
Call hierarchy stopped at 2 levels. 12 additional callers exist beyond
Level 2 for Encode — use /lsp-explore on specific symbols to drill deeper.