pi-serena-mcp

Serena MCP semantic code intelligence tools for Pi Coding Agent.

The extension exposes four read-only tools backed by Serena's LSP-powered MCP server:

• serena_find_symbol
• serena_get_symbols_overview
• serena_find_referencing_symbols
• serena_search_pattern

Compatibility

• Node.js 22.19.0 or newer
• Pi Coding Agent 0.81.1 was used for development validation
• Serena 0.1.4 was used for local runtime validation; other Serena versions may expose different MCP schemas

The extension checks for the four required Serena tools during connection and reports missing tools instead of starting with an incompatible server.

Install Serena

Serena's current recommended installation uses uv:

uv tool install -p 3.13 serena-agent
serena --help
serena init

The serena executable must be available through PATH, or configure an absolute path with SERENA_BIN:

export SERENA_BIN=/absolute/path/to/serena

The extension starts Serena as a local child process. It does not upload source code or provide telemetry. The child process inherits the Pi process environment, so avoid placing credentials in the environment when running untrusted local code.

Install the Pi package

pi install npm:pi-serena-mcp

Restart Pi after installation. To install a specific version:

pi install npm:pi-serena-mcp@0.1.0

If you previously used a standalone ~/.pi/agent/extensions/serena-mcp.ts, remove or rename that file before installing this package. Keeping both copies enabled registers the same four tool names twice.

Project detection and startup

The extension connects lazily, on the first Serena tool call. It does not start Serena during session_start.

Project root selection is:

1. SERENA_PROJECT_ROOT, when explicitly configured;
2. the nearest ancestor containing either .serena/project.yml or .git.

To use a project root that is not an ancestor of the current working directory:

export SERENA_PROJECT_ROOT=/absolute/path/to/project

If no project marker is found, Serena is not started and the tool returns a clear error. This prevents accidentally indexing $HOME, /tmp, or another broad non-project directory.

Output limits and cancellation

Every tool result is limited to 50 KB or 2,000 lines, whichever is reached first. When truncation occurs, the complete result is written to a private temporary file and its path is included in the result details. These temporary output directories are removed during session_shutdown.

Pi tool calls use sequential execution for these Serena tools. MCP request timeouts and Pi's AbortSignal are propagated to the Serena request. A single retry is attempted only when the transport is confirmed closed; Serena business errors are not retried.

Serena's own logs remain under ~/.serena/logs/. The extension suppresses the child process stderr stream so verbose LSP logs do not corrupt Pi's interactive terminal UI. For temporary terminal diagnostics:

SERENA_STDERR=inherit pi

Local development

From the repository root:

cd packages/pi-serena-mcp
npm install
npm run typecheck
npm test
npm run pack:check

The package can be loaded directly during development:

pi -e /absolute/path/to/packages/pi-serena-mcp/serena-mcp.ts