# 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`:

```bash
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`:

```bash
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

```bash
pi install npm:pi-serena-mcp
```

Restart Pi after installation. To install a specific version:

```bash
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:

```bash
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:

```bash
SERENA_STDERR=inherit pi
```

## Local development

From the repository root:

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

The package can be loaded directly during development:

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