jaggerxtrm/using-serena-lsp

Using Serena LSP Workflow

Core Principle: Use semantic, symbol-level access to understand and edit code without reading entire files. Combine with LSP plugins for real-time analysis.

Tools Reference

Full Tool Documentation: See REFERENCE.md

| Tool | Purpose | |------|---------| | get_symbols_overview | Start here. See high-level structure of a file. | | find_symbol | Read specific functions/classes (set include_body=true). | | find_referencing_symbols | Find usages before editing. | | replace_symbol_body | Surgically replace a function/class. | | insert_after_symbol | Add new code after an existing symbol. | | search_for_pattern | Regex search when symbol names are unknown. |

Standard Workflows

🚨 MANDATORY FIRST STEP FOR ALL WORKFLOWS:

Before using ANY Serena semantic tools (get_symbols_overview, find_symbol, replace_symbol_body, etc.), you MUST activate the project:

mcp__plugin_serena_serena__activate_project({ project: "/path/to/current/working/directory" })

Why this is critical: Without project activation, Serena cannot locate code symbols and will fail or loop indefinitely. This step establishes the working context for all symbolic operations.

---

1. Explore Code (The "Overview First" Pattern)

Avoid reading full files >300 LOC.

1. Activate Project: mcp__plugin_serena_serena__activate_project()
2. Understand Structure: get_symbols_overview(depth=1)
3. Drill Down: find_symbol(name_path="...", include_body=true)
4. Reflect: think_about_collected_information()

2. Surgical Editing

1. Activate Project: mcp__plugin_serena_serena__activate_project() (if not already done)
2. Locate: find_symbol(include_body=true) to get current code.
3. Check Impact: find_referencing_symbols() to find usages.
4. Edit: replace_symbol_body(...) to update.
5. Verify: Run tests or syntax checks (e.g., python -m py_compile).

3. Adding Features

1. Activate Project: mcp__plugin_serena_serena__activate_project() (if not already done)
2. Context: read_memory() or get_symbols_overview() to understand patterns.
3. Locate Anchor: find_symbol() to find where to insert.
4. Insert: insert_after_symbol(...) to add new class/function.

File Size Guidelines

| Lines of Code | Recommended Approach | |---------------|----------------------| | < 100 LOC | Read is acceptable. | | 100-300 LOC | get_symbols_overview → find_symbol. | | > 300 LOC | Semantic only. Do not read full file. |

Quick Tips

• LSP Integration: Read() on a Python file automatically triggers Pyright analysis. Use the feedback to fix type errors surgically.
• Symbol Names: Use substring_matching=true if you aren't sure of the exact name.
• Safety: Always find references before renaming or changing signatures.

⚠️ Critical Constraints

1. NEVER skip project activation - It must be the first Serena operation in any workflow
2. Use the current working directory - Pass the actual project path, not a placeholder
3. Activate once per session - After activation, all subsequent Serena tools will work correctly
4. Check activation status - If Serena tools fail with "symbol not found" errors, you likely forgot to activate