scottrbk/context-hub-plugin/using-serena-symbols

Using Serena Symbol Analysis

Serena provides LSP-powered code intelligence for accurate symbol extraction, relationship discovery, and cross-file analysis.

When to Use Serena vs Text Search

Key advantage: Serena understands code structure. find_symbol("UserService") finds the actual class definition, not every mention of "UserService" in comments or strings.

Core Tools

1. get_symbols_overview

Get high-level view of symbols in a file. Start here when exploring a new file.

mcp__plugin_serena_serena__get_symbols_overview({
  "relative_path": "src/services/auth.py",
  "depth": 1  # 0=top-level only, 1=include methods
})

Returns: Classes, functions, variables with their kind and location.

2. find_symbol

Find symbols by name pattern. Supports flexible matching.

Name path patterns:

• UserService - Find any symbol named "UserService"
• UserService/authenticate - Find method in class
• /UserService - Exact match (absolute path)
• Service with substring_matching: true - Matches "UserService", "AuthService", etc.

mcp__plugin_serena_serena__find_symbol({
  "name_path_pattern": "UserService/authenticate",
  "include_body": true,  # Get source code
  "depth": 0  # 0=just this symbol, 1=include children
})

Key parameters:

• include_body (bool): Include source code (use judiciously for context)
• depth (int): How many levels of children to retrieve
• relative_path (str): Restrict search to file/directory
• substring_matching (bool): Partial name matching

3. find_referencing_symbols

Find all references to a symbol. Essential for understanding impact.

mcp__plugin_serena_serena__find_referencing_symbols({
  "name_path": "UserService/authenticate",
  "relative_path": "src/services/auth.py"
})

Returns: Code snippets showing each reference with context.

4. search_for_pattern

Regex search when you need flexibility (like grep, but smarter file filtering).

mcp__plugin_serena_serena__search_for_pattern({
  "substring_pattern": "def.*async.*:",
  "restrict_search_to_code_files": true,
  "context_lines_before": 2,
  "context_lines_after": 2
})

Standard Workflow

Exploring a New Codebase

1. Directory structure - Understand layout

``python mcp__plugin_serena_serena__list_dir({ "relative_path": ".", "recursive": false }) ``

1. Entry points - Find main files

``python mcp__plugin_serena_serena__get_symbols_overview({ "relative_path": "src/main.py", "depth": 1 }) ``

1. Trace key classes - Understand structure

``python mcp__plugin_serena_serena__find_symbol({ "name_path_pattern": "App", "include_body": false, "depth": 1 }) ``

Understanding a Specific Class

1. Find the class with children

``python mcp__plugin_serena_serena__find_symbol({ "name_path_pattern": "AuthService", "depth": 1, "include_body": false }) ``

1. Read specific methods you need

``python mcp__plugin_serena_serena__find_symbol({ "name_path_pattern": "AuthService/validate_token", "include_body": true }) ``

1. Find who calls it

``python mcp__plugin_serena_serena__find_referencing_symbols({ "name_path": "AuthService/validate_token", "relative_path": "src/services/auth.py" }) ``

Tracing Dependencies

1. Find all imports of a module

``python mcp__plugin_serena_serena__search_for_pattern({ "substring_pattern": "from.*auth.*import|import.*auth", "restrict_search_to_code_files": true }) ``

1. Find references to trace usage

``python mcp__plugin_serena_serena__find_referencing_symbols({ "name_path": "AuthService", "relative_path": "src/services/auth.py" }) ``

Symbol Kinds Reference

LSP symbol kinds (for include_kinds/exclude_kinds filtering):

Example - find only classes:

mcp__plugin_serena_serena__find_symbol({
  "name_path_pattern": "Service",
  "substring_matching": true,
  "include_kinds": [5]  # Class only
})

Efficiency Tips

1. Use `relative_path` to scope searches - much faster than searching entire codebase
2. Start with `include_body: false` - get structure first, read code only when needed
3. Use `depth: 0` initially - expand to children only when exploring specific classes
4. Combine with Forgetful - create memories for important architectural findings

Language Support

Serena works with any language that has an LSP server configured:

• Python (pyright/pylsp)
• TypeScript/JavaScript (tsserver)
• Rust (rust-analyzer)
• Go (gopls)
• Java (jdtls)
• And more...

The specific features available depend on the language server's capabilities.