docs(plugins): serena example plugin doesn't return results — missing project activation

[shahe-dev]

The Serena example plugin at docs/plugins/examples/serena-plugin.mjs loads correctly into engram (engram plugin list shows it), but in real-world testing it doesn't contribute to the rich context packet.

Repro

1. Install latest: npm i -g engramx@3.0.2 (v3.0.2 confirmed)
2. Install uv / uvx (any recent version — tested with 0.9.2)
3. Copy the example: cp docs/plugins/examples/serena-plugin.mjs ~/.engram/plugins/serena.mjs
4. Verify load: engram plugin list → shows mcp:serena v0.1.0 ✓
5. Run a hook preview on any file: engram hook-preview <some-file>

Expected: Rich packet shows a SEMANTIC SYMBOLS (mcp:serena): section.
Actual: Only engram:git (or other built-ins) contribute. Serena does not appear.

Two issues with the example

1. find_symbol arg semantics

The example calls find_symbol with name_path: "{fileBasename}" (e.g., cli.py). Serena's find_symbol expects a symbol name path like MyClass.method, not a filename. Even when Serena is fully primed, this call returns nothing useful.

A more file-oriented tool from Serena's catalog is get_symbols_overview, which takes relative_path and returns top-level symbols defined in that file — much closer to what engram's per-Read flow wants.

2. Missing project activation

Serena's MCP server requires a project to be activated (via the activate_project tool) before its semantic tools return results. Inspection of Serena's tool catalog (uvx --from git+https://github.com/oraios/serena serena tools list) confirms activate_project and onboarding are required pre-steps for semantic queries.

The example plugin's mcpConfig.args are just ["--from", "git+...", "serena", "start-mcp-server"] — no project path injected, no activation call in the tools array. So even with the right tool name, Serena has no project context to query against.

3. Cold-start timeout (minor — already noted in the plugin's own docstring)

timeoutMs: 2500 is below realistic cold-start time for Serena on a fresh box (uvx fetch + LSP boot for a new language can be 15-30s). The plugin's own comment warns "keep ≥2s or you'll get zero results on the first file of a session" — but the value shipped is essentially the floor.

Suggested fixes

1. Update the example to call get_symbols_overview with relative_path: "{filePath}" instead of find_symbol — better match for the per-Read use case.
2. Add a project-activation step. Either:
   • Pass project root via CLI args: args: [..., "start-mcp-server", "--project", "{projectRoot}"] (if Serena supports this — would need to check)
   • OR: extend tools array to call activate_project first and get_symbols_overview second
   • OR: document that users must run serena project add for the project once before the plugin will return results
3. Bump the default timeoutMs to 15000–30000 to absorb cold-start, with a comment that subsequent calls are fast.

Happy to PR a fix once we agree on the activation strategy. The simplest path is probably (2c) — document the prerequisite — since automating activation through the engram plugin contract may run into MCP tool-ordering complications.

Environment

• Windows 11, Node v25.2.1, engramx 3.0.2 (npm-installed global)
• Serena fetched fresh via uvx 0.9.2
• Tested in a Python project (graph-core) — same result expected on TS projects.

Note: this is a docs/UX issue, not a runtime bug. The plugin loader correctly registers Serena and the resolver correctly times out / no-ops when Serena returns nothing — the safety net works exactly as designed. The issue is just that "follow the example, get nothing" is a confusing first experience for users discovering the new MCP plugin contract.