# Pi Serena Tools

Pi now gains IDE-like editing capabilities by bridging Serena’s semantic code tools into native Pi tools.

A Pi extension library that exposes the Serena MCP toolbox as native Pi tools via Streamable HTTP.
It auto-starts a per-session Serena MCP server and provides a configurable tool blacklist.

## Features

- IDE-like editing inside Pi via Serena’s semantic tooling
- Streamable HTTP transport for MCP calls
- Auto-started Serena MCP server scoped to the current project
- Per-instance port allocation (or override via `SERENA_MCP_PORT`)
- Tool blacklist with a UI menu (`/serena-tool-blocker`)
- Output truncation aligned with Pi defaults (50KB / 2000 lines)

## Installation

### As a Pi package

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

### Local development

```bash
pi -e /path/to/pi-serena-tools/index.ts
```

## Configuration

### Environment

- `SERENA_MCP_PORT` — Optional fixed port for the Serena MCP server (default: auto-select free port).

### Project settings

Add to `.pi/settings.json` to persist the tool blacklist:

```json
{
  "serena": {
    "blockedTools": ["read", "write", "edit", "ls", "find", "grep"]
  }
}
```

### Command

Use `/serena-tool-blocker` to toggle blocked tools in a TUI menu.

## Tools

The extension exposes Serena’s tool suite, including:

- **Symbolic tools**: `find_symbol`, `find_referencing_symbols`, `get_symbols_overview`, `insert_after_symbol`,
  `insert_before_symbol`, `replace_symbol_body`, `rename_symbol`, `restart_language_server`
- **JetBrains tools**: `jet_brains_find_symbol`, `jet_brains_find_referencing_symbols`,
  `jet_brains_get_symbols_overview`, `jet_brains_type_hierarchy`
- **File tools**: `read_file`, `list_dir`, `find_file`, `create_text_file`, `replace_content`, `delete_lines`,
  `replace_lines`, `insert_at_line`, `search_for_pattern`
- **Workflow/config**: `activate_project`, `check_onboarding_performed`, `onboarding`, `get_current_config`,
  `switch_modes`, `open_dashboard`, `initial_instructions`, `prepare_for_new_conversation`,
  `summarize_changes`, `think_about_collected_information`, `think_about_task_adherence`,
  `think_about_whether_you_are_done`
- **Memory tools**: `read_memory`, `write_memory`, `list_memories`, `delete_memory`, `rename_memory`, `edit_memory`
- **Command tools**: `execute_shell_command`

All tool signatures mirror the Serena repo definitions.

## Usage Examples

```text
find_symbol {
  "name_path_pattern": "MyClass/myMethod",
  "relative_path": "src",
  "include_body": false
}
```

```text
read_file {
  "relative_path": "src/index.ts",
  "start_line": 0,
  "end_line": 200
}
```

```text
replace_symbol_body {
  "name_path": "MyClass/myMethod",
  "relative_path": "src/my_class.ts",
  "body": "def myMethod(self):\n    pass"
}
```

## Requirements

- `uvx` on PATH (the extension runs `uvx --from git+https://github.com/oraios/serena serena ...`).

## Why this is great

With Serena wired in, Pi can edit code at the symbol level (classes, methods, functions) instead of raw text. That means safer refactors, accurate insertions, and IDE-like navigation directly from the terminal.

## Notes

- The extension activates the current project (if the tool exists) on session start.
- The Serena MCP server is per Pi instance (no shared port unless `SERENA_MCP_PORT` is set).