SuperClaude/Framework-Lite/MCP/MCP_Serena.md

Serena MCP Server

Purpose

Powerful coding agent toolkit providing semantic retrieval, intelligent editing capabilities, project-aware context management, and comprehensive memory operations for SuperClaude integration

Activation Patterns

Automatic Activation:

• Complex semantic code analysis requests
• Project-wide symbol navigation and referencing
• Advanced editing operations requiring context awareness
• Multi-file refactoring with semantic understanding
• Code exploration and discovery workflows

Manual Activation:

• Flag: --serena, --semantic

Smart Detection:

• Symbol lookup and reference analysis keywords
• Complex code exploration requests
• Project-wide navigation and analysis
• Semantic search and context-aware editing
• Memory-driven development workflows

Flags

--serena / --semantic

• Enable Serena for semantic code analysis and intelligent editing
• Auto-activates: Complex symbol analysis, project exploration, semantic search
• Detection: find/symbol/reference keywords, project navigation, semantic analysis
• Workflow: Project activation → Semantic analysis → Intelligent editing → Context preservation

--no-serena

• Disable Serena server
• Fallback: Standard file operations and basic search
• Performance: 10-30% faster when semantic analysis not needed

Workflow Process

1. Project Activation: Initialize project context and load semantic understanding
2. Symbol Analysis: Deep symbol discovery and reference mapping across codebase
3. Context Gathering with Selective Compression: Collect relevant code context with content classification
   • SuperClaude Framework (Complete exclusion): All framework directories and components
   • Session Data (Apply compression): Session metadata, checkpoints, cache content only
   • User Content: Preserve full fidelity for project code, user-specific content, configurations
4. Server Coordination: Sync with Morphllm for hybrid editing, Sequential for analysis
5. Semantic Search: Intelligent pattern matching and code discovery
6. Memory Management with Selective Compression: Store and retrieve development context with optimized storage
   • SuperClaude Framework Content: Complete exclusion from compression (0% compression)
   • Session Data: Compressed storage for session metadata and operational data only
   • Project Memories: Full preservation for user project insights and context
7. Intelligent Editing: Context-aware code modifications with semantic understanding
8. Reference Tracking: Maintain symbol relationships and dependency awareness
9. Language Server Integration: Real-time language analysis and validation
10. Dashboard Monitoring: Web-based interface for agent status and metrics

Integration Points

Commands: analyze, implement, refactor, explore, find, edit, improve, design, load, save

Thinking Modes:

• Works with all thinking flags for semantic analysis
• --think: Symbol-level context analysis
• --think-hard: Project-wide semantic understanding
• --ultrathink: Complex architectural semantic analysis

Other MCP Servers:

• Morphllm: Hybrid intelligence for advanced editing operations
• Sequential: Complex semantic analysis coordination
• Context7: Framework-specific semantic patterns
• Magic: UI component semantic understanding
• Playwright: Testing semantic validation

Core Capabilities

Semantic Retrieval

• Symbol Discovery: Deep symbol search across entire codebase
• Reference Analysis: Find all references and usages of symbols
• Context-Aware Search: Semantic pattern matching beyond simple text search
• Project Navigation: Intelligent code exploration and discovery

Intelligent Editing

• Context-Aware Modifications: Edits that understand surrounding code semantics
• Symbol-Based Refactoring: Rename and restructure with full dependency tracking
• Semantic Code Generation: Generate code that fits naturally into existing patterns
• Multi-File Coordination: Maintain consistency across related files

Memory Management

• Development Context: Store and retrieve project insights and decisions
• Pattern Recognition: Learn and apply project-specific coding patterns
• Context Preservation: Maintain semantic understanding across sessions
• Knowledge Base: Build cumulative understanding of codebase architecture

Language Server Integration

• Real-Time Analysis: Live language server integration for immediate feedback
• Symbol Information: Rich symbol metadata and type information
• Error Detection: Semantic error identification and correction suggestions
• Code Completion: Context-aware code completion and suggestions

Project Management

• Multi-Project Support: Handle multiple codebases with context switching
• Configuration Management: Project-specific settings and preferences
• Mode Switching: Adaptive behavior based on development context
• Dashboard Interface: Web-based monitoring and control interface

Use Cases

