Serena Integration

The MCP server delegates two responsibilities to Serena instead of reimplementing them:

1. LSP-grade AST queries — find_symbol, find_referencing_symbols, get_symbols_overview, get_diagnostics_for_file.
2. Cross-session, per-project memory — write_memory, read_memory, list_memories, persisted under the project’s .serena/memories/ directory.

Every instruction tool response (code-review, feature-implement, issue-debug, evidence-research, etc.) ends with a 🧭 Serena enrichment footer that names the exact Serena tool + arguments the model should invoke to ground its analysis in real symbol data and prior project context.

Two modes, one seam

The internal client lives at src/serena/client.ts. Tool code paths are identical regardless of mode — the seam picks an implementation at startup based on environment.

Advisory mode (default)

No setup required. Tool responses include a 🧭 Serena enrichment available footer of the form:

---

## 🧭 Serena enrichment available

Call `mcp__serena__list_memories` to ground this analysis in Serena's LSP-backed symbol surface and prior project memories.

_Rationale:_ List existing Serena memories for this project to discover prior notes worth reading.

The host MCP client (e.g. Claude Code with Serena loaded as a sibling server) executes the suggested call. No Serena subprocess is spawned by this server. Use this mode when your host already runs Serena.

Child-spawn mode (opt-in)

Set MCP_SERENA_COMMAND (and friends) in the environment of the MCP server process:

MCP_SERENA_COMMAND="uvx"
MCP_SERENA_ARGS="--from git+https://github.com/oraios/serena serena start-mcp-server --project /absolute/path/to/your/project"
# Optional:
MCP_SERENA_CWD="/absolute/path/to/your/project"

The server spawns Serena once lazily on the first query and resolves all subsequent Serena calls directly over stdio. The footer now carries real data:

---

## 🧭 Serena context

Result from `list_memories`:

​```json
{
  "content": [{ "type": "text", "text": "['design-notes', 'past-bugs', ...]" }],
  ...
}
​```

Pin `--project`

Serena keeps a global project registry. Without an explicit --project <path> argument it will refuse memory operations on a fresh cwd. Always pass --project so Serena auto-registers the directory and activates it on startup.

End-to-end verification

A real uvx serena round-trip test ships in the repo, gated by MCP_SERENA_E2E=1 so CI without uvx stays green:

MCP_SERENA_E2E=1 npm run test:mcp:serena

It exercises two paths:

• Direct ChildSerenaClient — write_memory → list_memories → read_memory against a real uvx serena start-mcp-server subprocess.
• Full MCP-server round-trip — pre-seeds a memory, spawns this MCP server with MCP_SERENA_COMMAND set, calls code-review through the SDK client, and asserts the response footer reads 🧭 Serena context (data mode, not advisory) and contains the seeded memory name.

If both pass locally, the seam is wired end-to-end.

Environment variables

Variable	Default	Description
MCP_SERENA_COMMAND	unset	When set, the server spawns Serena as a child stdio MCP server. When unset (the default), the server emits structured advisories that the host model executes.
MCP_SERENA_ARGS	unset	Space-separated args passed to MCP_SERENA_COMMAND. Recommended value: --from git+https://github.com/oraios/serena serena start-mcp-server --project <path>.
MCP_SERENA_CWD	unset	Working directory for the spawned Serena child. Defaults to the parent process’s cwd.
MCP_LOCAL_MEMORY	unset (false)	Opt-in switch for the legacy per-tool-call TOON memory artifacts under .mcp-ai-agent-guidelines/memory/. Off by default — Serena memory is the recommended cross-session channel.

Why this matters

Before this integration the MCP server maintained a parallel memory subsystem under .mcp-ai-agent-guidelines/ (TOON files for memories, sessions, fingerprint snapshots) and a 6,500-line custom symbol scanner. Both shipped and accumulated state on disk even though their outputs were rarely read back to enrich tool responses. Replacing them with Serena means:

• Symbol context comes from a real language server, not a heuristic regex scanner.
• Memory persists in a per-project, agent-readable format the host model already knows how to call.
• The MCP server does not write to ~/.mcp-ai-agent-guidelines/ or ~/.cache/mcp-ai-agent-guidelines/ at all, and only writes the workspace-local orchestration.toml when explicitly invoked.