chore: improve Serena MCP configuration and Claude Code awareness

[vredchenko]

Summary

Investigation revealed several improvements needed for Serena MCP server configuration and ensuring Claude Code effectively uses semantic code navigation capabilities.

Current State

Component	Status
CLAUDE.md guidance	Brief section (lines 235-248) explaining when to use Serena vs Grep/Glob
PreToolUse hook	prefer-serena.py prompts when Grep/Glob targets code files
MCP config	Using --context ide-assistant (non-existent context)
Serena project.yml	Exists with languages, encoding, gitignore settings
Serena memories	3 exist: project_overview, smartem_dependency_analysis, suggested_commands

Issues Identified

1. Wrong Context

Currently using --context ide-assistant in .mcp.json but this context doesn't exist. Should use --context claude-code which specifically disables tools that duplicate Claude Code's built-ins (read_file, create_text_file, execute_shell_command).

Fix:

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/oraios/serena",
        "serena", "start-mcp-server",
        "--context", "claude-code",
        "--project", "${PWD}"
      ]
    }
  }
}

2. Token Efficiency

Not using ENABLE_TOOL_SEARCH=true environment variable which loads tool descriptions on-demand rather than all at startup.

Fix:

"env": {
  "ENABLE_TOOL_SEARCH": "true"
}

3. Hook is Reactive Only

The prefer-serena.py hook only triggers after attempting to use Grep/Glob on code files. It doesn't help Claude proactively recognise Serena opportunities.

Consider:

• Expanding CLAUDE.md guidance with clearer decision tree
• Adding examples of Serena vs built-in tool selection
• Session startup prompt to read relevant Serena memories

4. Modes Not Configured

Serena supports modes like planning, editing, interactive, one-shot. Currently no mode configuration is used.

Consider:

• Default modes for different workflow types
• Dynamic mode switching via switch_modes tool

5. Memories Underutilised

Serena memories exist (project_overview, smartem_dependency_analysis, suggested_commands) but nothing prompts Claude to read them at session start.

Consider:

• Documenting memory contents in CLAUDE.md
• Adding guidance on when to read specific memories

Tasks

• Update .mcp.json to use --context claude-code
• Add ENABLE_TOOL_SEARCH=true to env config
• Expand CLAUDE.md Serena guidance section
• Review and update Serena memories
• Consider mode configuration for workflows
• Update smartem-workspace CLI to use correct context

References

• Serena docs: https://oraios.github.io/serena/
• Contexts: https://oraios.github.io/serena/02-usage/050_configuration.html
• Claude Code setup: https://oraios.github.io/serena/02-usage/030_clients.html