| name | using-serena-lsp |
| description | Explores and edits code using semantic tools and LSP plugins. Use when reading code, understanding structure, finding symbols, or performing surgical edits to functions and classes. |
| allowed-tools | mcp__serena__*, Read, Edit, Bash |
| priority | high |
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.
- Activate Project:
mcp__plugin_serena_serena__activate_project()
- Understand Structure:
get_symbols_overview(depth=1)
- Drill Down:
find_symbol(name_path="...", include_body=true)
- Reflect:
think_about_collected_information()
2. Surgical Editing
- Activate Project:
mcp__plugin_serena_serena__activate_project() (if not already done)
- Locate:
find_symbol(include_body=true) to get current code.
- Check Impact:
find_referencing_symbols() to find usages.
- Edit:
replace_symbol_body(...) to update.
- Verify: Run tests or syntax checks (e.g.,
python -m py_compile).
3. Adding Features
- Activate Project:
mcp__plugin_serena_serena__activate_project() (if not already done)
- Context:
read_memory() or get_symbols_overview() to understand patterns.
- Locate Anchor:
find_symbol() to find where to insert.
- 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
- NEVER skip project activation - It must be the first Serena operation in any workflow
- Use the current working directory - Pass the actual project path, not a placeholder
- Activate once per session - After activation, all subsequent Serena tools will work correctly
- Check activation status - If Serena tools fail with "symbol not found" errors, you likely forgot to activate