• Code Exploration: Navigate and understand large, complex codebases
• Semantic Refactoring: Rename variables, functions, classes with full impact analysis
• Pattern Discovery: Find similar code patterns and implementation examples
• Context-Aware Development: Write code that naturally fits existing architecture
• Cross-Reference Analysis: Understand how components interact and depend on each other
• Intelligent Code Search: Find code based on semantic meaning, not just text matching
• Project Onboarding: Quickly understand and navigate new codebases
• Memory Replacement: Complete replacement of ClaudeDocs file-based system
• Session Management: Save/load project context and session state
• Task Reflection: Intelligent task tracking and validation

Error Recovery & Resilience

Primary Recovery Strategies

• Connection lost → Graceful degradation with cached context → Automatic reconnection attempts
• Project activation failed → Manual setup with guided configuration → Alternative analysis pathways
• Symbol lookup timeout → Use cached semantic data → Fallback to intelligent text search
• Language server error → Automatic restart with state preservation → Manual validation backup
• Memory corruption → Intelligent memory reconstruction → Selective context recovery

Advanced Recovery Orchestration

• Context Preservation: Critical project context automatically saved for disaster recovery
• Multi-Language Fallback: When LSP fails, fallback to language-specific text analysis
• Semantic Cache Management: Intelligent cache invalidation and reconstruction strategies
• Cross-Session Recovery: Session state recovery from multiple checkpoint sources
• Hybrid Intelligence Failover: Seamless coordination with Morphllm when semantic analysis unavailable

Caching Strategy

• Cache Type: Semantic analysis results, symbol maps, and project context
• Cache Duration: Project-based with intelligent invalidation
• Cache Key: Project path + file modification timestamps + symbol signature

Quality Gates Integration

Serena contributes to the following validation steps:

• Step 2 - Type Analysis: Deep semantic type checking and compatibility validation
• Step 3 - Code Quality: Semantic code quality assessment and pattern compliance
• Step 4 - Security Assessment: Semantic security pattern analysis
• Step 6 - Performance Analysis: Semantic performance pattern identification

Hybrid Intelligence with Morphllm

Complementary Capabilities:

• Serena: Provides semantic understanding and project context
• Morphllm: Delivers precise editing execution and natural language processing
• Combined: Creates powerful hybrid editing engine with both intelligence and precision

Coordination Patterns:

• Serena analyzes semantic context → Morphllm executes precise edits
• Morphllm identifies edit requirements → Serena provides semantic validation
• Joint validation ensures both syntax correctness and semantic consistency

Strategic Orchestration

When to Use Serena

• Large Codebase Analysis: Projects >50 files requiring semantic understanding
• Symbol-Level Refactoring: Rename, extract, move operations with dependency tracking
• Project Context Management: Session persistence and cross-session learning
• Multi-Language Projects: Complex polyglot codebases requiring LSP integration
• Architectural Analysis: System-wide understanding and pattern recognition

Memory-Driven Development Strategy

Session Lifecycle Integration:

• Project activation → Context loading → Work session → Context persistence
• Automatic checkpoints on high-risk operations and task completion
• Cross-session knowledge accumulation and pattern learning

Memory Organization Strategy:

• Replace file-based ClaudeDocs with intelligent memory system
• Hierarchical memory structure: session → checkpoints → summaries → insights
• Semantic indexing for efficient context retrieval and pattern matching

Advanced Semantic Intelligence

• Project-Wide Understanding: Complete codebase context maintained across sessions
• Dependency Graph Analysis: Real-time tracking of symbol relationships and impacts
• Pattern Evolution Tracking: Code patterns learned and adapted over time
• Cross-Language Integration: Unified understanding across multiple programming languages
• Architectural Change Impact: System-wide implications analyzed for all modifications

Project Management

Essential tools for SuperClaude integration:

• activate_project: Initialize project context and semantic understanding
• list_memories / read_memory / write_memory: Memory-based development context
• onboarding / check_onboarding_performed: Project setup and validation

SuperClaude Integration

Session Lifecycle Commands:

• /sc:load → activate_project + list_memories + context loading
• /sc:save → write_memory + session persistence + checkpoint creation

Error Recovery

• Connection lost → Graceful degradation with cached context
• Project activation failed → Manual setup with guided configuration
• Symbol lookup timeout → Use cached semantic data → Fallback to intelligent text search