serena-mcp-agent

Serena MCP Agent Integration

Serena transforms LLMs into fully-featured coding agents with IDE-like intelligence by leveraging the Language Server Protocol (LSP) for structural code understanding.

Core Value Proposition

Capability	Benefit
Semantic code retrieval	Navigate by symbols, not text - 30x+ token reduction
Surgical editing	Modify function bodies while preserving structure
Project memory	Persist knowledge across sessions in .serena/memories/
Multi-client support	Claude Desktop, Claude Code, Codex, ChatGPT, custom agents

Project Lifecycle

1. Activation

Activate project before any operations:

"Activate the project /path/to/my_project"

First-time activation creates .serena/project.yml with default settings.

2. Onboarding

Run automatically on first session. Creates memories in .serena/memories/:

• tech_stack_and_dependencies.md
• code_style_and_conventions.md
• task_completion_guidelines.md

If not auto-triggered:

"Start the Serena onboarding process for this project."

Critical: Start NEW conversation after onboarding (context fills up during analysis).

3. Indexing (Large Projects)

Pre-index to prevent tool timeouts:

serena project index

Run once; auto-updates during use.

Tool Usage Strategy

Priority Order (Prefer Higher):

1. Symbolic tools - Most efficient, LSP-powered

   • get_symbols_overview → File structure without reading content
   • find_symbol → Locate definitions precisely
   • find_referencing_symbols → Impact analysis before changes
   • replace_symbol_body → Rewrite functions safely

2. Line-based tools - When symbols don't apply

   • replace_lines, insert_at_line, delete_lines

3. Full file operations - Last resort

   • read_file, create_text_file

See: references/tools-reference.md for complete tool taxonomy.

Memory Management

Persist knowledge in .serena/memories/:

Tool	Purpose
write_memory	Save contracts, schemas, progress
read_memory	Load prior session context
list_memories	Discover available memories
prepare_for_new_conversation	Generate continuation summary
summarize_changes	Document session work

Pattern: End sessions with summarize_changes → write_memory.

Thinking Tools

Force self-reflection during complex operations:

Tool	When to Use
think_about_collected_information	Before implementing
think_about_task_adherence	During long operations
think_about_whether_you_are_done	Before declaring complete

Client Configuration

Claude Desktop: Edit claude_desktop_config.json

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oraios/serena",
               "serena", "start-mcp-server", "--context", "desktop-app"]
    }
  }
}

Claude Code: From project directory:

claude mcp add serena -- uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server --context ide-assistant --project "$(pwd)"

See: references/client-setup.md for Codex, ChatGPT, Docker, etc.

Contexts and Modes

Contexts (set at startup, immutable):

• desktop-app - Claude Desktop (full toolset)
• claude-code - Claude Code (no duplicates)
• ide-assistant - IDE extensions (minimal tools)
• codex - OpenAI Codex
• chatgpt - ChatGPT via MCPO

Modes (combinable, switchable):

• editing + interactive - Standard development (default)
• planning - Analysis before implementation
• one-shot - Single-response tasks
• no-onboarding - Skip if memories exist

Switch dynamically: "Switch to planning mode"

See: references/contexts-and-modes.md for full reference.

Security Configuration

In .serena/project.yml:

read_only: true  # Disable all editing (analysis only)
excluded_tools:
  - execute_shell_command  # Always disable for untrusted contexts

Non-negotiables:

1. Use version control (Git) for all projects
2. Disable execute_shell_command unless explicitly needed
3. Set read_only: true for code review/analysis tasks
4. Never expose MCPO API keys

Debugging Framework

For complex automation workflows (n8n, Zapier, etc.):

1. Behavior Contract - Document expected behavior before changes
2. Snapshot Before - Capture current state
3. Parity Grid - Map contract → current → fix required
4. Dry-Run - Validate changes before applying
5. Apply + Validate - Execute with proof
6. Memory Harden - Persist final state

See: references/debugging-framework.md for canonical prompts and workflow.

Session Protocol

Start:

1. Verify project activation: get_current_config
2. Check onboarding: check_onboarding_performed
3. Load relevant memories: list_memories → read_memory
4. Run build/type-check command (establish baseline)

During:

• Read files BEFORE editing (prevent duplicates)
• Use symbolic tools preferentially
• Run validation after each change
• Use thinking tools for complex tasks

End:

1. Final validation (build/lint/test)
2. summarize_changes → write_memory
3. For continuation: prepare_for_new_conversation

When to Use Serena

Optimal:

• Large/complex/legacy codebases
• Refactoring across multiple files
• Analyzing dependencies and architecture
• Token-sensitive operations

Not Needed:

• New empty projects (nothing to analyze)
• Single-file scripts
• When entire context fits easily

Dashboard

Monitor operations at: http://localhost:24282/dashboard/index.html

View: tool calls, logs, configuration, active languages.