Call & Type Hierarchies

Relevant source files

The following files were used as context for generating this wiki page:

• src/tools/call-hierarchy.ts
• src/tools/type-hierarchy.ts
• src/schemas/tool-schemas.ts
• src/types.ts
• src/tools/smart-search.ts
• src/services/lsp-client.ts

Introduction

The Call and Type Hierarchy systems in the lsp-mcp-server provide semantic tools for navigating complex code relationships. These tools enable developers to trace function execution flows (Call Hierarchy) and explore object-oriented inheritance structures (Type Hierarchy). Unlike text-based searches, these hierarchies utilize the Language Server Protocol (LSP) to provide accurate, context-aware relationships between symbols, such as identifying all callers of a function or finding all subtypes of an interface.

These systems are exposed via specific Model Context Protocol (MCP) tools: lsp_call_hierarchy and lsp_type_hierarchy. They facilitate advanced code analysis by allowing "incoming" and "outgoing" call tracing, as well as "supertypes" and "subtypes" exploration.

Sources: src/index.ts:394-434, SKILL.md:200-205, CLAUDE.md:12-15

Call Hierarchy

The Call Hierarchy system allows for the tracing of function and method calls within a codebase. It is essential for understanding the impact of changes to a function and for mapping execution paths.

Request Flow and Direction

Users can request three directions of call data:

• Incoming: Identifies all symbols that call the target function.
• Outgoing: Identifies all symbols called by the target function.
• Both: Retrieves both incoming and outgoing relationships simultaneously.

Sources: src/schemas/tool-schemas.ts:241-248, src/tools/call-hierarchy.ts:114-131

Execution Logic

The process for retrieving a call hierarchy involves two distinct LSP phases:

1. Preparation: The prepareCallHierarchy request validates that the symbol at the given position is "callable" (e.g., a function or method).
2. Retrieval: Once a valid CallHierarchyItem is returned, the client performs secondary requests for incomingCalls or outgoingCalls based on the user's requested direction.

Sources: src/services/lsp-client.ts:400-425, src/tools/call-hierarchy.ts:98-111

The following diagram illustrates the sequence of operations required to resolve a call hierarchy:

Diagram shows the multi-step LSP request flow to resolve a specific callable symbol and its relations.
Sources: src/tools/call-hierarchy.ts:89-136, src/services/lsp-client.ts:400-425

Type Hierarchy

The Type Hierarchy system is used to explore class and interface inheritance. It allows developers to navigate up to parents (supertypes) or down to children (subtypes).

Request Flow and Direction

The system supports three exploration modes:

• Supertypes: Navigates up the inheritance chain (parents/implemented interfaces).
• Subtypes: Navigates down the inheritance chain (classes that extend or implement the target).
• Both: Retrieves the full hierarchy surrounding the target.

Sources: src/schemas/tool-schemas.ts:254-261, src/tools/type-hierarchy.ts:104-121

Core Components

Field	Type	Description
item	TypeHierarchyItemResult	The specific class or interface at the provided cursor position.
supertypes	TypeHierarchyItemResult[]	Optional list of parents/interfaces found for the item.
subtypes	TypeHierarchyItemResult[]	Optional list of children/implementations found for the item.

Sources: src/types.ts:792-796, src/tools/type-hierarchy.ts:45-72

Data Structures & Result Mapping

Both hierarchy systems share common data structures for representing symbols and their locations.

Result Format

LSP raw data is converted into a human-readable and 1-indexed format suitable for the MCP interface. This includes:

• Coordinates: Conversion from 0-indexed (LSP) to 1-indexed (MCP) for lines and columns.
• Symbol Metadata: Includes the symbol name, kind (Class, Function, etc.), and optional detail or tags (e.g., "deprecated").
• Range Information: Returns both the range (full body of the symbol) and the selection_range (the identifier itself).

Sources: src/tools/call-hierarchy.ts:43-70, src/tools/type-hierarchy.ts:45-72

Symbol Relationships

Diagram shows the relationship between a central symbol and its incoming call sources.
Sources: src/types.ts:758-787

Tool Integration: Smart Search

The lsp_smart_search tool provides a composite interface that includes call hierarchy data. When invoked with the appropriate include flags, it internally calls the hierarchy logic to return comprehensive context for a single symbol.

• Included Calls: Can trigger incoming_calls and outgoing_calls within a single request.
• Graceful Degradation: If a language server does not support hierarchies, the Smart Search tool catches the error and continues providing other symbol data (like definitions or hover info).

Sources: src/tools/smart-search.ts:145-212, SKILL.md:126-133

Error Handling

Hierarchies are sensitive to cursor position. If a user attempts to call these tools on a position that the language server does not recognize as a valid entry point (e.g., a variable, a keyword, or whitespace), a CAPABILITY_NOT_SUPPORTED error is thrown.

• Error Code: LSPErrorCode.CAPABILITY_NOT_SUPPORTED
• Suggestion: The system suggests using lsp_smart_search as an alternative, as it handles missing capabilities silently.

Sources: src/tools/call-hierarchy.ts:101-107, src/tools/type-hierarchy.ts:91-97, src/types.ts:517

Summary

Call and Type Hierarchies provide deep structural insights into codebases. By leveraging the multi-step LSP request process, the lsp-mcp-server enables callers to visualize execution paths and inheritance trees accurately. These tools are integrated into both specialized MCP commands and the broad lsp_smart_search utility, ensuring developers have access to semantic relationships regardless of their specific workflow.

Sources: CLAUDE.md:12-15, src/index.ts:1335-1355